> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> REST API and optional MCP server for agents, teams, and workflows in AgentOS.

Shipping an agent needs more than a `/run` endpoint. A live agent needs an API that can:

* Run agents in streaming mode and as background jobs
* Manage the sessions, memory, and learnings your agents accumulate
* Inspect runs, traces, and metrics
* Schedule recurring work
* Gate sensitive tool calls on human approval
* Resume paused runs once that approval comes back

AgentOS registers run routes for your agents, teams, and workflows. Database-backed routes and opt-in features such as scheduling, tracing, and MCP depend on the AgentOS configuration. Browse the live API at `/docs` or fetch the spec from `/openapi.json`.

<video autoPlay loop muted playsInline className="w-full rounded-lg" src="https://mintcdn.com/agno-v2-codex-docs-audit-20260719-0149/pW8PmtN5WDvNK9a4/videos/agentos-api-scroll.mp4?fit=max&auto=format&n=pW8PmtN5WDvNK9a4&q=85&s=6c0a9404f8ee75ca0e776ce114a2e0ff" data-path="videos/agentos-api-scroll.mp4" />

## Interfaces

Agents need to be reachable over more than one interface. Define an agent once and AgentOS can expose it over any interface you opt into. REST and SSE are on by default; add an MCP server, A2A, or a Slack interface as needed. The agent code stays the same; only the interface layer changes.

## The surface area

| Group                | What you can do                                                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Runs**             | Create, list, cancel, continue paused runs, resume disconnected streams. Stream over SSE or run as background jobs.                                            |
| **Sessions**         | Create, list, rename, update, delete. Pull every run in a session. Enforce per-user scoping with user isolation.                                               |
| **Memory**           | Create, update, delete user memories. Search content, filter by topic, view per-user stats. Run optimization to compact token usage.                           |
| **Learnings**        | Create, list, update, delete learnings captured from runs. List the users they belong to.                                                                      |
| **Knowledge**        | Upload files, text, URLs, or content from S3, GCS, SharePoint, GitHub. Search via vector, keyword, or hybrid. List sources, files in a source, content status. |
| **Evals**            | Run accuracy, agent-as-judge, performance, and reliability evals. List, update, delete eval runs.                                                              |
| **Traces**           | List, search with a filter DSL, view full span trees, group by session. Inspect individual LLM calls and tool invocations.                                     |
| **Metrics**          | Daily aggregated runs, sessions, users, token usage, model breakdown. Refresh on demand.                                                                       |
| **Schedules**        | CRUD, enable, disable, trigger now. List historical runs of a schedule.                                                                                        |
| **Approvals**        | List pending approvals, resolve them, count by user.                                                                                                           |
| **Components**       | Version your agents, teams, and workflows. Manage drafts, publish, roll back to a previous version.                                                            |
| **Service Accounts** | Mint a service account token (returned once), list accounts, revoke them.                                                                                      |
| **Database**         | Migrate one or all database schemas to a target version.                                                                                                       |

## How a request looks

Run endpoints accept `multipart/form-data` so a single call can carry text, files, and media. Agents, teams, and workflows share this request pattern; each response identifies the component type that ran. An agent request looks like this:

```bash theme={null}
curl -X POST http://localhost:7777/agents/my-agent/runs \
  -F "message=Hello" \
  -F "user_id=alice" \
  -F "session_id=thread-42" \
  -F "stream=false"
```

```json theme={null}
{
  "run_id": "run_abc123",
  "session_id": "thread-42",
  "user_id": "alice",
  "agent_id": "my-agent",
  "status": "COMPLETED",
  "content": "Hi Alice!",
  "created_at": 1777061700
}
```

Pass `stream=true` for Server-Sent Events. Pass `background=true` to run async and poll for completion.

## Adding your own routes

AgentOS is built on FastAPI. Register additional routes for webhooks, custom dashboards, integrations:

```python theme={null}
# `agent_os` is your AgentOS instance; `agent` is an Agent registered with it
app = agent_os.get_app()

@app.post("/webhooks/stripe")
async def handle_stripe(event: dict):
    response = await agent.arun(
        f"Process Stripe event: {event}",
        user_id="system",
    )
    return {"ok": True, "agent_response": response.content}
```

The agent is a regular Python object. Call `agent.run(...)` or `await agent.arun(...)` from anywhere.

## Auth

When `authorization=True`, central REST routes require a valid JWT in the `Authorization: Bearer ...` header except for the public routes (`/`, `/health`, `/info`, and API docs routes such as `/docs` and `/openapi.json`). AgentOS validates the token, extracts claims, and applies RBAC scopes before agent code runs. Self-authenticating interfaces such as Slack, Telegram, and WhatsApp verify requests through their own interface middleware.

See [Security & Auth](/features/security-and-auth) for the details.