Agentic Architectures

Catalogue / Reasoning & Self-critique

Reflexion

Try, check, write down the lesson, and try again with it

Shape
loop
Model calls
1 per trial + 1 lesson per failed trial before the last (1 to 7)
Latency
high
Complexity
medium

Also known as Verbal reinforcement, Try-learn-retry

1

Why does my agent repeat the same mistake when I let it retry?

A plain retry starts from the same prompt, so it often fails the same way. Reflexion checks each attempt against a clear success signal, such as tests passing. After a failure, the agent writes a short lesson on what went wrong, and the next attempt starts with every lesson so far.

You may need it if

  • Retrying a failed task gives a different wording but the same failure.
  • You have an automatic check that says pass or fail, such as tests, a validator or a sample calculation.
  • Errors come from a wrong approach, not from missing information.
2

When is a lesson loop the wrong tool?

Use it when

  • Success can be checked automatically and cheaply after each attempt.
  • Failures carry information, such as an error message, a failed test or a wrong total.
  • Several attempts are affordable and a correct result matters more than speed.

Avoid it when

  • There is no automatic check, only a judgement of quality. Use a critic with criteria instead.
    Use Reflection instead
  • The task fails because facts are missing, not because the approach is wrong. Lessons cannot supply facts.
    Use Corrective RAG instead
  • Lessons should help future, different tasks, not just the retries of this one.
    Use Workflow Memory instead
  • Each attempt has real side effects, such as sending emails, so a failed try cannot simply be discarded.
    Use Dry Run instead

What it costs

Model calls
1 per trial + 1 lesson per failed trial before the last (1 to 7)
Latency
high
Complexity
medium
3

How does a failure become a lesson that shapes the next attempt?

The actor attempts the task with any lessons so far. An evaluator runs the check. A plain rule decides: success leaves at once, failure with trials left goes to the reflector, which writes a lesson to memory and sends the actor back. At the trial limit the run leaves through a separate exit.

passedfailed, trialsleftfailed, triallimit reachedretryTask: The task, together with the check that tells whether an attempt succeeded.TaskLesson memory: Short lessons written after each failed trial, read by every later attempt.Lesson memoryActor: Attempts the task, taking every stored lesson into account.ActorEvaluator: Runs the check on the attempt, such as the test suite, and returns pass or fail with the details.EvaluatorPassed?: A plain rule on the check's result and the number of trials used.Passed?Reflector: Reads the failed attempt and the check's details, and writes one lesson on what to do differently.ReflectorSolved: The attempt that passed, with the check's result and the lessons that led to it.SolvedOut of trials: The failure report after the last trial, with every lesson and the last check result.Out of trials
  1. Step 1 of 6

    First attempt

    The actor works on the task as any agent would. On the first trial the lesson memory is empty.

  2. Step 2 of 6

    A real check

    The evaluator runs a check that does not depend on the model's opinion, such as the test suite or a comparison with known totals, and reports what failed.

  3. Step 3 of 6

    The rule decides

    A plain rule reads the result. A pass leaves at once through the success exit. A failure goes to the reflector while trials remain.

  4. Step 4 of 6

    Write the lesson

    The reflector compares the attempt with the failure details and writes two or three sentences on the cause and what to change. The lesson is stored, not the whole attempt.

  5. Step 5 of 6

    Retry with the lessons

    The actor starts again with the task and every lesson so far. It is not asked to patch the last attempt, but to avoid the recorded mistakes.

  6. Step 6 of 6

    Out of trials

    After the fourth failed trial, the run leaves through a separate exit with the lessons and the last result, so whatever comes next knows the task was not solved.

What each part does
Task
The task, together with the check that tells whether an attempt succeeded.
Lesson memory
Short lessons written after each failed trial, read by every later attempt.
Actor
Attempts the task, taking every stored lesson into account.
Evaluator
Runs the check on the attempt, such as the test suite, and returns pass or fail with the details.
Passed?
A plain rule on the check's result and the number of trials used.
Reflector
Reads the failed attempt and the check's details, and writes one lesson on what to do differently.
Solved
The attempt that passed, with the check's result and the lessons that led to it.
Out of trials
The failure report after the last trial, with every lesson and the last check result.
  • Lesson memory → Actor: lessons so far
  • Actor → Evaluator: attempt
  • Evaluator → Passed?: pass or fail, with details
  • Passed? → Solved: passed
  • Passed? → Reflector: failed, trials left
  • Passed? → Out of trials: failed, trial limit reached
  • Reflector → Lesson memory: new lesson
  • Reflector → Actor: retry

