GET /api/agents — List and Retrieve Agent Definitions

Retrieve all registered agents or fetch a single agent definition by ID, including is_team flags, display names, and capability descriptions.

The Agents API lets you discover what agents are registered on your Agent Manager instance. You can list every agent — including team agents — or look up a specific agent by its identifier. Agent definitions include the is_team flag that distinguishes single agents from multi-agent teams.

All requests require a valid bearer token in the Authorization header.

---

List all agents

includeInactive · boolean · default: "false"

When true, the response includes agents that have been marked inactive. Defaults to false, returning only active agents.

GET /api/agents

Returns every agent (and team) registered in the system. Use the is_team field to filter teams from single agents.

cURL

curl --request GET \
  --url "http://localhost:8080/api/agents?includeInactive=false" \
  --header "Authorization: Bearer {token}"

[] · object[]

An array of AgentDefinition objects.

Show AgentDefinition fields

id · string · required

Unique string identifier for the agent. Used as the agentId path parameter in run endpoints.

name · string · required

Human-readable display name for the agent.

description · string

A short summary of what the agent does and which domains it covers.

is_team · boolean · required

true if this agent definition represents a multi-agent team. Team agents are executed via the same run endpoints as single agents.

Example response

[
  {
    "id": "procurator_assistant",
    "name": "Procurator Assistant",
    "description": "Expert on the Operativus framework. Trained on docs.agno.com.",
    "is_team": false
  },
  {
    "id": "finance_agent",
    "name": "Finance Assistant",
    "description": "Analyzes stock data and financial metrics.",
    "is_team": false
  },
  {
    "id": "research_team",
    "name": "Research Team",
    "description": "Coordinator team that delegates to web and finance specialists.",
    "is_team": true
  }
]

---

Get a specific agent

GET /api/agents/{agentId}

Fetches the definition for a single agent. Returns 404 Not Found when no agent with the given ID exists.

agentId · string · required

The unique identifier of the agent to retrieve.

cURL

curl --request GET \
  --url "http://localhost:8080/api/agents/finance_agent" \
  --header "Authorization: Bearer {token}"

id · string · required

Unique string identifier for the agent.

name · string · required

Human-readable display name.

description · string

Short description of the agent’s purpose and capabilities.

is_team · boolean · required

true if this agent is a multi-agent team.

Example response

{
  "id": "finance_agent",
  "name": "Finance Assistant",
  "description": "Analyzes stock data and financial metrics.",
  "is_team": false
}

Error responses

Status	Description
404 Not Found	No agent exists with the specified agentId.

The agentId value you receive here is used as the path parameter in all execution endpoints — POST /api/agents/{agentId}/runs, /runs/stream, and /runs/background.