API Server

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

Overview

The docker agent serve 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
$ docker agent api agent.yaml

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

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

# Auto-refresh from OCI registry every 10 minutes
$ docker agent 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

docker-agent 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.