The roadmap

Mastering agentic design patterns, in order.

A self-contained route from "what is an agent?" to production-ready — six chapters, fifteen stops, each building on the last. The lesson lives right here on the road. Mark a stop mastered and the road fills in behind you.

15 stops · ~25 min read

0 of 15 stops mastered

Your progress saves automatically — pick up anytime.

The arcChapter 01→Chapter 02→Chapter 03→Chapter 04→Chapter 05→Chapter 06

Chapter 01 · 2 stops

What is an agent?

Strip away the hype: an agent is a language model placed in a loop, given tools and a standing brief, choosing its own next action.

Chapter 01

What is an agent?

An LLM in a loop, given tools and a standing brief, deciding its own next action.

TeachesIntegrator

Perceptionraw input from the user or world, grounded into structured percepts.
The brainthe LLM carries the reasoning and the agent's picture of what's true so far.
Standing briefthe system prompt fixes the role and shapes how it plans.
The handstools — typed functions — let it query a DB, run code, fetch a page.
The loop closesresults return as observations; it acts again or answers.

Stabilizes

Conceptual fog — “agent” used as a buzzword instead of a precise architecture.

Five parts of every single agent

Input · Perception

Raw input grounded into structured percepts the core can reason over.

LLM · The brain

Carries the reasoning and maintains the agent's world model.

System prompt · Standing brief

Defines the role, gives operating instructions, shapes the plan.

Tools · The hands

The model emits a structured tool call — a typed function it may invoke.

Output · Feedback

Observations return; the agent evaluates and loops or answers.

The dividing line

Workflow: you wire the control flow; the model fills the slots. Agent: the model decides the control flow at runtime. Autonomy is a spectrum — and more of it always costs you predictability.

Checkpoint — you can…

Name the five parts of an agent and the one move that distinguishes an agent from a plain model call.

Chapter 01

The ReAct loop

The atom of agency: think, act, observe — then think again with what you saw.

TeachesDeliberatorExecutor

Thought→Action→Observation↻ repeat

Thoughtthe model reasons about the state and names what it needs next.
Actionit emits a tool call grounded in that thought — not a blind guess.
Observationthe result folds back into context, so the next thought sees reality.
Repeatthe loop continues until the goal is met or a bound is hit.

Stabilizes

Acting blind — choosing actions without grounding them in what just happened.

Why interleaving matters

Reasoning and acting alternate so every decision is conditioned on what just happened. Errors get caught inside the loop instead of compounding across it.

Checkpoint — you can…

Trace one turn of a ReAct loop and say which step owns ‘think’ versus ‘act’.

Chapter 02 · 3 stops

Why one agent isn't enough

A prompt is a probabilistic suggestion, not a contract. Left ungoverned it drifts, loops, and hallucinates — sometimes all the way to court.

Chapter 02

Prompts are not software

A prompt is a probabilistic suggestion, not a deterministic instruction. Confusing the two is the original sin of agent engineering.

Orientation — no formal pattern yet

f(x)in→outsame every run

p(x)in→abc?sampled

Non-deterministicthe same input is sampled from a distribution — not reproduced.
Weakly specifiedbehaviour is coaxed in prose, not pinned by code and types.
Demo ≠ correctten green runs are ten samples, not a proof. The eleventh can fail live.
Wrap, don't trustmake the system reliable — validate, bound, retry, checkpoint.

Stabilizes

The category error — mistaking a probabilistic suggestion for a deterministic instruction.

The category error

	Software	Prompt
Output	Same in, same out	Sampled from a distribution
Spec	Pinned by code & types	Coaxed in natural language
Testing	Assert exact values	Check properties, not strings
Failure	Reproducible	Intermittent, non-deterministic
Trust	From the compiler	From the guardrails around it

The reframe

Don't ask the model to be reliable. Keep the probabilistic step small and well-scoped, and surround it with deterministic structure. The gap between a demo and a product is the patterns.

Checkpoint — you can…

State two ways a prompt differs from a function, and what you'd add around one before shipping.

Chapter 02

Case in point — Air Canada

An unsupervised chatbot invented a refund policy. A tribunal made the airline pay. Hallucination has a dollar figure.

Orientation — no formal pattern yet

chatbot→“refund policy”→LIABLECAD $812.02

