AI Agents Design Patterns

20 production-ready LLM agent design patterns in Python, each runnable offline, benchmarked against the others, and traced step by step. From simple Prompt Chaining to multi-agent orchestration, ReAct loops, and constitutional AI. No API key required.

If this helps you compare agent patterns, a ⭐ helps others find it too.

Also by the author:

• RAG Interview System — Retrieval-Augmented Generation pipeline for technical interview prep
• AI System Design Interview — Structured guides and patterns for AI/ML system design interviews

Contents

• The problem this solves
• Quick start
• Architecture
• Patterns
  • Simple and Linear
  • Iterative Refinement
  • Tool-Using Agents
  • Multi-Agent Coordination
  • Control Flow and State
• Interview prep
• Benchmark
• Project structure
• Contributing a pattern
• Environment variables
• License

The problem this solves

Most LLM agent design pattern repositories give you isolated tutorials with no way to compare them. They don't tell you which pattern to reach for, and they won't run without an API key and 30 minutes of setup.

This repo answers the question you actually have: which agentic AI pattern fits my task, and why? It runs the same four tasks through all 20 patterns in offline mock mode and prints a single tradeoff table, cost, latency, and reliability side by side. Every run is traced: you can watch each reasoning step, tool call, and observation as it happens.

Quick start

No API key needed — every pattern runs against a deterministic offline mock:

make install                  # install the package and dev deps
make demo                     # run ReAct in mock mode — prints the trace tree
make bench                    # run all 20 patterns on 4 tasks — prints the tradeoff table

To run against a live model:

cp .env.example .env          # fill in ANTHROPIC_API_KEY
python patterns/07-react/example.py

Run any individual pattern offline:

make routing-demo             # Routing
make memory-demo              # Memory-Augmented
make debate-demo              # Debate
# … see Makefile for all per-pattern targets

Architecture

Every pattern imports from shared/ and stays provider-agnostic. Setting USE_MOCK=1 (or leaving ANTHROPIC_API_KEY unset) swaps AnthropicClient for MockClient transparently — the pattern code is identical in both modes.

┌────────────────────────────────────┐   ┌──────────────────────┐
│        patterns/NN-name/           │   │      bench/          │
│  pattern.py · example.py · tests   │   │    compare.py        │
└──────────────┬─────────────────────┘   └──────────┬───────────┘
               │ imports                            │ imports
               └──────────────┬────────────────────┘
                    ┌──────────▼───────────┐
                    │        shared/       │
                    │  LLMClient protocol  │
                    │  ToolRegistry        │
                    │  Trace / timed_step  │
                    │  Config · Types      │
                    │  Errors · Loader     │
                    └─────┬──────────┬─────┘
                          │          │
             ┌────────────▼───┐  ┌───▼────────────────┐
             │ AnthropicClient│  │    MockClient       │
             │  (live mode)   │  │  (offline / tests)  │
             └────────────────┘  └────────────────────┘

Patterns

Simple and Linear

The cheapest and most predictable patterns. Reach for these first.

Prompt Chaining

• The task has clear sequential sub-goals (extract → transform → format).
• Each step produces output that the next step must refine or extend.
• You want predictable structure: the pipeline shape is known up front.

USE_MOCK=1 python patterns/01-prompt-chaining/example.py

Routing

• A single classification determines which specialized handler runs.
• You have distinct task types (billing, technical, general) requiring different prompts.
• You want the cheapest possible agent baseline, one classification call plus one handler call.

make routing-demo

Parallelization

• You want diverse perspectives on one question (critic, optimist, analyst).
• Independent verification: run the same task N times and check for agreement.
• Throughput: wall-clock time is the slowest branch, not the sum of all branches.

USE_MOCK=1 python patterns/03-parallelization/example.py

Self-Ask

• Questions that require chaining facts across multiple hops.
• You want the reasoning chain to be inspectable — every sub-question and answer are recorded in the trace.
• Tasks where a single-pass response is likely to miss intermediate steps.

make self-ask-demo

Least-to-Most

• A problem is too complex to solve in one shot but can be scaffolded easiest-first.
• Multi-step math or compositional reasoning where intermediate results feed into harder steps.
• Tasks where you want to verify incremental correctness before tackling the hardest part.

make least-to-most-demo

Iterative Refinement

Improve output quality through loops. Pay in latency; gain in quality.

Evaluator-Optimizer

• You have explicit, checkable criteria for a good output.
• The task benefits from iterative refinement rather than one-shot generation.
• Using separate generator and evaluator models reduces self-serving bias.

USE_MOCK=1 python patterns/05-evaluator-optimizer/example.py

Reflection

• You want self-improvement without external criteria — the model decides what's good.
• The task has soft quality goals (clarity, tone, completeness) that are hard to enumerate.
• You want a single-model setup — no separate evaluator client needed.

USE_MOCK=1 python patterns/08-reflection/example.py

Constitutional

• You have explicit quality criteria (safety, clarity, brevity, tone) the output must satisfy.
• You want traceable, auditable improvements with one critique step per principle.
• Useful for regulated content: compliance text, customer communications, policies.

make constitutional-demo

Tool-Using Agents

Patterns that call external APIs, run code, or query databases. Use when the model alone isn't enough.

Code Execution

• The task requires exact computation (math, data transformation, string operations).
• LLM output quality improves with real feedback from execution.
• You want verifiable results: code output is deterministic.

USE_MOCK=1 python patterns/06-code-execution/example.py

ReAct (Reason + Act)

• The task needs external information or computation the model doesn't have (search, an API, a database).
• The number of steps isn't known up front — the model decides when it has enough to answer.
• You want the agent's intermediate reasoning and tool use to be inspectable.

make demo

Plan-and-Execute

