Agent checkpointing

On this page 7

Agent checkpointing is the practice of persisting a complete snapshot of an agent’s state at defined points during execution, so that the run can later be resumed, rewound, inspected or forked. In the field of AI agents, a checkpoint typically captures the conversation history, working memory, pending tool calls and position in the workflow graph, which together are enough to reconstruct the agent exactly as it was.

Checkpointing matters most for long-running agents that execute dozens or hundreds of steps, call external tools and wait for human approval. Without it, a crash, timeout or deployment restart forces the agent to start over, repeating expensive model calls and, worse, repeating actions that have already changed the outside world.

What an agent checkpoint contains

An agent checkpoint contains every piece of state needed to continue the run deterministically from the saved point. In graph-based agent frameworks, the checkpoint is written after each node or super-step and is keyed by a thread identifier and a monotonically increasing checkpoint identifier, so the full history of a run becomes a sequence of snapshots.

The table below lists the usual components of a checkpoint and why each one is required.

ComponentWhat it holdsWhy it is needed
Message historyUser, model and tool messages so farRebuilds the model context
Agent state objectStructured variables, plans, scratchpadRestores working memory
Execution positionCurrent node and next scheduled stepsResumes at the correct step
Pending tool callsRequested calls and their completion statusPrevents duplicate side effects
Interrupt dataQuestions awaiting human inputSupports approval pauses
MetadataTimestamps, model version, parent checkpointEnables audit and forking
Typical components of an agent checkpoint

Checkpoints should not store secrets such as API keys or session tokens. Credentials are reattached at resume time from a secure store, because checkpoint databases are often retained for weeks and read by debugging tools.

How checkpointing enables resume, rewind and fork

Checkpointing turns a linear agent run into a navigable history. Because each snapshot records its parent, an operator or the system itself can return to any earlier point and continue from there with different input, a different model or a corrected tool result.

OperationWhat happensTypical use
ResumeLoad the latest checkpoint and continueRecovery after a crash or restart
Human-in-the-loop pauseStop at an interrupt, wait, then continueApproval of payments or deployments
RewindReload an earlier checkpointUndo a wrong plan or bad tool output
ForkBranch a new thread from an old checkpointCompare alternative strategies
ReplayRe-run recorded steps for inspectionDebugging and agent evaluation
Operations that a checkpoint history supports

The human-in-the-loop pause is the most common production use. An agent that needs approval can stop for hours or days without holding a process in memory, since its full state sits in durable storage until a reviewer responds.

Checkpointing compared with agent memory and logging

Agent checkpointing is often confused with agent memory and with observability traces, but each serves a different purpose and lifetime. Checkpoints are exact, short-to-medium-term execution state; memory is curated knowledge carried across sessions; traces are records for humans that cannot be loaded back into a running agent.

MechanismScopeRestorable into a runPrimary purpose
Agent checkpointingOne thread or taskYes, exactlyFault tolerance and pauses
Agent memoryAcross sessions and tasksPartially, as retrieved contextLong-term personalization
Agent observability tracesOne run, read-onlyNoMonitoring and debugging
Context compactionWithin one context windowNot applicableReduce token usage
Checkpointing and related state mechanisms

The distinction has practical consequences. Restoring an agent from a trace is not possible because traces usually omit internal state and truncate large payloads, while restoring from memory yields a new run informed by the past rather than a continuation of the old one.

Designing a reliable checkpointing strategy

A reliable checkpointing strategy balances recovery granularity against storage and latency cost. Writing a checkpoint after every step gives the finest recovery but adds a database write to each step; writing only at milestones is cheaper but loses more work on failure.

  • Checkpoint before and after every side-effecting tool call, so the system knows whether an action completed.
  • Use idempotency keys for external actions such as payments or emails, so a retried step cannot execute twice.
  • Store state in durable backends, such as PostgreSQL or a managed key-value store, rather than process memory.
  • Version the state schema, because a code change can make old checkpoints unreadable.
  • Set retention limits, for example 7 to 30 days for completed threads, to control storage and privacy exposure.

The decision table below matches checkpoint frequency to typical workloads.

WorkloadRecommended frequencyReason
Short chat agent under one minuteEnd of each turnLow failure cost, minimal overhead
Coding agent running for hoursAfter every tool callExpensive steps, frequent restarts
Workflow with approval gatesAt every interrupt and tool callLong waits require durable pauses
High-volume batch agentsAt milestones onlyStorage and write cost dominate
Choosing checkpoint frequency

Limitations and common mistakes

Checkpointing restores the agent, not the external world. If an agent created a file, sent a message or modified a database before a rewind, those effects remain, and the restored agent may act on a reality that no longer matches its saved state. Compensating actions or sandboxed environments are required when true rollback is needed.

A second limitation is non-determinism of language models. Resuming from a checkpoint guarantees identical inputs, but the next model call can still produce a different output unless sampling is fixed and the same model version is available. Teams that rely on replay for evaluation therefore record model outputs, not only inputs.

  • Checkpointing only messages and forgetting structured state, which breaks resumption of planners.
  • Saving after a tool call but not before, which hides whether an interrupted action executed.
  • Unbounded checkpoint growth in long threads, which slows loading; compaction or pruning is needed.
  • Storing personal data indefinitely, which conflicts with data protection obligations.

Stripped to the essentials

Agent checkpointing works like saving a game. An AI agent that works through a long task stores a snapshot of where it is, what it knows and what it was about to do. If something breaks, it loads the last save instead of starting over.

The same saves let a person pause the agent to approve a step, or go back to an earlier point and try a different path. One thing a save cannot do is undo real-world actions, meaning what the agent already did in the real world, such as an email that was already sent.

Where it is applied

A software team runs a coding agent that migrates a codebase of about 400 files to a new framework version. A full run takes roughly four hours and several hundred model and tool calls. The agent writes a checkpoint after every tool call to a PostgreSQL database, keyed by a thread identifier for each migration task.

Halfway through, a container restart during a routine deployment kills the process. Instead of losing two hours of work, the orchestrator resumes from the last checkpoint within seconds, sees that one test command was requested but not confirmed, and safely runs it again. Later, a reviewer notices that the agent chose a poor refactoring pattern at step 140, rewinds to that checkpoint, adds a corrective instruction and forks a new branch. The team estimates that checkpointing cut wasted compute on failed runs by more than half.