It hallucinated a policythe bot promised a retroactive bereavement fare that never existed.
“The AI said it” failedthe tribunal held the company liable for what its agent says.
Not an isolated bugthe $1 Tahoe and Avianca's fake citations are the same missing pattern.
Guardrails aren't polishthey're the line between a feature and a liability.

Stabilizes

The illusion that hallucination is harmless — it carries legal, financial, and reputational cost.

The precedent

Moffatt v. Air Canada

BC Civil Resolution Tribunal · February 2024

The chatbot hallucinated a retroactive bereavement-fare refund policy. The tribunal found Air Canada liable for negligent misrepresentation — the company, not the bot, owns what the bot says.

Two more from the record

Chevrolet “$1 Tahoe” (Dec 2023)

A customer prompt-injected a dealership assistant into a “legally binding” $1 car offer. Unscoped agents say anything.

Mata v. Avianca (Jun 2023)

Lawyers were sanctioned after ChatGPT fabricated six fictional case citations in a court filing.

Checkpoint — you can…

Name the failure mode behind the ruling and one pattern that would have prevented it.

Chapter 02

The four walls a lone agent hits

A single ReAct loop is powerful — until the task gets deep, the tools get unsafe, the work needs specialists, or it has to survive Tuesday.

Orientation — no formal pattern yet

DepthplanLearningreflectSafetytoolsScalemulti-agent

Reasoning depthone-shot thinking collapses on long multi-step tasks → you need Planning.
Causal learningit repeats mistakes it never diagnosed → you need Reflection.
Unsafe boundariesraw tool calls corrupt state → you need a safe Tool-Use boundary.
Coordinationreal specialists need bounded communication → you need multi-agent patterns.

Stabilizes

The belief that a single clever prompt scales — it doesn't, and the walls predict exactly where it breaks.

This is the hinge of the story

Each wall names a failure mode of the lone agent — and each one is answered by a named pattern in the next chapter. Hold the four walls in mind; the patterns are the doors through them.

Checkpoint — you can…

List the four walls and name the pattern family that breaks through each.

Chapter 03 · 5 stops

The solution patterns

The same handful of shapes recur everywhere. Each names one failure mode and the structure that contains it — for one agent, then for many.

Chapter 03

Reflection

Draft, critique, improve. The agent learns from its own mistakes instead of repeating them.

TeachesReflector

too vague?check factsadd sources

Draftoutput

→

Critiquediagnose

→

Improverevise

quality

56%↻ revise ×0

Name the defectspecific, not “this is bad” — “it omits the refund window asked for.”
Find the root causeso the fix targets the cause, not the symptom.
Apply a concrete revisionan actionable change the next draft is measured against.
Anchor the judgeto a test or a human — a model grading itself can agree with its own error.

Stabilizes

Causal learning — repeating the same failure because the cause was never diagnosed.

Checkpoint — you can…

Describe draft→critique→improve and what a critique must produce to be useful.

Chapter 03

Tool use

Agents act on the world through tools — APIs, databases, the web. The boundary must be safe.

TeachesTool UseExecutor

Agent

API {…}DBWEB

Validate argumentscheck every argument against a schema before dispatch.
Scope capabilitiesleast privilege — the agent can only call what it's granted.
Normalize errorsfailures return as structured, recoverable signals, not crashes.
Standardise itMCP gives one client + one server contract for any tool (Chapter 04).

Stabilizes

Unsafe tool boundaries — drifting schemas and unscoped calls that poison the graph.

Checkpoint — you can…

Name two things the tool boundary must enforce before a call is dispatched, and why.

Chapter 03

Planning

Decompose the goal before you act. A plan turns a vague intent into ordered, inspectable steps.

TeachesPlannerSelector

Goal→Check?→researchexecute

Define
Gather
Execute
Review

Decomposethe Planner breaks a complex goal into ordered sub-goals.
Prioritisethe Selector chooses which sub-goal to pursue next.
Plan-first vs. plan-as-you-goReWOO commits up front; ReAct re-plans each turn. Most blend both.
Legibilityan explicit plan is cacheable, parallelisable, and points at the failure.

Stabilizes

Reasoning depth — complex tasks that exceed what one-shot reasoning can hold.

Checkpoint — you can…

Sketch a multi-step task as ordered sub-goals and say which you'd run first and why.

Chapter 03

The graph language

Workflows and agents share one vocabulary: nodes, edges, state, reducers. Learn the syntax once and every pattern reads the same.

Orientation — no formal pattern yet

