Concepts
How turns end
Distinguish completed, incomplete, failed, and cancelled Turns, and understand waiting and budget holds.
Turn status is the authoritative lifecycle:
| Status | Meaning |
|---|---|
queued | Accepted and waiting for an execution attempt |
running | The model-and-tool loop is active |
waiting | A host tool result is required; no worker is held |
budget_hold | A resumable consumption limit or credit check stopped progress |
completed | The model finished, or an interrupt ended work at a clean boundary |
incomplete | A configured limit ended work cleanly; partial output is valid |
failed | Work could not end cleanly; inspect error |
cancelled | The caller discarded unfinished work |
completed, incomplete, failed, and cancelled are final. Prefer the SDK's
isTerminalTurnStatus() or the stream event's terminal signal to maintaining
your own status list.
Interrupt and cancel mean different things
Interrupt asks a running Turn to stop at the next clean boundary. The Turn ends
completed with stopReason: "interrupted", and valid work can carry into a
Conversation's next Turn.
Cancel settles the Turn as cancelled and excludes unfinished work from later
Conversation context. Use it when the work is no longer wanted.
Waiting and budget holds are not terminal
Submit required host-tool results to move a waiting Turn back to queued.
Increase an allowed limit or add credits to release a budget_hold. Deadlines
pause while a Turn is on budget hold.
Read the final result instead of treating a closed network connection as the outcome.