Skip to main content

​
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
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "assistant"
}

​
Error Responses

{
  "error": "Invalid manifest format"
}

​
List Agents

Get all active agents with enriched metadata:
GET /api/agents
curl http://127.0.0.1:4200/api/agents

[
  {
    "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

{
  "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.

​
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)
{
  "response": "2 + 2 equals 4.",
  "input_tokens": 128,
  "output_tokens": 12,
  "iterations": 1,
  "cost_usd": 0.000156
}

​
Error Responses

{
  "error": "Agent not found"
}

​
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

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

​
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

{
  "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
{
  "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

{
  "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

[
  {
    "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