nodeedgestatereducer

Nodeone unit of work — an LLM or tool call — typed in and out.
Edgea directed line; the edge set defines what's possible. The runtime invents nothing.
Statethe typed object threaded through the graph — shared working memory.
Reducerthe rule for merging a node's writes into state — overwrite, append, combine.

Stabilizes

Vocabulary drift — every framework reinventing the same nouns under different names.

The four nouns

Node

A unit of work — one LLM or tool call. Typed input, typed output. Pure where it can be.

Edge

A directed connection. Static (always) or conditional (an LLM picks). The edge set is the space of legal moves.

State

The shared, typed object every node reads from and writes to. The system's working memory.

Reducer

Per-field merge rule for a node's writes — overwrite a value, append to a list, combine a set.

Why a shared language matters

Once flow is data — nodes and edges, not buried if-statements — you can checkpoint it, resume it, visualise it, and reason about it. It also makes the next distinction precise: a Pipeline forbids cycles and LLM-chosen edges; a Graph allows both, bounded by a recursion limit.

Checkpoint — you can…

Define node, edge, state, reducer — and the one rule separating a Pipeline from a Graph.

Chapter 03

The six coordination patterns

Orchestrator, Pipeline, Graph, Blackboard, Swarm, Human-in-the-Loop. Almost every system is one of these — or a composition.

TeachesCoordinator

StructureAutonomy

PipelineOrchestratorGraphBlackboardSwarm

+ Human-in-the-Loop composes on any of them

One spectrumfrom fully developer-wired (Pipeline) to fully self-organising (Swarm).
One questioneach answers “who decides who works next?” differently.
HITL composesa human gate layers on top of any of the other five.
Escalate reluctantlypick the most structured pattern that solves the problem.

Stabilizes

Pattern sprawl — drowning in named variants instead of seeing the six underlying shapes.

The six coordination patterns

Orchestrator / Agent-as-Tool

Encapsulation

Who holds the flow together? Who delegates to whom?

Specialists are exposed as typed callables — tools — and the orchestrator sees only the signature, not the prompt or model. That boundary is what makes specialists hot-swappable across implementations and frameworks, including remote A2A agents.

Pipeline / Workflow (DAG)

Structure-deterministic

Which order is fixed? What can run in parallel?

Control flow is fully wired in code: which nodes run, in what order, with what fan-out. The graph is identical every run; only the model-generated content inside nodes is non-deterministic.

Graph (Fan-out / Fan-in)

Bounded variability

Are there conditional branches, and points where results converge?

Pipeline plus two relaxations — conditional edges chosen by an LLM, and cycles bounded by a recursion limit. The node set is still closed and the state schema is still validated; only the path through them is runtime.

Blackboard (Shared State)

Decoupled topology

Where does the shared working state live? How does the knowledge of all agents grow?

Communication runs through a shared state surface, not addressed messages. Adding an agent is a subscription, not a rewire — the other agents do not learn of its existence. The only pattern with an open agent set at runtime.

Swarm (Self-Organizing Handoffs)

Emergent topology

Can the agents decide for themselves who takes over next?

The graph is a runtime artefact. Each agent declares which peers it may hand off to; the path through the network materialises as the run progresses. Appropriate for problems where no static plan can be drawn in advance.

Human-in-the-Loop

Temporal, not topological

Where must a human intervene, and with what question?

Suspend the run at a designated node, persist state, ask a human a structured question, resume when the answer arrives. Innovation is in the time dimension — HITL composes with every other pattern instead of competing with them.

The trade-offs at a glance

Pattern	Controls flow	Cycles	Determinism
Orchestrator	Orchestrator LLM	No	Medium
Pipeline	Developer	No	High
Graph	Developer + LLM	Yes	Medium
Blackboard	All agents	Yes	Medium
Swarm	Agents (handoffs)	Yes	Low
HITL	Human + system	No	High

Checkpoint — you can…

Match each pattern to its guiding question, and place the six on the structure→autonomy spectrum.

Chapter 04 · 3 stops

How they're applied

Choose the simplest pattern that works, pick a framework that fits its shape, and connect across boundaries with two open protocols.

Chapter 04

The decision framework

Before you pick a pattern, ask whether you need an agent at all. Six questions, in order, route you to the simplest thing that works.

Orientation — no formal pattern yet

1One prompt?2Tools?3Predictable?4–6agent → multi → prodstop at the first 'no'

