AI agents · Five patterns · Arrow keys to step
Designing an agent graph
An agent system is a graph: model calls, tools, routers, checks, memory and people, joined by handoffs that carry state. Pick a pattern, step a token of state through it, and click any node to see what it reads and what it writes.
One agent, some tools
step 1 of 13
One model in a loop: it reads the task, calls a tool, reads what came back, and decides what to do next until it decides it is done.
← → step through · Tab to a node, Enter to pin it · Esc to unpin
A task arrives
The token now holds
"Dates before 1970 come out wrong. Fix it."
The token is here
Person
Person
Asks for the work and gets the answer.
- Reads
- The answer
- Writes
- The task
Asks for the work, and approves what cannot be undone.
When to use it
Start here. One model in a loop with a few well-described tools handles most tasks, and it is the easiest graph to debug: every decision is made in one place.
Cost and latency
One model, so one bill and one prompt cache. Every turn resends the history, so a long task gets dearer per turn as it goes, and each turn waits on the one before.
How it fails
The model decides when it is finished. It can stop early, retry a failing tool forever, or never run the tests at all.
Where code should hold the gate
The tests here are just another tool, and the model is the one reading their output. Move them out of the loop into a gate the run must pass, and "done" stops being the model's opinion.
Model calls in this walk
- 6 × Sonnet$2 in / $10 out per million
- 5 × tools and gates no tokens
At list prices an Opus token costs 40× a Haiku token, so which tier sits on the busiest node matters more than how many nodes there are.
The graph as text
Nodes
- Person (person): Asks for the work and gets the answer. Reads: The answer. Writes: The task.
- Notes (memory): The project's conventions, loaded into the context before the first turn. Writes: Conventions, commands.
- Agent (Sonnet): Plans, calls tools, reads their results, and decides when the task is finished. Reads: The task, the notes, every tool result so far. Writes: Tool calls, then the answer.
- Search (tool): Finds code by name or text. Reads: A query. Writes: Matching files and lines.
- Run tests (tool): Runs the test suite. Here it is only a tool: the model reads the output and decides what it means. Reads: A command. Writes: Test output.
- Edit file (tool): Applies a change to a file. Reads: A patch. Writes: The changed file.
Handoffs
- Person to Agent: The task
- Notes to Agent: Conventions and commands (memory)
- Agent to Search: A query
- Search to Agent: Matches
- Agent to Run tests: Run the suite
- Run tests to Agent: Test output
- Agent to Edit file: A patch
- Edit file to Agent: Done
- Agent to Person: The answer
The walk
Nodes and edges
Draw any agent system and the same six kinds of node turn up. A model call reads its context and decides or writes something. A tool is code the model asks to run. A router picks where an input goes next. A gate is plain code that passes or fails the work. Memory is whatever outlives a single call, and a person asks for the work and approves what cannot be undone.
The edges matter as much as the nodes. Every handoff carries some state, and the design question at each one is how little it can carry. A worker that hands back a three-line summary instead of every file it read keeps the next model's context small, cheap and sharp.
Choosing a pattern
Start with the simplest graph that could work, which is usually one model with a few good tools, and add nodes only when a measured failure asks for one. A router earns its place when requests really do come in different kinds. Workers earn theirs when the job splits into independent pieces. An evaluator earns its place when there is a rubric and a first draft is usually close.
Each node you add is another call to pay for, another place to fail, and another handoff where state can get lost. More agents is not more intelligence; it is more plumbing.
Where code should hold the gate
A model asked whether its own work is finished tends to say yes. So every decision a script can make (does it compile, do the tests pass, is the data well formed) should be a gate in code, not a model's opinion. Gates are free, fast, and cannot be talked round. Models hold only the checks that need judgment or eyes, and they hold them against criteria written down before the work began.
People belong at the steps that cannot be undone. Ask them once, late, with everything they need to say yes at a glance.
What to take with a pinch of salt
- The walks are scripted. Each one is written to show how its pattern behaves, including a failure where one teaches something. Nothing on this page calls a model.
- Tiers are illustrative. The patterns cast Opus, Sonnet and Haiku the way /lab/agents does. Prices are list prices as of October 2026, and no token counts are shown because there is no real run to count.
- Real graphs blur. A single agent often spawns workers for a moment, and a feature loop contains an evaluator. The patterns are parts to combine, not boxes to pick one of.
Sources
- Anthropic 2024 · E. Schluntz and B. Zhang, "Building effective agents", Anthropic (2024): routing, orchestrator–workers and evaluator–optimizer
- Yao et al. 2022 · S. Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models" (2022): the single agent's think, act, observe loop
- Madaan et al. 2023 · A. Madaan et al., "Self-Refine: Iterative Refinement with Self-Feedback" (2023): a draft, a critique, a revision
- Anthropic pricing · Claude API list prices per million tokens, as of October 2026