How to Build a ReAct Agent from Scratch

The ReAct pattern — short for Reasoning and Acting — is one of the most influential agent architectures in practical AI development. Published in a 2022 paper by Yao et al., it describes a simple but powerful idea: interleave the model’s reasoning steps with its action steps, making both visible and traceable. Rather than having the model jump straight from a question to a tool call, ReAct asks the model to first think about what it knows and what it needs to find out, then act, then observe the result, then think again. This alternation of thought and action produces agents that are more transparent, more reliable, and easier to debug than agents that reason silently.

The ReAct Loop: Thought, Action, Observation

A ReAct agent operates on a strict three-step cycle that repeats until the agent reaches a final answer:

  • Thought — the model reasons about the current state: what do I know, what do I still need to find out, and what should I do next?
  • Action — the model decides which tool to call and with what input
  • Observation — the result of the tool call is fed back to the model as the next input

This cycle continues until the model produces a “Final Answer” action rather than a tool call. The key insight is that the Thought step is explicit and logged — you can read exactly what the model was reasoning when it made each decision. This transparency makes ReAct agents far easier to debug than agents where reasoning is implicit. When something goes wrong, the thought trace tells you where the model’s reasoning diverged from correct.

Why ReAct Works Better Than Direct Action

The alternative to ReAct is having the model decide on actions directly without an explicit reasoning step. This works for simple tasks but degrades quickly on tasks requiring multiple steps, tasks where the right tool depends on earlier results, and tasks where the model needs to track partial information across steps. The explicit Thought step gives the model a “scratchpad” to work on — it can reason about what it has found so far, notice gaps, and plan the next step more carefully than it can when forced to jump directly to an action. Studies show that ReAct reduces hallucination and incorrect tool use on multi-step tasks compared to direct action approaches, because the explicit reasoning step catches many errors before they become actions.

Figure 1 — ReAct agent: thought-action-observation cycle

Thought Reason about state & next step Action Call tool with chosen input Observation Tool result added to context Final Answer or loop back to Thought ← repeat until final answer reached

Implementing a ReAct Agent from Scratch

A ReAct agent is built around a prompt that instructs the model to follow the Thought/Action/Observation format, and a parser that extracts the action from the model’s output. The prompt is the most important component — it defines the format the model should follow and provides examples of the cycle. A typical ReAct system prompt explains: you have access to these tools (list them with descriptions), always start your response with a Thought explaining your reasoning, then either call a tool or provide a Final Answer.

The parser reads the model’s response and identifies whether it contains a tool call or a final answer. If it finds a tool call, it extracts the tool name and input, executes the tool, formats the result as an Observation, appends it to the conversation, and loops. If it finds “Final Answer:”, it extracts the answer text and returns it. The implementation is straightforward — the complexity lies in prompt design and handling the edge cases where the model does not follow the expected format.

Format Enforcement

A practical challenge with ReAct is that models occasionally produce responses that do not follow the expected Thought/Action format — they might skip the Thought step, produce malformed action syntax, or start generating a Final Answer mid-reasoning. Robust ReAct implementations handle these cases gracefully:

  • If the response contains no recognisable action but is not a Final Answer, feed it back to the model with a prompt reminding it to follow the format
  • If the action syntax is malformed, return a parsing error as an Observation and let the model try again
  • Cap retries at 2–3 attempts per step to prevent infinite correction loops

Modern frontier models (Claude 3.5+, GPT-4o) follow the ReAct format reliably with a clear system prompt. Smaller models and older versions require more robust parsing and more explicit format examples in the prompt.

Tool Design for ReAct Agents

ReAct’s explicit reasoning makes tool design errors more visible than in other agent patterns — you can see in the Thought trace when the model is confused about which tool to use or what a tool returns. This visibility is useful for improving tool definitions iteratively. When you see the model consistently reasoning incorrectly about a tool, the fix is usually in the tool description rather than the agent loop. Common improvements: making the tool’s return format explicit in the description (“returns a list of up to 10 results, each with title, URL, and snippet”), specifying when to use the tool vs alternatives (“use this for current information; use the knowledge base tool for established facts”), and adding examples of correct tool input format.

