Agent Architectures: ReAct, Tool Use, Planning
Jump to section
Why architecture matters
You can have the most intelligent model in the world, but if you wrap it in a bad architecture, you get a bad agent. Architecture determines how an agent thinks, decides, and acts. In this lesson, we will look at three fundamental approaches.
ReAct: Reasoning + Acting
ReAct (Reasoning and Acting) is the most widely used agent architecture. The principle is simple: the model alternates between thinking and acting. Thought (I need to figure out...) -> Action (call a tool) -> Observation (see the result) -> Thought (based on the result, what next) -> Action...
Task: Find out what framework the project uses and what dependencies it has
Thought: I need to check the project structure. I'll start by reading package.json.
Action: read_file("package.json")
Observation: { "dependencies": { "next": "16.x", "react": "19.x" ... } }
Thought: It's Next.js 16 with React 19. Let me check tsconfig for more info.
Action: read_file("tsconfig.json")
Observation: { "compilerOptions": { "target": "ES2022" ... } }
Thought: I have enough info. The project uses Next.js 16, React 19, TypeScript.
Answer: The project uses Next.js 16 with React 19 and TypeScript...ReAct is the foundation of Claude Code, Cursor, and most modern coding agents. When you see Claude Code reading files, thinking, and writing code, you are watching ReAct in action.
Advantages of ReAct: transparent reasoning (you see why the agent does what it does), good for tasks where the plan changes based on results, simple to implement. Disadvantages: can loop (thought -> action -> thought about the same thing), each step costs tokens/money, slower than direct approaches.
Plan and Execute
An alternative approach: the agent first creates a plan of all steps, then executes them. Unlike ReAct where the agent thinks after each step, here it thinks at the beginning and executes sequentially.
Task: Add authentication to the application
Plan:
1. Analyze existing app structure
2. Install auth library (next-auth)
3. Create auth API route
4. Add login/logout components
5. Protect existing pages
6. Add tests
7. Run build and verify
Execution:
Step 1: read_file("src/app/layout.tsx") -> OK, got the structure
Step 2: run_command("npm install next-auth") -> OK
Step 3: write_file("src/app/api/auth/[...nextauth]/route.ts") -> OK
...Advantages: more efficient for tasks with a clear procedure, fewer thinking steps = lower costs, easier for users to track progress. Disadvantages: the plan might prove wrong during execution, less flexible than ReAct, requires sufficient initial context.
Tool Use (Function Calling)
Tool use is not an architecture by itself, but the fundamental building block of all agent architectures. The model receives descriptions of available tools and decides which to use. Key: the model does NOT execute the tool — it returns a structured request (tool name + parameters) and your code executes it.
# Tool definition for Claude API
tools = [{
"name": "read_file",
"description": "Reads the contents of a file at the given path",
"input_schema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Path to the file"
}
},
"required": ["path"]
}
}]
# Model decides to use a tool
# and returns: {"name": "read_file", "input": {"path": "src/app/page.tsx"}}
# Your code reads the file and sends the result back to the modelAs of March 2026, all three major providers (Anthropic, OpenAI, Google) offer native tool use/function calling. The API differs slightly, but the principle is the same: describe your tools, the model chooses which to use, and you execute it.
Advanced patterns
Reflection
The agent evaluates its own work after completing a task and fixes mistakes. For example: writes code -> runs tests -> tests fail -> analyzes the error -> fixes code -> runs tests again. This is common in coding agents like Claude Code.
Tool search
When an agent has access to hundreds of tools, not all are sent in context. Instead, the agent first searches for relevant tools. Anthropic offers a Tool Search Tool that saves up to 85% of context compared to traditional approaches.
Parallel tool calls
An agent can call multiple tools simultaneously — for example, reading 5 files in parallel. This dramatically speeds up execution, especially for I/O-bound operations.
How to choose an architecture
- ReAct: when you do not know all steps in advance, the task requires exploration, or the plan changes based on results
- Plan and Execute: when the task is clearly defined, steps are predictable, and you want to minimize costs
- Hybrid: plan at the start, but with the ability to replan after each step — the most commonly used approach in practice
When choosing between ReAct and Plan-and-Execute, ask: 'Do I know all the steps upfront?' If yes, Plan-and-Execute is more efficient. If the task requires exploration (e.g., debugging, code discovery), ReAct handles the unknown better.
You have this task: 'Go through the entire codebase, identify all TODO comments, and create GitHub issues from them with assigned priority and labels.' 1. Which approach do you choose — ReAct, Plan and Execute, or hybrid? Justify your choice. 2. What tools will the agent need? 3. Draw a flow diagram of the agent loop for this task. 4. Where can the agent fail and how do you handle that?
Hint
This task has clearly defined steps (scan -> parse -> create issues), so Plan and Execute is a natural choice. But what if you encounter a TODO without enough context for prioritization? That is where you need ReAct flexibility.
Take the ReAct trace from the lesson example and extend it with a realistic failure scenario. Write out a complete ReAct trace (Thought -> Action -> Observation) for this task: 'Find the database configuration in this project and check if connection pooling is configured.' Your trace should include: 1. At least 5 Thought-Action-Observation cycles 2. At least one dead end (file not found, wrong assumption) 3. The agent recovering from the dead end and trying a different approach 4. A final answer with specific findings Write the full trace in the format shown in the lesson.
Hint
A realistic trace would start with checking common config files (settings.py, .env, config/database.yml), then might need to grep for keywords like 'pool', 'connection', 'database'. Include a moment where the agent looks in the wrong place first.
Take this task: 'Refactor all API endpoints in the project to use consistent error response format.' Design the agent approach using BOTH architectures: 1. Plan and Execute version: - Write a complete plan (numbered steps) - Identify where the plan might break - Estimate number of tool calls needed 2. ReAct version: - Write the first 3 Thought-Action-Observation cycles - Show how the agent adapts when it discovers unexpected patterns - Estimate number of tool calls needed Compare: which would complete faster? Which would produce better results? Which would cost less in API calls?
Hint
Plan-and-Execute would be more efficient IF all endpoints follow the same pattern. But in real codebases, endpoints are often inconsistent — some use exceptions, some return dicts, some use custom classes. ReAct handles this variation better.
- ReAct = alternating reasoning and acting — most flexible, foundation of most agents
- Plan and Execute = plan upfront, then execute — more efficient for clear tasks
- Tool use = model selects tools, your code executes them — building block of all architectures
- Hybrid approaches are most common in practice — plan + ability to replan
- Architecture determines agent quality more than model intelligence
In the next lesson, we dive into Building an Agent with Claude API — a technique that gives you a clear edge. Unlock the full course and continue now.
2/7 complete — keep going!