Skip to main content
POST
/
api
/
v1
/
agents
Provision Agent
curl --request POST \
  --url https://api.example.com/api/v1/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "board_id": "<string>",
  "status": "<string>",
  "heartbeat_config": {},
  "identity_profile": {},
  "identity_template": "<string>",
  "soul_template": "<string>"
}
'
Creates a new agent record in Mission Control and provisions it on the associated gateway. The agent will be assigned a unique workspace and receive its configuration files (TOOLS.md, IDENTITY.md, etc.).

​
Authentication

Requires admin or agent authentication via Authorization: Bearer <token> header.

​
Request Body

​
name
string
required
Human-readable agent display name (e.g., “Ops triage lead”)
​
board_id
UUID
Board ID to scope this agent. Omit only when creating gateway-level agents (requires special permissions)
​
status
string
default:"provisioning"
Initial lifecycle state: provisioning, active, paused, retired
​
heartbeat_config
object
Runtime heartbeat behavior overrides
{
  "interval_seconds": 30,
  "missing_tolerance": 120
}
​
identity_profile
object
Profile hints used by routing and policy checks
{
  "role": "incident_lead",
  "skill": "triage"
}
​
identity_template
string
Template that defines initial intent and behaviorExample: “You are a senior incident response lead.”
​
soul_template
string
Template representing deeper agent instructionsExample: “When critical blockers appear, escalate in plain language.”

​
Response

Returns an AgentRead object with the same structure as List Agents.

​
Provisioning Workflow

When you create an agent, Mission Control:
  1. Validates board access and capacity limits
  2. Creates an agent record with status provisioning
  3. Generates a unique agent key: mc-<uuid>
  4. Calculates workspace path: {gateway.workspace_root}/workspace-{agent_key}/
  5. Calls gateway RPC: agents.create(mc-<uuid>)
  6. Writes configuration files via agents.files.set():
    • TOOLS.md - API credentials and endpoints
    • IDENTITY.md - Agent role and behavior (if identity_template provided)
    • SOUL.md - Deeper instructions (if soul_template provided)
  7. Updates status to ready

​
Agent IDs and Session IDs

Mission Control agents use a specific ID format:
  • Agent Key: mc-<uuid> (e.g., mc-c91361ef-6d85-439c-82e1-8f388a302e6a)
  • Session ID: agent:mc-<uuid>:main (stored in openclaw_session_id)
  • Workspace Path: {workspace_root}/workspace-mc-<uuid>/
These are distinct from manually configured agents in openclaw.json (e.g., cfo, architect).

​
Example Request

curl -X POST "https://api.example.com/api/v1/agents" \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial Operations Lead",
    "board_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "identity_profile": {
      "role": "cfo",
      "specialty": "budget_planning"
    },
    "identity_template": "You are a CFO agent responsible for financial planning and analysis."
  }'

​
Example Response

{
  "id": "c91361ef-6d85-439c-82e1-8f388a302e6a",
  "gateway_id": "55cc268a-4b45-400f-accf-201e025232ac",
  "board_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Financial Operations Lead",
  "status": "ready",
  "gateway_agent_id": "agent-01JCXYZ123",
  "workspace_path": "/home/ubuntu/.openclaw/workspace-mc-c91361ef-6d85-439c-82e1-8f388a302e6a",
  "is_mc_agent": true,
  "is_board_lead": false,
  "is_gateway_main": false,
  "openclaw_session_id": "agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main",
  "created_at": "2026-03-05T10:30:00Z",
  "updated_at": "2026-03-05T10:30:00Z",
  "identity_profile": {
    "role": "cfo",
    "specialty": "budget_planning"
  }
}

​
Error Responses

​
403 Forbidden
Insufficient permissions or board capacity exceeded
​
404 Not Found
Board ID does not exist or is not accessible
​
422 Unprocessable Entity
Validation failed (e.g., name is empty or too long)
​
502 Bad Gateway
Gateway RPC call failed (gateway unreachable or authentication failed)

​
Notes

  • Agent tokens are automatically generated during provisioning and stored in TOOLS.md
  • The agent must be able to read TOOLS.md from its workspace to authenticate with Mission Control
  • If the gateway entry is missing from openclaw.json, sync will fail (use Template Sync with rotate_tokens=true)

Build docs developers (and LLMs) love

Get started for freeTalk to us