What is Checkpointing?
Also called state persistence, durable execution.
Checkpointing is the practice of persisting an agent's state at defined points during a run so that execution can resume from the last saved point after an interruption, rather than restarting from the beginning. It underpins long running agents, human approval pauses, and recovery from process crashes or deployments.
Without checkpoints, an interruption discards everything. A run that made forty tool calls before a process restart has to repeat all forty, paying the cost again and, worse, repeating any side effects those calls produced. Checkpointing converts a long run from a single fragile operation into a sequence of durable steps.
A useful checkpoint holds enough to resume: conversation or step history, working state and variables, the position in the plan or graph, and pending tool calls. It should not hold live connections, open file handles, or credentials, all of which must be reacquired on resume. What is deliberately excluded matters as much as what is saved.
Checkpointing pairs with idempotency. Resuming near a tool call that may already have executed risks performing it twice, which is harmless for a read and serious for a payment or a message. Recording the outcome of each side effecting call before checkpointing, and keying such calls so repeats are detected, is what makes resume safe.
Checkpoints also enable pausing by design rather than only recovery. An agent that reaches an approval gate can checkpoint and stop consuming resources, then resume hours later when a person responds. Long lived work that waits on external events is impractical without this, since holding a process open for hours is both fragile and wasteful.
Key points
- Persists state so runs resume instead of restarting
- Save history, working state, and position, not live handles
- Requires idempotent side effects to resume safely
- Enables pausing for approval without holding a process
- Frequency trades storage and latency against lost work
In practice
A migration agent processing 5,000 records checkpoints after each batch of 100, recording which batches completed. A deployment restarts the worker at record 3,200. On resume it reads the last checkpoint, sees batches through 3,200 are done, and continues from 3,201 rather than reprocessing everything, and the already migrated records are not touched a second time.