Table of Contents

Listing and Accessing Agents via Core API

This guide explains how to list agents using the Core API. There are two methods depending on your use case.

Overview

The Core API provides two endpoints for listing agents:

Endpoint Purpose Auth Methods
GET /completions/agents List agents accessible for completions Entra ID or Agent Access Token
GET /management/.../agents List agents for management Entra ID only

Method 1: List Accessible Agents (for Completions)

Use this endpoint to get agents the current user can send completions to. This is the user-facing endpoint used by chat interfaces.

URL Pattern:

GET https://{core-api-url}/instances/{instanceId}/completions/agents

Using curl

# With Bearer token
curl -X GET "$CORE_API_URL/instances/$INSTANCE_ID/completions/agents" \
  -H "Authorization: Bearer $TOKEN"

# With Agent Access Token
curl -X GET "$CORE_API_URL/instances/$INSTANCE_ID/completions/agents" \
  -H "X-AGENT-ACCESS-TOKEN: your-agent-access-token"

Response:

[
  {"resource":
    {
        "type": "generic-agent",
        "name": "knowledge-agent",
        "display_name": "Knowledge Agent",
        "description": "General knowledge assistant",
        "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/knowledge-agent",
        ...
    }
  }
]

Using Python

import os
import requests

# Configuration
CORE_API_URL = os.getenv("FLLM_CORE_API_URL")
INSTANCE_ID = os.getenv("FLLM_INSTANCE_ID")
TOKEN = os.getenv("FLLM_TOKEN")

# Standard Core API base URL
FLLM_ENDPOINT = f"{CORE_API_URL}/instances/{INSTANCE_ID}/"

def get_headers():
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

def get_allowed_agents():
    """Get agents the user can send completions to."""
    url = f"{FLLM_ENDPOINT}completions/agents"
    
    # Ignore SSL certificate verification when running locally or in test, in production use verify=True.
    response = requests.get(url, headers=get_headers(), verify=False)
    response.raise_for_status()
    return response.json()

# List accessible agents
agents = get_allowed_agents()
for agent in agents:
    print(agent['resource']['name'])

Method 2: List Agents for Management

Use this endpoint to get agents you can manage (create, edit, delete). This uses the Core API's /management endpoint path.

URL Pattern:

GET https://{core-api-url}/management/instances/{instanceId}/providers/FoundationaLLM.Agent/agents

Using curl

# Basic list
curl -X GET "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents" \
  -H "Authorization: Bearer $TOKEN"

# With role information
curl -X GET "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents?includeRoles=true" \
  -H "Authorization: Bearer $TOKEN"

# With action information
curl -X GET "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents?includeActions=true" \
  -H "Authorization: Bearer $TOKEN"

# With both
curl -X GET "$CORE_API_URL/management/instances/$INSTANCE_ID/providers/FoundationaLLM.Agent/agents?includeRoles=true&includeActions=true" \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "resource": {
      "type": "agent",
      "name": "my-custom-agent",
      "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-custom-agent",
      "display_name": "My Custom Agent",
      "description": "Custom agent I created",
      "conversation_history_settings": {
        "enabled": true,
        "max_history": 5
      }
    },
    "roles": ["Owner"],
    "actions": ["FoundationaLLM.Agent/agents/read", "FoundationaLLM.Agent/agents/write", "FoundationaLLM.Agent/agents/delete"]
  }
]

Using Python

import requests

# Configuration
CORE_API_URL = os.getenv("FLLM_CORE_API_URL")
INSTANCE_ID = os.getenv("FLLM_INSTANCE_ID")
TOKEN = os.getenv("FLLM_TOKEN")

# Core API management endpoint base
CORE_API_MGMT = f"{CORE_API_URL}/management/instances/{INSTANCE_ID}/"

def get_headers():
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

def list_agents_for_management(include_roles=False, include_actions=False):
    """List agents via Core API's management endpoint."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents"
    
    params = {}
    if include_roles:
        params['includeRoles'] = 'true'
    if include_actions:
        params['includeActions'] = 'true'
    
    # Ignore SSL certificate verification when running locally or in test, in production use verify=True.
    response = requests.get(url, headers=get_headers(), params=params, verify=False)
    response.raise_for_status()
    return response.json()

# List all manageable agents with roles and actions
agents = list_agents_for_management(include_roles=True, include_actions=True)
for item in agents:
    resource = item.get('resource', item)
    roles = item.get('roles', [])
    actions = item.get('actions', [])
    
    print(f"\nAgent: {resource.get('name')}")
    print(f"  Display Name: {resource.get('display_name')}")
    print(f"  Roles: {', '.join(roles)}")
    print(f"  Actions: {', '.join(actions)}")

Query Parameters

Parameter Type Description
includeRoles boolean Include user's roles for each agent
includeActions boolean Include authorized actions for each agent

Filtering and Processing Results

Filter by Role

def get_agents_by_role(role_name):
    """Get agents where user has a specific role."""
    agents = list_agents_for_management(include_roles=True)
    
    return [
        item.get('resource', item)
        for item in agents
        if role_name in item.get('roles', [])
    ]

# Get agents you own
owned_agents = get_agents_by_role("Owner")
print(f"You own {len(owned_agents)} agents:")
for agent in owned_agents:
    print(f"  - {agent.get('name')}")

Getting a Single Agent

def get_agent(agent_name):
    """Get details of a specific agent."""
    url = f"{CORE_API_MGMT}providers/FoundationaLLM.Agent/agents/{agent_name}"
    
    # Ignore SSL certificate verification when running locally or in test, in production use verify=True.
    response = requests.get(url, headers=get_headers(), verify=False)
    response.raise_for_status()
    
    result = response.json()
    if isinstance(result, list) and len(result) > 0:
        return result[0].get('resource', result[0])
    return result

# Get specific agent
agent = get_agent("my-custom-agent")
print(f"Agent: {agent.get('display_name')}")
print(f"Description: {agent.get('description')}")
print(f"History enabled: {agent.get('conversation_history_settings', {}).get('enabled')}")

Comparing the Two Methods

Feature /completions/agents /management/.../agents
Purpose Get agents for chat Get agents to manage
Auth Entra ID or Agent Access Token Entra ID only
Use case Chat interfaces Agent Configuration interfaces