Browse documentation
Runs and turns
Understand durable runs, individual turns, sandboxes, and cancellation.
View MarkdownA run is the durable agent context. A turn is one accepted unit of work inside that run.
Ownership
| Object | Owns |
|---|---|
| Deployment | Immutable agent and sandbox configuration |
| Run | Pi session, workspace, active sandbox, and pinned deployment |
| Turn | One input, its execution state, output, and error |
| Sandbox | Replaceable compute for the run |
Turn states
| Status | Meaning |
|---|---|
queued | Accepted and waiting to start |
in_progress | Provider or tool execution is active |
cancelling | Cancellation is accepted and is settling |
completed | Work and required durability steps completed |
failed | Execution or required durability work failed |
cancelled | The turn was intentionally cancelled |
incomplete | Execution stopped without a complete result |
Run and turn states can differ
The run state reports whether the durable context can accept work. The turn status reports the selected unit of work.
For example, a cancelled turn can leave its run idle. The client can then
submit a new turn to the same run. A run can stay busy after one queued turn
is cancelled because another turn is still active.
Cancellation
Cancel current work:
POST /api/v1/runs/{runId}/cancelCancel a selected active or queued turn:
{
"turn_id": "turn_01J..."
}Cancellation:
- requests an abort for active provider and tool work;
- removes a selected queued turn;
- settles the turn lifecycle;
- stops active sandbox compute through run cleanup when required.
Deletion
Deletion is cleanup for an idle run. Do not use deletion as a substitute for cancellation of active work.