liveBook · Manning

Chapter 7: Reflection and evaluation: How your agent audits and learns from itself

What you will learn in chapter 7 of Designing AI Agents

The chapter introduction shows why useful fixes to individual agent failures need evaluation across runs to determine whether the system is improving.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The chapter introduction shows why useful fixes to individual agent failures need evaluation across runs to determine whether the system is improving.

Key terms: reflection, local checks, repairs, combined cost

7.1 What is reflection?

This section defines reflection as feedback that can change an agent’s behavior and introduces the questions that make such changes trustworthy.

Key terms: reflection, feedback, current task, later work, evidence, unit test

7.1.1 Why another pass is not enough

Explains why a second pass is not reliable reflection by itself and how grounded evidence and a distinct review perspective make critique more dependable.

Key terms: intrinsic self-correction, second pass, probabilistic generation, verification, focused regression test, tool-interactive feedback, evidence, Critic, Generator, review frame

7.2 Pattern: Generator-Critic

Introduces Generator-Critic as a separate review path for a current artifact, with explicit review criteria and bounded iteration.

Key terms: Generator, Critic, artifact, generate -> critique -> revise, criteria, evidence, permitted verdicts, stop policy, blind spot, Reflection × Chain

7.2.1 One artifact, a different line of inquiry

This section explains why Generator-Critic review must examine an artifact through a different line of inquiry, make claims only within its evidence, and return critique to improve that artifact.

Key terms: Generator, Critic, line of inquiry, cross-model review, feedback scope, domain reviewer, review scope, Generator-Critic, reflection pattern, Adversarial Review

7.2.2 Design the Critic before adding iterations

This section establishes the Critic contract as the priority, then explains how to bound review iterations and measure whether critique improves results.

Key terms: Critic contract, Critic, iteration, review budget, best known artifact, confirmed-issue precision, task quality, iterations to acceptance, oscillation rate, latency

7.2.3 Building Generator-Critic

This section outlines a Generator-Critic implementation that keeps critiques traceable to independent evidence and artifact versions, then selects the best version using domain evidence.

Key terms: review objects, evidence identifiers, verdict, Critic, review traversal, Critique, artifact version, bounded implementation, best-version preservation, select_best

7.2.4 When Generator-Critic breaks

This section identifies ways Generator-Critic review can fail and the safeguards that keep critique, revision, and evaluation trustworthy.

Key terms: Shared blind spot, Critique hallucination, Critic, Generator, Rubber-stamp acceptance, criterion-level findings, self-preference, position effects, Oscillation, issue and artifact signatures

7.3 Pattern: Self-Heal Loop

Introduces Self-Heal Loop as bounded, verifiable recovery from a failed task, with explicit limits on what repair may change.

Key terms: Self-Heal Loop, Reflection × Loop, rollback, handoff, recovery envelope, writable and protected state, baseline, verifier

7.3.1 Recovery requires permission and responsibility

This section defines what a Self-Heal Loop may repair, what it must verify, and when it must hand off or seek separate approval.

Key terms: Self-Heal Loop, authoritative domain knowledge, handoff, modification authority, rollback point, recovery envelope, verifier, acceptance criteria, protected tests, independent verifiers

7.3.2 The fail-diagnose-fix-verify loop

This section lays out a bounded recovery loop that uses failure evidence to propose repairs, applies only authorized changes, and verifies recovery efficiently.

Key terms: Capture, Diagnose, Propose, Decide, restorable baseline, declared writable scope, Check authority, Apply atomically, checkpoint, sandbox

7.3.3 Building Self-Heal Loop

This section shows how to build a Self-Heal Loop that keeps repair proposals within system-defined authority, restores failed attempts, detects lack of progress, and records a useful handoff.

Key terms: recovery policy, structured change, trusted workspace, authority check, allowed tool set, baseline, checkpoint, atomic application, verification, regression

7.3.4 When Self-Heal Loop breaks

This section identifies ways a Self-Heal Loop can fail and explains why safe recovery requires trustworthy verification, rollback, and measurement beyond the current task.

Key terms: missing oracle or knowledge, verifier, domain knowledge, verifier subversion, tests, acceptance criteria, whack-a-mole repair, failure signatures, regression results, rollback gap

7.4 Pattern: Skill Package

This section introduces Skill Package as a way to reuse successful procedures on later tasks, while distinguishing the package itself from the decisions that admit and route it.

Key terms: Skill Package, Reflection × Route, general solver, Skill, discovery metadata, SKILL.md, interface, dependencies, version, applicability contract

7.4.1 A successful run creates a candidate

A successful run can propose a reusable Skill, but an applicability contract and staged admission tests are needed before it joins the active library.

Key terms: successful trace, isolated benchmark, coexist, router, candidate, applicability contract, stable logical identity, version, isolated gate, coexistence gate

7.4.2 One active Skill or conditional coexistence