Where it connects

Entry
task
Task

A task with an automatic success check, such as tests, a validator or expected values. The stage cannot run without one.

Exit
solved
Answer

When: An attempt passed the check within the trial limit.

The passing attempt, the check's result, the number of trials used and the lessons recorded on the way.

Exit
exhausted
Verdict

When: The trial limit was reached and no attempt passed the check.

A failure verdict with the last check result, every lesson recorded and the best attempt, clearly marked as unsolved.

Working memory for one run
lessons
Knowledge

The lessons for this task, one per failed trial, kept for the trials of this run and discarded when it ends.

4

What do I ask my assistant to set up?

The agents to launch

Actor

Solve the task. If lessons are listed, read them first and make sure your attempt avoids every mistake they describe. Return the complete attempt, not a patch of an earlier one.

Sees: The task and the lessons so far. Not earlier attempts and not the hidden part of the check.

Reflector

The attempt failed the check. In two or three sentences, state the most likely cause and the specific change the next attempt should make. Do not write the solution. Do not repeat an earlier lesson.

Sees: The task, the failed attempt, the check's failure details and the earlier lessons.

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 "Reflexion" 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]

# Reflexion
Try, check, write down the lesson, and try again with it.
Input: the task above. It must provide: A task with an automatic success check, such as tests, a validator or expected values. The stage cannot run without one. If something essential is missing, ask for it before starting.

Agents to launch:
- Actor: Solve the task. If lessons are listed, read them first and make sure your attempt avoids every mistake they describe. Return the complete attempt, not a patch of an earlier one.
  Context for this agent: The task and the lessons so far. Not earlier attempts and not the hidden part of the check.
- Reflector: The attempt failed the check. In two or three sentences, state the most likely cause and the specific change the next attempt should make. Do not write the solution. Do not repeat an earlier lesson.
  Context for this agent: The task, the failed attempt, the check's failure details and the earlier lessons.

Procedure:
1. Confirm the task has an automatic check. If not, stop and report that this pattern needs one.
2. Create an empty lesson list for this task.
3. Launch the actor with the task and the lessons. Run the check on its attempt.
4. If the check passes, release the attempt as solved.
5. If it fails and fewer than four trials were used, launch the reflector in a fresh context, append its lesson, and repeat from the actor step.
6. If the fourth trial fails, release the failure report with the lessons and the attempt that came closest.

Stop rule: Stop when the check passes, or after four trials, whichever comes first.

Exits:
- `solved`, when: An attempt passed the check within the trial limit. Deliver: The passing attempt, the check's result, the number of trials used and the lessons recorded on the way.
- `exhausted`, when: The trial limit was reached and no attempt passed the check. Deliver: A failure verdict with the last check result, every lesson recorded and the best attempt, clearly marked as unsolved.

# Final deliverable
Either the passing attempt with the trial count and lessons, or a failure report marked unsolved with the last check result and every lesson.

The same thing in code

LangGraph, python, package langgraph
from typing import TypedDict

from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph

MAX_TRIALS = 4
model = init_chat_model("anthropic:claude-sonnet-5-5")


def run_check(attempt: str) -> tuple[bool, str]:
    # plug in the task's automatic check, such as a test suite with a hidden part
    return False, "stub: no check wired"


class Input(TypedDict):
    task: str
    lessons: list[str]
    trials: int


class State(TypedDict):
    task: str
    lessons: list[str]  # lesson memory, read by every later attempt
    attempt: str
    passed: bool
    details: str
    trials: int


async def actor(state: State) -> dict:
    # the actor sees the task and the lessons, never its earlier attempts
    lessons = "\n".join(f"- {l}" for l in state["lessons"]) or "none"
    msg = await model.ainvoke(
        "Solve the task. Read the lessons first and avoid every mistake they describe. "
        f"Return the complete attempt, not a patch.\nLessons:\n{lessons}\n\nTask: {state['task']}")
    return {"attempt": msg.text, "trials": state["trials"] + 1}


