Agents API

Manage agent configurations and chat sessions.

Agent Configuration

List Agent Configurations

Returns all configured agents.

GET /v1/agent/config

Response:

{
  "configs": [
    {
      "name": "assistant",
      "description": "A helpful AI assistant",
      "model_name": "claude-haiku-4-5-20251001",
      "enabled": true,
      "mcp_names": [],
      "mcp_tools": {
        "filesystem": [
          "read_file"
        ]
      },
      "system_prompt": "You are a helpful assistant.",
      "system_prompt_file": null,
      "can_manage_agents": false,
      "enable_extended_thinking": false,
      "reasoning_effort": null
    }
  ]
}

Get Agent Configuration

Returns configuration for a specific agent.

GET /v1/agent/config/{name}

Path Parameters:

Response: Single agent configuration object.

Create Agent Configuration

Creates a new agent configuration.

POST /v1/agent/config

Request Body:

{
  "name": "new-agent",
  "model_name": "claude-sonnet-4-5-20250929",
  "enabled": true,
  "description": "A new agent",
  "mcp_names": [],
  "mcp_tools": {
    "database": null
  },
  "system_prompt": "You are an expert assistant.",
  "system_prompt_file": null,
  "can_manage_agents": false,
  "reasoning_effort": "medium"
}

Parameters:

Reasoning Effort

The reasoning_effort field controls the model’s reasoning behavior. See the Responses API documentation for details on how different providers handle each level.

Note: If neither reasoning_effort nor enable_extended_thinking is set, the provider’s default behavior is used.

Response: 201 Created with the created agent configuration.

Update Agent Configuration

Updates an existing agent configuration.

PUT /v1/agent/config/{name}

Path Parameters:

Request Body: Same fields as create, all optional.

Response: 200 OK with the updated agent configuration.

Delete Agent Configuration

Deletes an agent configuration.

DELETE /v1/agent/config/{name}

Path Parameters:

Response: 204 No Content

List Available Agents

Returns a list of enabled agents that can be used for chat.

GET /v1/agent

Query Parameters:

Response:

{
  "agents": [
    {
      "name": "assistant",
      "mcps": [
        "filesystem",
        "database"
      ]
    }
  ]
}

Agent Chat

Create Agent Chat

Creates a new chat session with an agent.

POST /v1/agent/chat

Request Body:

{
  "agent_name": "assistant",
  "parent_chat_id": 1,
  "initial_message": "Hello, I need help with..."
}

Parameters:

Response:

{
  "agent_chat_id": 42,
  "agent_name": "assistant",
  "parent_chat_id": 1,
  "model_name": "claude-haiku-4-5-20251001",
  "agent_management_enabled": false
}

Chat Messages

Get Messages

Retrieves messages from a chat.

GET /v1/chat/{chat_id}/message

Path Parameters:

Response: Array of message objects.

Send Message

Sends a message to a chat.

POST /v1/chat/{chat_id}/message

Path Parameters:

Request Body:

{
  "agent": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello, how can you help me?"
    }
  ]
}

Response:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'm here to help! What would you like to know?"
    }
  ],
  "error": null
}

Delete Chat

Deletes a chat session.

DELETE /v1/chat/{chat_id}

Path Parameters:

Response: 204 No Content

Agent Management

Control agent management capabilities for chat sessions.

Enable Agent Management

Enables agent management capabilities for a chat, allowing the agent to spawn and manage other agents.

POST /v1/agent/management/{chat_id}/enable

Path Parameters:

Response: 200 OK

Disable Agent Management

Disables agent management capabilities for a chat.

POST /v1/agent/management/{chat_id}/disable

Path Parameters:

Response: 200 OK

Agent Monitoring

List Active Agents

Returns currently active agent sessions.

GET /v1/agent/monitoring/active

Response:

{
  "active_agents": [
    {
      "chat_id": 1,
      "user_data": {},
      "pending": false,
      "has_messages": true,
      "last_model": "claude-haiku-4-5-20251001",
      "agent_management_enabled": false,
      "message_count": 5
    }
  ],
  "total": 1
}

List Waiting Agents

Returns agent sessions waiting for input (e.g., waiting for tool results).

GET /v1/agent/monitoring/waiting

Response:

{
  "waiting_agents": [
    {
      "agent_chat_id": 42,
      "parent_chat_id": 1,
      "inflight_id": "abc123"
    }
  ],
  "total": 1
}

Examples

Create and Use an Agent

# Create agent
curl -X POST http://localhost:8080/v1/agent/config \
  -H "Content-Type: application/json" \
  -d '{
    "name": "helper",
    "model_name": "claude-haiku-4-5-20251001",
    "enabled": true,
    "system_prompt": "You are a helpful assistant."
  }'

# Use via Responses API (recommended)
curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:helper",
    "input": "What can you help me with?"
  }'

Create Agent with Reasoning

# Create agent with high reasoning for complex tasks
curl -X POST http://localhost:8080/v1/agent/config \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reasoning-agent",
    "model_name": "gpt-5.1",
    "enabled": true,
    "system_prompt": "You are a problem-solving assistant.",
    "reasoning_effort": "high"
  }'

# Create agent with no reasoning for fast responses
curl -X POST http://localhost:8080/v1/agent/config \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fast-agent",
    "model_name": "gpt-5.1",
    "enabled": true,
    "system_prompt": "You are a quick assistant.",
    "reasoning_effort": "none"
  }'

List and Filter Agents

# List all agent configs
curl http://localhost:8080/v1/agent/config

# List enabled agents
curl http://localhost:8080/v1/agent

# Filter by MCP access
curl "http://localhost:8080/v1/agent?mcp=database"

Next Steps

• Responses API → - Use agents via the Responses API (recommended)
• Tools API → - Configure MCP tools for agents
• Agent Configuration → - File-based agent configuration