liveBook · Manning

Progress tracking

As explained in Designing AI Agents

A persistence pattern that records task state and completed work so an interrupted agent can resume execution.

Progress tracking preserves the state needed to resume bounded work after a reset, session break, or handoff. The orchestrator records the task’s current contract and the evidence accumulated against it, so the next worker can verify what remains instead of restarting. section 4.4

The central design question is what must survive a reset. A checkpoint is a recovery contract, not a prose recap or a record of private chain-of-thought. It can live in a file, database row, or framework checkpoint; its contents matter more than its container. section 4.4

A useful checkpoint records:

  • The bounded goal and acceptance condition, completed artifacts, and supporting evidence. section 4.4
  • Pending work, the next decision, authoritative versions, and unresolved conflicts. section 4.4
  • Executed side effects, their receipts and idempotency keys, and the condition for human handoff. section 4.4

Resuming after a reset

An agent edits files, runs a migration, and opens an external review. “Continue the migration” does not say which effects already occurred. Recovery needs artifact versions, verification results, the migration receipt, the review URL, and the next decision; otherwise, an accurate recap can still lead to a repeated effect. section 4.4.4

A fresh session can read a progress log, a JSON feature list, and version history, then verify them against the repository. The log identifies recent work and the next step; the feature list states acceptance items; version history provides reversible evidence of changes. Inspectable artifacts, rather than inherited context, make the handoff possible. section 4.4

Waiting for clarification

A diagram operation saves the requested action, diagram type, candidate locations, and current stage. When the user selects a location, the runtime resumes that operation rather than inferring the original request from the short answer alone. section 11.3.1

The pattern works best when artifacts and decision boundaries are inspectable and completed effects can be verified. It breaks when checkpoints omit acceptance evidence, authoritative versions, or the reason a decision was settled. Concurrent workers also need conflict detection when updating the same checkpoint. section 4.4.4

Measure recovery against a baseline: orientation tokens and latency, duplicated reads or edits, repeated external effects, checkpoint freshness, and the fraction of checkpoints that resume without reopening settled decisions. Report the workload and failure boundary alongside any improvement claim. For a single project, maintained files and version history may suffice; add a dedicated service when concurrency, cross-system recovery, or policy requires it. section 4.4 section 4.4.4

How Designing AI Agents covers it

How deep it goes
Specifies checkpoint contents, recovery verification, failure modes, and measurements without prescribing a particular storage format.
Examples
Uses a migration with an external review, a repository-based agent harness, and a diagram operation awaiting location clarification.
What you can do after
Operate and configure resumable workflows by recording checkpoints, verifying completed effects, and measuring recovery.
How it connects
Connects recovery state to write-ahead logs, distributed checkpointing, version history, and idempotency keys.

Also explained in

Compare how 2 books explain progress tracking →

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.