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

# Serve as an API

> Turn agents into an HTTP service with streaming, sessions, and auth.

`AgentOS` serves your agents as a FastAPI application. Every agent gets run, session, and memory endpoints. Your product surfaces call those endpoints.

```python theme={null}
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

agent = Agent(
    id="copilot",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    add_history_to_context=True,
    enable_agentic_memory=True,
)

agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="copilot:app", port=7777)
```

## Calling it from a surface

Every run endpoint takes the same shape, whether the caller is a browser widget or a backend job.

```bash theme={null}
curl -X POST http://localhost:7777/agents/copilot/runs \
  -F 'message=Summarize this thread' \
  -F 'user_id=sarah@acme.com' \
  -F 'session_id=thread-42' \
  -F 'stream=false'
```

```json theme={null}
{
  "run_id": "run_abc123",
  "session_id": "thread-42",
  "user_id": "sarah@acme.com",
  "agent_id": "copilot",
  "status": "completed",
  "content": "..."
}
```

From a browser widget with streaming and a JWT:

```javascript theme={null}
async function askCopilot(message, userId, threadId) {
  const res = await fetch("https://os.yourproduct.com/agents/copilot/runs", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${jwt}`,
    },
    body: JSON.stringify({
      message,
      user_id: userId,
      session_id: threadId,
      stream: true,
    }),
  });
  return res.body; // SSE stream into the UI
}
```

| Want                       | Pass                                    |
| -------------------------- | --------------------------------------- |
| Token stream for a live UI | `stream=true` (Server-Sent Events)      |
| Long job, poll later       | `background=true`                       |
| Per-user isolation         | `user_id` and a per-thread `session_id` |

## What you get without building it

| Endpoint group     | Covers                                                                     |
| ------------------ | -------------------------------------------------------------------------- |
| Runs               | Create, stream, cancel, run in background, resume disconnected streams     |
| Sessions           | Create, list, rename, delete, pull every run in a session, scoped per user |
| Memory             | Create, update, delete, search user memories                               |
| Traces and metrics | Per-run spans, token usage, model breakdown                                |

Browse the live OpenAPI spec at the `/docs` endpoint of your running AgentOS.

## Custom routes

`AgentOS` is a FastAPI app. Add routes for webhooks, dashboards, or product-specific endpoints. The agent is a regular Python object you can call from anywhere.

```python theme={null}
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, "response": response.content}
```

## Auth

Set `authorization=True` and every endpoint except `/health` and `/openapi.json` requires a valid JWT.

```python theme={null}
agent_os = AgentOS(agents=[agent], authorization=True)
```

AgentOS validates the token before any agent code runs and injects `user_id`, `session_id`, and scope claims into the run. RBAC scopes are enforced per endpoint.

## Next steps

| Task                          | Guide                                              |
| ----------------------------- | -------------------------------------------------- |
| Add Slack or browser surfaces | [Interfaces](/use-cases/product-agents/interfaces) |
| Lock down endpoints           | [Security and auth](/features/security-and-auth)   |

## Developer Resources

* [Serve as an API](/features/api)
* [AgentOS](/agent-os/connect-your-os)
* [Deploy](/features/deploy)