Start cheapestcould one well-engineered prompt do it? Then stop here.
Climb only when forcedeach ‘yes’ moves you up one rung, never more.
Most tasks stop earlyfar earlier than teams expect — pure reasoning or a workflow.
Production is its own rungshipping makes the System-Operation patterns mandatory.

Stabilizes

Over-engineering — building a multi-agent system for a problem one prompt could solve.

Walk it in order

One mind, looping over a task.

How a single agent reasons internally — thought, action, observation, reflection. The unit you'll keep returning to, even inside the bigger systems.

Steps you wire in code. The LLM fills the slots.

Structure belongs in code. Workflow patterns are the deterministic skeleton: sequential, routing, parallel, loops. The model produces content; you control flow.

Specialists. Who decides who works next?

The point where coordination becomes the system's hardest problem. Supervisors, handoffs, swarms, blackboards — twelve canonical answers to the same question.

Memory, tools, runtime, governance, evals.

This is the floor every other rung was already standing on. We present L4 last because skipping it is the #1 reason agent prototypes die on contact with Tuesday — but conceptually, it is the foundation, not a final step.

Checkpoint — you can…

Walk a real task down the six questions and stop at the rung that fits it.

Chapter 04

Framework fit

The framework decides how your agent thinks. There's no “best” — only fit to your problem's shape and your stack.

Orientation — no formal pattern yet

Frameworkhow it thinksRuntimeexecution & stateHarnesspackaged loop

LangGraphCrewAITemporal

Three layersFramework (authoring), Runtime (execution & state), Harness (a packaged loop).
Shop by patternmatch a candidate's “best for” to the pattern you already need.
Read the “watch out”against your real constraints — control, cost, debuggability.
Two axes decide itcontrol ↔ convenience, and the ecosystem you already stand in.

Stabilizes

Framework cargo-culting — picking by hype instead of by pattern, control needs, and ecosystem.

A representative slice

LangGraph

Runtime

BestAuditable, stateful graphs needing deterministic control and human-in-the-loop.

WatchHigh boilerplate; strict state management is overkill for simple linear flows.

CrewAI

Framework

BestFast prototyping of role-based team workflows with built-in layered memory.

WatchHigh abstraction makes internal state hard to debug ('black box').

AutoGen / AG2

Framework

BestMulti-agent debates, negotiations, and code reviews via conversation.

WatchChat histories drive high token consumption; no built-in persistence.

Pydantic AI

Framework

BestStructured extraction and validated RAG pipelines with strict typing.

WatchWeaker for endlessly cyclic graphs than LangGraph.

AWS Strands SDK

Framework

BestShipping model-driven agents fast on AWS (Bedrock, Lambda, ECS).

WatchLittle low-level control; the LLM drives the graph, so flows are less deterministic.

Temporal

Runtime

BestLong-running, stateful orchestration that must survive crashes and resume exactly where it left off.

WatchGeneral-purpose workflow infrastructure, not agent-native — you bring the LLM / agent layer yourself.

Checkpoint — you can…

Pick a pattern, then a framework whose “best for” matches and a constraint its “watch out” violates.

Chapter 04

Connect — MCP & A2A

Two open protocols cross the boundary out of any framework. One standardises agent↔tool; the other, agent↔agent.

TeachesTool UseCoordinator

AgentA2A → Peer

MCP ↓

tooldataprompt

MCP — verticalN agents × M tools collapses to N+M. “A USB-C port for AI apps.”
A2A — horizontalagents on different frameworks cooperate as opaque peers.
Complementarythe framework decides how it thinks; protocols decide who it talks to.
Privacy by designA2A peers expose a capability and a result — never their reasoning.

Stabilizes

Lock-in — agents and tools that can't cross a framework or vendor boundary.

Two protocols, two boundaries

	MCP	A2A
Scope	Agent ↔ tool / data	Agent ↔ agent
Standardises	Tool discovery & I/O	Agent discovery, task lifecycle
Core objects	Tools · Resources · Prompts	Agent Cards · Tasks · Artifacts
Steward	Anthropic (open spec)	Linux Foundation (Google-initiated)

A2A in motion — one trip, three vendors

Discover

Fetch the remote's Agent Card from /.well-known/agent-card.json — skills, endpoint, auth.

Authenticate

Obtain a token per the card's scheme. The remote treats the caller as untrusted until it does.

