liveBook · Manning

Checkpointing

As explained in Designing AI Agents

The practice of recording execution state at checkpoints so a workflow can resume after interruption.

Checkpointing records enough execution state to resume bounded work after an interruption, context reset, session break, or handoff. For agent workflows, an activity recap is not enough: a fresh worker must be able to inspect what was completed, what remains, and which external effects already occurred. section 4.4 section 4.4.4

A useful checkpoint preserves:

  • The goal, acceptance condition, completed artifacts, and evidence that work is complete. section 4.4
  • Pending work, the next decision, authoritative versions, unresolved conflicts, and the condition for human handoff. section 4.4
  • Receipts and idempotency keys for executed effects, so recovery can distinguish intended actions from completed ones. section 4.4 section 4.4.2

The recovery contract matters more than the container: a checkpoint can be a file, database row, or framework-managed state. Record inspectable decisions and evidence, not private chain-of-thought. On resumption, verify the checkpoint against current artifacts before continuing. section 4.4

Resuming a long-running agent

A fresh session reads a progress log, a JSON feature list, and version-control history, then checks the repository state. The log identifies recent work and the next step; the feature list makes acceptance items explicit; version history provides reversible evidence of changes. section 4.4

Persistent graph checkpoints restore state at execution boundaries, not at the interrupted source line. A task that started but did not finish may run again. Checkpointing alone therefore does not guarantee exactly-once external effects; application code must handle their idempotency. section 6.4.3 section 4.4.2

Table 4.5 LangGraph persistence roles
LangGraph mechanism
 
Scope
 
Persistence note
 
InMemorySaver
Thread-scoped checkpoints
 
Process memory; does not survive restart
 
SqliteSaver
Thread-scoped local checkpoints
SQLite integration
PostgresSaver
Thread-scoped production checkpoints
PostgreSQL integration
Store
Information shared across threads
Separate store API and backing implementation

Compare thread-scoped LangGraph checkpoint backends with the separate store for information shared across threads; in-memory checkpoints do not survive a process restart. section 4.4.2

For a single-writer local workflow, a JSON checkpoint can be flushed to a temporary file and atomically replace the previous copy. Distributed workflows need stronger concurrency, migration, and recovery guarantees; concurrent checkpoint updates without conflict detection can break recovery. section 6.4.3 section 4.4.4

Rolling back a repair

Before applying a repair, snapshot the workspace. Apply the change atomically and run protected verification; restore the snapshot if application raises an error, verification fails, or a regression appears. A handoff can preserve the failure, attempted changes, verifier results, versions, and restored baseline. section 7.3.3

Listing 7.8 Applying and verifying one repair attempt
def apply_and_verify(workspace, proposal, policy):
    checkpoint = workspace.snapshot()
    try:
        workspace.apply_atomic(proposal.change, policy)
        report = workspace.verify_protected()
    except Exception:
        workspace.restore(checkpoint)
        raise
    if not report.passed or report.regressed:
        workspace.restore(checkpoint)
    return report, checkpoint

Inspect the snapshot, atomic application, verification, and restore sequence for one repair attempt. section 7.3.3

Checkpointing works best when artifacts and completed effects are inspectable. Measure checkpoint freshness and recovery fidelity alongside duplicated reads or edits, repeated external effects, and orientation time. Compare recovery against a baseline and report the workload and failure boundary. section 4.4 section 4.4.4

How Designing AI Agents covers it

How deep it goes
Details checkpoint contents, local persistence, recovery verification, replay risks, and repair rollback, while deferring stronger distributed-store guarantees.
Examples
Uses a progress log and JSON feature list, a local atomic checkpoint, and a workspace snapshot before repair.
What you can do after
Apply checkpointing to resumable workflows and rollback attempts while accounting for repeated tasks and external effects.
How it connects
Connects checkpointing to progress tracking, write-ahead logs, idempotency, version control, and verification.

Also explained in

Compare how 7 books explain checkpointing →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Agents. The section links point to the parts of the book it draws on.