Agents API

Spawn, manage, and communicate with AI agents

Overview

Agents are autonomous AI entities that process messages, execute tools, and maintain conversation context. Each agent has its own manifest, model, tools, and session history.

Spawn Agent

Create a new agent from a TOML manifest:

POST /api/agents

curl -X POST http://127.0.0.1:4200/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_toml": "name = \"assistant\"\nprofile = \"Full\"\n[model]\nprovider = \"anthropic\"\nmodel = \"claude-sonnet-4-20250514\""
  }'

Request Body

manifest_toml · string · required

Agent manifest in TOML format. Maximum size: 1MB.

signed_manifest · string

Optional Ed25519-signed manifest JSON for enhanced security.

Response

agent_id · string

UUID of the newly spawned agent

name · string

Name of the agent from the manifest

201 Created

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "assistant"
}

Error Responses

400 Bad Request

{
  "error": "Invalid manifest format"
}

{
  "error": "Manifest signature verification failed"
}

{
  "error": "Manifest too large (max 1MB)"
}

List Agents

Get all active agents with enriched metadata:

GET /api/agents

curl http://127.0.0.1:4200/api/agents

200 OK

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "assistant",
    "state": "Running",
    "mode": "Auto",
    "created_at": "2025-03-06T12:00:00Z",
    "last_active": "2025-03-06T12:30:00Z",
    "model_provider": "anthropic",
    "model_name": "claude-sonnet-4-20250514",
    "model_tier": "smart",
    "auth_status": "configured",
    "ready": true,
    "profile": "Full",
    "identity": {
      "emoji": "🤖",
      "avatar_url": null,
      "color": "#3B82F6"
    }
  }
]

Get Agent

Retrieve detailed information about a specific agent:

GET /api/agents/{id}

curl http://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000

200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "assistant",
  "state": "Running",
  "mode": "Auto",
  "profile": "Full",
  "created_at": "2025-03-06T12:00:00Z",
  "session_id": "abc123-def456-789012",
  "model": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "capabilities": {
    "tools": ["bash", "read", "write", "edit"],
    "network": false
  },
  "description": "A helpful AI assistant",
  "tags": ["general", "assistant"],
  "identity": {
    "emoji": "🤖",
    "avatar_url": null,
    "color": "#3B82F6"
  },
  "skills": [],
  "skills_mode": "all",
  "mcp_servers": [],
  "mcp_servers_mode": "all",
  "fallback_models": []
}

Send Message

Send a message to an agent and receive a complete response:

POST /api/agents/{id}/message

curl -X POST http://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000/message \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is 2+2?"
  }'

Request Body

message · string · required

The message to send to the agent. Maximum size: 64KB.

attachments · array

Array of file attachment references from prior uploads.

Show Attachment Object

file_id · string

UUID of the uploaded file

filename · string

Original filename

content_type · string

MIME type (only image/* types are processed)

Response

response · string

The agent’s text response (with <think> tags stripped)

input_tokens · integer

Total input tokens consumed across all iterations

output_tokens · integer

Total output tokens generated across all iterations

iterations · integer

Number of LLM turns taken (agent loop iterations)

cost_usd · number

Estimated cost in USD (null if unavailable)

200 OK

{
  "response": "2 + 2 equals 4.",
  "input_tokens": 128,
  "output_tokens": 12,
  "iterations": 1,
  "cost_usd": 0.000156
}

Error Responses

404 Not Found

{
  "error": "Agent not found"
}

{
  "error": "Message too large (max 64KB)"
}

{
  "error": "Message delivery failed: quota exceeded"
}

Stream Message (SSE)

Send a message and receive a streaming response via Server-Sent Events:

POST /api/agents/{id}/message/stream

curl -X POST http://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000/message/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me a story"}' \
  --no-buffer

Event Types

event: chunk

{
  "content": "Once upon a time",
  "done": false
}

{
  "tool": "bash"
}

{
  "tool": "bash",
  "input": {"command": "ls -la"}
}

{
  "phase": "thinking",
  "detail": "Analyzing request..."
}

{
  "done": true,
  "usage": {
    "input_tokens": 256,
    "output_tokens": 128
  }
}

Get Agent Session

Retrieve the agent’s conversation history:

GET /api/agents/{id}/session

curl http://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000/session

200 OK

{
  "session_id": "abc123-def456-789012",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_count": 4,
  "context_window_tokens": 1024,
  "label": null,
  "messages": [
    {
      "role": "User",
      "content": "What is 2+2?"
    },
    {
      "role": "Assistant",
      "content": "2 + 2 equals 4."
    }
  ]
}

Change Agent Mode

Switch the agent’s operational mode:

PUT /api/agents/{id}/mode

curl -X PUT http://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000/mode \
  -H "Content-Type: application/json" \
  -d '{"mode": "Manual"}'

Request Body

mode · enum · required

Show Available Modes

• Auto: Automatically use tools and respond
• Manual: Require approval for tool use
• Observe: Read-only mode (no actions)

200 OK

{
  "status": "updated",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "Manual"
}

Delete Agent

Terminate an agent and release its resources:

DELETE /api/agents/{id}

curl -X DELETE http://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000

200 OK

{
  "status": "killed",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000"
}

Tool Profiles

Get available tool profiles and their included tools:

GET /api/profiles

curl http://127.0.0.1:4200/api/profiles

200 OK

[
  {
    "name": "minimal",
    "tools": ["bash", "read", "write"]
  },
  {
    "name": "coding",
    "tools": ["bash", "read", "write", "edit", "glob", "grep"]
  },
  {
    "name": "full",
    "tools": ["bash", "read", "write", "edit", "glob", "grep", "web_fetch", "web_search"]
  }
]

WebSocket Connection

Connect to an agent via WebSocket for real-time bidirectional communication:

const ws = new WebSocket('ws://127.0.0.1:4200/api/agents/550e8400-e29b-41d4-a716-446655440000/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'message',
    content: 'Hello!'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Agent:', data);
};

WebSocket connections support Bearer authentication. See Authentication for details.

Next Steps

Memory API

Store and retrieve agent memories

Workflows API

Orchestrate multi-agent pipelines