message/send

A Task opens in state submitted; progress streams back over SSE as working.

Artifact

A flight-options artifact returns; the task is completed — reasoning never leaves the boundary.

Where this leaves you

From one ungoverned prompt to a governed agent that reaches any tool over MCP and cooperates with any agent over A2A — structured, observable, accountable end to end.

Checkpoint — you can…

Explain the vertical problem MCP solves and the horizontal problem A2A solves.

Chapter 05 · 1 stop

Anti-patterns to avoid

The patterns have evil twins. Knowing the named traps means you spot the failure before it ships, not after the post-mortem.

Chapter 05

The traps to avoid

Every pattern has an evil twin. These are the named failure modes — recognise the symptom, reach for the fix.

Orientation — no formal pattern yet

⚠ God Orchestrator→small specialists⚠ Unbounded loop→recursion limit

Over-agentificationmulti-agent where a workflow would do → walk the decision ladder.
Unbounded loopno exit condition → hard recursion limit + step budget.
God Orchestratorone node holds everything → push work into small specialists.
Self-graded hallucinationa model agrees with its own error → anchor judgement externally.

Stabilizes

The post-mortem — catching named failure modes in review instead of in production.

Symptom → fix

Hallucinated Routing

SymptomReflection loops never converge. Recursion limits trip at runtime instead of design time.

FixSchema-validate router decisions. Hard recursion_limit, hard max_handoffs.

Tool Explosion

SymptomTool selection accuracy collapses. The model hallucinates calls and parameter names.

FixLeast privilege per role. Gate large catalogues behind a Tool Registry plus capability routing.

Hidden State in Prompts

SymptomBehaviour drifts over long conversations. Bugs reproduce only intermittently.

FixPydantic v2 state at every node boundary. Forbid extra attributes. State belongs in code.

Cascading Security Failures

SymptomA poisoned doc in a shared index contaminates every downstream consumer. Prompt injection propagates via handoffs.

FixTreat every agent-to-agent message as a trust boundary. Partition knowledge bases by trust level.

The meta-lesson

Anti-patterns aren't exotic — they're the default outcome of skipping a pattern. Each fix above is just a pattern from Chapters 03–04, applied on purpose.

Checkpoint — you can…

Pick two anti-patterns, state the symptom you'd see in logs, and the pattern that fixes each.

Chapter 06 · 1 stop

Production-ready

Safe, reliable, scalable: guardrails that hold, state that survives, and the observability that proves it.

Chapter 06

Production-ready

Safe, reliable, scalable. Guardrails that hold, state that survives, skills that compound.

TeachesControllerRecorderSkill Build

Guardrailllm-judge

→

Agentgraph

→

Approvehuman

metricslogsalertsstate

monitoring · guardrails · checkpoints — live

Guardrails — Controlleroutput validation + LLM-as-judge that can halt the run.
Durable state — Recordercheckpoint at every node; a step-11 crash resumes from 11.
Compounding skillsrepeated solutions become versioned, reusable assets.
Observabilitymetrics, logs, traces, alerts — you can't operate what you can't see.

Stabilizes

Drift, lost state, and eroding guardrails over long-running sessions.

The floor, not the finish

These aren't a last step — they're the ground every other chapter was standing on. Skipping them is the #1 reason prototypes die on contact with real traffic. That's the whole road.

Checkpoint — you can…

Name the three things that keep an agent production-ready and which ADP owns each.

Roadmap complete · 100%

Production-ready.

From “what is an agent?” to the guardrails that hold under load — you've walked the whole road.

Where to next

After the paths.

FoundationsThe LadderEvery system starts at Single Agent. Climb L1 → L4 from there.Climb L1 → L4 PatternsPattern OverviewAll four pattern categories on one map.Open the overview PerspectiveDecision HeuristicA short tree for choosing the right altitude.Which pattern when

Mastering agentic design patterns, in order.

What is an agent?

What is an agent?

The ReAct loop

Why one agent isn't enough

Prompts are not software

Case in point — Air Canada

Moffatt v. Air Canada

The four walls a lone agent hits

The solution patterns

Reflection

Tool use

Planning

The graph language

The six coordination patterns

How they're applied

The decision framework

Framework fit

Connect — MCP & A2A

Anti-patterns to avoid

The traps to avoid

Production-ready

Production-ready

Production-ready.

After the paths.

Search