ReAct vs Chain-of-Thought

ReAct is often compared to Chain-of-Thought (CoT) prompting, which also asks the model to show its reasoning. The key difference is that ReAct interleaves reasoning with real-world tool use — the Observation steps bring in actual information from external sources rather than keeping everything within the model’s reasoning. CoT is useful for tasks the model can solve with its existing knowledge and careful step-by-step reasoning. ReAct is necessary when solving the task requires information or actions beyond the model’s training knowledge — searching the web, querying a database, running code, or interacting with external services. In practice, most production agents use ReAct-style reasoning because they need to interact with external tools, while CoT remains useful for reasoning-heavy tasks that do not require external data.

Handling Long ReAct Traces

For tasks that require many steps, the accumulated Thought/Action/Observation trace can grow very long and eventually exceed the model’s context window. Two strategies manage this: trace compression, where older observations are summarised and replaced with a shorter summary (“Searched for X, found Y. Searched for Z, found W.”) to free up context space; and fresh-context continuation, where the essential state from the current trace is extracted and used to seed a new conversation when the trace gets long. Both approaches work well; trace compression is simpler to implement and preserves more detail, while fresh-context continuation produces cleaner reasoning in the new session by avoiding attention dilution from very long histories.

When to Use ReAct

ReAct is the right pattern when you want transparent, debuggable agent behaviour on tasks that require multiple tool calls and where understanding the model’s reasoning matters. It is particularly valuable during development — the thought trace makes it easy to see what the model understood about the task and where it went wrong. For production systems where the reasoning trace is less important than speed, other patterns like direct tool calling (without explicit thought steps) may be more efficient. ReAct’s overhead — the additional tokens from the Thought steps — is a real cost on high-volume systems, though for most use cases the improvement in reliability and debuggability justifies it. If you are building your first agent or debugging a complex one, start with ReAct.

ReAct remains one of the foundational agent patterns in practical AI engineering because it solves a real problem elegantly: it makes the agent’s reasoning visible and interruptible without requiring complex architectural changes. The implementation is simple enough to build in a few hours, the debugging experience is substantially better than opaque agent loops, and the reliability improvements on multi-step tasks are well-documented. For developers building agents that need to be understood, maintained, and improved over time, ReAct is the natural starting point.

ReAct in Production: Practical Considerations

Deploying a ReAct agent in production introduces considerations that do not arise in development. Latency is the most visible one — every Thought step adds tokens and therefore time and cost. For tasks where users expect near-real-time responses, the multi-step ReAct loop may be too slow. A common mitigation is streaming the Thought steps to the user as they are generated, so the user sees the agent working rather than waiting for a complete response — this does not reduce latency but significantly improves perceived responsiveness. Cost is the other production concern: complex tasks with many steps can accumulate substantial token counts across the Thought/Action/Observation trace. Monitor token usage per completed task during development and set alerts in production when costs per task exceed expected ranges, since a confused agent looping through many steps can be expensive before it times out.

ReAct with Multiple Tools: Tool Selection Quality

As the number of available tools grows, the quality of the model’s tool selection in the Action step becomes the main determinant of agent performance. With 2–3 tools, the model almost always selects the right one. With 10+ tools, selection errors become more common — the model picks a plausible-sounding tool that is not the best fit, producing results that are technically valid but unhelpful. Two strategies improve tool selection quality at scale: tool descriptions that explicitly state when NOT to use a tool (“use this for live web search; for established facts that do not change, use the knowledge base tool instead”), and tool grouping where related tools are presented together with a brief explanation of when each is appropriate. The Thought step helps here too — asking the model to reason about which tool is most appropriate before calling one produces better selection than jumping straight to an action, which is another reason the explicit Thought step improves ReAct performance on complex tasks with rich tool sets.

Leave a Comment