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.

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.

curl -X POST http://localhost:7777/agents/copilot/runs \
  -F 'message=Summarize this thread' \
  -F 'user_id=[e-mail]' \
  -F 'session_id=thread-42' \
  -F 'stream=false'

{
  "run_id": "run_abc123",
  "session_id": "thread-42",
  "user_id": "[e-mail]",
  "agent_id": "copilot",
  "status": "completed",
  "content": "..."
}

From a browser widget with streaming and a JWT:

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.

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.

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
Lock down endpoints	Security and auth

Developer Resources

• Serve as an API
• AgentOS
• Deploy