Runs

A run is one execution of the graph within a session. These endpoints list and read runs, start runs either attached to the original streaming request or detached in the background, cancel visible runs, and open live Server-Sent Events streams to active runs.

POST /v1/runs starts an attached run and streams events on the same response. If that response is dropped before the run finishes, the run is cancelled. POST /v1/runs/start starts a detached run and returns its IDs immediately; the run continues after the response is sent. Use GET /v1/runs/{run_id}/events to observe live events from a running run, and PUT /v1/runs/{run_id}/cancel to explicitly cancel a visible run.

Find runs for a session

Find runs for a session with optional filtering and pagination.

Get a run by ID

Get a run by ID.

Create a new run

Create a new attached run and stream its events back as Server-Sent Events (SSE).

curl -X POST http://localhost:8080/v1/runs \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: acme" \
  -d '{
    "session_id": "8f3e19d8-3bc0-4fd5-bb02-7ac89af9d7bc",
    "model": {
      "override": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-6",
        "inference_params": {
          "max_tokens": 4096
        }
      },
      "timeout": 30000,
      "retry": {
        "max_attempts": 3,
        "initial_backoff": 250,
        "max_backoff": 5000
      }
    },
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "value": "What is 42 plus 7?" }
        ]
      }
    ]
  }'

The stream keeps the connection alive with periodic keep-alive comments between events. Closing the connection before the run finishes cancels the attached run. A full run looks like this on the wire:

event: run_started
data: {"kind":"run_started","timestamp":1710000000.0,"session_id":"...","run_id":"..."}

event: messages_snapshot
data: {"kind":"messages_snapshot","timestamp":1710000000.1,"messages":[...]}

event: text_message_start
data: {"kind":"text_message_start","timestamp":1710000000.2,"message_id":"..."}

event: text_message_content
data: {"kind":"text_message_content","timestamp":1710000000.3,"message_id":"...","delta":"Hello"}

event: text_message_end
data: {"kind":"text_message_end","timestamp":1710000000.4,"message_id":"..."}

event: run_finished
data: {"kind":"run_finished","timestamp":1710000000.5,"session_id":"...","run_id":"...","status":"completed","interrupt_payload":null,"result":null}

Start a detached run

Start a new run and return immediately with its IDs instead of keeping a streaming response open.

The request body accepts the same fields as POST /v1/runs. The run continues on the server after the HTTP response is returned. Dropping this request's connection after the response has been sent does not cancel the run.

curl -X POST http://localhost:8080/v1/runs/start \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: acme" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "value": "What is 42 plus 7?" }
        ]
      }
    ]
  }'

The response body contains the IDs to use for later lookup, cancellation, or live reattachment:

{
  "run_id": "f7b97459-06a7-4e01-bb91-b8072d40452f",
  "session_id": "8f3e19d8-3bc0-4fd5-bb02-7ac89af9d7bc"
}

Cancel a run

Cancel a visible run by ID.

Cancellation is idempotent for a run that exists in the caller's tenant. The endpoint returns 204 No Content whether the call transitions a running run to cancelled or the run was already in a terminal state. A run that does not exist and a run that belongs to another tenant both return 404.

curl -X PUT -o /dev/null -w "%{http_code}\n" \
  http://localhost:8080/v1/runs/f7b97459-06a7-4e01-bb91-b8072d40452f/cancel \
  -H "X-Tenant-ID: acme"

Reattach to run events

Open a live Server-Sent Events stream to a run that is currently running.

Reattachment is live-only. The stream receives events produced after the request attaches; it does not replay events that were produced earlier. Dropping this stream closes only this observer and does not cancel the run. Use PUT /v1/runs/{run_id}/cancel when the client wants to stop the run.

curl -N http://localhost:8080/v1/runs/f7b97459-06a7-4e01-bb91-b8072d40452f/events \
  -H "X-Tenant-ID: acme"

Only runs with status running can be reattached to. A visible run that has already completed, failed, interrupted, or been cancelled returns 409. A missing run, or a run owned by another tenant, returns 404.

Reattach across replicas

Reattach uses pub/sub to deliver live run events to GET /v1/runs/{run_id}/events streams. By default, generated standalone agents use an in-memory transport with no external service:

export AGENT__PUBSUB__KIND=memory
export AGENT__PUBSUB__CAPACITY=4096

The in-memory transport is process-local. If a deployment has multiple replicas and a reattach request may land on a different process than the one executing the run, configure the Redis-compatible transport:

export AGENT__PUBSUB__KIND=redis
export AGENT__PUBSUB__URL=redis://localhost:6379

Dragonfly can provide that Redis-compatible pub/sub service:

services:
  dragonfly:
    image: docker.dragonflydb.io/dragonflydb/dragonfly
    ulimits:
      memlock: -1
    ports:
      - 6379:6379

Pub/sub carries live events only. It does not store run history or replay missed events. Cancelling a run is persisted through the shared database and does not depend on pub/sub.

Types

ContextVar

A single client-supplied context variable made available to a run.

ToolDefinition

A client-defined tool made available to a run.

InferenceParams

Inference parameters for a model request. Every field is optional; omitted fields use the provider or model defaults.

ModelConfig

Per-run model call configuration. Timeout and retry values supplied here take precedence over manifest and startup defaults independently. Omitted values continue to use the corresponding startup defaults. The override object controls model selection and inference parameters only for this run.

AG-UI clients can supply the same object through forwarded_props.model. It is interpreted by the ReAct adapter and does not add fields to the AG-UI protocol itself.

ModelConfigOverride

Per-run overrides for the agent's configured model. Any omitted field falls back to the manifest configuration.

ModelConfigRetry

Retry policy for transient failures before the model response stream is established. A response stream that has already started is not retried.

CapabilityOverride

Per-run override for the agent's capability set. The strategy field selects how the supplied capabilities combine with the agent's configured capabilities.

PatchOperation

A single RFC 6902 JSON Patch operation, discriminated by op. State deltas and tool activity updates are expressed as arrays of these operations.