ReAct (tool-use loop)
Also known as: tool-calling loop, the agent loop, function-calling agent, augmented LLM in a loop, multi-step agent (smolagents), agentic loop (Claude Agent SDK)
Intent
Give one model a goal and a set of tools, and let it pick the next action after seeing the result of the previous one. Your code runs each tool call, feeds the result back, and stops the loop when the model gives a final answer or a limit is hit.
The number and order of steps are not written anywhere in advance. They come out of what the model observes along the way.
About the name. Strictly, ReAct is the 2022 prompting method by Yao et al., where the model writes Thought:, Action: and Observation: lines as plain text. Today the word is used loosely for any model that calls tools in a loop, including loops built on native function calling with hidden or no reasoning text. This page covers both, and calls the original "text ReAct" when the difference matters. LangGraph's create_react_agent, for example, is a native tool-calling loop, not a text-parsing one.
Problem
You are building a coding assistant. A developer types: "CI is red on branch feature/x. Fix it."
Nobody knows the steps yet. Which test fails? Which file is at fault? Did a dependency change? How many edit-and-retest cycles will it take? The two obvious designs both fail on this request:
- A fixed pipeline breaks on the first surprise. "Read file A, edit it, run the tests" only works if you already know that file A is the culprit. Here the failing test points to a file you did not plan for.
- A single prompt cannot look or act. Pasting the whole repository overflows the context, and the model still cannot run the tests or save an edit.
- Reasoning without tools invents causes. A model that only thinks will give a confident diagnosis it never checked. In the ReAct paper's error analysis on HotpotQA, hallucination caused 56% of chain-of-thought failures and 0% of ReAct failures, because ReAct based its claims on retrieved text (Yao et al., Table 2).
Solution
Put the model in a loop with tools. On each turn it reads everything so far (the task, its earlier actions and their results) and returns either a tool call or a final answer. Your code, the harness, runs the tool and appends the result. Anthropic describes agents as "typically just LLMs using tools based on environmental feedback in a loop."
On the CI task, a run looks like this (the trace is adapted from the research notes; the repository is invented):
- Look. The model does not know what fails, so it calls
run_tests. Result: 1 failed, 41 passed;test_discountexpected 90.0 and got 0.9. - Decide from what it saw. A ratio instead of a price suggests the discount function. It calls
search_code("def apply_discount")and getsshop/pricing.py:12. - Read. It calls
read_fileand sees line 13:return (100 - pct) / 100. The price factor is missing. - Act. It calls
edit_fileto replace that line withreturn price * (100 - pct) / 100. The tool confirms one occurrence was replaced. - Check. It runs
run_testsagain instead of assuming the edit worked. Result: 42 passed. - Finish. It returns a final answer with no tool call: root cause, the line changed, 42 of 42 tests passing. The harness ends the loop.
The decisions are split between the model and the harness on purpose. The model decides which tool to call, with which arguments, in which order, and when it is done. The harness decides whether a call is allowed, how it runs, how much of the result the model sees, and when to force a stop. Anything you need guaranteed (permissions, limits, valid arguments, truncation) belongs in the harness, not in the prompt.
The closest neighbour is Plan-and-Execute. ReAct chooses only the next action, after seeing the latest result, so it handles surprises well. Plan-and-Execute writes the whole plan up front and replans only when needed, which uses fewer large-model calls and gives you a plan a person can review.
Real-world analogy
A plumber called for a leak. They do not arrive with a fixed list of steps. They look under the sink, feel which pipe is wet, tighten a joint, turn the water back on and watch. If it still drips, they try the next joint. Each move depends on what the last one showed. The plumber is the model, the wrench and the tap are the tools, and "turn the water on and watch" is the verification step.
The analogy stops at limits. A plumber knows when the job is getting out of hand and calls the customer. A model loop does not stop by itself reliably, so the harness has to count turns and money and cut it off.
Structure
- Context. The system prompt (role, rules, how to finish), the tool definitions (name, description, JSON Schema for the arguments) and the message history. It is append-only by default, which is how the model remembers earlier findings and also why it grows with every step.
- Model. Reads the whole context and returns one or more tool calls, or a final answer. How well it picks tools and knows when it is done is mostly a property of the model: Anthropic's SWE-bench post credits much of a score jump to a newer model on an unchanged scaffold.
- Harness. Your code. It checks that the tool exists, that the arguments are valid and that the call is permitted, then runs it and catches errors. It also enforces the limits and records a trace of every step.
- Tools and environment. Functions that read data or change something: the file system, a test runner, a search API, a database. They run in your process, or on the provider's side for hosted tools such as web search.
- Observation. The tool's output or an error message, truncated and formatted, appended as a
tool_result,function_call_outputorToolMessagedepending on the API. Errors go back as observations so the model can try something else. - Final answer. The natural end: a reply with no tool call, an explicit
finishtool, or a structured output that passes validation. - Forced stop. The harness ends the run when max turns, a token or dollar budget, a timeout or repeated identical calls are reached, and returns an error or a partial result.
Prompt generator
Describe one agent: its role, its goal, the tools it can call and how it should prove the work is done. The result is a system prompt for a single tool-calling agent. Paste it as the system prompt of a raw provider API loop, or as the instructions of a prebuilt agent (LangChain create_agent, OpenAI Agents SDK Agent, Claude Agent SDK, Google ADK LlmAgent). The tool descriptions you write here should also go into the tool definitions themselves.
Generated prompt
Highlighted text comes from the form. [Bracketed] text is still to fill in.
Anthropic reports spending more time on tools than on the overall prompt for its SWE-bench agent. Clear tool descriptions, small token-efficient results and actionable error messages matter more than wording here. The turn limit and approval rules in this prompt only inform the model: the harness has to enforce them.
Applicability
Use it when
- The number and order of steps cannot be predicted. Debugging, research, lookups across several systems and data exploration all depend on what the first steps reveal.
- The environment can tell the model whether it is right. Tests, compilers, search results and API responses give ground truth after each step, so the model can check itself instead of trusting its own reasoning.
- Mistakes are recoverable or sandboxed. The loop will take wrong steps along the way. That is fine in a container or a branch, less fine against production data.
- You can afford the latency and cost. Every step is at least one model call plus the tool's run time, and coding tasks often take minutes.
Avoid it when
- The steps are known and stable. A fixed prompt chain or a router is cheaper, faster and fully predictable. Anthropic and smolagents both advise defaulting to no agency when it is enough.
- One call answers the question. Summaries, translation and general knowledge gain nothing from tool round trips, only latency.
- The work splits into many independent parts. Use Parallelization or Orchestrator–Workers. If you want a plan up front, or fewer large-model calls, use Plan-and-Execute.
- Actions are irreversible and there is no approval step. Add Human-in-the-Loop gates first, or keep the agent read-only.
- One agent would combine private data, untrusted content and a way to send data out. Simon Willison calls this the "lethal trifecta": a prompt injection in a web page or email can exfiltrate data. Split the capabilities across agents or remove one of the three.
How to implement
- Check that you need an agent. Anthropic recommends the simplest solution first and notes that a single well-prompted call with retrieval is often enough.
- Design a small set of tools. Start with 3 to 10 well-described tools rather than one per API endpoint. Combine multi-step operations (one
schedule_eventinstead of list-availability plus create), prefersearch_*overlist_*, and avoid tools that overlap. OpenAI suggests keeping the tools available at the start of a turn under about 20, as a soft guideline, and using tool search for larger sets. - Make mistakes hard. Anthropic's SWE-bench agent made errors with relative paths after changing directory; requiring absolute paths fixed it. Its exact-match
str_replaceedit (fail unless the text occurs exactly once) was the most reliable editing method they tried. Use strict schemas and enums so invalid calls cannot be produced. - Return results the model can use. Readable names instead of UUIDs, pagination and truncation with sensible defaults, and a note saying how to narrow the query when output is cut. Claude Code caps tool responses at 25,000 tokens by default. Errors should say what was wrong and show a valid input, not a stack trace.
- Write the loop on the provider API first. With the Anthropic Messages API it is "while
stop_reasonistool_use, run the tools and sendtool_resultblocks". OpenAI's function calling is the same round trip withfunction_call_output. Adopt a framework once you know what it does for you. - Add layered stop conditions before running it on anything real. A natural end (no tool call or a
finishtool), a max-turns cap, a token or dollar budget, a timeout, and a repetition check (the same tool with the same arguments several times in a row, for example three: tell the model to change strategy). Decide what a hard stop returns: an error, a partial answer, or one last tool-free "summarize what you found" call. - Return every tool error as an observation. Unknown tool, invalid arguments, denied permission and exceptions all become short
is_errorresults. The run should never crash on a bad call. - Manage context once runs get long. In order of cost: truncate at the tool, clear old tool results, compact the history near the limit, let the agent keep notes in a file, load content just in time with search tools, and hand large explorations to a sub-agent that returns a summary (Anthropic cites about 1,000 to 2,000 tokens). Cache the stable prefix (system prompt and tool definitions).
- Trace every step and build an eval set. Log the model output, tool name and arguments, result size, errors, tokens, latency and cost. Read transcripts, not only scores, and measure stop reasons and repeat reliability (see below).
The core of the loop, independent of the provider (simplified from the research notes):
for turn in range(max_turns):
resp = model.generate(messages, tools=schemas)
messages.append(assistant(resp))
if not resp.tool_calls:
return success(resp.text)
results = [run_checked(call) for call in resp.tool_calls] # errors become results
messages.append(user(results)) # all results of the turn in one message
if over_budget() or repeating(): return stop_early()
if too_long(messages): messages = compact(messages)
return error_max_turns()
| Framework | How the loop appears | Default step limit |
|---|---|---|
| Raw provider APIs | You write the loop over tool_use / tool_result (Anthropic) or function_call / function_call_output (OpenAI). Anthropic SDKs also have a beta tool runner. | Yours to set |
| LangChain v1 | create_agent(model, tools, ...), extended with middleware (retries, human approval, summarization). | Not stated in our sources |
| LangGraph | create_react_agent: an agent node and a tools node, looping while the message has tool calls. Now deprecated in favour of create_agent; writing the two-node graph by hand is the usual way to customize it. | recursion_limit |
| OpenAI Agents SDK | Runner.run(agent, ...) loops through tool calls and handoffs; tool_use_behavior controls whether a tool result ends the run. | max_turns, 10, raises MaxTurnsExceeded |
| Claude Agent SDK | query() runs the Claude Code loop with built-in tools, permission modes, hooks and automatic compaction. Read-only tools run in parallel, state-changing ones in sequence. | max_turns and max_budget_usd, no limit by default |
| Google ADK | LlmAgent with tools; optional PlanReActPlanner for prompted plan and act sections. | max_llm_calls, 500 |
| smolagents | ToolCallingAgent (JSON calls) or CodeAgent (code actions), ending with the final_answer tool. | max_steps |
| LlamaIndex | FunctionAgent (native calls), ReActAgent (text ReAct, for models without function calling), CodeActAgent. | Not stated in our sources |
Caveat. Framework defaults change quickly. The OpenAI Agents SDK default of 10 turns comes from its reference and the v0.16.0 release notes, and the ADK default of 500 from its runtime docs; re-check both. The legacy LangChain AgentExecutor default often quoted online could not be confirmed and is left out. MCP (Model Context Protocol, announced by Anthropic on 25 November 2024) is not a loop: it is a standard way to expose tools that all of these frameworks can consume.
Variants
Text ReAct (the original)
The model writes Thought:, Action: and Observation: lines in plain text. The harness stops generation at Observation:, parses the action with a regex, runs it and pastes the result. The paper used a frozen PaLM-540B with 1 to 6 examples and three actions for HotpotQA: search[entity], lookup[string] and finish[answer]. It works with any completion model and shows its reasoning, but parsing is fragile and the model may write its own observations. In the paper's ablations, acting without thoughts and thinking without actions both did worse on most tasks.
Native function-calling loop
The model returns structured tool calls through the API, and reasoning may be visible, hidden in a thinking model, or absent. This is what nearly every current framework implements. It supports parallel tool calls in one turn; Anthropic requires all their results in a single user message, or the model learns to stop parallelizing.
Code as action (CodeAct)
The action is a Python snippet run in an interpreter. One step can call several tools, loop and keep variables. The CodeAct authors report up to 20% higher success than JSON or text actions across 17 models, a best-case figure from their own benchmark. smolagents' CodeAgent follows this idea. It needs a secure sandbox.
Hosted loop
The provider runs the loop for its own server-side tools, such as Anthropic's web search and code execution inside one API call. When its internal iteration cap is reached it returns stop_reason: "pause_turn" and you resend to continue.
Hybrid with backoff
Switch methods when one fails. In the paper, ReAct fell back to self-consistent chain-of-thought after 7 steps on HotpotQA (5 on FEVER) without an answer, and the reverse combination used ReAct when sampled answers disagreed. These combinations were the best prompting results in the paper: 35.1 exact match on HotpotQA and 64.6 accuracy on FEVER.
Periodic planning
smolagents' planning_interval and ADK's PlanReActPlanner insert explicit planning steps into the loop. This sits halfway to Plan-and-Execute.
Retries with lessons (Reflexion)
After a failed episode the agent writes down what went wrong and tries again. That is a verifier loop wrapped around the agent, covered in Evaluator–Optimizer.
Agents as tools
One loop exposes another agent as a tool (ADK AgentTool, OpenAI Agents SDK agent.as_tool()). The caller keeps control. This is the building block of a Supervisor.
Pros and cons
Pros
- Handles situations nobody planned for, and recovers from errors by reading the result of each step.
- Grounds answers in observations. In the ReAct paper, hallucination caused none of ReAct's HotpotQA failures, against 56% for chain-of-thought.
- Large gains on interactive tasks in the paper: 71% success on ALFWorld (best of 6) against 37% for an imitation-learning agent.
- Simple to build: a few dozen lines on a function-calling API, and every major framework ships one.
- Inspectable when traced: every action and result is in the log.
Cons
- Not more accurate by itself on knowledge questions: ReAct alone scored 27.4 exact match on HotpotQA against 29.4 for chain-of-thought. These are 2022 PaLM-540B numbers, so read them as directional.
- Cost grows with steps times context size. Each step resends the growing history, so without caching or compaction the cost rises roughly with the square of the step count (our own reasoning, not a measured figure).
- Slow: model calls are sequential, and coding tasks take minutes.
- Errors compound: one wrong early step can derail the run.
- Unpredictable: the path differs every run, which makes testing harder than for a fixed workflow.
- Every side-effecting tool is a safety question, and every observation is a possible prompt injection.
Failure modes
- Repetitive loops
-
The agent repeats the same action with the same arguments. The ReAct paper reports repeated thoughts and actions as a frequent reasoning error, which the authors suspect comes from greedy decoding.
Mitigation: a hard turn and budget cap; detect repeated (tool, arguments) pairs and inject "change strategy or finish"; make error messages specific so retries differ. The OpenAI Agents SDK resets
tool_choiceafter a tool call by default to avoid forced tool loops. - False success
-
The model says it is done without checking. Anthropic's SWE-bench post describes models believing they had succeeded when the hidden tests failed.
Mitigation: require a verification step in the prompt and give the agent the tool to do it; check completion in the harness (run the tests when
finishis called); add an evaluator. - Never stopping
-
The agent keeps exploring: one more search, one more file.
Mitigation: an explicit
finishtool, a budget, prompt guidance on when enough is enough, and a partial result returned at the limit. - Invented tools, arguments or observations
-
The model calls a tool that does not exist, makes up an ID, or guesses a required value it was not given. In text ReAct it may write its own
Observation:line.Mitigation: native function calling with strict schemas and enums; reply "unknown tool, available: ..." as an error; tell the model to ask when information is missing; for text ReAct, a stop sequence at
Observation:. - Bad results derail the reasoning
-
An empty or off-topic search result sends the agent down the wrong path. Uninformative search results caused 23% of ReAct's HotpotQA failures.
Mitigation: better retrieval tools, results that say "no match, try X", and room for the model to reformulate the query.
- Context overflow
-
Large tool outputs crowd out the task and recall degrades as the context grows. After compaction, early instructions can be lost.
Mitigation: truncate and paginate at the tool, clear old results, compact, use sub-agents. SWE-agent collapses observations older than the last 5 into one line; in its ablation, full history scored 15.0% on SWE-bench Lite against 18.0% for the collapsed default. Keep permanent rules in a file that is re-injected on every request.
- Prompt injection through observations
-
A web page, email, file or tool output contains instructions, and the model follows them.
Mitigation: do not combine private data, untrusted content and outbound communication in one agent; restrict consequential actions after reading untrusted content; label tool output as data. Defences are still an open research area, so do not rely on a guardrail classifier alone.
- Unsafe actions
-
Destructive commands, deleted data, unexpected spending.
Mitigation: allow and deny lists, scoped permissions, sandboxes or containers, checkpoints for file edits, and human approval for side effects.
- Cost blow-ups and inconsistent runs
-
Failed runs are the most expensive. SWE-agent's successful runs had a median of 12 steps and $1.21, while failed runs averaged 21 steps and $2.52 (the paper mixes medians and means, so the comparison is approximate). On τ-bench, GPT-4o function-calling agents solved under 50% of tasks, and succeeded on all 8 repeated trials in under 25% of retail tasks.
Mitigation: dollar budgets, early-failure checks, cheaper models for sub-steps, caching; measure reliability over repeated runs (pass^k), not one lucky run.
What to measure
Task success with a verifiable outcome (tests pass, final database state matches the goal). Reliability over repeats. Steps, tool calls, tokens and dollars per task. Error and invalid-argument rates per tool, which point to unclear descriptions. The distribution of stop reasons: how many runs end in success, at max turns, or on budget. Unit-test the tools on their own, and test the loop with a mocked model for the limit and error paths.
Relations with other patterns
- Prompt Chaining: use a chain instead when the steps are known. One step of a chain can contain a small agent loop when that step needs open-ended tool use.
- Routing: a router makes one classification decision, once. An agent makes a routing-like decision (which tool next) on every turn.
- Parallelization: independent calls run at the same time by design. Parallel tool calls are the model choosing to fan out within one turn.
- Evaluator–Optimizer: adds a critic or verifier around or inside the loop. Reflexion-style retries live there.
- Plan-and-Execute: often confused with ReAct. It plans all steps up front and replans when needed, trading adaptivity for fewer large-model calls. ReWOO and LLMCompiler were designed to cut the cost and latency of the ReAct loop.
- Orchestrator–Workers: a lead loop that starts worker loops as sub-agents. Handing an exploration to a sub-agent is also a context-management technique for one agent.
- Supervisor: a ReAct loop whose tools are other agents; control returns to it after every worker call.
- Hierarchical teams: supervisors stacked in levels. Every node is still one of these loops.
- Swarm / Handoffs: a special tool call that transfers control to another loop instead of returning a result. The OpenAI Agents SDK runner handles handoffs inside the same loop.
- Group Chat: several loops share one message thread and a selector picks who speaks next.
- Blackboard: specialists coordinate through a shared store instead of messages. Each one can be a tool-using loop.
- Council / Debate: several agents answer the same question and react to each other's answers. Members may or may not use tools.
- Human-in-the-Loop: approval gates on tool calls, interrupts and permission modes. It plugs into the harness's permission check.
Further reading
- ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2022): the original method, its action space, benchmark tables and error analysis.
- Building effective agents (Anthropic, 2024): workflows versus agents, when to use an agent, and the appendix on designing the agent-computer interface.
- Writing effective tools for agents, with agents (Anthropic, 2025): tool consolidation, namespacing, response formats, error messages and how to evaluate tools.
- Effective context engineering for AI agents (Anthropic, 2025): compaction, tool-result clearing, note-taking and just-in-time retrieval for long loops.
- SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering (Yang et al., 2024): a coding agent built on this loop, with ablations showing which interface choices matter.
- The lethal trifecta for AI agents (Simon Willison, 2025): the prompt-injection risk model for tool-using agents.