Design patterns
Building agents · topic building-agents/patterns
Recurring shapes for how an agent thinks and acts. This topic covers reasoning interleaved with acting, reflection on one's own output, explicit planning, the trade-off between planning everything up front and reacting step by step, and breaking large goals into levels of plans.
Concepts
- ReAct
- A pattern where the model alternates a short written reasoning step with an action, observes the result and reasons again. Making the reasoning explicit before each tool call improves tool choice and leaves a readable trace of why the agent did what it did. Most tool-using agent loops are a form of this pattern, whether or not the reasoning is shown to the user. glossary
- Reflection
- Having the model critique its own output, or a second model call critique it, and then revise. Reflection catches errors a single pass misses, especially in code, arguments and formats with checkable rules. It costs extra calls and can loop on trivial edits, so bound the rounds and give the critic concrete criteria rather than asking whether the answer is good. glossary
- Planning
- Having the agent write out the steps to a goal before taking them, as a list it then works through and updates. A written plan improves multi-step tasks, makes progress visible and gives a human a moment to correct course cheaply. Plans go stale as steps reveal new facts, so the pattern includes revisiting the plan, not only following it. glossary
- Plan-then-execute vs reactive
- Two ends of a spectrum. Plan-then-execute decides the whole sequence first and then runs it, which is predictable, cheap to review and brittle when a step surprises. Reactive decides one step at a time from the latest observation, which adapts well and is harder to predict or bound. Most agents mix the two: plan coarsely, react within a step. glossary
- Hierarchical planning
- Breaking a large goal into subgoals, each with its own plan, often handled by its own agent call or subagent with a fresh context. The top level tracks subgoals and their status; lower levels handle detail. It keeps any one context small and focused and maps well onto decomposed specifications, at the cost of coordination and of information lost between levels. glossary
Links
- Builds on: The agent loop and harness
- Leads to: Orchestration and multi-agent
- Competencies drawing on it: Designs and orchestrates multi-agent systems
Lessons
- Plan everything first or react step by step (explanation)
- Writing the plan before taking the steps (tutorial)
- Reasoning before each action (tutorial)
- A second pass that critiques the first (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Plan everything first or react step by step
Unlocks when you finish Plan everything first or react step by step.
Takeaways
- Plan-then-execute decides every step first. It is predictable and easy to review, and a step that surprises can make it wrong. The reactive end decides each step from the result before it, so it adapts, and its length is hard to bound.
- Use a fixed workflow when the steps are known and an agent when the task needs decisions by the model, and start with the simplest that works. Most agents plan coarsely and react inside each step.
- At twelve steps a fixed workflow makes 0 model calls and a plan that only runs makes 1. A check after each step or a reactive loop makes 13, and a critic on each step raises it to 25.
- Hierarchical planning gives each subgoal its own plan, and a subgoal can run in a fresh context, as a Claude Code subagent does. Each level knows only what the handoff gives it. Write down what passes at each handoff of a composition, and test each handoff with a fault.
Example
The calls of six patterns · open in the lesson
Run this, and compare what you see with the output below.
python3 costs.pyPrints the lines below (verified in CI from site/examples/building-agents/plan-or-react/costs.py)
12 tool steps, 3 s per model call, 1 s per tool call pattern model tool seconds fixed workflow 0 12 12 plan then execute 1 12 15 plan, check after each step 13 12 51 reactive 13 12 51 coarse plan of 3 phases 16 12 60 reactive with a critic 25 12 87
Writing the plan before taking the steps
Unlocks when you finish Writing the plan before taking the steps.
Takeaways
- Planning has the agent write the steps to a goal before it takes them, as a list it works through and ticks off.
- A written plan shows a reader where the run is, and in research on math problems a plan-first prompt led to fewer answers that skipped a step.
- A plan can go stale when a step returns a new fact. Give the model the plan and the results after a step, and let it change the steps still to come, at the cost of a model call each time.
- Before the first step, the plan is text and nothing has changed, so a person can correct it cheaply, as Claude Code's plan mode lets you do. For a task of one or two steps a plan costs a call and gives little.
Example
The plan for the kettle · open in the lesson
Run this, and compare what you see with the output below.
python3 agent.py planPrints the lines below (verified in CI from site/examples/building-agents/planning/plan.py)
goal: Replace the broken kettle from order 1042. plan v1: 1. [ ] Look up order 1042 2. [ ] Read the returns policy 3. [ ] Check that a kettle is in stock 4. [ ] Send a replacement kettle 5. [ ] Email the customer that a new kettle has shipped
Reasoning before each action
Unlocks when you finish Reasoning before each action.
Takeaways
- ReAct alternates a short reasoning step with an action and reads the result before it reasons again.
- On a task with a fixed path, the reasoning line adds a readable reason for each call and leaves the calls the same.
- When the next tool depends on an earlier result, the reasoning step can change which tool the model asks for, at the cost of one more line per step that the loop sends back in every round.
- A tool-using loop already alternates decisions and actions, and on Claude a thinking model can reason between tool calls whether or not the loop shows it. A shown thought can leave out what drove the choice, and the round lines are the record of what the loop ran.
Example
The trace with thoughts · open in the lesson
Run this, and compare what you see with the output below.
show(run("Can I still return order 1042?", model=model_reasons))Prints the lines below (verified in CI from site/examples/building-agents/react/return_reasons.py)
user: 'Can I still return order 1042?'
thought: A return depends on when the order arrived, so I look up the order.
round 1: get_order(order_id='1042') -> {'ok': True, 'item': 'kettle', 'days_since_delivery': 12}
thought: It arrived 12 days ago. I need the return window to compare.
round 2: get_policy(topic='returns') -> {'ok': True, 'text': 'Returns and refunds within 30 days of delivery.'}
stop: end_turn
answer: Yes. The kettle arrived 12 days ago, inside the 30-day window.A second pass that critiques the first
Unlocks when you finish A second pass that critiques the first.
Takeaways
- Reflection has a critic read an output and return revision requests, and a reviser apply them, until the critic has none.
- A critic without concrete criteria keeps asking for changes, and models that critique their own answers without an outside signal can make them worse.
- Criteria a draft passes or fails and a cap of two or three rounds keep the loop useful and bounded, and specific feedback beats generic feedback.
- Every round adds model calls that run in sequence. Reflection helps on outputs a critic can check, such as code and formats with rules, and it doesn't suit a flow that must answer fast.
Example
Two faults in one draft · open in the lesson
Run this, and compare what you see with the output below.
python3 agent.py two_faultsPrints the lines below (verified in CI from site/examples/building-agents/reflection/two_faults.py)
draft: Book flights at least 10 days ahead, through the travel desk. round 1: critic -> ['Use only numbers the passage states. 10 is not in it.', 'Quote the sentence you relied on, word for word.'] revised: Book flights at least 14 days ahead, through the travel desk. "Flights are booked through the travel desk at least 14 days ahead." round 2: critic -> [] stop: passed after 2 rounds, 4 model calls
Sources
AEC-04Agentic design patterns: ReAct, reflection, tool use, planning, Agent Engineer Course (course)AEC-06Planning and reasoning: the loop, plan-then-execute, hierarchy, Agent Engineer Course (course)DLAI-11Agentic AI: M1 workflows and autonomy, M2 reflection, M4 evals and error analysis, M5 autonomous agents, DeepLearning.AI (course)Academy building-with-the-claude-apiBuilding with the Claude API, Claude Academy (course)Yao 2022ReAct: Synergizing Reasoning and Acting in Language Models, International Conference on Learning Representations (ICLR 2023), arXiv preprint 2210.03629 (paper)Madaan 2023Self-Refine: Iterative Refinement with Self-Feedback, Advances in Neural Information Processing Systems 36 (NeurIPS 2023), pages 46534 to 46594 (paper)Huang 2023Large Language Models Cannot Self-Correct Reasoning Yet, International Conference on Learning Representations (ICLR 2024), arXiv preprint 2310.01798 (paper)Wang 2023Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models, Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers) (ACL 2023), 2609-2634 (paper)Anthropic effective agentsBuilding effective agents, Anthropic Engineering (reference)