• You want to inspect or validate the plan before committing to execution.
• The task has predictable sub-steps that can be enumerated upfront.
• Execution is expensive — the plan acts as a checkpoint before committing.

USE_MOCK=1 python patterns/09-plan-and-execute/example.py

Memory-Augmented

• The agent needs to persist facts between turns within a session.
• You want the model to decide what is worth storing rather than recording everything automatically.
• Tasks span multiple questions where earlier answers inform later ones.

make memory-demo

Multi-Agent Coordination

Multiple specialized agents working together. Use when different roles or perspectives add value.

Orchestrator-Workers

• The task requires different specializations (research, analysis, writing).
• You want to isolate concerns: workers don't see each other's context.
• The number of subtasks is determined dynamically by the orchestrator.

USE_MOCK=1 python patterns/04-orchestrator-workers/example.py

Multi-Agent

• Different role perspectives are needed on the same problem.
• You want dynamic selection: the supervisor decides which experts are relevant.
• Agents are reusable across tasks — add them to a pool, supervisor picks at runtime.

USE_MOCK=1 python patterns/10-multi-agent/example.py

Debate

• You want to stress-test a decision by generating the strongest arguments on both sides.
• You need a balanced synthesis for a contentious or nuanced question.
• You want to surface blind spots a single-agent answer would miss.

make debate-demo

Mixture-of-Experts

• A query spans multiple domains and no single system prompt handles all facets well.
• Different framing radically changes the answer (technical, legal, business angles).
• You want multiple independent expert opinions before a final synthesis.

make moe-demo

Control Flow and State

Patterns with explicit state, human gates, or structured execution strategies.

Human-in-the-Loop

• Tools have irreversible side-effects (sending emails, deleting records, making purchases).
• You need a compliance or audit trail — every human decision is recorded in the trace.
• Gradual autonomy: start with many checkpoints and remove them as you gain confidence.

make human-loop-demo

State Machine

• The task has well-defined phases that must execute in a controlled order (triage → diagnose → resolve).
• You want to constrain the agent to a known set of actions rather than free choice.
• The business process has compliance or audit requirements that demand a fixed workflow.

make state-machine-demo

Speculative Execution

• The solution space is large (algorithms, code, essays) and a single attempt may miss important cases.
• You want self-consistency checking without a human in the loop.
• Quality variance across attempts is high and you can afford more LLM calls.

make speculative-demo

Event-Driven

• An agent must react to a stream of incoming events and maintain state across them.
• Monitoring pipelines (metric → alert → resolve) or workflow automation.
• Multi-step processes where each step produces an event that triggers the next.

make event-driven-demo

Interview prep

Every pattern directory includes an interview.md file with 8 questions and answers covering:

• Conceptual — what the pattern is and why you'd choose it
• Trade-offs — how it compares to similar patterns and when it breaks down
• Implementation & Failure Modes — concrete failure scenarios and how to guard against them
• Extension — realistic modifications (tool calls, hybrid patterns, scaling)

INTERVIEW_PREP.md at the repo root is a master index with a recommended study path, organized from foundational to advanced, plus 8 cross-pattern comparison questions that interviewers often ask (e.g., ReAct vs. Plan-and-Execute, Reflection vs. Evaluator-Optimizer, when to use Debate vs. Constitutional).

Benchmark

make bench loads all 20 patterns via load_pattern_module, runs the same four customer-support tasks through each in offline mock mode, and prints a single Rich table.

make bench

The table columns — Pattern, Avg Steps, Avg Tokens, Avg ms, Success Rate — let you compare cost/latency/reliability tradeoffs across every pattern on the same workload. Simple patterns like Routing score the lowest step and token counts; iterative patterns like Debate and Constitutional score higher counts in exchange for more thorough outputs.

Switch to live mode for real latency and token numbers:

cp .env.example .env          # set ANTHROPIC_API_KEY
python -m bench.compare

Project structure

ai-agents-design-patterns/
├── INTERVIEW_PREP.md        # master interview index — study path + cross-pattern questions
├── patterns/
│   └── NN-name/
│       ├── pattern.py       # implementation — one run_* function + result dataclass
│       ├── example.py       # runnable demo with deterministic mock_planner
│       ├── test_pattern.py  # pytest tests via load_pattern_module
│       ├── diagram.md       # Mermaid flowchart + tradeoff prose
│       └── interview.md     # 8 Q&A pairs for interview preparation
├── shared/
│   ├── llm_client.py        # LLMClient protocol · AnthropicClient · MockClient · build_client()
│   ├── tools.py             # Tool dataclass · ToolRegistry with JSON Schema validation
│   ├── trace.py             # Trace / Step · timed_step context manager
│   ├── config.py            # Config.from_env() — resolves mock/live mode and all overrides
│   ├── types.py             # Message · LLMResponse · ToolCall · ToolResult · Usage
│   ├── loader.py            # load_pattern_module("NN-name") — file-path import
│   ├── errors.py            # MaxStepsExceeded · ToolValidationError · AgentError
│   └── observability.py     # structured JSON logging (AGENT_LOG) + @timed decorator
├── bench/
│   └── compare.py           # cross-pattern comparison harness
├── docs/                    # static assets (banner image, etc.)
├── Makefile                 # install · demo · bench · test · per-pattern demo targets
└── pyproject.toml

Contributing a pattern

See CONTRIBUTING.md for the full walkthrough. Short version: duplicate patterns/07-react/, rewrite pattern.py, update example.py and test_pattern.py, write diagram.md and interview.md, then add a row to the pattern table above. The shared client, tool registry, tracing, config, and test style carry over unchanged — adding a pattern is typically a ~50-line diff to pattern.py.

Environment variables

License

MIT.