AI agent design patterns, one folder each: a runnable LangGraph graph, the same pattern in plain Python, and a README with diagrams and a simple explanation.
uv sync
uv run pytest
uv run python -m agent_patterns.p01_react.graph # LangGraph version, prints each node as it runs
uv run python -m agent_patterns.p01_react.simple # same pattern in plain PythonEverything runs offline on a scripted mock LLM — no API key needed.
cp .env.example .env # put your OPENROUTER_API_KEY in .env
USE_OPENROUTER=1 uv run --env-file .env python -m agent_patterns.p01_react.graphPick another model with OPENROUTER_MODEL (default anthropic/claude-haiku-5.5).
| # | Pattern | Family | Idea | LLM calls* | Use when | Avoid when |
|---|---|---|---|---|---|---|
| 01 | ReAct | Tool agent | Think → act → observe loop, one LLM call per step | 3 | Steps unknown upfront; must react to tool results | Fixed workflows; tight latency/cost budgets |
| 02 | ReWOO | Tool agent | Plan every tool call once with #E variables, run them, then solve | 2 | Predictable multi-tool lookups; fewer tokens than ReAct | Later steps depend on surprises in earlier results |
| 03 | Plan-and-Execute | Tool agent | Planner writes steps, executor does one, replanner adjusts | 5 | Long multi-step tasks; strong planner + cheap executor | Short tasks (planning overhead); hard real-time |
| 04 | Reflexion | Self-correction | Retry with verbal lessons learned from an external evaluator | 3 | You have a ground-truth check (tests, rules, env reward) | No reliable evaluator; one-shot tasks |
| 05 | Self-Refine | Self-correction | Same model drafts, critiques itself, refines until no issues | 4 | Polishing writing/code style; no external checker | Factual errors the model can't see; cost-sensitive |
| 06 | LLMCompiler | Tool agent | Planner emits a task DAG; independent tool calls run in parallel | 2 | Many independent tool calls; latency matters | Strictly sequential tasks; side-effecting tools that need ordering |
| 07 | Prompt chaining | Workflow | Fixed sequence of LLM calls with code gates between them | 3 | Task splits into known steps; want checkable intermediates | Steps vary per input |
| 08 | Routing | Workflow | Classify the input, send it to one specialized handler | 2 | Distinct input categories needing different prompts/models | Categories overlap; one prompt handles all well |
| 09 | Parallelization (map-reduce) | Workflow | Same LLM step on many inputs in parallel, then combine | 4 | Many independent chunks/docs; voting for confidence | Items depend on each other; strict rate limits |
| 10 | Orchestrator-workers | Workflow | LLM decides subtasks at runtime; workers run in parallel; results merged | 4 | Subtasks not known until you see the input | Fixed splits (use map-reduce); tiny tasks |
| 11 | Evaluator-optimizer | Workflow | Generator + separate judge loop until PASS | 4 | Clear quality rubric; iterating measurably helps | No articulable criteria; first draft usually fine |
| 12 | Self-Ask | Tool agent | Model asks itself follow-up questions; search answers each | 3 | Multi-hop factual questions | Single-hop questions; non-factual tasks |
| 13 | Chain-of-Verification | Self-correction | Draft, plan check questions, answer them independently, revise | 6 | Cutting factual hallucinations in lists/long answers | Creative tasks; latency-sensitive chat |
| 14 | Tree of Thoughts | Search | Branch into candidate thoughts, score, prune, search (BFS/beam) | 10 | Puzzles/planning where partial steps can be scored | Simple Q&A; no way to score intermediate steps |
| 15 | LATS | Search | MCTS over real actions: LLM scores branches, failed paths write lessons, search backtracks | 9 | Agent tasks with real feedback where retrying paths is safe | Real-time chat; irreversible actions without a sandbox |
| 16 | Supervisor | Multi-agent | A boss LLM picks which specialist agent acts next, loops until FINISH | 7 | Specialist agents; next step depends on the last result | Fixed steps (use chaining); one agent is enough |
| 17 | Hierarchical teams | Multi-agent | A top boss picks teams; each team lead runs its own members | 23 | Many agents; group them into teams with their own leads | A few agents (one Supervisor is enough); low latency |
* LLM calls in the repo's mock example — a rough cost/latency signal.
- Tool agents (01 ReAct, 02 ReWOO, 03 Plan-and-Execute, 06 LLMCompiler, 12 Self-Ask) — the LLM decides which tools to call and when.
- Workflows (07–11) — the flow is fixed in code and LLM calls fill in the steps.
- Self-correction (04 Reflexion, 05 Self-Refine, 13 Chain-of-Verification) — check the output and improve it.
- Search (14 Tree of Thoughts, 15 LATS) — explore several reasoning or action paths and prune the weak ones.
- Multi-agent (16 Supervisor, 17 Hierarchical teams) — several specialist agents, each with its own prompt and tools, coordinated.
Start with the simplest workflow that works; reach for an agent only when the steps can't be known up front.
flowchart TD
S{"What do you need?"}
S -->|known steps| W{"Shape of the work?"}
S -->|tools, open-ended| T{"How do tool calls<br/>depend on results?"}
S -->|better output| Q{"What is wrong<br/>with it?"}
S -->|search| X{"Search over what?"}
X -->|thoughts| TOT["Tree of Thoughts"]
X -->|real actions| LATS["LATS"]
S -->|agent team| MA{"How do agents<br/>coordinate?"}
MA -->|central boss| SUP["Supervisor"]
MA -->|teams of teams| HT["Hierarchical<br/>teams"]
W -->|fixed sequence| PC["Prompt chaining"]
W -->|pick one path| RT["Routing"]
W -->|same step, many items| MR["Parallelization<br/>(map-reduce)"]
W -->|parts decided at runtime| OW["Orchestrator-<br/>workers"]
T -->|react to each result| RA["ReAct"]
T -->|plan all, run in order| RW["ReWOO"]
T -->|plan all, run in parallel| LC["LLMCompiler"]
T -->|long task, replan| PE["Plan-and-Execute"]
T -->|multi-hop facts| SA["Self-Ask"]
Q -->|have tests or rules| RX["Reflexion"]
Q -->|clear rubric| EO["Evaluator-<br/>optimizer"]
Q -->|style and clarity| SR["Self-Refine"]
Q -->|wrong facts| CV["Chain-of-<br/>Verification"]
Quick picks
- Fixed sequence of steps → Prompt chaining
- Different kinds of input need different handling → Routing
- Same step over many independent items → Parallelization (map-reduce)
- Subtasks only known after reading the input → Orchestrator-workers
- Open-ended tool use, each step depends on the last result → ReAct
- Tool calls predictable up front, run in order → ReWOO
- Tool calls predictable up front, many independent → LLMCompiler
- Long multi-step task that may need replanning → Plan-and-Execute
- Multi-hop factual question → Self-Ask
- You have tests/rules to grade attempts → Reflexion
- You can write a rubric for a separate judge → Evaluator-optimizer
- Polish style and clarity, no checker → Self-Refine
- Factual answers that must not hallucinate → Chain-of-Verification
- Hard puzzle/planning where partial steps can be scored → Tree of Thoughts
- Agent actions with real feedback, worth trying several paths and backing up → LATS
- Several specialist agents, a boss picks who acts next → Supervisor
- Too many agents for one boss: teams with their own leads → Hierarchical teams