1Why is the first answer rarely the best one?
A model writing in one pass cannot step back from its own text. Reflection separates writing from judging: one agent drafts, another scores the draft against explicit criteria, and the draft is rewritten until it passes.
You may need it if
- First drafts are usable but need the same manual corrections every time.
- You can say what "good" looks like as a short list of criteria.
- Quality matters more than answering within a second.
2When is a review loop wasted effort?
Use it when
- The result is a text or code artifact that a reader can judge on its own.
- You can write three to six criteria that separate a good result from a weak one.
- A wrong or clumsy result costs more than a few extra model calls.
Avoid it when
- The answer depends on facts the model does not have. A critic cannot invent missing evidence.
Use Corrective RAG instead - Correctness can be checked by running something, such as tests or a calculation.
Use Plan–Execute–Verify instead - Users wait for the reply in a live conversation and a good-enough answer is acceptable.
What it costs
- Model calls
- 1 + 2 × rounds (typically 3 to 7)
- Latency
- medium
- Complexity
- low
3How does a draft move through the loop?
The generator writes a draft. The critic scores it against the criteria and lists concrete defects. A fixed bar decides: rewrite with the critique attached, or release. A round limit guarantees the loop ends.
- Step 1 of 5
A draft is written
The generator answers the task in one pass, exactly as a single prompt would. Nothing is special yet.
- Step 2 of 5
The critic judges it cold
The critic receives only the task, the criteria and the draft. It lists defects first, then gives a score per criterion.
- Step 3 of 5
The bar decides
A plain rule, not a model, compares the score with the target. This keeps the stopping decision predictable and cheap.
- Step 4 of 5
Rewrite with the critique
Below the target, the draft returns to the generator together with the defect list. The generator fixes those defects and nothing else.
- Step 5 of 5
Release
Once the target is met, or the round limit is reached, the latest draft leaves with its score so a reader knows how far it got.
What each part does
- Task
- The request, or an existing draft to improve, plus the quality criteria.
- Generator
- Writes the first draft, then rewrites it using the latest critique.
- Critic
- Scores the draft against each criterion and lists specific defects.
- Good enough?
- Compares the score with the target and counts the rounds used.
- Refined result
- The last draft, with its final score and the critique history.
- Generator → Critic: draft
- Critic → Good enough?: score and defects
- Good enough? → Generator: below target, rounds left
- Good enough? → Refined result: target met or rounds spent
Where it connects
A request to fulfil, or an existing result to improve. Quality criteria are optional, the stage writes them when absent.
When: The score reaches the target, or the round limit is spent.
The final version, its score per criterion, and whether the target was met.
4What do I ask my assistant to set up?
The agents to launch
Generator
Produce the best result you can for the task. When you receive a critique, fix every listed defect and change nothing else. Return only the result.
Sees: The task, the criteria, and from round two the previous draft with its critique.
Critic
Judge the draft against each criterion. First list concrete defects with the passage concerned. Then give a score from 1 to 10 per criterion. Do not rewrite the draft and do not praise it.
Sees: The task, the criteria and the current draft only. Never the generator's reasoning or earlier scores.
A prompt you can paste
Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.
You are the orchestrator of a multi-agent workflow that follows the "Reflection" architecture. Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it. # Task [Describe your task here] # Reflection Draft, criticise, rewrite, until the work clears the bar. Input: the task above. It must provide: A request to fulfil, or an existing result to improve. Quality criteria are optional, the stage writes them when absent. If something essential is missing, ask for it before starting. Agents to launch: - Generator: Produce the best result you can for the task. When you receive a critique, fix every listed defect and change nothing else. Return only the result. Context for this agent: The task, the criteria, and from round two the previous draft with its critique. - Critic: Judge the draft against each criterion. First list concrete defects with the passage concerned. Then give a score from 1 to 10 per criterion. Do not rewrite the draft and do not praise it. Context for this agent: The task, the criteria and the current draft only. Never the generator's reasoning or earlier scores. Procedure: 1. Restate the task and write three to six quality criteria. If the input already contains a draft, use it as the first draft. 2. Launch the generator to produce a draft. 3. Launch the critic in a fresh context on that draft. 4. Compute the lowest criterion score. If it is below 8 and fewer than 3 rounds were used, send the draft and the defect list back to the generator and repeat from the critic step. Stop rule: Stop when every criterion scores 8 or more, or after 3 rounds, whichever comes first. Exit: - `refined`, when: The score reaches the target, or the round limit is spent. Deliver: The final version, its score per criterion, and whether the target was met. # Final deliverable The final result, the score per criterion for each round, and one line stating whether the target was met.
The same thing in code
from typing import TypedDict
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel
CRITERIA = ["Answers every part of the task", "Each claim is specific", "Clear structure, no filler"]
TARGET, MAX_ROUNDS = 8, 3
GENERATOR = ("Produce the best result you can for the task. When you receive a critique, fix every "
"listed defect and change nothing else. Return only the result.")
CRITIC = ("Judge the draft against each criterion. First list concrete defects with the passage "
"concerned, then score each criterion from 1 to 10. Do not rewrite or praise the draft.")
class Score(BaseModel):
criterion: str
score: int
class Critique(BaseModel):
defects: list[str]
scores: list[Score]
class State(TypedDict):
task: str
draft: str
critique: Critique | None
history: list[Critique]
rounds: int
model = init_chat_model("anthropic:claude-sonnet-5-5")
critic_model = model.with_structured_output(Critique)
def brief(task: str) -> str:
return f"Task: {task}\nCriteria:\n" + "\n".join(f"- {c}" for c in CRITERIA)
async def generator(state: State) -> dict:
prompt = brief(state["task"])
if state["critique"]: # from round two: previous draft plus its defect list
prompt += f"\n\nPrevious draft:\n{state['draft']}\n\nDefects to fix:\n" + "\n".join(state["critique"].defects)
reply = await model.ainvoke([SystemMessage(GENERATOR), HumanMessage(prompt)])
return {"draft": reply.text, "rounds": state["rounds"] + 1}
async def critic(state: State) -> dict:
# fresh context: task, criteria and draft only, never the generator's reasoning
raw = await critic_model.ainvoke([SystemMessage(CRITIC), HumanMessage(f"{brief(state['task'])}\n\nDraft:\n{state['draft']}")])
critique = Critique.model_validate(raw)
return {"critique": critique, "history": [*state["history"], critique]}
def lowest(critique: Critique | None) -> int:
return min((s.score for s in critique.scores), default=0) if critique else 0
def bar(state: State) -> str:
# the gate is a plain rule: every criterion at 8 or more, or 3 rounds spent
if lowest(state["critique"]) >= TARGET or state["rounds"] >= MAX_ROUNDS:
return END
return "generator"
builder = StateGraph(State)
builder.add_node("generator", generator)
builder.add_node("critic", critic)
builder.add_edge(START, "generator")
builder.add_edge("generator", "critic")
builder.add_conditional_edges("critic", bar, ["generator", END])
graph = builder.compile()
async def run(task: str) -> dict:
final = await graph.ainvoke({"task": task, "draft": "", "critique": None, "history": [], "rounds": 0})
return {
"result": final["draft"],
"scores_per_round": [{s.criterion: s.score for s in c.scores} for c in final["history"]],
"target_met": lowest(final["critique"]) >= TARGET,
}
Replace CRITERIA with three to six criteria that can be checked on your own output; generic criteria make the critic vague.
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel
CRITERIA = ["Answers every part of the task", "Each claim is specific", "Clear structure, no filler"]
TARGET, MAX_ROUNDS = 8, 3
AGENTS = {
"generator": AgentDefinition(
description="Writes the draft, or rewrites it to fix a critique.",
prompt="Produce the best result you can for the task. When you receive a critique, fix every "
"listed defect and change nothing else. Return only the result.",
),
"critic": AgentDefinition(
description="Scores a draft against the criteria and lists its defects.",
prompt="Judge the draft against each criterion. First list concrete defects with the passage "
"concerned, then score each criterion from 1 to 10. Do not rewrite or praise the draft.",
),
}
class Score(BaseModel):
criterion: str
score: int
class Critique(BaseModel):
defects: list[str]
scores: list[Score]
async def delegate(agent: str, message: str, schema: type[BaseModel] | None = None) -> ResultMessage:
# one fresh session per call, so each sub-agent sees only the message it is given
options = ClaudeAgentOptions(
agents=AGENTS,
allowed_tools=["Agent"],
output_format={"type": "json_schema", "schema": schema.model_json_schema()} if schema else None,
)
prompt = f"Delegate this to the {agent} agent, passing it verbatim, and return its reply unchanged:\n\n{message}"
async for msg in query(prompt=prompt, options=options):
if isinstance(msg, ResultMessage):
return msg
raise RuntimeError("no result")
async def run(task: str) -> dict:
brief = f"Task: {task}\nCriteria:\n" + "\n".join(f"- {c}" for c in CRITERIA)
draft, history = "", list[Critique]()
for _ in range(MAX_ROUNDS): # the gate: stop at 3 rounds
prompt = brief
if history:
prompt += f"\n\nPrevious draft:\n{draft}\n\nDefects to fix:\n" + "\n".join(history[-1].defects)
draft = (await delegate("generator", prompt)).result or ""
reply = await delegate("critic", f"{brief}\n\nDraft:\n{draft}", Critique)
history.append(Critique.model_validate(reply.structured_output))
if min(s.score for s in history[-1].scores) >= TARGET:
break
return {
"result": draft,
"scores_per_round": [{s.criterion: s.score for s in c.scores} for c in history],
"target_met": min(s.score for s in history[-1].scores) >= TARGET,
}
Replace CRITERIA with three to six criteria that can be checked on your own output; generic criteria make the critic vague.
from agents import Agent, Runner
from pydantic import BaseModel
CRITERIA = ["Answers every part of the task", "Each claim is specific", "Clear structure, no filler"]
TARGET, MAX_ROUNDS = 8, 3
class Score(BaseModel):
criterion: str
score: int
class Critique(BaseModel):
defects: list[str]
scores: list[Score]
generator = Agent(
name="Generator",
instructions="Produce the best result you can for the task. When you receive a critique, fix every "
"listed defect and change nothing else. Return only the result.",
)
critic = Agent(
name="Critic",
instructions="Judge the draft against each criterion. First list concrete defects with the passage "
"concerned, then score each criterion from 1 to 10. Do not rewrite or praise the draft.",
output_type=Critique,
)
def lowest(critique: Critique) -> int:
return min((s.score for s in critique.scores), default=0)
async def run(task: str) -> dict:
brief = f"Task: {task}\nCriteria:\n" + "\n".join(f"- {c}" for c in CRITERIA)
draft, history = "", list[Critique]()
for _ in range(MAX_ROUNDS): # the gate: stop at 3 rounds
prompt = brief
if history: # from round two: previous draft plus its defect list
prompt += f"\n\nPrevious draft:\n{draft}\n\nDefects to fix:\n" + "\n".join(history[-1].defects)
draft = (await Runner.run(generator, prompt)).final_output_as(str)
# separate run: the critic never sees the generator's conversation
judged = await Runner.run(critic, f"{brief}\n\nDraft:\n{draft}")
history.append(judged.final_output_as(Critique))
if lowest(history[-1]) >= TARGET:
break
return {
"result": draft,
"scores_per_round": [{s.criterion: s.score for s in c.scores} for c in history],
"target_met": lowest(history[-1]) >= TARGET,
}
Replace CRITERIA with three to six criteria that can be checked on your own output; generic criteria make the critic vague.
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent } from 'ai';
import { z } from 'zod';
const CRITERIA = ['Answers every part of the task', 'Each claim is specific', 'Clear structure, no filler'];
const TARGET = 8;
const MAX_ROUNDS = 3;
const critiqueSchema = z.object({
defects: z.array(z.string()),
scores: z.array(z.object({ criterion: z.string(), score: z.number().int().min(1).max(10) })),
});
type Critique = z.infer<typeof critiqueSchema>;
const model = anthropic('claude-sonnet-5-5');
const generator = new ToolLoopAgent({
model,
instructions:
'Produce the best result you can for the task. When you receive a critique, fix every ' +
'listed defect and change nothing else. Return only the result.',
});
const critic = new ToolLoopAgent({
model,
instructions:
'Judge the draft against each criterion. First list concrete defects with the passage ' +
'concerned, then score each criterion from 1 to 10. Do not rewrite or praise the draft.',
output: Output.object({ schema: critiqueSchema }),
});
const lowest = (c: Critique) => Math.min(...c.scores.map((s) => s.score));
export async function run(task: string) {
const brief = `Task: ${task}\nCriteria:\n${CRITERIA.map((c) => `- ${c}`).join('\n')}`;
let draft = '';
const history: Critique[] = [];
for (let round = 0; round < MAX_ROUNDS; round++) { // the gate: stop at 3 rounds
const last = history.at(-1);
const prompt = last
? `${brief}\n\nPrevious draft:\n${draft}\n\nDefects to fix:\n${last.defects.join('\n')}`
: brief;
draft = (await generator.generate({ prompt })).text;
// separate call: the critic sees task, criteria and draft only
const { output } = await critic.generate({ prompt: `${brief}\n\nDraft:\n${draft}` });
history.push(output);
if (lowest(output) >= TARGET) break;
}
const final = history[history.length - 1];
return {
result: draft,
scoresPerRound: history.map((c) => Object.fromEntries(c.scores.map((s) => [s.criterion, s.score]))),
targetMet: lowest(final) >= TARGET,
};
}
Replace CRITERIA with three to six criteria that can be checked on your own output; generic criteria make the critic vague.
Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.
What goes wrong
- A critic that shares the generator's context approves what it already believes. Keep the contexts separate.
- Vague criteria such as "be clear" produce vague critiques. Each criterion must be checkable on the text.
- Letting the generator rewrite freely drifts away from parts that were already good. Restrict it to the listed defects.
Chain it
Its result can feed
- Chain of Verification conditional
Condition: Build the link only when Reflection's refined payload is an answer, not a document.
- Debate conditional
Condition: Build the link only when Reflection's refined payload is an answer to a question or decision, not a document.
- Constitutional Critique direct
Treat the refined text as the draft to check against every constitution rule, revising only the rules it fails.
It can take the result of
- Tool Use
- ReAct
- Plan–Execute–Verify
- Tree of Thoughts
- Meta-Controller
- Graph Memory
- Language Agent Tree Search
- Agentic RAG
- Corrective RAG
- Self-RAG
- Adaptive RAG
- GraphRAG
- Debate
- Workflow Memory
- Magentic Orchestration
- ReWOO
- LLMCompiler
- Code as Action
- Dual LLM
- Recursive Language Model
- LLM Cascade
- As-Needed Decomposition
- Chain of Agents
- Tool Retrieval
- Trusted Monitoring
- Recoverable Execution
- Speculative Actions