Foundations
Pattern 02 of 26
ReAct Pattern
Most agent bugs live in one of three places
ReAct is the loop that most agents are actually running, even when the framework does not call it that. The model reasons about what to do, calls a tool, reads the result, then reasons again. That cycle repeats until the task is done or something breaks. Once I understood this I stopped debugging agent failures as mysteries and started treating them as broken steps in a sequence. That shift matters a lot.
Why it matters
When a Claude Code session goes sideways, it went wrong at a specific Thought, Action, or Observation. Knowing there is a loop to inspect changes how you approach debugging entirely. It is the difference between "the agent failed" and "the agent reasoned wrong after this specific tool call." The second one you can actually fix.
Deep Dive
ReAct, which stands for Reasoning and Acting, came from a 2022 paper by Shunyu Yao and collaborators at Google and Princeton. It was published at ICLR 2023. The central idea is to interleave reasoning traces with tool calls, so the model writes out what it is thinking before it acts and again after it gets a result back. That sounds small. It is not. Making the reasoning visible means you can read an agent transcript and see exactly where the decision process went wrong, rather than just seeing a wrong final output with no explanation for how it got there.
The pattern addressed a real failure mode that existed before it. Models that acted without reasoning would take wrong turns and keep going, accumulating errors. Models that reasoned without acting would loop on analysis without making progress. ReAct gives you the Thought step, where the model reasons about the current situation; the Action step, where it calls a tool or returns an answer; and the Observation step, where it reads the tool result. The cycle continues from there. What makes this useful is that each step is inspectable, so when the loop goes wrong you can find the exact point.
Most agent frameworks implement this as their default execution model, sometimes under different names. LangGraph agent nodes, LlamaIndex agent runners, the OpenAI Assistants API, Claude Code itself: they all follow this basic structure. The failure modes are consistent across all of them. A bad Thought leads to a wrong Action. A misread Observation causes the next Thought to go in the wrong direction. A tool that returns an unexpected format breaks the Observation step entirely. Once you know the loop, you know where to look. That is most of debugging.