def evaluator(state: State) -> dict:
    passed, details = run_check(state["attempt"])
    return {"passed": passed, "details": details}


def gate(state: State) -> str:
    # the gate: pass leaves at once, four failed trials leave through the other exit
    if state["passed"] or state["trials"] >= MAX_TRIALS:
        return END
    return "reflector"


async def reflector(state: State) -> dict:
    msg = await model.ainvoke(
        "The attempt failed the check. In two or three sentences, state the most likely cause "
        "and the specific change the next attempt should make. Do not write the solution. "
        f"Do not repeat an earlier lesson.\nTask: {state['task']}\nAttempt:\n{state['attempt']}\n"
        f"Check details: {state['details']}\nEarlier lessons: {state['lessons']}")
    return {"lessons": state["lessons"] + [msg.text]}


graph = StateGraph(State, input_schema=Input)
graph.add_node("actor", actor)
graph.add_node("evaluator", evaluator)
graph.add_node("reflector", reflector)
graph.add_edge(START, "actor")
graph.add_edge("actor", "evaluator")
graph.add_conditional_edges("evaluator", gate, ["reflector", END])
graph.add_edge("reflector", "actor")
app = graph.compile()


async def run(task: str):
    state = await app.ainvoke({"task": task, "lessons": [], "trials": 0})
    status = "solved" if state["passed"] else "unsolved"
    return {"status": status, "trials": state["trials"], "attempt": state["attempt"],
            "check": state["details"], "lessons": state["lessons"]}

Wire run_check to a real automatic check and keep part of it hidden from the actor, or a passing attempt may only have gamed the visible tests.

Claude Agent SDK, python, package claude-agent-sdk
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query

MAX_TRIALS = 4

AGENTS = {
    "actor": AgentDefinition(
        description="Attempts the task from scratch, applying every stored lesson.",
        prompt="Solve the task. If lessons are listed, read them first and make sure your "
               "attempt avoids every mistake they describe. Return the complete attempt, "
               "not a patch of an earlier one."),
    "reflector": AgentDefinition(
        description="Turns one failed attempt into one concrete lesson.",
        prompt="The attempt failed the check. In two or three sentences, state the most likely "
               "cause and the specific change the next attempt should make. Do not write the "
               "solution. Do not repeat an earlier lesson."),
}


async def delegate(agent: str, payload: str) -> str:
    # each call is a fresh session, so no sub-agent carries memory between trials
    options = ClaudeAgentOptions(agents=AGENTS, allowed_tools=["Agent"])
    prompt = (f"Launch the {agent} agent with exactly this input and return its reply "
              f"verbatim:\n{payload}")
    async for msg in query(prompt=prompt, options=options):
        if isinstance(msg, ResultMessage):
            return msg.result or ""
    raise RuntimeError("no result")


def run_check(attempt: str) -> tuple[bool, str]:
    # plug in the task's automatic check, such as a test suite with a hidden part
    return False, "stub: no check wired"


async def run(task: str):
    lessons: list[str] = []  # lesson memory
    attempt, details = "", ""
    for trial in range(1, MAX_TRIALS + 1):  # the gate: at most four trials
        listed = "\n".join(f"- {l}" for l in lessons) or "none"
        # the actor sees the task and lessons, never its earlier attempts
        attempt = await delegate("actor", f"Lessons:\n{listed}\n\nTask: {task}")
        passed, details = run_check(attempt)
        if passed:
            return {"status": "solved", "trials": trial, "attempt": attempt, "lessons": lessons}
        if trial < MAX_TRIALS:
            lessons.append(await delegate(
                "reflector", f"Task: {task}\nFailed attempt:\n{attempt}\n"
                             f"Check details: {details}\nEarlier lessons:\n{listed}"))
    return {"status": "unsolved", "trials": MAX_TRIALS, "last_attempt": attempt,
            "check": details, "lessons": lessons}

Wire run_check to a real automatic check and keep part of it hidden from the actor, or a passing attempt may only have gamed the visible tests.

