- Approval gates (
requires_approval) are declarative permission checks that fire before a runnable executes. Use them for irreversible actions: refunds, deploys, account deletions, outbound emails, anything that costs money or moves data. suspend()is a control-flow primitive a handler calls from the inside to ask the user for arbitrary input (a clarifying question, a picked option, a confirmation). Use it to build interaction tools likeask_userorconfirm.
resume={...}. They share the same durable rails (parent_id + tracing provider). The only real difference is when they pause and what they resume with.
requires_approval (gate) | suspend() (interaction) | |
|---|---|---|
| Intent | ”may I do this?" | "tell me / give me” |
| Pauses | before the handler runs | inside the handler |
| Handler ran? | no (zero code) | yes, up to the suspend() call (re-runs on resume) |
| Resumes with | bool / ApprovalResolution | arbitrary value |
| Applied | declaratively on any runnable (even ones you don’t own) | by calling suspend() in the handler |
| Event | ApprovalEvent | InteractionEvent |
| Cancel reason | approval_required | input_required |
resume={id: value} is the single channel for continuing any paused run. For an approval gate the value is a decision (True/False or an ApprovalResolution); for a suspend() call it’s the arbitrary value the handler asked for. A Cancel value works for either and aborts the whole run. The id-spaces are disjoint, so one resume dict can settle a mix of pending approvals and suspensions in a single call. Unrecognized ids are ignored with a warning.On this page group
- Approval gates —
requires_approval, resolutions, edit-on-approve, redaction, time limits, workflows - Suspend & interaction tools —
suspend(), writingask_user/ask_user_multi/confirm,InteractionEvent, response schemas - Resuming a paused run — cancel, durable cross-process resume, duplicate-worker protection, enumerating pending
- Client integration (HTTP) — the
/streamwire contract a frontend talks to - Observability — status reasons, usage counters, common patterns