Mental model
A checkpoint is a versioned recovery boundary containing durable state, completed effects, pending intent, budgets, and the code or policy version needed to interpret it.
Learning outcomes
- Explain the mechanism and ownership boundaries behind Agent State Checkpointing.
- Compare the main design alternatives and their operational trade-offs.
- Diagnose common failures and select evidence for a production decision.
Theory
Checkpoint only deterministic orchestration state and references to large evidence. Record which external actions committed, use monotonic sequence numbers, and make resume validate schema, policy, credentials, and environment freshness before continuing.
Trade-offs
Frequent checkpoints reduce replay work but increase storage, coordination, and privacy surface. Sparse checkpoints are cheaper but make recovery slower and can repeat expensive reasoning.
Failure modes and misconceptions
Saving prompts without tool effects; resuming under incompatible policy; storing secrets; treating cached model text as authoritative state; and allowing two workers to resume one checkpoint.
Decision scenario
A long-running research agent restarts after completing three external writes. Define the checkpoint fields needed to resume without repeating them.
Why must a checkpoint record committed external effects separately from the model conversation?
Primary sources
anthropic-context-engineeringw3c-prov-overview