Using the API

Call the AgentOS API to run agents, teams, and workflows.

AgentOS exposes endpoints for running agents and managing sessions, memories, knowledge, and evals. The same API powers the control plane and can be used to build your AI products.

Instance Discovery

GET /info is unauthenticated and returns what a client needs to bootstrap against an instance: which authentication mode it enforces and whether an MCP server is mounted.

curl http://localhost:7777/info

{
  "os_id": "my-agent-os",
  "name": null,
  "agno_version": "2.7.2",
  "agent_count": 1,
  "team_count": 0,
  "workflow_count": 0,
  "mcp": {
    "enabled": true,
    "path": "/mcp",
    "oauth": null
  },
  "auth_mode": "none"
}

Field	Description
auth_mode	Authentication enforced by the instance: none, security_key, or jwt
mcp.enabled	Whether the MCP server is mounted
mcp.path	Mount path of the MCP server, null when disabled
mcp.oauth	OAuth discovery details when the MCP endpoint is OAuth-protected, null otherwise
agent_count, team_count, workflow_count	Registered components
agno_version	Agno version running on the instance

Endpoints

Resource	Operations
Agents	Run, list, get
Teams	Run, list, get
Workflows	Run, list, get
Sessions	Create, list, get, update, delete
Memories	Create, list, get, update, delete
Knowledge	Add, search, list, get, update, delete
Evals	Create, list, get, update, delete
Metrics	Get, refresh

See the API reference for full documentation.

Running Agents

curl http://localhost:7777/agents/my-agent/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Tell me about Agno" \
  -d "stream=true" \
  -d "user_id=[e-mail]" \
  -d "session_id=session_123"

Teams and workflows follow the same pattern:

• POST /teams/{team_id}/runs
• POST /workflows/{workflow_id}/runs

Authentication

The auth_mode field from GET /info tells you which credential to send:

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

curl http://localhost:7777/agents/my-agent/runs \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Your query here"

Service-account tokens (agno_pat_...) are accepted as bearer credentials in every mode on instances with a database. See Security & Authorization to configure authentication.

Passing Dependencies

Pass runtime parameters like dependencies, session_state, or metadata as form fields:

curl http://localhost:7777/agents/story-writer/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Write me a 5 line story" \
  -d 'dependencies={"robot_name": "Anna"}'

Output Schema

Pass a JSON schema to structure the response:

curl http://localhost:7777/agents/story-writer/runs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "message=Write a story" \
  -d 'output_schema={"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"}},"required":["title","content"]}'

Cancelling Runs

curl -X POST http://localhost:7777/agents/story-writer/runs/123/cancel