Agentic Design Patterns: The Shapes Every Coding Agent Reuses

This is an adapted excerpt from a guide in my AI Knowledge Hub. The full interactive version is linked at the end. Agentic design patterns are named control structures for arranging LLM calls and tools. This post 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. Everything here is model-agnostic and grounded in Anthropic's Building Effective Agents and the Claude Agent SDK. Workflow vs. agent: the split that decides everything Anthropic divides all agentic systems into two categories, and the split decides every downstream tradeoff: | 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 | Every pattern composes one unit: the augmented LLM — an LLM enhanced with retrieval, tools, and memory. It generates its own search queries, selects tools, and decides what to retain. If a single augmented LLM call solves the task, stop — no pattern required. The escalation rule is the whole game: find "the simplest solution possible, and only increasing complexity when needed" — which "might mean not building agentic systems at all." Agentic systems trade latency and cost for better task performance, so only escalate when a specific failure mode forces it. The agent loop: gather → act → verify → repeat For open-ended tasks, every agent runs the same four-beat loop: - Gather context — read files, run agentic search ( grep /find /tail to 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. Here it is wired up with the Claude Agent SDK: # pip install claude-agent-sdk # 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) Three ways to verify, best first | 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 | The four workflow patterns | Pattern | Shape | When it wins | 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 | | 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→cheap model, hard→frontier model | | 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 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. Mind the token cost. In Anthropic's research system, a Claude Opus 4 lead with Claude Sonnet 4 subagents outperformed single-agent Opus 4 by 90.2% on their internal research eval — but "agents typically use about 4× more tokens than chat interactions, and multi-agent systems use about 15× more tokens" than chats. Multi-agent only pays off for valuable, parallelizable, breadth-first work exceeding one context window. The scaling rule from the lead prompt: simple fact-finding = 1 agent with 3–10 tool calls; direct comparisons = 2–4 subagents with 10–15 calls each; complex research = more than 10 subagents. Evaluator–optimizer (reflection) "One LLM call generates a response while another provides evaluation and feedback in a loop." The broader literature calls this reflection — 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. 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: a 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 wins: speed (intermediate steps skip the big model), cost (the large model is only called for re-planning steps), and quality (the planner must explicitly think through all the steps). Footgun: no replanning means a wrong initial plan executes faithfully to a wrong answer. ReAct: the LLM only plans for one sub-problem at a time — think → act → observe, one tool call per turn, adapting continuously. It wins on simple, dynamic tasks solvable in a few tool calls where each next step depends on the last observation. For long-running work, Anthropic's harness operationalizes plan/execute/review as a planner / generator / evaluator structure with durable artifacts that survive a context reset: an initializer agent writes an init.sh script, a claude-progress.txt file, and an initial git commit; a coding agent makes incremental progress against a feature list (JSON) of 200+ granular, testable features marked passing/failing; and it verifies as an engineer would, marking a feature done only when it actually works. One hard rule: never let an agent delete its own tests — "it is unacceptable to remove or edit tests because this could lead to missing or buggy functionality." Treat the test suite as immutable ground truth. The decision table Read top to bottom; stop at the first row that fits. | 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 | Patterns compose, and frameworks can hide them. A real coding agent might route a request, hand hard ones to an orchestrator that fans work to workers each running a gather → act → verify loop with rules-based checks. Layer only as far as the task demands. Frameworks "make it easy to get started" but "often create extra layers of abstraction that can obscure the underlying prompts and responses, making them harder to debug" — start with raw API calls and understand the shape before a framework hides it. This is an adapted excerpt. The full interactive version — including a pattern explorer that animates ho