Agentic Architectures

Catalogue / Reasoning & Self-critique

Reflection

Draft, criticise, rewrite, until the work clears the bar

Shape
loop
Model calls
1 + 2 × rounds (typically 3 to 7)
Latency
medium
Complexity
low

Also known as Self-Refine, Generator–Critic

1

Why 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.
2

When 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
3

How 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.

below target,rounds lefttarget met orrounds spentTask: The request, or an existing draft to improve, plus the quality criteria.TaskGenerator: Writes the first draft, then rewrites it using the latest critique.GeneratorCritic: Scores the draft against each criterion and lists specific defects.CriticGood enough?: Compares the score with the target and counts the rounds used.Good enough?Refined result: The last draft, with its final score and the critique history.Refinedresult
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

Entry
task
TaskQuestionDraftAnswerDocument

A request to fulfil, or an existing result to improve. Quality criteria are optional, the stage writes them when absent.

Exit
refined
AnswerDocument

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.

4

What 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.

Framework-agnostic prompt
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

LangGraph, python, package langgraph
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.

Claude Agent SDK, python, package claude-agent-sdk
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.

OpenAI Agents SDK, python, package openai-agents
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.

Vercel AI SDK, typescript, package ai
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

It can take the result of

Source