Agents

An agent is a named, reusable unit of work backed by a model and a set of capabilities. You create it once, then execute it on demand. Execution is asynchronous: you submit a task and get back an execution_id to track.

All calls need authentication. See Authentication. Every /api/v1 endpoint is scoped to your organization: the agent_id, execution_id, and other resource ids in these paths only resolve within the organization your credentials belong to, and return 404 otherwise, so the ids are safe to pass around inside your own systems.

Create an agent

Most teams create agents in the app, but you can also do it over the API.

POST /api/v1/agents
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Support Triage",
  "agent_type": "support_operations",
  "description": "Triages inbound tickets into an escalation path.",
  "capabilities": ["support.escalation.triage"],
  "system_prompt": "You are a senior B2B support operations analyst...",
  "enabled": true
}

The response contains the new agent’s id. Seeded agents already exist in a new organization; list them with GET /api/v1/agents.

Run an agent

Submit a task to an agent. The body is free-form task data. Set task_type to the capability you want, and add whatever fields that capability reads.

POST /api/v1/agents/{agent_id}/execute
Authorization: Bearer <token>
Content-Type: application/json

{
  "task_type": "support.escalation.triage",
  "ticket": "Checkout API returns intermittent 500s for 3 hours. Enterprise plan.",
  "priority_hint": "high"
}

The call returns 202 Accepted immediately with an execution handle:

{
  "data": {
    "execution_id": "…",
    "celery_task_id": "…",
    "status": "queued"
  }
}

Get the result (poll)

Fetch the execution until its status is terminal (completed, failed, or cancelled).

GET /api/v1/agents/{agent_id}/executions/{execution_id}
Authorization: Bearer <token>

{
  "data": {
    "id": "…",
    "status": "completed",
    "success": true,
    "duration_ms": 18420,
    "result": {
      "task_type": "support.escalation.triage",
      "steps_completed": 3,
      "results": [ … ]
    },
    "error_message": null
  }
}

• status: queued, executing, then a terminal state.
• success: whether the run finished cleanly.
• result: the agent’s structured output. The shape depends on the agent.
• error_message: populated only when success is false.

List past runs with GET /api/v1/agents/{agent_id}/executions.

Stream the result (SSE)

Instead of polling, subscribe to a Server-Sent Events stream to receive progress and the final result as they happen.

GET /api/v1/agents/{agent_id}/executions/{execution_id}/stream
Authorization: Bearer <token>
Accept: text/event-stream

Events arrive as they occur, ending with a terminal event that carries the result. Use this for live UIs; use polling for simple back-end jobs.

Cancel or retry

POST /api/v1/agents/{agent_id}/executions/{execution_id}/cancel
POST /api/v1/agents/{agent_id}/executions/{execution_id}/retry

Cancel stops an in-flight run. Retry re-queues a failed or cancelled run with the same task data.

End-to-end example

BASE=http://localhost:8002/api/v1
KEY="sk_live_…"

# 1. Pick an agent
AGENT=$(curl -s "$BASE/agents?page_size=1" -H "X-API-Key: $KEY" \
  | jq -r '.data.items[0].id')

# 2. Run it
EXEC=$(curl -s "$BASE/agents/$AGENT/execute" -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"task_type":"general","task":"Summarize today priorities."}' \
  | jq -r '.data.execution_id')

# 3. Poll until done
while :; do
  S=$(curl -s "$BASE/agents/$AGENT/executions/$EXEC" -H "X-API-Key: $KEY" \
    | jq -r '.data.status')
  echo "$S"; [ "$S" = completed ] || [ "$S" = failed ] && break
  sleep 3
done

Next: Agent to agent.