1Why pay a model to reread the whole trace before every tool call?
A loop that thinks, acts and observes sends the growing trace back to the model before each step. ReWOO has the model write every tool call up front, with placeholders where a result is needed. Plain code runs the calls and fills the placeholders. One last model call reads the evidence and answers.
You may need it if
- The same tool results are sent to the model again at every step of a long loop.
- The calls a question needs are predictable from the question alone.
- Most of the token bill comes from prompts that repeat earlier observations.
2When can the calls not be written before any result is seen?
Use it when
- The tool calls a question needs can be listed from the question and the tool descriptions alone.
- Later calls use earlier results only as arguments, pasted in as they are.
- Prompt size matters more than the ability to change course midway.
Avoid it when
- A result should change which tool is called next, or whether one is called at all. The planner here never sees a result.
Use ReAct instead - A failed or empty tool call should lead to a new approach. Here it is recorded as evidence and the run goes on.
Use Planning instead - Most calls do not depend on each other and waiting for them one after the other is too slow.
Use LLMCompiler instead - One or two calls answer the question. A plan and a solver add two model calls around them.
Use Tool Use instead
What it costs
- Model calls
- 2 model calls (1 planner + 1 solver), whatever the number of tool calls
- Latency
- medium
- Complexity
- low
3How do placeholders let the calls run without the model?
A straight line with no way back. The planner writes every step, each bound to a variable such as #E1. A worker that is plain code runs the calls in order, pastes earlier results into later inputs and stores each output. The solver reads the plan and the evidence once and answers.
- Step 1 of 6
The whole plan, before any call
For "How many days of stock are left for our best-selling product?", the planner writes three steps: #E1 = top_seller[last 30 days], #E2 = stock_level[#E1], #E3 = daily_sales[#E1]. Each has a one-line reason. It has seen no result.
- Step 2 of 6
The worker runs the first call
Plain code reads step one. Its input has no variable, so it calls top_seller as written and stores the output, "SKU-204, Trail bottle", under #E1. No model is involved.
- Step 3 of 6
Variables are filled in
Step two's input is #E1. The worker replaces it with the stored text and calls stock_level. Step three is handled the same way. Nobody reads the results in between.
- Step 4 of 6
Nothing returns to the planner
If daily_sales returns an error, the error is stored under
- Step 5 of 6
One solver call
The solver receives the task, the three steps with their reasons and the three results. It divides the stock by the daily sales, or says the evidence is not enough if one result is an error.
- Step 6 of 6
The answer
The answer leaves with the plan and the evidence, so a reader can check each figure against the call that produced it.
What each part does
- Task
- The task or question. The tool list with one-line descriptions is already configured.
- Planner
- Writes the whole plan in one call: a reason, a variable, a tool and its input for each step. Never sees a result.
- Plan
- The ordered steps. Inputs may contain variables such as #E1 that stand for earlier results.
- Worker
- Plain code. Takes the steps in order, replaces variables with stored results and calls the named tool.
- Tools
- Your functions, such as a search or a database lookup. A plain model call may be one of them.
- Evidence
- One entry per variable: the raw output of its call, or the error it returned.
- Solver
- Reads the task, the plan and all the evidence, then writes the answer. Calls no tool.
- Answer
- The answer, with the plan and the evidence it was written from.
- Planner → Plan: steps with variables
- Plan → Worker: next step
- Evidence → Worker: values for variables
- Worker → Tools: call with values filled in
- Tools → Worker: raw result, next step
- Worker → Evidence: result under its variable
- Worker → Solver: every step has run
- Plan → Solver: steps and reasons
- Evidence → Solver: all results
Where it connects
A task or question whose tool calls can be foreseen from its wording. The tools and their descriptions are already configured.
When: The solver has written its answer, after every planned call has run once.
The answer, then the plan and the evidence stored for each variable, as returned by the tools. Errors are kept as evidence and flagged.
Ordered steps, each with a reason, a variable name, a tool and an input that may reference earlier variables. Written once, never revised.
One raw tool output or error message per variable, in the order the calls ran.
4What do I ask my assistant to set up?
The agents to launch
Planner
Write the complete plan for the task before anything runs. Each step has a one-line reason, a variable (E1, E2, and so on), one tool from the list and its input. Where an input needs an earlier result, write its variable, such as #E1. Use at most 8 steps. You will never see a result, so plan only calls whose form you can write now.
Sees: The task and the tool list with descriptions. No tool output, at any point.
Solver
Answer the task from the plan and the evidence. Evidence can be wrong, empty or an error message: use it with caution, and say plainly what it does not support. Do not call tools and do not add facts that are not in the evidence.
Sees: The task, every step with its reason, and the evidence stored for each variable. It cannot call tools.
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 "ReWOO" 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] # ReWOO Plan every tool call with placeholders, run them, then answer once. Input: the task above. It must provide: A task or question whose tool calls can be foreseen from its wording. The tools and their descriptions are already configured. If something essential is missing, ask for it before starting. Agents to launch: - Planner: Write the complete plan for the task before anything runs. Each step has a one-line reason, a variable (E1, E2, and so on), one tool from the list and its input. Where an input needs an earlier result, write its variable, such as #E1. Use at most 8 steps. You will never see a result, so plan only calls whose form you can write now. Context for this agent: The task and the tool list with descriptions. No tool output, at any point. - Solver: Answer the task from the plan and the evidence. Evidence can be wrong, empty or an error message: use it with caution, and say plainly what it does not support. Do not call tools and do not add facts that are not in the evidence. Context for this agent: The task, every step with its reason, and the evidence stored for each variable. It cannot call tools. Procedure: 1. Write the tool list with a one-line description and an input format for each tool. 2. Launch the planner once on the task and the tool list. Store its steps as the plan. 3. Check the plan in code, without a model. Keep the first 8 steps. A step that names an unknown tool gets an error as its evidence. 4. In plain code, take the steps in order. Replace each variable in the input with the stored result, call the tool and store the output under the step's variable. 5. If a call fails, store the error text as its evidence and go on. Do not retry and do not go back to the planner. 6. Launch the solver once with the task, the plan and all the evidence. Return its answer. Stop rule: Stop after the solver's single call. Each planned call runs once, 8 at most. No result goes back to the planner, so there is no second round. Exit: - `answer`, when: The solver has written its answer, after every planned call has run once. Deliver: The answer, then the plan and the evidence stored for each variable, as returned by the tools. Errors are kept as evidence and flagged. # Final deliverable The answer, then the plan as written and the evidence for each variable. Flag every variable whose evidence is an error or empty.
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
MAX_CALLS = 8
def top_seller(period: str) -> str:
return f"stub: best-selling product for {period}" # plug in your sales system
def stock_level(product: str) -> str:
return f"stub: units in stock for {product}"
def daily_sales(product: str) -> str:
return f"stub: units sold per day for {product}"
TOOLS = {"top_seller": top_seller, "stock_level": stock_level, "daily_sales": daily_sales}
PLANNER = ("Write the complete plan for the task before anything runs. Each step has a one-line reason, "
"a variable (E1, E2, ...), one tool and its input. Where an input needs an earlier result, write "
f"its variable, such as #E1. At most {MAX_CALLS} steps. You will never see a result.")
SOLVER = ("Answer the task from the plan and the evidence. Evidence can be wrong, empty or an error: use it "
"with caution and say what it does not support. Add no fact that is not in the evidence.")
class Step(BaseModel):
reason: str
var: str # E1, E2, ...
tool: str
input: str # may contain #E1, #E2 from earlier steps
class Plan(BaseModel):
steps: list[Step]
class State(TypedDict):
task: str
plan: Plan | None
evidence: dict[str, str]
answer: str
model = init_chat_model("anthropic:claude-sonnet-5-5")
planner_model = model.with_structured_output(Plan)
async def planner(state: State) -> dict:
prompt = f"Task: {state['task']}\nTools: {', '.join(TOOLS)}" # no tool output, at any point
return {"plan": Plan.model_validate(await planner_model.ainvoke([SystemMessage(PLANNER), HumanMessage(prompt)]))}
async def worker(state: State) -> dict:
# plain code: no model reads a result between two calls
plan, evidence = state["plan"], {}
assert plan is not None
for step in plan.steps[:MAX_CALLS]:
text = step.input
for var in sorted(evidence, key=len, reverse=True):
text = text.replace(f"#{var}", evidence[var])
tool = TOOLS.get(step.tool)
try:
evidence[step.var] = tool(text) if tool else f"error: unknown tool {step.tool}"
except Exception as exc: # an error is kept as evidence; the plan is not rewritten
evidence[step.var] = f"error: {exc}"
return {"evidence": evidence}
async def solver(state: State) -> dict:
plan = state["plan"]
assert plan is not None
lines = "\n".join(
f"{s.reason}\n#{s.var} = {s.tool}[{s.input}]\n-> {state['evidence'].get(s.var, '(not run)')}" for s in plan.steps
)
reply = await model.ainvoke([SystemMessage(SOLVER), HumanMessage(f"Task: {state['task']}\n\n{lines}")])
return {"answer": reply.text}
builder = StateGraph(State)
builder.add_node("planner", planner)
builder.add_node("worker", worker)
builder.add_node("solver", solver)
builder.add_edge(START, "planner")
builder.add_edge("planner", "worker") # a straight line: no edge returns to the planner
builder.add_edge("worker", "solver")
builder.add_edge("solver", END)
graph = builder.compile()
async def run(task: str) -> dict:
s = await graph.ainvoke({"task": task, "plan": None, "evidence": {}, "answer": ""})
flagged = [v for v, e in s["evidence"].items() if not e or e.startswith("error")]
return {"answer": s["answer"], "plan": s["plan"].model_dump(), "evidence": s["evidence"], "flagged": flagged}
Replace the stub tools with real ones. Results are pasted whole into later inputs; trim them in the worker if your tools return long text.
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel
MAX_CALLS = 8
def top_seller(period: str) -> str:
return f"stub: best-selling product for {period}" # plug in your sales system
def stock_level(product: str) -> str:
return f"stub: units in stock for {product}"
def daily_sales(product: str) -> str:
return f"stub: units sold per day for {product}"
TOOLS = {"top_seller": top_seller, "stock_level": stock_level, "daily_sales": daily_sales}
AGENTS = {
"planner": AgentDefinition(
description="Writes every tool call up front, with variables for results.",
prompt="Write the complete plan for the task before anything runs. Each step has a one-line reason, "
"a variable (E1, E2, ...), one tool and its input. Where an input needs an earlier result, write "
f"its variable, such as #E1. At most {MAX_CALLS} steps. You will never see a result.",
),
"solver": AgentDefinition(
description="Answers from the plan and the collected evidence.",
prompt="Answer the task from the plan and the evidence. Evidence can be wrong, empty or an error: use it "
"with caution and say what it does not support. Add no fact that is not in the evidence.",
),
}
class Step(BaseModel):
reason: str
var: str # E1, E2, ...
tool: str
input: str # may contain #E1, #E2 from earlier steps
class Plan(BaseModel):
steps: list[Step]
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")
def work(plan: Plan) -> dict[str, str]:
# the worker is plain code: no model reads a result between two calls
evidence: dict[str, str] = {}
for step in plan.steps[:MAX_CALLS]:
text = step.input
for var in sorted(evidence, key=len, reverse=True):
text = text.replace(f"#{var}", evidence[var])
tool = TOOLS.get(step.tool)
try:
evidence[step.var] = tool(text) if tool else f"error: unknown tool {step.tool}"
except Exception as exc: # an error is kept as evidence; the plan is not rewritten
evidence[step.var] = f"error: {exc}"
return evidence
async def run(task: str) -> dict:
# call 1: the planner sees the task and the tool names, and no tool output
planned = await delegate("planner", f"Task: {task}\nTools: {', '.join(TOOLS)}", Plan)
plan = Plan.model_validate(planned.structured_output)
evidence = work(plan)
lines = "\n".join(f"{s.reason}\n#{s.var} = {s.tool}[{s.input}]\n-> {evidence.get(s.var, '(not run)')}" for s in plan.steps)
# call 2: the solver reads everything once; nothing goes back to the planner
solved = await delegate("solver", f"Task: {task}\n\n{lines}")
flagged = [v for v, e in evidence.items() if not e or e.startswith("error")]
return {"answer": solved.result or "", "plan": plan.model_dump(), "evidence": evidence, "flagged": flagged}
The tools run in your own code, not inside the agent sessions, so no session ever holds a growing trace of observations.
from agents import Agent, Runner
from pydantic import BaseModel
MAX_CALLS = 8
def top_seller(period: str) -> str:
return f"stub: best-selling product for {period}" # plug in your sales system
def stock_level(product: str) -> str:
return f"stub: units in stock for {product}"
def daily_sales(product: str) -> str:
return f"stub: units sold per day for {product}"
TOOLS = {"top_seller": top_seller, "stock_level": stock_level, "daily_sales": daily_sales}
class Step(BaseModel):
reason: str
var: str # E1, E2, ...
tool: str
input: str # may contain #E1, #E2 from earlier steps
class Plan(BaseModel):
steps: list[Step]
planner = Agent(
name="Planner",
instructions="Write the complete plan for the task before anything runs. Each step has a one-line reason, "
"a variable (E1, E2, ...), one tool and its input. Where an input needs an earlier result, write "
f"its variable, such as #E1. At most {MAX_CALLS} steps. You will never see a result.",
output_type=Plan,
)
solver = Agent(
name="Solver",
instructions="Answer the task from the plan and the evidence. Evidence can be wrong, empty or an error: use it "
"with caution and say what it does not support. Add no fact that is not in the evidence.",
)
def work(plan: Plan) -> dict[str, str]:
# the worker is plain code: no model reads a result between two calls
evidence: dict[str, str] = {}
for step in plan.steps[:MAX_CALLS]:
text = step.input
for var in sorted(evidence, key=len, reverse=True):
text = text.replace(f"#{var}", evidence[var])
tool = TOOLS.get(step.tool)
try:
evidence[step.var] = tool(text) if tool else f"error: unknown tool {step.tool}"
except Exception as exc: # an error is kept as evidence; the plan is not rewritten
evidence[step.var] = f"error: {exc}"
return evidence
async def run(task: str) -> dict:
# call 1: the planner sees the task and the tool names, and no tool output
plan = (await Runner.run(planner, f"Task: {task}\nTools: {', '.join(TOOLS)}")).final_output_as(Plan)
evidence = work(plan)
lines = "\n".join(f"{s.reason}\n#{s.var} = {s.tool}[{s.input}]\n-> {evidence.get(s.var, '(not run)')}" for s in plan.steps)
# call 2: the solver reads everything once; nothing goes back to the planner
answer = (await Runner.run(solver, f"Task: {task}\n\n{lines}")).final_output_as(str)
flagged = [v for v, e in evidence.items() if not e or e.startswith("error")]
return {"answer": answer, "plan": plan.model_dump(), "evidence": evidence, "flagged": flagged}
Neither agent is given tools: the planner only names them and your code calls them. That is what keeps observations out of the model until the solver.
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent } from 'ai';
import { z } from 'zod';
const MAX_CALLS = 8;
const model = anthropic('claude-sonnet-5-5');
// stubs: plug in your sales and stock systems
const TOOLS: Record<string, (input: string) => Promise<string>> = {
top_seller: async (period) => `stub: best-selling product for ${period}`,
stock_level: async (product) => `stub: units in stock for ${product}`,
daily_sales: async (product) => `stub: units sold per day for ${product}`,
};
const planSchema = z.object({
steps: z.array(
z.object({
reason: z.string(),
variable: z.string().describe('E1, E2, ...'),
tool: z.string(),
input: z.string().describe('may contain #E1, #E2 from earlier steps'),
}),
),
});
type Plan = z.infer<typeof planSchema>;
const planner = new ToolLoopAgent({
model,
instructions:
'Write the complete plan for the task before anything runs. Each step has a one-line reason, ' +
'a variable (E1, E2, ...), one tool and its input. Where an input needs an earlier result, write ' +
`its variable, such as #E1. At most ${MAX_CALLS} steps. You will never see a result.`,
output: Output.object({ schema: planSchema }),
});
const solver = new ToolLoopAgent({
model,
instructions:
'Answer the task from the plan and the evidence. Evidence can be wrong, empty or an error: use it ' +
'with caution and say what it does not support. Add no fact that is not in the evidence.',
});
// the worker is plain code: no model reads a result between two calls
async function work(plan: Plan) {
const evidence = new Map<string, string>();
for (const step of plan.steps.slice(0, MAX_CALLS)) {
let text = step.input;
for (const name of [...evidence.keys()].sort((a, b) => b.length - a.length)) {
text = text.split(`#${name}`).join(evidence.get(name) ?? '');
}
const tool = TOOLS[step.tool];
try {
evidence.set(step.variable, tool ? await tool(text) : `error: unknown tool ${step.tool}`);
} catch (err) {
evidence.set(step.variable, `error: ${String(err)}`); // kept as evidence; the plan is not rewritten
}
}
return evidence;
}
export async function run(task: string) {
// call 1: the planner sees the task and the tool names, and no tool output
const { output: plan } = await planner.generate({ prompt: `Task: ${task}\nTools: ${Object.keys(TOOLS).join(', ')}` });
const evidence = await work(plan);
const lines = plan.steps
.map((s) => `${s.reason}\n#${s.variable} = ${s.tool}[${s.input}]\n-> ${evidence.get(s.variable) ?? '(not run)'}`)
.join('\n');
// call 2: the solver reads everything once; nothing goes back to the planner
const { text: answer } = await solver.generate({ prompt: `Task: ${task}\n\n${lines}` });
const flagged = [...evidence].filter(([, e]) => !e || e.startsWith('error')).map(([name]) => name);
return { answer, plan, evidence: Object.fromEntries(evidence), flagged };
}
Neither agent is given tools: the planner only names them and your code calls them. Replace the stubs with real functions.
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 long result pasted whole into the next input can break that call. Plan a step that extracts the one value needed, or trim results in the worker.
- A plan can look reasonable and rest on a wrong guess, such as a source holding a fact it does not hold. The solver must be allowed to say the evidence is not enough.
- Adding a retry loop that calls the planner again turns this into Planning and brings the rereading cost back.
- Every tool description is read by the planner. A long tool list makes its choices worse.
Chain it
Its result can feed
- Reflection conditional
Condition: Holds only when ReWOO's answer is a substantial prose text (a report, summary or explanation), not a short fact, number or label, and only the answer part is handed over as the result to improve.
- Chain of Verification conditional
Condition: Holds when the solver's answer is passed as the answer whose claims are checked, with the raw evidence block kept as background rather than as a work item.
- Debate conditional
Condition: Holds when the solver's answer is passed as the existing answer to challenge, with the evidence block kept as background.
- Constitutional Critique conditional
Condition: Holds when the solver's answer is passed as the text to check, with the evidence block kept as background.
- Textual Backpropagation conditional
Condition: Holds only when ReWOO's answer is a substantial prose text, not a short fact, number or label, and only the answer part is handed over as material to improve.