1Why 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.
2When 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
3How 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
A task with an automatic success check, such as tests, a validator or expected values. The stage cannot run without one.
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.
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.
The lessons for this task, one per failed trial, kept for the trials of this run and discarded when it ends.
4What 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.
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
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.
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.
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.
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.