OpenAI Agents SDK, python, package openai-agents
from agents import Agent, Runner

MAX_TRIALS = 4

actor = Agent(
    name="Actor",
    instructions="Solve the task. If lessons are listed, read them first and make sure your "
                 "attempt avoids every mistake they describe. Return the complete attempt, not "
                 "a patch of an earlier one.")
reflector = Agent(
    name="Reflector",
    instructions="The attempt failed the check. In two or three sentences, state the most likely "
                 "cause and the specific change the next attempt should make. Do not write the "
                 "solution. Do not repeat an earlier lesson.")


def run_check(attempt: str) -> tuple[bool, str]:
    # plug in the task's automatic check, such as a test suite with a hidden part
    return False, "stub: no check wired"


async def run(task: str):
    lessons: list[str] = []  # lesson memory
    attempt, details = "", ""
    for trial in range(1, MAX_TRIALS + 1):  # the gate: at most four trials
        listed = "\n".join(f"- {l}" for l in lessons) or "none"
        # a fresh run each trial: the actor gets the task and lessons, not past attempts
        result = await Runner.run(actor, f"Lessons:\n{listed}\n\nTask: {task}")
        attempt = str(result.final_output)
        passed, details = run_check(attempt)
        if passed:
            return {"status": "solved", "trials": trial, "attempt": attempt, "lessons": lessons}
        if trial < MAX_TRIALS:
            lesson = await Runner.run(
                reflector, f"Task: {task}\nFailed attempt:\n{attempt}\n"
                           f"Check details: {details}\nEarlier lessons:\n{listed}")
            lessons.append(str(lesson.final_output))
    return {"status": "unsolved", "trials": MAX_TRIALS, "last_attempt": attempt,
            "check": details, "lessons": lessons}

Wire run_check to a real automatic check and keep part of it hidden from the actor, or a passing attempt may only have gamed the visible tests.

Vercel AI SDK, typescript, package ai
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const model = anthropic('claude-sonnet-5-5');
const MAX_TRIALS = 4;

// plug in the task's automatic check, such as a test suite with a hidden part
async function runCheck(_attempt: string): Promise<{ passed: boolean; details: string }> {
  return { passed: false, details: 'stub: no check wired' };
}

export async function run(task: string) {
  const lessons: string[] = []; // lesson memory
  let attempt = '';
  let details = '';
  for (let trial = 1; trial <= MAX_TRIALS; trial++) { // the gate: at most four trials
    const listed = lessons.map((l) => `- ${l}`).join('\n') || 'none';
    // the actor sees the task and lessons only, never its earlier attempts
    ({ text: attempt } = await generateText({
      model,
      instructions:
        'Solve the task. If lessons are listed, read them first and make sure your attempt ' +
        'avoids every mistake they describe. Return the complete attempt, not a patch of an earlier one.',
      prompt: `Lessons:\n${listed}\n\nTask: ${task}`,
    }));
    const check = await runCheck(attempt);
    details = check.details;
    if (check.passed) return { status: 'solved', trials: trial, attempt, lessons };
    if (trial < MAX_TRIALS) {
      const { text: lesson } = await generateText({
        model,
        instructions:
          'The attempt failed the check. In two or three sentences, state the most likely cause ' +
          'and the specific change the next attempt should make. Do not write the solution. ' +
          'Do not repeat an earlier lesson.',
        prompt: `Task: ${task}\nFailed attempt:\n${attempt}\nCheck details: ${details}\nEarlier lessons:\n${listed}`,
      });
      lessons.push(lesson);
    }
  }
  return { status: 'unsolved', trials: MAX_TRIALS, lastAttempt: attempt, check: details, lessons };
}

Wire runCheck to a real automatic check and keep part of it hidden from the actor, or a passing attempt may only have gamed the visible tests.

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 check the actor can see in full gets gamed. Keep part of it hidden, or review the passing attempt once.
  • Lessons that only say "be more careful" change nothing. Ask for a cause and a concrete change.
  • Feeding the actor its last attempt makes it patch rather than rethink, and the same mistake survives.

Chain it

This architecture stands alone: the compatibility matrix allows no link into or out of it.

Source