First Principles · 12 min mission
Agentic Design Patterns: The Shapes Every Coding Agent Reuses
Learn the tool-agnostic patterns — the agent loop, chaining, routing, fan-out, orchestrator–workers, reflection — and exactly when each one wins.
On this page
Agentic design patterns are named control structures for arranging LLM calls and tools. This guide gives you the decision rule for picking one, the exact shape of each pattern, and the cost each adds — so you can match a task to the minimum structure that solves it.
| Category | Definition | Control lives in | Use when |
|---|---|---|---|
| Workflow | LLMs and tools orchestrated through predefined code paths | Your code | You can pre-map the decision tree; want accuracy, control, lower cost |
| Agent | LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks | The model | Open-ended task where you can't predict the number of steps |
Explore the patterns
Agentic pattern explorer
Six composable shapes for wiring LLMs and tools — from a single self-directing loop to fixed workflows. Pick one and watch control and data flow through it: edges light up in order, parallel branches glow together, and dashed lines are feedback loops. Each comes with a one-line use when.
Single agent loop
AgentOne model runs tools in a loop, reading the result of each action back from the environment before choosing the next. It keeps going — gathering ground truth as it goes — until it decides the task is complete.
Single agent loop: tracing flow, step 0 of 6.
The agent loop: gather → act → verify → repeat
For open-ended tasks, every agent runs the same four-beat loop (Anthropic, verbatim): gather context → take action → verify work → repeat.
- Gather context — read files, run agentic search (
grep/find/tailto pull relevant slices instead of whole files), or delegate to subagents with isolated context windows. - Take action — execute via tools: bash, code generation, file edits, MCP servers.
- Verify work — check the result before declaring done, using ground truth from the environment (tool results, test output).
- Repeat — a failed verification loops back to "take action."
Without ground-truth feedback at each step, the model guesses and compounds errors. Verification is the beat that makes this an agent rather than a script.
# pip install claude-agent-sdk
# Ships the gather -> act -> verify -> repeat loop that powers Claude Code, with
# built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch),
# Subagents (via the Agent tool, isolated context), and MCP support.
# TS equivalent: npm i @anthropic-ai/claude-agent-sdk
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main() -> None:
options = ClaudeAgentOptions(
# Make "verify" deterministic: a rule that either passes or fails.
allowed_tools=["Read", "Edit", "Bash", "Grep"],
system_prompt=(
"Fix the failing test in tests/. After every edit, run "
"'pytest -q' and only stop when it passes. Do not edit or delete "
"tests to make them pass."
),
)
async for message in query(
prompt="The auth test is red after the password-reset change. Make it green.",
options=options,
):
print(message) # gather -> act -> (pytest = verify) -> repeat until green
anyio.run(main)| Method | How it verifies | When to use it | Cost / caveat |
|---|---|---|---|
| Rules-based *(linters, types, tests)* | A defined rule passes or fails; the agent is told which rule failed and why | Anything expressible as a deterministic check — "the best form of feedback" | Cheap and fast; needs the rule to exist |
| Visual feedback | Screenshots / renders the model inspects | Layout, styling, responsiveness — things a test cannot assert | Needs a render step and a vision-capable model |
| LLM-as-judge | A separate model scores against fuzzy criteria | Only when no rule or render can capture the criterion | "Heavy latency tradeoffs" for marginal gains — last resort |
| Pattern | Shape | When it wins (verbatim) | Example |
|---|---|---|---|
| Prompt chaining | Sequence of steps; each LLM call processes the previous output; optional programmatic gates between steps | Task can be "easily and cleanly decomposed into fixed subtasks" | Outline → gate-check outline meets brief → write doc; copy → translate |
| Routing | A classifier (LLM or classical) sorts input, then sends it to a specialized handler | "Distinct categories that are better handled separately, and where classification can be handled accurately" | Support desk: general / refund / tech → different flows; easy→Haiku, hard→Sonnet |
| Parallelization — sectioning | "Breaking a task into independent subtasks run in parallel" | Subtasks parallelizable for speed | One model answers while another screens for inappropriate content |
| Parallelization — voting | "Running the same task multiple times to get diverse outputs" | Multiple attempts/perspectives needed for higher-confidence results | Several prompts review code for vulns; vote with a threshold |
Parallelization vs orchestrator–workers
Both fan work across multiple LLM calls. The distinction is who draws the subtasks:
- Parallelization runs pre-defined subtasks — you decided the branches in code before the model ran.
- Orchestrator–workers is model-driven: "a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results," and "the subtasks aren't pre-defined, but determined by the orchestrator based on the specific input."
Use orchestrator–workers for "complex tasks where you can't predict the subtasks needed" — Anthropic's example is "coding products that make complex changes to multiple files each time." If subtasks are fixed, hardcode and parallelize; if they vary per input, let the orchestrator decide.
Orchestrated fan-out, live
Orchestrated fan-out
One orchestrator drives every worker; nothing flows worker-to-worker. Pick a substrate per lane, give it a prompt, and hit Run. Each lane fills in parallel at its own pace with a live token and cost meter — then a synthesis node merges the results and surfaces only the cross-module conflicts.
orchestrator
main thread · one-directional fan-out
idle · cap $0.500
idle · cap $0.500
idle · cap $0.500
synthesis
Waits for every worker, then merges in the main thread.
The orchestration call
Idle. Orchestrator ready to fan out across 3 worker lanes.
Evaluator–optimizer (reflection)
"One LLM call generates a response while another provides evaluation and feedback in a loop." The broader literature calls this reflection (Andrew Ng's taxonomy) — the same shape under a different name.
It is "particularly effective when we have clear evaluation criteria, and when iterative refinement provides measurable value." Two signals it fits: a human articulating feedback demonstrably improves the output, and the LLM can produce that critique itself. Anthropic's examples: literary translation; multi-round search where an evaluator decides whether more searching is warranted. With fuzzy criteria you get an expensive loop that polishes nothing — prefer deterministic verification first.
Plan-and-execute vs ReAct: when the model thinks
Plan-and-execute (LangChain)
Planner generates a full multi-step plan up front; executor(s) carry out each step (often smaller, cheaper models); a replanning step decides whether to finish or generate a follow-up plan.
Three stated wins: speed (intermediate steps skip the big model), cost (large model "only called for (re-)planning steps"), quality (planner must "explicitly think through all the steps").
Footgun: no replanning = rigid — a wrong initial plan executes faithfully to a wrong answer.
ReAct (Yao et al.)
"The LLM only plans for 1 sub-problem at a time" — think → act → observe, one tool call per turn, adapting continuously.
Wins on simple, dynamic tasks solvable in a few tool calls where each next step depends on the last observation.
Anthropic folds planning into the agent category and states a core principle verbatim: "Prioritize transparency by explicitly showing the agent's planning steps."
Long-running agents: the plan → execute → review structure
Anthropic's long-running-agents harness operationalizes plan/execute/review as a planner / generator / evaluator structure with durable artifacts that survive a context reset:
- An initializer agent runs once: writes an
init.shscript, aclaude-progress.txtprogress file, and an initial git commit. - A coding agent makes incremental progress session-by-session against a feature list (JSON) of 200+ granular, testable features marked passing/failing.
- The agent verifies as an engineer would: run the dev server via
init.sh, do real end-to-end testing (e.g. a Puppeteer MCP server), and mark a feature done only when it actually works.
| If the task… | Use | Because |
|---|---|---|
| is solved by one augmented LLM call | No pattern | Simplest solution first; patterns add latency and cost |
| splits into fixed, clean sequential steps | Prompt chaining | Each easier subtask raises accuracy; gates catch drift |
| has distinct input categories handled best separately | Routing | Specialized prompts per class; cheap model for easy inputs |
| splits into fixed independent subtasks, or needs many attempts | Parallelization *(section / vote)* | Run them at once for speed, or vote for confidence |
| has subtasks you cannot predict until you see the input | Orchestrator–workers | The model decides the subtasks at runtime |
| has a clear pass/fail check and improves with iteration | Evaluator–optimizer | A critique loop measurably refines the output |
| is open-ended with no predictable number of steps | Agent *(loop / plan-execute)* | You can't hardcode the path; the model needs ground-truth feedback |
Knowledge check
You build a coding feature that changes an unpredictable number of files — sometimes two, sometimes a dozen, depending on the request. Which pattern fits, and why?
Reach the end and this star joins your charted sky.