Agent API

Agent-backed products need an API that covers the state and controls around every run. AgentOS provides REST endpoints for agents, teams, and workflows, plus sessions, memory, knowledge, traces, evaluations, schedules, approvals, and versioned components. 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.

Interfaces

AgentOS can expose the same registered component through several interfaces. REST and SSE are on by default; add an MCP server, A2A, or a Slack interface as needed. Each interface uses the same registered agent.

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:

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"

{
  "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, dashboards, and integrations:

# `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 for the details.

Welcome

Get Started

Features

Use Cases

Interfaces

The surface area

How a request looks

Adding your own routes

Auth

Developer Resources

​Interfaces

​The surface area

​How a request looks

​Adding your own routes

​Auth

​Developer Resources

Interfaces

The surface area

How a request looks

Adding your own routes

Auth

Developer Resources