Sessions and runs

Sessions

Create a session with agent_slug or deployment_id.

The session stays pinned to its selected deployment snapshot.

deployment_source	Meaning
`published`	The slug selected the active deployment, or the newest published deployment when none is active.
`legacy`	Pantheon used a legacy deployment snapshot.

Sandbox status

Value	Meaning
`ready`	The sandbox is available.
`stopped`	The sandbox exists but is stopped.
`missing`	The recorded sandbox no longer exists.
`none`	This session does not require a sandbox.
`unknown`	Pantheon could not determine availability.

Runs

Start one run at a time. Stream until the run becomes terminal or waits for input.

Value	Meaning
`queued`	The run is waiting for a worker.
`running`	The agent is processing the turn.
`waiting_for_input`	The run needs an application tool result.
`completed`	The run finished successfully.
`failed`	The run stopped with an error.
`cancelled`	A client cancelled the run.
`expired`	The run passed its wait deadline.

Recover from SESSION_BUSY

A second run returns HTTP 409 with SESSION_BUSY.

JSON response

{
  "error": {
    "code": "SESSION_BUSY",
    "message": "Session 'session_123' has an active run 'run_123' in status 'waiting_for_input'.",
    "request_id": "request_123",
    "active_run_id": "run_123",
    "active_run_status": "waiting_for_input",
    "recovery": [
      "cancel the active run via POST /v1/sessions/session_123/runs/run_123/cancel",
      "or resume it via POST /v1/sessions/session_123/runs/run_123/resume"
    ]
  }
}

Resume the active run when it waits for a tool. Otherwise wait or cancel it.

Terminal

curl -sS -X POST \
  "$PANTHEON_BASE_URL/v1/sessions/$SESSION_ID/runs/$ACTIVE_RUN_ID/cancel" \
  -H "Authorization: Bearer $PANTHEON_API_KEY"

Archive a session

Archive finished sessions. Pantheon then destroys the attached sandbox.

Terminal

curl -sS -X POST "$PANTHEON_BASE_URL/v1/sessions/$SESSION_ID/archive" \
  -H "Authorization: Bearer $PANTHEON_API_KEY"

Publish updates

Update the agent

Changing an agent creates a new version.

Publish again

Create a deployment for that version and its tool definitions.

Create a session

New slug sessions select the active deployment, or the newest published deployment when none is active. Existing sessions stay pinned.

Roll back a deployment

Send POST to /v1/deployments/{id}/activate with the earlier published deployment id.

This makes that deployment active for new sessions created by agent slug. Existing pinned sessions stay unchanged.

Only published deployments can be activated. Legacy snapshots return HTTP 409.

An active deployment takes precedence over newer publications until you activate another deployment.

Use agent_id to filter GET /v1/deployments.

Each returned deployment includes an active boolean. Activation returns the deployment with this flag set to true.

Pitfalls

Session creation can take about 2.5 seconds: Sandbox provisioning happens during creation when required.
Run creation can take about 2.7 seconds: Show a pending state before streaming begins.
Pantheon recreates a missing sandbox: Treat sandbox.recreated as data loss for unpublished workspace files.