This section explains when to keep one active Skill, merge duplicates, or retain multiple Skills for different conditions.

Key terms: Skill, admission process, applicability contract, horizontal evaluation

7.4.3 Route in layers

Skill routing should use eligibility rules and task evidence before model judgment, rather than choosing a routing method by library size alone.

Key terms: Rules exclude, Evidence narrows, model interprets context, general solver, library size, model judgment, vector search, plausible matches

7.4.4 Building Skill Package

This section sketches how Skill Packages are represented, admitted with independent evidence, and routed through eligibility checks before selection.

Key terms: stable capability identity, current version, evidence, state, admission function, independent, isolated, coexistence, trial results, durable evidence identifier

7.4.5 Maintain the library from operating evidence

This section explains how to maintain a Skill library using operating evidence while keeping promotion and withdrawal subject to safeguards.

Key terms: trajectories, reflection job, admission path, operating record, hard filtering, selected version, Harness versions, processing cadence, portfolio review, weighted scores

7.4.6 When Skill Package breaks

This section identifies ways Skill Packages can fail and the evidence, maintenance, and authority boundaries that keep them reliable.

Key terms: candidate, isolated, coexistence, trial evidence, active library, routing ambiguity, applicability contracts, hard filters, evidence narrowing, abstention

7.5 Pattern: Experience Replay

This section introduces Experience Replay as a way to turn past execution into relevant, evidence-backed advice for later tasks without putting unverified lessons into live context.

Key terms: feedback clocks, execution traces, immediate label, Experience Replay, execution trajectories, Reflection × Hierarchy, scoped heuristics, raw traces, candidate lessons, replayable heuristics

7.5.1 From an execution trace to a replayable lesson

This section explains how execution traces become evidence-backed, context-specific lessons without becoming executable instructions.

Key terms: L0, raw trace, L1, candidate lesson, L2, replayable heuristic, conflicting experiences, applicability, conditions, Experience Replay

7.5.2 Feedback latency changes the admission test

The section explains how the timing and reliability of outcome evidence determine when an execution trace can support a replayable lesson.

Key terms: feedback latency, verifier result, trace, proxy, lesson, attribution, replay record, causal link, hypothesis, domain expert

7.5.3 Record, admit, and recall

This section explains how experience replay moves from recorded lessons to selective recall, with eligibility checks and outcome tracking.

Key terms: record, distill, validate, admit, recall, observe, preflight recall, targeted recovery recall, item budget, context cost

7.5.4 Building Experience Replay

This section shows how to represent, admit, recall, and evaluate lessons in Experience Replay without treating a successful outcome as proof of causation.

Key terms: raw evidence, candidate lessons, replayable lessons, versions, conflicts, admission, repeated-case rule, domain policy, causal path, task-family scope

7.5.5 When Experience Replay breaks

This section identifies five ways Experience Replay can fail and the boundaries that keep recalled lessons useful and safe.

Key terms: candidate leakage, replayable stores, superstitious learning, cross-task admission, context flooding, recall, hard scope filters, context budget, stale or conflicting advice, version constraints

7.6 Composing reflection patterns

This section shows how four reflection patterns can share evidence while keeping current-task changes, cross-task learning, and authority to change safeguards separate.

Key terms: Generator-Critic, Self-Heal Loop, Skill Package, Experience Replay, trace, admission path, protected evidence, writable path, regression-tested changes, human approval

7.6.1 A current-task coordinator

This section explains how a current-task coordinator decides whether to deliver or hand off an artifact after review and verification, while recording a trace for possible cross-run learning.

Key terms: accepted review, initial verification, recovered healing, handed off, review status, reviewed artifact, protected verifier, execution or state-only recovery, trace, Skill

7.7 Evaluation belongs beside the change

This section explains how to choose evaluation evidence that fits the question and the ways each reflection pattern can fail.

Key terms: evaluation evidence stack, signals, Generator-Critic, Self-Heal, Skill Package, Experience Replay

7.7.1 Build and protect the evaluation set

This section explains how to turn production failures into a trustworthy evaluation set and use protected evidence, hard gates, and cost measures to make release decisions.

Key terms: production traces, evaluation set, protected evidence, provenance, regression set, hard gates, aggregate scores, composite scores, promotion, invariant

7.8 Argus checkpoint: Reflection

This checkpoint summarizes how Argus uses reflection for feedback within a task, admits selected learning for later use, and records its reuse decisions.

Key terms: Generator-Critic, Self-Heal Loop, protected verifier, Skill candidate, capability admission, Experience candidate, replay admission, active Skills, replayable lessons, legal candidate set

7.9 Summary

7.10 References

This section lists sources for the chapter’s discussion of reflection and evaluation.

Where this is used later

Concepts explained in this chapter

← Chapter 6: Action: How your agent acts is where strategy meets consequences Chapter 8: Collaboration: When one agent is not enough →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.