Agents → Loop-back / reflection (critic, verifier, replanning)
What it is
Reflection is the agent asking "is this actually right?" before delivering, and doing something about the answer. Three distinct patterns often lumped together:
| Pattern | Trigger | Action | Bound |
|---|---|---|---|
| Self-critique | After producing output | Model reviews its own work against criteria, revises | 1–2 rounds |
| Separate critic | After producing output | A different call (often a different model or a checklist-driven prompt) evaluates and returns structured feedback | 1–2 rounds |
| Replanning | A step failed or produced unexpected results | Revise the plan, not the output | 1–2 replans |
Plus the humblest and most valuable: retry-on-tool-error, where the error text goes back to the model (single agent loop).
The critical property is bounded. Reflection loops have three failure modes: oscillation (the critic asks for A, the reviser produces B, the critic asks for A again), diminishing returns (round 3 changes nothing), and cost explosion (each round is a full generation plus a full critique). A separate critic with explicit, checkable criteria and a hard cap of 1–2 rounds captures most of the value.
How to implement
- Define checkable criteria — not "is this good" but a rubric: schema valid, all parts addressed, every claim cited, no contradictions, within length, tone matches. Machine-check what you can before spending an LLM call.
- Separate critic call with the criteria, the original task, and the output; returns
{pass: bool, issues: [{criterion, problem, suggested_fix}], severity}. - Revise once with the issues named explicitly in the prompt; re-run only the failed criteria on the second check.
- Hard cap:
max_reflection_rounds = 1or2. On still-failing, deliver the best version with a caveat, escalate to a stronger model (routing & escalation), or hand to a human (human-in-the-loop) — but stop. - Detect oscillation: hash the output each round; if it repeats or alternates, stop immediately.
- Replanning path: when a step fails deterministically, revise the plan (task decomposition) rather than retrying the same step; bound replans separately.
- Log every round: what the critic flagged, what changed, whether quality actually improved.
Small example
CRITIC_SYS = """You review an assistant's output against explicit criteria. Be specific and terse.
Criteria:
1. Every factual claim has at least one citation id.
2. Every part of the user's question is addressed, or explicitly marked as not answerable.
3. No claim contradicts another claim in the output.
4. Output matches the required JSON schema.
5. No content is invented beyond the provided context.
Output JSON: {"pass": bool, "issues": [{"criterion": int, "problem": string, "fix": string}], "severity": "low"|"high"}
If it passes, return {"pass": true, "issues": []}. Do not rewrite the output yourself."""
def machine_checks(output, retrieved, question) -> list[dict]:
"""Free checks first — never pay for an LLM critique of something code can verify."""
issues = []
valid = {c["chunk_id"] for c in retrieved}
for cl in output.get("claims", []):
if not cl.get("citations"): issues.append({"criterion": 1, "problem": f"uncited: {cl['text'][:60]}", "fix": "cite or remove"})
for cid in cl.get("citations", []):
if cid not in valid: issues.append({"criterion": 1, "problem": f"invalid citation {cid}", "fix": "cite a provided passage"})
if not output.get("answer"): issues.append({"criterion": 4, "problem": "empty answer", "fix": "produce an answer"})
return issues
def reflect(question, retrieved, produce_fn, max_rounds=2, budget=None):
seen_hashes, output, all_issues = set(), produce_fn(), []
for rnd in range(max_rounds):
h = hash_output(output)
if h in seen_hashes:
log_reflection("oscillation_detected", rnd); break # stop immediately
seen_hashes.add(h)
issues = machine_checks(output, retrieved, question)
if not issues:
critique = json.loads(llm("critic", CRITIC_SYS, [{"role": "user", "content":
f"<question>{question}</question><context>{render(retrieved)}</context>"
f"<output>{json.dumps(output)}</output>"}], max_tokens=600).text)
if critique["pass"]:
log_reflection("passed", rnd); return output
issues = critique["issues"]
all_issues.append(issues)
log_reflection("revising", rnd, n_issues=len(issues))
if budget: budget.check()
output = produce_fn(revision_feedback=issues, previous=output) # revise with issues named
log_reflection("max_rounds_reached", max_rounds, unresolved=len(issues))
return output | {"quality_caveat": [i["problem"] for i in issues], "reflection_rounds": max_rounds}
def replan_on_failure(plan, failed_step, error, max_replans=1, attempt=0):
if attempt >= max_replans:
return {"status": "abandoned", "reason": f"{failed_step} failed: {error}"}
revised = json.loads(llm("replan", REPLAN_SYS, [{"role": "user", "content":
f"<plan>{plan.model_dump_json()}</plan><failed_step>{failed_step}</failed_step><error>{error}</error>"
"Revise the plan to work around this failure, or state that the goal cannot be achieved."}]).text)
if not revised.get("achievable"):
return {"status": "abandoned", "reason": revised.get("reason")}
return {"status": "replanned", "plan": Plan.model_validate(revised["plan"]), "attempt": attempt + 1}
Pros
- Measurable quality gains on structured tasks with checkable criteria — citations, completeness, schema adherence.
- Catches the specific failures you care about when criteria are explicit.
- Retry-on-tool-error is nearly free and dramatically improves robustness (single agent loop).
- Replanning rescues runs that would otherwise fail entirely.
- The critic's issue list is excellent triage data (feedback capture & triage).
Cons
- Cost doubles or triples per reflected response.
- Oscillation and diminishing returns are real; round 3 rarely helps.
- Self-critique is weak: a model that made an error often can't see it. A separate call with explicit criteria is meaningfully better; a different model better still.
- Vague criteria produce vague critiques ("could be clearer") that cause churn without improvement.
- Latency: each round is a full generation.
- Can make outputs worse — over-revision toward hedging and verbosity.
When to use
- Structured outputs with checkable criteria: reports, extractions, code, citations, compliance checks.
- High-stakes, low-volume outputs where doubling cost is acceptable.
- Agent runs where a failed step has an obvious alternative path (replanning).
- Always for tool errors — that one is free.
When NOT to use
- High-volume, low-stakes generation — the cost multiplier isn't justified.
- When criteria can't be made explicit — you'll get churn, not improvement.
- Latency-critical paths.
- As a substitute for fixing the primary prompt: if reflection fires on 60% of outputs, fix the generator (prompt versioning & evaluation).
Production at scale
Machine checks before model checks, always. Schema validity, citation existence, required-field presence, length, forbidden phrases — all free and deterministic. Only pay for an LLM critique on what code cannot verify. This ordering typically eliminates half the critique calls.
A separate critic beats self-critique, and a critic with a checklist beats a critic with a vibe. Where budget allows, use a different model for the critique — different failure modes catch more.
Cap at one round for most paths, two for high stakes. Measure the marginal gain per round on your golden set; almost always round 1 captures the majority and round 3 captures nothing.
Oscillation detection is mandatory: hash outputs, stop on repeats. Also track "issues unchanged between rounds" — a critic repeating the same complaint means the reviser can't fix it, and more rounds won't help.
Reflection rate is a health metric. If the critic rejects 50% of first attempts, the generator prompt needs work — reflection is masking a fixable problem at 2× the cost (feedback capture & triage).
Budget interaction: reflection rounds consume the run budget (cost & step budgets). A reflection loop inside an agent loop inside a fan-out is how a $0.05 task becomes $3. Cap reflection at the run level, not just per output.
Never deliver silently degraded output. When rounds are exhausted with issues remaining, attach the caveat and log it — the same visible-failure principle as everywhere else (bounded escalation with visible failure, refusal / no-answer path).
Evaluate the critic itself (LLM-as-judge): does its pass verdict correlate with human judgement? A critic that passes bad output is worse than no critic, because it manufactures confidence.
Prod checklist
- Explicit, checkable criteria; machine checks run before any LLM critique
- Separate critic call (ideally a different model), returning structured issues
- Hard cap of 1–2 rounds, enforced in code; counted against the run budget
- Oscillation detection (output hashing) and unchanged-issues detection
- Revision prompt names the specific issues; only failed criteria re-checked
- Exhausted rounds → deliver with caveat / escalate tier / human, never silent
- Replanning bounded separately from output reflection
- Reflection rate monitored as a generator-quality signal
- Critic verdicts calibrated against human labels
Metrics to watch
| Metric | Why |
|---|---|
| Reflection trigger rate | Generator quality (high = fix the prompt) |
| Quality gain per round (golden set) | Whether rounds earn their cost |
| Oscillation / unchanged-issue rate | Loop health |
| Cost multiplier from reflection | Budget impact |
| Critic verdict vs human judgement | Whether the critic works |
Related
- Agent loop — retry-on-tool-error
- Task decomposition — replanning revises the plan
- Faithfulness — a specialised, cheap verifier
- Budgets — reflection consumes them
- LLM-as-judge — evaluating the critic