Using the API

Run agents, manage state, and operate AgentOS through its REST API.

Application engineers use the AgentOS API to embed agents in products and manage runtime state from any HTTP client.

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