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 red CI task goes to a fixed pipeline, which edits the wrong file, and to a model without tools, which invents a cause it never checked. CI is red "fix feature/x" Fixed pipeline read file A, edit it, run tests One call, no tools reasons about the code from memory Wrong file the bug was elsewhere Invented cause never ran the tests
Both designs fix the path before anyone has seen the failing test. What is missing is a way to look, decide, act and check again.

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):

  1. Look. The model does not know what fails, so it calls run_tests. Result: 1 failed, 41 passed; test_discount expected 90.0 and got 0.9.
  2. Decide from what it saw. A ratio instead of a price suggests the discount function. It calls search_code("def apply_discount") and gets shop/pricing.py:12.
  3. Read. It calls read_file and sees line 13: return (100 - pct) / 100. The price factor is missing.
  4. Act. It calls edit_file to replace that line with return price * (100 - pct) / 100. The tool confirms one occurrence was replaced.
  5. Check. It runs run_tests again instead of assuming the edit worked. Result: 42 passed.
  6. 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

The task enters the context; the model reads the context and either returns a final answer or a tool call; the harness validates and runs the tool against the environment; the observation is appended to the context and the loop repeats until the model finishes or a limit forces a stop. done tool call append limit hit Task Context prompt, tools, history Model picks the next step Final answer no tool call Harness validate, permit, run Tools files, tests, web Observation result or error, trimmed Forced stop turns, budget, time 1 2 3 4 5 6 7
The accent arrows are the loop: context, model, harness, observation, back to context. Dashed arrows carry results. The loop ends either when the model answers without a tool call or when the harness hits a limit.
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Observation. The tool's output or an error message, truncated and formatted, appended as a tool_result, function_call_output or ToolMessage depending on the API. Errors go back as observations so the model can try something else.
  6. Final answer. The natural end: a reply with no tool call, an explicit finish tool, or a structured output that passes validation.
  7. 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.

Tools one row per tool; keep the set small
Tool-call style

Generated prompt

Highlighted text comes from the form. [Bracketed] text is still to fill in.

The prompt is the smaller half

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

Avoid it when

How to implement

  1. 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.
  2. 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_event instead of list-availability plus create), prefer search_* over list_*, 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.
  3. 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_replace edit (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.
  4. 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.
  5. Write the loop on the provider API first. With the Anthropic Messages API it is "while stop_reason is tool_use, run the tools and send tool_result blocks". OpenAI's function calling is the same round trip with function_call_output. Adopt a framework once you know what it does for you.
  6. Add layered stop conditions before running it on anything real. A natural end (no tool call or a finish tool), 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.
  7. Return every tool error as an observation. Unknown tool, invalid arguments, denied permission and exceptions all become short is_error results. The run should never crash on a bad call.
  8. 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).
  9. 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 support (check current docs before use)
FrameworkHow the loop appearsDefault step limit
Raw provider APIsYou 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 v1create_agent(model, tools, ...), extended with middleware (retries, human approval, summarization).Not stated in our sources
LangGraphcreate_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 SDKRunner.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 SDKquery() 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 ADKLlmAgent with tools; optional PlanReActPlanner for prompted plan and act sections.max_llm_calls, 500
smolagentsToolCallingAgent (JSON calls) or CodeAgent (code actions), ending with the final_answer tool.max_steps
LlamaIndexFunctionAgent (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_choice after 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 finish is called); add an evaluator.

Never stopping

The agent keeps exploring: one more search, one more file.

Mitigation: an explicit finish tool, 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

Further reading