Orchestration

Orchestration decides when an agent runs and how to handle failures mid-run. You submit a run; the orchestrator schedules, retries, and reports on it.

What the orchestrator does

• Schedules the run onto available capacity.
• Wakes the harness when the next step is ready.
• Retries failed steps with back-off, idempotently.
• Cancels a run cleanly on request, releasing the sandbox and the resources it held.

Durability

Every step is appended to the session as an idempotent event, so the orchestrator can resume a run exactly where it left off after a network failure, tool timeout, or pod eviction. Retries don't produce duplicate effects.

Triggering a run

A single request creates a run. Two endpoints, picked by whether you want to pin a specific version:

# Run the agent's latest active version
curl -X POST https://api.levainlabs.com/api/v1/agents/$AGENT_ID/runs \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -d '{ "prompt": "Summarise the latest weekly report" }'

# Pin to a specific version (must be active — draft and archived
# versions are not runnable)
curl -X POST https://api.levainlabs.com/api/v1/agents/$AGENT_ID/versions/3/runs \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -d '{ "prompt": "Summarise the latest weekly report" }'

The response carries the freshly-created run_id and session_id. From there, poll GET /api/v1/runs/{run_id} for status transitions and GET /api/v1/sessions/{session_id}/events for the streaming event timeline (assistant messages and step-by-step status pulses).

To continue an existing conversation, post follow-up turns to POST /api/v1/sessions/{session_id}/messages — they ride the same recipe and version the session was dispatched with.

Cancelling a run

Cancellation is a session-level operation. To stop the run currently in flight, call POST /api/v1/sessions/{session_id}/cancel. The orchestrator stops scheduling new steps, drains the in-flight step, marks the run cancelled, and terminates the session. Earlier events stay readable on the session for inspection.