liveBook · Manning

Fail-diagnose-fix-verify loop

As explained in Designing AI Agents

A process for recovering from a failure by capturing its context, diagnosing a cause, proposing and applying a repair, verifying the result, and deciding what to do next.

A fail-diagnose-fix-verify loop recovers a failed task through bounded diagnosis, repair, and verification. Each change is accepted only if protected checks pass without regression; otherwise it is rolled back. The loop retries within its budget or hands the task to an authorized person or process. section 7.3 section 7.3.2

Use the loop when failure is observable and a repair can be isolated, verified, and reversed. Before attempting a repair, define writable state and protected state, capture a restorable baseline, and keep the verifier outside the repair path. The agent must not be able to change the evidence that determines whether its repair succeeded. section 7.3 section 7.3.1

A recovery attempt follows a controlled sequence:

  • Capture the failure, relevant state, dependency versions, and a restorable baseline; diagnose a likely cause using the evidence and prior attempts. section 7.3.2
  • Propose a repair within writable scope. Reject or escalate changes that touch protected evidence, policy, credentials, or state outside the sandbox. section 7.3.2
  • Checkpoint and apply the change atomically. Run protected checks for the original failure and surrounding regressions; restore the checkpoint if application or verification fails. section 7.3.2 section 7.3.3
  • Return success, retry within budget, roll back, or hand off. Stop when progress stalls; the domain must define what counts as no progress. section 7.3.2 section 7.3.3
Figure 7.2 The Self-Heal Loop. The agent captures a baseline, diagnoses a failure, checks repair authority, applies a change atomically, verifies it, and either recovers, retries, rolls back, or hands off.

The flow maps the authority check and verification gates to recovery, retry, rollback, and handoff. section 7.3.1

Authority enforcement belongs to trusted infrastructure, not the proposing agent. Derive affected paths and tools from the structured change, check them against policy, and enforce the policy again during the write. A model critic can review a proposal, but the protected verifier decides whether recovery succeeded. section 7.3.3 section 7.3.2

Repairing a tool invocation

A tool rejects an argument removed in a newer version. Inside a sandbox, the agent inspects the current contract, revises the invocation, and runs the check again. If the failure instead requires authoritative domain knowledge the system lacks, repeated retries cannot supply it; request that knowledge or hand off. section 7.3.1

Order checks by cost: run applicable schema or format checks before linting, builds, and larger regression suites. Record diagnoses, exact changes, verifier results, versions, and the restored baseline for handoff. Measure recovery and regression rates, rollback success, attempts, cost, and handoffs; repeated repairs add latency and state complexity, and shared external state may be hard to restore. section 7.3.2 section 7.3.3 section 7.3 section 7.3.1

A successful local repair does not automatically justify a persistent rule. Shared rules and configuration changes begin as proposals for a separate cross-run process; consequential changes require appropriate approval. Without cross-run review, individually useful safeguards can accumulate and make the system slower or conflicted. section 7.3.1 section 7.0

How Designing AI Agents covers it

How deep it goes
Builds a policy-bounded recovery loop with checkpoints and verification, while leaving snapshot details and no-progress detection to the workspace and domain.
Examples
Uses a removed tool argument to illustrate sandboxed repair and accumulated safeguards to illustrate cross-run costs.
What you can do after
Builds a bounded recovery loop with authority checks, rollback, protected verification, and handoff.
How it connects
Connects recovery to test-driven development, automated remediation, transactional recovery, and Generator-Critic review.

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.