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.

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, 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

If authentication is enabled, include a JWT token:

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

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