1Why does a tool-using agent lose its way on longer tasks?
Without a written reason for each call, an agent repeats lookups, forgets what it already learned and drifts from the goal. ReAct makes it write a short thought before every action and a plain observation after it. That trace steers the next step.
You may need it if
- The agent calls the same tool twice with the same arguments.
- Tasks need five or more dependent lookups, each one shaped by the last result.
- When a run goes wrong, nobody can tell why the agent made a given call.
2When is the reasoning trace just overhead?
Use it when
- Each step depends on what the previous result revealed, so the path cannot be planned upfront.
- You need an auditable record of why each action was taken.
- Tasks run from five to twenty steps: long enough to drift, short enough for one context.
Avoid it when
- One or two tool calls answer the question. A trace adds cost and nothing else.
Use Tool Use instead - The steps are known before starting and their order rarely changes.
Use Planning instead - Each step must be proven correct before the next one starts.
Use Plan–Execute–Verify instead
What it costs
- Model calls
- 1 per step, plus 1 observer call per action (typically 6 to 20)
- Latency
- medium
- Complexity
- low
3How do thought, action and observation take turns?
The reasoner writes a thought and one action. The tool runs it. An observer reads the raw result and writes a short, factual observation into the trace. The reasoner reads the whole trace before its next thought. A step limit ends the loop.
- Step 1 of 5
A thought before the first action
Asked "Why did this customer churn?", the reasoner writes "I should first check their support tickets from the last quarter", then the matching tool call.
- Step 2 of 5
The action runs
The tool runs exactly the action written in the trace. Its raw output, possibly long and messy, goes to the observer rather than straight back to the reasoner.
- Step 3 of 5
The result becomes an observation
The observer writes what the result shows, such as "Three tickets about invoice errors, last one unresolved". It adds no interpretation and no next step.
- Step 4 of 5
The trace steers the next thought
The reasoner rereads the whole trace and writes its next thought, which builds on the last observation. Repeated or pointless actions become visible in the log.
- Step 5 of 5
Finish
When the trace supports an answer, the reasoner writes a finish action. At the step limit it must finish with what it has and say what is still unknown.
What each part does
- Task
- The goal or question, the tool list, and optionally a rough plan to follow.
- Reasoner
- Writes one thought, then one action, or a finish action with the answer.
- Trace
- The running log of thought, action and observation for every step.
- Tools
- Runs the chosen action and returns its raw result.
- Observer
- Reads the raw result and states what it shows, in one or two factual sentences.
- Answer
- The final answer, with the full trace that led to it.
- Trace → Reasoner: steps so far
- Reasoner → Trace: thought and action
- Reasoner → Tools: action, steps left
- Tools → Observer: raw result
- Observer → Trace: observation
- Observer → Reasoner: next step
- Reasoner → Answer: finish, or step limit reached
Where it connects
A goal or question that needs several dependent tool calls, with the tool list. A plan, if given, is treated as a guide the reasoner may depart from.
When: The reasoner writes a finish action, or the step limit is reached.
The final answer, the full trace of thoughts, actions and observations, and a flag saying whether the step limit cut it short.
Ordered steps, each with a thought, the exact action, and the observation of its result. Discarded when the run ends unless returned with the answer.
4What do I ask my assistant to set up?
The agents to launch
Reasoner
Work toward the goal one step at a time. Each turn, write one short thought stating what you know and what you need next, then exactly one action from the tool list, or FINISH with your answer. Never repeat an action whose observation is already in the trace.
Sees: The goal, the tool list, any given plan and the full trace. Never raw tool output.
Observer
You receive the raw result of one action. State in at most two sentences what it shows, with exact figures, dates and names. If it is empty or an error, say so. Do not interpret, recommend or guess.
Sees: The action that was run and its raw result. Not the reasoner's thought or the goal.
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 "ReAct" 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] # ReAct Think out loud, act, read what happened, think again. Input: the task above. It must provide: A goal or question that needs several dependent tool calls, with the tool list. A plan, if given, is treated as a guide the reasoner may depart from. If something essential is missing, ask for it before starting. Agents to launch: - Reasoner: Work toward the goal one step at a time. Each turn, write one short thought stating what you know and what you need next, then exactly one action from the tool list, or FINISH with your answer. Never repeat an action whose observation is already in the trace. Context for this agent: The goal, the tool list, any given plan and the full trace. Never raw tool output. - Observer: You receive the raw result of one action. State in at most two sentences what it shows, with exact figures, dates and names. If it is empty or an error, say so. Do not interpret, recommend or guess. Context for this agent: The action that was run and its raw result. Not the reasoner's thought or the goal. Procedure: 1. Write the goal, the tool list with one-line descriptions, and the step limit. If a plan came in, attach it as a guide. 2. Launch the reasoner with the goal and the empty trace. Record its thought and action in the trace. 3. Run the action. Launch the observer on the action and its raw result, and append the observation to the trace. 4. Send the updated trace back to the reasoner and repeat. If the reasoner proposes an action already in the trace, return it with a note to choose differently. 5. At 12 steps, tell the reasoner to finish now with what it knows. Stop rule: Stop when the reasoner writes FINISH, or after 12 actions. At the limit the reasoner must finish and list what remains unknown. Exit: - `answer`, when: The reasoner writes a finish action, or the step limit is reached. Deliver: The final answer, the full trace of thoughts, actions and observations, and a flag saying whether the step limit cut it short. # Final deliverable The final answer, the numbered trace (thought, action, observation per step), and a line stating whether the step limit was reached.
The same thing in code
import operator
from typing import Annotated, 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_STEPS = 12
def search(query: str) -> str:
return f"stub: results for {query}" # plug in your search API
def lookup(entity: str) -> str:
return f"stub: record for {entity}" # plug in your database
TOOLS = {"search": search, "lookup": lookup}
REASONER = ("Work toward the goal one step at a time. Write one short thought (two sentences at most), "
"then exactly one action from the tool list, or FINISH with your answer as input. "
"Never repeat an action whose observation is already in the trace.")
OBSERVER = ("You receive the raw result of one action. State in at most two sentences what it shows, "
"with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.")
class Step(BaseModel):
thought: str
action: str # a tool name, or FINISH
input: str # the tool input, or the final answer
class State(TypedDict):
goal: str
trace: Annotated[list[dict], operator.add]
pending: Step | None
raw: str
answer: str
limit_hit: bool
model = init_chat_model("anthropic:claude-sonnet-5-5")
reasoner_model = model.with_structured_output(Step)
def render(trace: list[dict]) -> str:
return "\n".join(f"{i}. {s['thought']} | {s['action']} | {s['observation']}" for i, s in enumerate(trace, 1)) or "(empty)"
async def reasoner(state: State) -> dict:
actions = [s for s in state["trace"] if s["action"] != "(repeat)"]
limit = len(actions) >= MAX_STEPS
prompt = f"Goal: {state['goal']}\nTools: {', '.join(TOOLS)}\nTrace:\n{render(state['trace'])}"
if limit: # the step limit: finish now and say what is still unknown
prompt += "\n\nStep limit reached. FINISH now and list what remains unknown."
step = Step.model_validate(await reasoner_model.ainvoke([SystemMessage(REASONER), HumanMessage(prompt)]))
if step.action == "FINISH" or limit:
return {"answer": step.input or step.thought, "limit_hit": limit}
if any(s["action"] == f"{step.action}({step.input})" for s in actions):
note = {"thought": step.thought, "action": "(repeat)", "observation": "Already in the trace. Choose differently."}
return {"trace": [note], "pending": None}
return {"pending": step}
async def tools(state: State) -> dict:
step = state["pending"]
assert step is not None
tool = TOOLS.get(step.action)
return {"raw": tool(step.input) if tool else f"error: unknown tool {step.action}"}
async def observer(state: State) -> dict:
step = state["pending"]
assert step is not None
# the observer sees the action and its raw result, not the thought or the goal
action = f"{step.action}({step.input})"
reply = await model.ainvoke([SystemMessage(OBSERVER), HumanMessage(f"Action: {action}\nRaw result:\n{state['raw']}")])
return {"trace": [{"thought": step.thought, "action": action, "observation": reply.text}], "raw": ""}
def after_reasoner(state: State) -> str:
return END if state["answer"] else "tools" if state["pending"] else "reasoner"
builder = StateGraph(State)
builder.add_node("reasoner", reasoner)
builder.add_node("tools", tools)
builder.add_node("observer", observer)
builder.add_edge(START, "reasoner")
builder.add_conditional_edges("reasoner", after_reasoner, ["tools", "reasoner", END])
builder.add_edge("tools", "observer")
builder.add_edge("observer", "reasoner")
graph = builder.compile()
async def run(task: str) -> dict:
state = await graph.ainvoke(
{"goal": task, "trace": [], "pending": None, "raw": "", "answer": "", "limit_hit": False},
{"recursion_limit": 60},
)
return {"answer": state["answer"], "trace": state["trace"], "step_limit_reached": state["limit_hit"]}
Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel
MAX_STEPS = 12
def search(query: str) -> str:
return f"stub: results for {query}" # plug in your search API
def lookup(entity: str) -> str:
return f"stub: record for {entity}" # plug in your database
TOOLS = {"search": search, "lookup": lookup}
AGENTS = {
"reasoner": AgentDefinition(
description="Chooses the next thought and action from the trace.",
prompt="Work toward the goal one step at a time. Write one short thought (two sentences at most), "
"then exactly one action from the tool list, or FINISH with your answer as input. "
"Never repeat an action whose observation is already in the trace.",
),
"observer": AgentDefinition(
description="States what one raw tool result shows.",
prompt="You receive the raw result of one action. State in at most two sentences what it shows, "
"with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.",
),
}
class Step(BaseModel):
thought: str
action: str # a tool name, or FINISH
input: str # the tool input, or the final answer
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:
trace: list[dict] = [] # the trace store: thought, action, observation per step
for n in range(MAX_STEPS + 1):
lines = "\n".join(f"{i}. {s['thought']} | {s['action']} | {s['observation']}" for i, s in enumerate(trace, 1))
prompt = f"Goal: {task}\nTools: {', '.join(TOOLS)}\nTrace:\n{lines or '(empty)'}"
if n == MAX_STEPS: # the step limit: finish now and say what is still unknown
prompt += "\n\nStep limit reached. FINISH now and list what remains unknown."
step = Step.model_validate((await delegate("reasoner", prompt, Step)).structured_output)
if step.action == "FINISH" or n == MAX_STEPS:
return {"answer": step.input, "trace": trace, "step_limit_reached": n == MAX_STEPS}
action = f"{step.action}({step.input})"
if any(s["action"] == action for s in trace):
trace.append({"thought": step.thought, "action": "(repeat)", "observation": "Already in the trace. Choose differently."})
continue
tool = TOOLS.get(step.action)
raw = tool(step.input) if tool else f"error: unknown tool {step.action}"
# the observer sees the action and raw result, never the thought or the goal
seen = await delegate("observer", f"Action: {action}\nRaw result:\n{raw}")
trace.append({"thought": step.thought, "action": action, "observation": seen.result or ""})
raise AssertionError("unreachable")
Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.
from agents import Agent, Runner
from pydantic import BaseModel
MAX_STEPS = 12
def search(query: str) -> str:
return f"stub: results for {query}" # plug in your search API
def lookup(entity: str) -> str:
return f"stub: record for {entity}" # plug in your database
TOOLS = {"search": search, "lookup": lookup}
class Step(BaseModel):
thought: str
action: str # a tool name, or FINISH
input: str # the tool input, or the final answer
reasoner = Agent(
name="Reasoner",
instructions="Work toward the goal one step at a time. Write one short thought (two sentences at most), "
"then exactly one action from the tool list, or FINISH with your answer as input. "
"Never repeat an action whose observation is already in the trace.",
output_type=Step,
)
observer = Agent(
name="Observer",
instructions="You receive the raw result of one action. State in at most two sentences what it shows, "
"with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.",
)
async def run(task: str) -> dict:
trace: list[dict] = [] # the trace store: thought, action, observation per step
for n in range(MAX_STEPS + 1):
lines = "\n".join(f"{i}. {s['thought']} | {s['action']} | {s['observation']}" for i, s in enumerate(trace, 1))
prompt = f"Goal: {task}\nTools: {', '.join(TOOLS)}\nTrace:\n{lines or '(empty)'}"
if n == MAX_STEPS: # the step limit: finish now and say what is still unknown
prompt += "\n\nStep limit reached. FINISH now and list what remains unknown."
step = (await Runner.run(reasoner, prompt)).final_output_as(Step)
if step.action == "FINISH" or n == MAX_STEPS:
return {"answer": step.input, "trace": trace, "step_limit_reached": n == MAX_STEPS}
action = f"{step.action}({step.input})"
if any(s["action"] == action for s in trace):
trace.append({"thought": step.thought, "action": "(repeat)", "observation": "Already in the trace. Choose differently."})
continue
tool = TOOLS.get(step.action)
raw = tool(step.input) if tool else f"error: unknown tool {step.action}"
# the observer sees the action and raw result, never the thought or the goal
seen = await Runner.run(observer, f"Action: {action}\nRaw result:\n{raw}")
trace.append({"thought": step.thought, "action": action, "observation": seen.final_output_as(str)})
raise AssertionError("unreachable")
Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent } from 'ai';
import { z } from 'zod';
const MAX_STEPS = 12;
const model = anthropic('claude-sonnet-5-5');
// stubs: plug in your search API and your database
const TOOLS: Record<string, (input: string) => Promise<string>> = {
search: async (query) => `stub: results for ${query}`,
lookup: async (entity) => `stub: record for ${entity}`,
};
const reasoner = new ToolLoopAgent({
model,
instructions:
'Work toward the goal one step at a time. Write one short thought (two sentences at most), ' +
'then exactly one action from the tool list, or FINISH with your answer as input. ' +
'Never repeat an action whose observation is already in the trace.',
output: Output.object({
schema: z.object({
thought: z.string(),
action: z.string().describe('a tool name, or FINISH'),
input: z.string().describe('the tool input, or the final answer'),
}),
}),
});
const observer = new ToolLoopAgent({
model,
instructions:
'You receive the raw result of one action. State in at most two sentences what it shows, ' +
'with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.',
});
type TraceStep = { thought: string; action: string; observation: string };
export async function run(task: string) {
const trace: TraceStep[] = []; // the trace store: thought, action, observation per step
for (let n = 0; n <= MAX_STEPS; n++) {
const lines = trace.map((s, i) => `${i + 1}. ${s.thought} | ${s.action} | ${s.observation}`).join('\n');
let prompt = `Goal: ${task}\nTools: ${Object.keys(TOOLS).join(', ')}\nTrace:\n${lines || '(empty)'}`;
if (n === MAX_STEPS) prompt += '\n\nStep limit reached. FINISH now and list what remains unknown.';
const { output: step } = await reasoner.generate({ prompt });
if (step.action === 'FINISH' || n === MAX_STEPS) {
return { answer: step.input, trace, stepLimitReached: n === MAX_STEPS };
}
const action = `${step.action}(${step.input})`;
if (trace.some((s) => s.action === action)) {
trace.push({ thought: step.thought, action: '(repeat)', observation: 'Already in the trace. Choose differently.' });
continue;
}
const tool = TOOLS[step.action];
const raw = tool ? await tool(step.input) : `error: unknown tool ${step.action}`;
// the observer sees the action and raw result, never the thought or the goal
const { text } = await observer.generate({ prompt: `Action: ${action}\nRaw result:\n${raw}` });
trace.push({ thought: step.thought, action, observation: text });
}
throw new Error('unreachable');
}
Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.
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
- Thoughts that grow into essays cost tokens without adding direction. Cap each thought at two sentences.
- An observer that adds advice turns into a second reasoner. Keep it to what the result shows.
- A trace that outgrows the context gets truncated silently. For long runs, summarise old steps but keep every observation's facts.
Chain it
Its result can feed
- Reflection conditional
Condition: Use only when the task asks ReAct for a written answer or report, not for actions whose payload is an outcome or for a bare short fact.
- Chain of Verification conditional
Condition: Use only when ReAct's payload is an answer that makes factual claims, not an outcome of executed actions.
- Debate conditional
Condition: Use only when ReAct's payload is an answer to a question or decision, not an outcome of executed actions.
- Constitutional Critique conditional
Condition: Use only when ReAct's payload is a text answer, not an outcome of executed actions.
- Textual Backpropagation conditional
Condition: Build the link only when ReAct's payload is a written answer to the task, not an outcome report of actions it executed.