Start a new run on the conversation

Inserts a row in agent_runs, kicks off the workflow that drives the agent loop, and returns immediately. The response has status: "pending" — poll GET /agents/runs/{id} to track progress.

Runs are asynchronous. This endpoint does not wait for the model to reply. Typical end-to-end latency is 3–10 seconds for a single-iteration run, longer for multi-iteration tool-use loops (60–120 seconds is common for 6–8 iterations against an MCP server).

Required fields

• client_op_id — UUID you generate. Used as the idempotency key, scoped to (conversation_id, client_op_id). Re-sending the same value returns the original run row unchanged. Always generate a fresh UUID for a fresh logical request; reusing one is only safe if the second call is a retry of the first.
• expected_version — the conversation’s current version, read from GET /agents/conversations/{id} just before this call. If it doesn’t match at run-creation time, you get a 409 Version Conflict. Recovery: refetch the conversation, re-read version, retry the run with the fresh value.
• payload — kind: "user_message" to start a fresh user turn, or kind: "tool_outputs" to resume a previously-paused (requires_action) run.

Optional fields

• tool_choice — bias the model toward (or away from) using tools on iteration 1 of this run. Three values: auto, any, specific_tool (see schema). Applies only to iteration 1 of this run; iteration 2+ are back on auto. To re-force a specific tool on the next run, set tool_choice again on its request body.
• config_override — sparse override of the conversation’s defaults. Any field you set replaces the conversation-level value for this single run. The two list fields (mcp_servers, client_tools) are wholesale-replaced, not merged. The system_prompt cannot be overridden.

Run lifecycle (state diagram)

pending  →  running  →  completed         ← model produced a final answer
                    ↘   requires_action   ← model called a client-side tool
                    ↘   failed            ← non-recoverable error

You stop polling on any of the three terminal states. For requires_action, the run can be resumed by posting a new run on the same conversation with payload.kind: "tool_outputs". For completed and failed, the run is done.

Examples

Example 1 — fresh user message, no tools

{
  "client_op_id": "696b022c-e86d-4b3e-b6d7-ceb7eb1a495e",
  "expected_version": 0,
  "payload": { "kind": "user_message", "text": "What is 2 + 2?" }
}

Returns:

{
  "id": "82eb9cb7-619e-46bb-ac1c-8a32b0112c1c",
  "status": "pending",
  "started_at": "2026-05-18T13:21:30.355180Z",
  "submitted_inference_job_ids": [],
  "pending_tool_calls": [],
  "effective_config": { ... },
  ...
}

Then poll GET /agents/runs/{id} until status: completed. Final final_text: "4".

Example 2 — force a specific tool, override max_iterations

{
  "client_op_id": "c8aef867-eca6-46f7-8a99-e22dd0ee6062",
  "expected_version": 0,
  "payload": { "kind": "user_message", "text": "Find me a meeting time for tomorrow afternoon." },
  "tool_choice": { "kind": "specific_tool", "name": "user-confirm_booking" },
  "config_override": { "max_iterations": 10 }
}

The model is forced to call user-confirm_booking on iteration 1. Since user-confirm_booking is a client tool, the run terminates with status: requires_action after one iteration; pending_tool_calls contains the model’s proposed arguments.

Example 3 — resume a paused run

First, refetch the conversation to get the new version (it has advanced because the paused run’s assistant turn was persisted):

curl "$API/agents/conversations/{id}" -H "Authorization: Bearer $TOKEN"
# → { "version": 2, ... }

Then post the resume:

{
  "client_op_id": "7fb6795c-60a2-4cf9-a0db-0cc645279704",
  "expected_version": 2,
  "payload": {
    "kind": "tool_outputs",
    "outputs": [{
      "tool_use_id": "tooluse_DWXPKZ50JDGib5GmShyUgJ",
      "content": "User confirmed the proposed slot.",
      "is_error": false
    }]
  }
}

The model sees the tool result and continues; this run usually terminates completed after one iteration with a contextual final answer.

Idempotency

Re-sending the same body with the same client_op_id returns the original agent_runs row verbatim. Idempotency is on (conversation_id, client_op_id):

• Same client_op_id, same conversation → same run row returned, no new workflow started.
• Same client_op_id, different conversation → new run, new workflow.

Use a fresh UUID per logical request, never per retry of an in-flight request.

Common error responses

Permission

agent_conversations resource with write verb.