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, 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 caller-declared 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": "confirm_booking" },
  "config_override": { "max_iterations": 10 }
}

The model is forced to call confirm_booking on iteration 1. Since confirm_booking is a caller-declared tool (dash-free name, listed in tools[]), the run terminates with status: requires_action after one iteration; pending_tool_calls contains the model’s proposed arguments.

To pin an MCP-resolved tool instead, include the mcp_alias field:

"tool_choice": { "kind": "specific_tool", "mcp_alias": "docs", "name": "search_kb" }

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

Status	type slug	Cause	Recovery
400	/invalid-tool-alias	config_override.mcp_servers[] has a bad alias	Fix the alias
400	/tool-name-too-long	config_override introduced a wire name > 64 chars	Shorten alias or tool name
400	/unknown-tool-use-id	tool_outputs references an id not on the latest assistant turn	Refetch the prior run’s pending_tool_calls
400	/not-a-client-tool-call	tool_outputs references a server-resolved call	Filter to client-side ids only
400	/incomplete-tool-outputs	Missing or extra outputs[] entries	Match the pending set exactly
400	/no-assistant-turn	tool_outputs payload on a conversation with no assistant turn yet	Use user_message payload instead
404	/conversation-not-found	Conversation doesn’t exist, is in another company, or was created by a different user	Verify the id; conversations are scoped to the bearer-token’s (company_id, user_id)
409	/version-conflict	expected_version mismatch	Refetch the conversation, retry
500	/workflow-start-failed	Platform couldn’t reach the workflow engine	Retry with the same client_op_id

Permission

agent_conversations resource with write verb.