API Server

Expose your agents via an HTTP API for programmatic access, web frontends, and integrations.

Overview

The cagent api command starts an HTTP server that exposes your agents through a REST-style API with Server-Sent Events (SSE) streaming. Use it to build web UIs, integrate with CI/CD pipelines, or connect agents to other services.

# Start the API server
$ cagent api agent.yaml

# Custom listen address
$ cagent api agent.yaml --listen 0.0.0.0:8080

# With session persistence
$ cagent api agent.yaml --session-db ./sessions.db

# Auto-refresh from OCI registry every 10 minutes
$ cagent api agentcatalog/coder --pull-interval 10

Endpoints

All endpoints are under the /api prefix.

Agents

Sessions

Agent Execution

Health

Streaming Responses

The agent execution endpoints (POST /api/sessions/:id/agent/:agent) return Server-Sent Events (SSE). Each event is a JSON object representing a runtime event:

# Send a message and stream the response
$ curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/my-agent \
  -H "Content-Type: application/json" \
  -d '[{"role": "user", "content": "Hello!"}]'

# Response (SSE stream):
data: {"type":"stream_started","session_id":"...","agent":"root"}
data: {"type":"agent_choice","content":"Hello! How","agent":"root"}
data: {"type":"agent_choice","content":" can I help","agent":"root"}
data: {"type":"agent_choice","content":" you today?","agent":"root"}
data: {"type":"stream_stopped","session_id":"...","agent":"root"}

Event types include:

• stream_started / stream_stopped — Agent execution lifecycle
• agent_choice — Streamed text content (partial responses)
• tool_call — Agent requesting tool execution
• tool_call_confirmation — Tool call waiting for user approval
• tool_call_response — Tool execution result
• error — Error during execution

Typical Workflow

1. List agents — GET /api/agents to discover available agents
2. Create session — POST /api/sessions to start a conversation
3. Send message — POST /api/sessions/:id/agent/:agent with user messages
4. Stream response — Read SSE events as the agent processes
5. Handle confirmations — If a tool call needs approval, POST /api/sessions/:id/resume
6. Continue — Send follow-up messages to the same session

# 1. List available agents
$ curl http://localhost:8080/api/agents
[{"name":"my-agent","multi":false,"description":"A helpful assistant"}]

# 2. Create a session
$ curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" -d '{}'
{"id":"abc-123","title":"","created_at":"..."}

# 3. Run the agent with a message
$ curl -N -X POST http://localhost:8080/api/sessions/abc-123/agent/my-agent \
  -H "Content-Type: application/json" \
  -d '[{"role":"user","content":"What files are in the current directory?"}]'

CLI Flags

cagent api <agent-file>|<agents-dir> [flags]

Session Persistence

Sessions are stored in a SQLite database (default: session.db in the current directory). This means:

• Sessions survive server restarts
• Multiple server instances can share a database
• Use --session-db to specify a custom path

Tool Call Approval

By default, tool calls require approval. In the API workflow:

1. Agent makes a tool call → server emits a tool_call_confirmation event
2. Client reviews and sends POST /api/sessions/:id/resume with the decision
3. Execution continues based on approval/denial

Toggle auto-approve with POST /api/sessions/:id/tools/toggle for automated workflows.