Durable Agent patterns
Choose script or durable mode and design waits, subtasks, checkpoints, history, compensation, and data stages for replay.
Script and durable mode use the same seven Agent primitives. Script mode replays from the handler start; durable mode stores explicit serializable state and advances it through repeated step() calls. Choose the mode that makes workflow state easiest to understand, not the one that appears more capable.
The seven primitives
| Need | Primitive |
|---|---|
| Model reasoning | ctx.turn() |
| Read, page, branch, or truncate durable history | ctx.ledger.* |
| Durable result, checkpoint, or audit fact | ctx.commit() |
| Human or external decision | ctx.await() |
| Registered child work | ctx.spawn(subtask, input) |
| Partitioned volume | ctx.map() |
| Deterministic aggregation | ctx.reduce() |
Supporting boundaries
| Need | Runtime boundary |
|---|---|
| Governed external action | ctx.invoke() or ctx.invokeAsync() against a pinned Resource |
| Replay-safe local memoization | ctx.step(name, fn) |
| Bounded delegated authority | ctx.request() under Policy |
| Typed observation | ctx.analytics.emit() |
These operations do not add Agent-language words. Tools are model-facing Resource capabilities, while joins, retries, races, transcripts, planners, and ReAct are derived compositions over primitives and durable Handles.
Every handle has a stable id, resolution state, sequence, outcome, result, error, and cancellation method. Suspension is a runtime control transfer; rethrow it rather than catching it as an application error. Use JSON-schema-bound waits, explicit timeout behavior, and stable labels so operators can understand and safely resolve pending work.
Commits may select storage tier, require a gate, register compensation, deliver to another ledger, assert the expected head, or checkpoint prior history. Treat compensation as forward recovery: each registered task must be versioned, replayable, and honest about any world effect.
Runs pin the Agent deployment, Policies, Resources, Toolset, budgets, and accepted identity. Operator controls occur at safe points unless the requested control explicitly aborts work. Read The seven Agent primitives, Durable execution for API details, and Run operations for operational controls.