Serve as an API

AgentOS serves registered agents through a FastAPI application. Run routes are component-specific, while database-backed session and memory routes operate across the AgentOS. Your product surfaces call those endpoints.

copilot.py

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],
    db=db,
    cors_allowed_origins=[
        "http://localhost:3000",
        "https://app.yourproduct.com",
        "https://os.agno.com",
    ],
)
app = agent_os.get_app()

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

Supplying cors_allowed_origins replaces the AgentOS defaults. Include every browser and AgentOS UI origin that needs to call the backend.

Run the API

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

uv venv --python 3.12
.venv\Scripts\activate

Install dependencies

uv pip install -U "agno[os]" openai sqlalchemy "psycopg[binary]"

Export your OpenAI API key

export OPENAI_API_KEY="your_openai_api_key_here"

$Env:OPENAI_API_KEY="your_openai_api_key_here"

Run PgVector

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

docker run -d `
  -e POSTGRES_DB=ai `
  -e POSTGRES_USER=ai `
  -e POSTGRES_PASSWORD=ai `
  -e PGDATA=/var/lib/postgresql `
  -v pgvolume:/var/lib/postgresql `
  -p 5532:5432 `
  --name pgvector `
  agnohq/pgvector:18

Start AgentOS

Save the code as copilot.py, then run:

python copilot.py

Calling it from a surface

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

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'

{
  "run_id": "run_abc123",
  "session_id": "thread-42",
  "user_id": "sarah@acme.com",
  "agent_id": "copilot",
  "status": "COMPLETED",
  "content": "..."
}

After enabling authorization, a browser widget can stream with a JWT:

async function askCopilot(message, threadId, jwt) {
  const body = new FormData();
  body.append("message", message);
  body.append("session_id", threadId);
  body.append("stream", "true");

  const res = await fetch("https://os.yourproduct.com/agents/copilot/runs", {
    method: "POST",
    headers: { "Authorization": `Bearer ${jwt}` },
    body,
  });
  return res.body; // SSE stream into the UI
}

Want	Pass
Token stream for a live UI	`stream=true` (Server-Sent Events, the default)
A single JSON response	`stream=false`
Long job, poll later	`background=true` and `stream=false`
User and thread attribution	`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, and pull every run in a session. Per-user enforcement requires user isolation.
Memory	Create, update, delete, search user memories
Traces and metrics	Per-run spans when tracing is enabled, plus token usage and model metrics

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.

A public Stripe webhook must read the raw request body and verify its Stripe-Signature with the endpoint secret before parsing or passing an event to the agent. Never accept an unverified decoded dictionary. See Stripe’s webhook signature guide.

Auth

Set authorization=True to require a valid JWT on protected central routes. Set JWT_VERIFICATION_KEY or JWT_JWKS_FILE before building the app. Add user_isolation=True to filter user-scoped data for non-admin callers.

from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    agents=[agent],
    db=db,
    authorization=True,
    authorization_config=AuthorizationConfig(user_isolation=True),
    cors_allowed_origins=[
        "http://localhost:3000",
        "https://app.yourproduct.com",
        "https://os.agno.com",
    ],
)

AgentOS validates the token before agent code runs. The JWT sub pins user_id, and the scopes claim drives RBAC. An optional session_id claim overrides the form value; otherwise the client supplies the session ID with the request.

Next steps

Task	Guide
Add Slack or browser surfaces	Interfaces
Lock down endpoints	Security and auth

Welcome

Get Started

Features

Use Cases

Serve as an API

Run the API

Calling it from a surface

What you get without building it

Custom routes

Auth

Next steps

Developer Resources

​Run the API

​Calling it from a surface

​What you get without building it

​Custom routes

​Auth

​Next steps

​Developer Resources

Run the API

Calling it from a surface

What you get without building it

Custom routes

Auth

Next steps

Developer Resources