> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField query="includeInactive" type="boolean" default="false">
  When `true`, the response includes agents that have been marked inactive. Defaults to `false`, returning only active agents.
</ParamField>

```
GET /api/agents
```

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

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/agents?includeInactive=false" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

<ResponseField name="[]" type="object[]">
  An array of `AgentDefinition` objects.

  <Expandable title="AgentDefinition fields">
    <ResponseField name="id" type="string" required>
      Unique string identifier for the agent. Used as the `agentId` path parameter in run endpoints.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Human-readable display name for the agent.
    </ResponseField>

    <ResponseField name="description" type="string">
      A short summary of what the agent does and which domains it covers.
    </ResponseField>

    <ResponseField name="is_team" type="boolean" required>
      `true` if this agent definition represents a multi-agent team. Team agents are executed via the same run endpoints as single agents.
    </ResponseField>
  </Expandable>
</ResponseField>

**Example response**

```json theme={null}
[
  {
    "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.

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent to retrieve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/agents/finance_agent" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

<ResponseField name="id" type="string" required>
  Unique string identifier for the agent.
</ResponseField>

<ResponseField name="name" type="string" required>
  Human-readable display name.
</ResponseField>

<ResponseField name="description" type="string">
  Short description of the agent's purpose and capabilities.
</ResponseField>

<ResponseField name="is_team" type="boolean" required>
  `true` if this agent is a multi-agent team.
</ResponseField>

**Example response**

```json theme={null}
{
  "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`. |

<Note>
  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`.
</Note>