Using the API

The full AgentOS API exposes agents, teams, workflows, and runtime state over REST. Call it from an authorized application or HTTP client.

For anonymous product clients, Public Surface selects a narrower route and input contract. Its public rosters omit runtime configuration, /info and /config return 404, and callers cannot supply the runtime-context overrides shown later on this page.

curl http://localhost:7777/agents/support-agent/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Where is my order?" \
  -d "user_id=customer-42" \
  -d "session_id=order-support-42" \
  -d "stream=false"

The response includes the run output, run_id, and session_id. Reuse the same session_id to group later runs in the same thread. Configure chat history when the model needs messages from earlier runs.

Teams and workflows use the same run pattern:

Component	Run endpoint
Agent	`POST /agents/{agent_id}/runs`
Team	`POST /teams/{team_id}/runs`
Workflow	`POST /workflows/{workflow_id}/runs`

Discover an Instance

GET /info returns the metadata a client needs before making authenticated calls. The endpoint is public.

curl http://localhost:7777/info

Field	Description
`auth_mode`	Active authentication mode: `none`, `security_key`, or `jwt`
`agent_count`, `team_count`, `workflow_count`	Number of registered runtime components
`mcp.enabled`	Whether the MCP server is mounted
`mcp.path`	MCP mount path when enabled
`mcp.oauth`	OAuth discovery details when the MCP endpoint uses OAuth
`agno_version`	Agno version running on the instance

Use GET /config to retrieve component IDs, database IDs, interfaces, and domain configuration. Send credentials when auth_mode requires them.

API Surfaces

Task	Resources
Execute application logic	Agents, teams, workflows, runs
Manage conversation and user state	Sessions, memories, learnings
Manage retrieval content	Knowledge, content sources, search
Measure behavior	Evaluations, metrics, traces
Control sensitive operations	Approvals, run continuation, cancellation
Automate recurring work	Schedules and schedule runs
Operate the runtime	Configuration, models, databases, service accounts

See the API reference for every path and schema.

Stream Run Events

Run endpoints stream Server-Sent Events by default. Use curl -N to print events as they arrive:

curl -N http://localhost:7777/agents/support-agent/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Investigate this account" \
  -d "stream=true"

Set stream=false when the caller needs one JSON response after the run completes.

Pass Runtime Context

Run endpoints accept JSON-encoded form fields alongside the message:

Field	Use
`dependencies`	Values available to tools and runtime functions
`session_state`	State carried through the current session
`metadata`	Application metadata stored with the run
`knowledge_filters`	Filters applied during knowledge retrieval
`output_schema`	JSON Schema for structured output

curl http://localhost:7777/agents/story-writer/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Write a short story" \
  -d 'dependencies={"reader_age":10}' \
  -d 'metadata={"source":"reading-app"}' \
  -d 'output_schema={"type":"object","properties":{"title":{"type":"string"},"story":{"type":"string"}},"required":["title","story"]}' \
  -d "stream=false"

Authenticate Requests

Read auth_mode from GET /info, then send the matching credential:

`auth_mode`	Credential
`none`	No authorization header
`security_key`	`Authorization: Bearer <OS_SECURITY_KEY>`
`jwt`	`Authorization: Bearer <jwt-token>`

curl http://localhost:7777/agents/support-agent/runs \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Summarize my open tickets" \
  -d "stream=false"

Service-account tokens beginning with agno_pat_ are bearer credentials for machine callers. They are available when the AgentOS instance has a database.

REST or Python Client

Client	Use when
REST API	The application uses another language, needs direct HTTP control, or calls a small set of endpoints
`AgentOSClient`	A Python application needs typed run outputs and helpers for sessions, memory, knowledge, and configuration

import asyncio

from agno.client import AgentOSClient


async def main():
    client = AgentOSClient(base_url="http://localhost:7777")
    response = await client.run_agent(
        agent_id="support-agent",
        message="Where is my order?",
        user_id="customer-42",
        session_id="order-support-42",
    )
    print(response.content)


asyncio.run(main())

Next Steps

Task	Guide
Browse every endpoint	API reference
Use the Python client	AgentOS Client
Configure authentication	Security & Auth
Manage sessions	Session management example
Run AgentOS as an MCP server	AgentOS as MCP Server