Skip to main content
A run is one execution of an agent with a specific set of inputs. The API is run-centric: you start a run, receive a task_id, then observe state changes until the run reaches a terminal state.

​
Lifecycle

  1. Start — Your client sends an execute request with agent_id, inputs, and environment. The API returns task_id.
  2. Running — Nodes execute; the model may request tool calls.
  3. Paused for tools — Status such as awaiting_tool_calls. Your integration runs tool handlers and submits results so the run can continue.
  4. Terminal — completed (with final output), failed, cancelled, or similar.

​
Waiting for completion

The usual client experience (run_agent, CLI execute --wait) keeps a long-lived HTTP connection so the server can push status updates (SSE). That is the default path in Getting started. If you architect around HTTP callbacks instead (for example jobs that span hours or days), see Running agents and Webhooks.