Agent patterns

1 · Recap — the loop needs a strategy

Here is a failure you have almost certainly seen a demo agent commit. You give it a two-part task — “find the two busiest cities and add their populations” — and it confidently blurts a single answer that's wrong, because it tried to do everything in one leap instead of one step at a time. The loop from 4.1 gave the agent hands (it can call tools) but not a method for using them. This chapter is about the method.

Think of the difference between a kitchen full of equipment and a recipe. In 4.1 you built the kitchen: the knives, the stove, the pantry — the tools the agent can reach for. But hand a stocked kitchen to someone with no recipe and no order of operations and you get chaos, or a dish that's raw in the middle. A pattern is the recipe: it tells the cook when to chop, when to taste, when to start over. Same kitchen, wildly different dinner.

The common mistake here is to assume the model's raw intelligence is the strategy — that a smart enough model will just figure out the right sequence on its own. Sometimes it does. But “sometimes” is the enemy of production: an agent that solves a task nine times and quietly mangles it the tenth is worse than useless, because you can't trust any single run. Imposing an explicit control-flow structure is what turns “usually works” into “works because I can see exactly how it works.” The structure is also what you inspect when something goes wrong — you can't debug a black box, but you can debug a loop with a visible trace.

In 4.1 the agent loop was: give the model a goal and a set of tools; it emits a tool call; you run the tool and hand back the result; repeat until the model says it is done. That is the mechanism. What it does not tell you is how the model should decide what to do at each step — and for anything beyond one tool call, that structure is what separates a reliable agent from one that flails.

The patterns below are the well-known, publicly documented ways to impose that structure. They are not competing products; they are shapes of control flow. A production agent often composes several: route first, then run a plan, reflecting on the risky step, retrying any tool that fails.

2 · ReAct — reason, act, observe, repeat

Watch how a careful person actually solves an unfamiliar problem and you'll never see them sprint to the answer. They take one step, look at what happened, and let that result shape the next step. You look up a train time, then — knowing it — decide whether to book the hotel or keep searching. ReAct is that same discipline, made explicit for an agent: think a little, act once, look at the result, and only then decide what to do next.

ReAct (Reason + Act) is the workhorse pattern for multi-step reasoning. Instead of guessing the whole answer at once, the model alternates between a Thought (private reasoning about what to do next), an Action (a concrete tool call), and an Observation (the tool's result). It reads the observation, thinks again, and repeats until it can answer. The interleaving is the point: each action is chosen in light of what the previous one returned.

The word doing the heavy lifting is interleave. A model left to reason in one long monologue will happily invent a fact, build three more inferences on top of it, and present a fluent, confident, wrong answer — because nothing ever checked its assumptions against reality. ReAct breaks that spell by forcing the model to act and observe between thoughts. Each observation is a small collision with the real world: the tool returns 2,100,000, or it returns an error, and either way the next thought has to reckon with what actually came back rather than what the model wished were true. That grounding is why ReAct is the default reach for open-ended tasks.

The classic mistake beginners make is collapsing Thought and Action into one blurred move — asking the model to “think about the population and also fetch it” in a single turn. When you do that you lose the observation step, and with it the whole benefit: the model never pauses to read what the tool returned before committing to the next action. Keep the three beats separate and named. The other trap is forgetting the loop can run indefinitely — a confused model may thought-and-act in circles — which is why the bound (max_steps) below is not decoration but a safety belt. Think, act, observe, and only then think again: the rhythm is the pattern.

Here is a full ReAct loop solving a 2-step task — look up two facts, then combine them. The fake_model() stands in for the LLM: given the running trace, it returns the next Thought+Action. In production this one function becomes a model call; the loop around it does not change.

react.py# ReAct: interleave Thought -> Action -> Observation until we can answer.
# The 'model' is a deterministic fake so this runs offline; swap it for a real
# LLM call and the control flow is IDENTICAL.

TOOLS = {
    'population': lambda city: {'Paris': 2_100_000, 'Lyon': 500_000}[city],
}

def fake_model(trace):
    """Return the next 'Thought' + 'Action' given the trace so far.
    A real LLM replaces this; it reads the same trace and emits the same shape."""
    obs = [line for line in trace if line.startswith('Observation:')]
    if len(obs) == 0:
        return ('Thought: I need the population of Paris first.',
                ('population', 'Paris'))
    if len(obs) == 1:
        return ('Thought: Now I need the population of Lyon.',
                ('population', 'Lyon'))
    return ('Thought: I have both; I can answer now.', ('finish', None))

def react(goal, max_steps=6):
    trace = [f'Goal: {goal}']
    facts = []
    for step in range(max_steps):
        thought, (tool, arg) = fake_model(trace)
        trace.append(thought)
        if tool == 'finish':
            total = sum(facts)
            trace.append(f'Answer: combined population = {total:,}')
            break
        trace.append(f'Action: {tool}({arg!r})')
        result = TOOLS[tool](arg)
        facts.append(result)
        trace.append(f'Observation: {result:,}')
    return trace

for line in react('total population of Paris and Lyon'):
    print(line)

Goal: total population of Paris and Lyon
Thought: I need the population of Paris first.
Action: population('Paris')
Observation: 2,100,000
Thought: Now I need the population of Lyon.
Action: population('Lyon')
Observation: 500,000
Thought: I have both; I can answer now.
Answer: combined population = 2,600,000

Notice the loop never assumes how many steps it takes — it keeps going until the model emits finish, bounded by max_steps. That decide-as-you-go quality is ReAct's strength: the agent adapts to what each observation reveals. Its cost is that it thinks step by step, so it can wander if the model is weak or the tools are noisy.

3 · Plan-and-execute — decide the whole path first

Some journeys you improvise; others you map before you leave. Wandering a new city on foot, you decide each turn as you go — that's ReAct. But when you're driving a delivery route with twelve fixed stops, you don't rediscover the road at every corner; you plan the whole route once, then just follow it. When a task's shape is known in advance, re-deciding every step is wasted effort — and every one of those re-decisions, for an agent, is another model call you pay for.

Plan-and-execute flips the order. The model first writes a plan — an explicit, ordered list of steps — and only then executes each step in turn. Where ReAct decides the next move after every observation, plan-and-execute commits to the path upfront. That makes the agent cheaper and more predictable for tasks whose shape is known, at the cost of adaptability if reality diverges from the plan.

The real payoff is more than saving model calls. A plan is legible: because the whole path exists as data before anything runs, you can print it, log it, show it to a human for approval, or diff two runs against each other. That's a property ReAct simply can't offer — in ReAct the “plan” only exists in hindsight, scattered across the trace. When a workflow is repeatable and the stakes of a wrong step are high (touching production, spending money, emailing a customer), being able to see and gate the plan before execution is worth a great deal.

The mistake to avoid is treating a plan as a promise the world is obliged to keep. Reality diverges: an order list comes back empty, an API you planned to call is down, step three assumed something step two disproved. An agent that marches through a now-invalid plan produces confidently wrong results — the brittleness this pattern trades for its predictability. The mature answer, shown in the tip after the lab, is to re-plan: execute the plan, but the moment a step's outcome contradicts an assumption, hand control back to the planner to revise what's left. That hybrid is where most production systems actually live — plan for the predictable spine, adapt at the joints.

plan_execute.py# Plan-and-execute: model writes an ordered plan, then we run each step.
# fake_planner() is deterministic; a real LLM would generate the plan text.

STEP_TOOLS = {
    'fetch_orders': lambda: [12, 7, 31],
    'sum_orders':   lambda xs: sum(xs),
    'format':       lambda n: f'Total orders this week: {n}',
}

def fake_planner(goal):
    """Return an ordered plan (list of step names). A real LLM writes this."""
    return ['fetch_orders', 'sum_orders', 'format']

def execute(goal):
    plan = fake_planner(goal)
    print('PLAN:')
    for i, step in enumerate(plan, 1):
        print(f'  {i}. {step}')
    print('EXECUTE:')
    state = None
    for step in plan:
        if step == 'fetch_orders':
            state = STEP_TOOLS[step]()
        elif step == 'sum_orders':
            state = STEP_TOOLS[step](state)
        elif step == 'format':
            state = STEP_TOOLS[step](state)
        print(f'  ran {step} -> {state!r}')
    return state

print('RESULT:', execute('report this week\'s order total'))

PLAN:
  1. fetch_orders
  2. sum_orders
  3. format
EXECUTE:
  ran fetch_orders -> [12, 7, 31]
  ran sum_orders -> 50
  ran format -> 'Total orders this week: 50'
RESULT: Total orders this week: 50

4 · Reflection — draft, critique, revise

Nobody sends the first draft. A good writer bangs out a rough version, then reads it back with a colder eye — “this paragraph doesn't answer the question, this claim has no support” — and fixes what they find. The first pass is for getting something down; the second is for getting it right. Reflection gives an agent that same second pass, and it's often the difference between an answer that looks plausible and one that's actually correct.

Reflection (self-critique) adds a quality gate: after producing a first attempt, the model critiques its own output against the requirements, then revises. It is the agent equivalent of “read your work before you hand it in.” You reach for it when correctness matters more than latency — the extra pass costs time and tokens but catches mistakes a single shot would ship.

Why does critiquing work at all, when the same model wrote the flawed draft? Because judging is easier than generating. Producing a complete, correct answer in one shot forces the model to juggle every requirement at once; but handed a finished draft and asked the narrower question “does this mention the cause and the fix?”, it only has to check, not create. Splitting the hard job into write then grade against a checklist plays to a real strength — the same reason a proofreader catches errors the author's own eye slid past. The critique step is most powerful when you give it explicit requirements to check against, rather than a vague “make it better.”

The failure mode that bites people is the loop that never ends. If the critic is fussy — or worse, if revising to satisfy one requirement quietly breaks another — the draft ping-pongs forever, and every round is more tokens and more latency on the meter. That's why reflection always ships with a hard max_rounds cap and a clean exit the moment the critique comes back empty, as the warning after the lab insists. The second, subtler mistake is reflecting on everything: reflection earns its cost only when correctness genuinely outranks speed. For a throwaway summary it's overkill; for a customer-facing refund decision it's cheap insurance.

reflection.py# Reflection: draft -> critique -> revise. All three 'model' calls are faked
# deterministically here; a real LLM replaces each, control flow unchanged.

REQUIRED = ['cause', 'fix']   # a good incident summary must mention both

def fake_draft(task):
    return 'The checkout service went down.'   # incomplete on purpose

def fake_critique(text):
    """Return a list of missing requirements. A real LLM judges the draft."""
    missing = []
    if 'queue' not in text.lower():
        missing.append('cause')
    if 'restart' not in text.lower() and 'scale' not in text.lower():
        missing.append('fix')
    return missing

def fake_revise(text, missing):
    add = {'cause': ' The queue backed up.',
           'fix': ' Drain the queue and scale the consumer group to fix it.'}
    for m in missing:
        text += add[m]
    return text

def reflect(task, max_rounds=3):
    draft = fake_draft(task)
    print(f'draft: {draft}')
    for r in range(max_rounds):
        missing = fake_critique(draft)
        if not missing:
            print(f'round {r}: looks complete, stopping.')
            break
        print(f'round {r}: missing {missing} -> revising')
        draft = fake_revise(draft, missing)
    return draft

print('final:', reflect('summarize the checkout incident'))

draft: The checkout service went down.
round 0: missing ['cause', 'fix'] -> revising
round 1: looks complete, stopping.
final: The checkout service went down. The queue backed up. Drain the queue and scale the consumer group to fix it.

5 · Routing — classify first, then dispatch

Call any large company and the first thing you hit is a menu — press 1 for billing, 2 for tech support, 3 for everything else. It feels bureaucratic, but it's doing something smart: instead of training every operator to handle every possible question, it sends your call to someone who only needs to know one domain deeply. Routing gives an agent that same front desk, and it's how you stop one bloated prompt from trying to be an expert at everything at once.

When an agent faces heterogeneous requests — a billing question, a bug report, a how-to — you do not want one giant prompt trying to handle everything. Routing puts a lightweight classifier step first: it reads the request, picks the right sub-flow (or tool, or specialized model), and dispatches to it. Each downstream handler stays small and focused, which makes the whole system easier to reason about and cheaper to run.

The trap is the one-mega-prompt agent: a single instruction block stuffed with “if it's about billing do this, unless it's a bug in which case do that, but for general questions…” It works in the demo and rots in production — every new case makes the prompt longer, the handlers interfere with each other, and you can't test any one behaviour in isolation because they all share the same tangled context. Routing cuts that knot. Because each handler is a small, independent unit, you can test it alone, give it its own tools, its own tuned prompt, even its own cheaper or more capable model — a trivial FAQ handler doesn't need your most expensive model, and a delicate billing flow can have one. The classifier stays deliberately thin; the intelligence lives in the focused handlers behind it.

One thing to keep honest: routing only shifts the problem, it doesn't erase it. A misclassification sends the request to the wrong expert, and a handler confidently answering the wrong question can be worse than an honest “I'm not sure.” So the classifier deserves real care — a sensible default bucket for the ambiguous cases (note the general fallback in the lab), and, in higher-stakes systems, a way to escalate or ask a clarifying question rather than force every request into a box. Route confidently, but design for the request that fits no clean category.

router.py# Routing: a classifier picks the handler, then we dispatch to it.
# fake_route() is deterministic; a real LLM (or a small classifier) replaces it.

def fake_route(request):
    """Classify the request into an intent. A real model does this step."""
    r = request.lower()
    if any(w in r for w in ('refund', 'charge', 'invoice')):
        return 'billing'
    if any(w in r for w in ('error', 'crash', 'broken', 'down')):
        return 'bug'
    return 'general'

HANDLERS = {
    'billing': lambda q: f'[billing] looking up your account for: {q}',
    'bug':     lambda q: f'[bug] opening a ticket for: {q}',
    'general': lambda q: f'[general] answering: {q}',
}

def agent(request):
    intent = fake_route(request)
    return intent, HANDLERS[intent](request)

for req in ['I want a refund on invoice 88',
            'the checkout page is down',
            'what are your hours?']:
    intent, reply = agent(req)
    print(f'{intent:8} <- {req!r}')
    print(f'         {reply}')

billing  <- 'I want a refund on invoice 88'
         [billing] looking up your account for: I want a refund on invoice 88
bug      <- 'the checkout page is down'
         [bug] opening a ticket for: the checkout page is down
general  <- 'what are your hours?'
         [general] answering: what are your hours?

The router itself is trivial control flow — classify, then look up a handler. The value is architectural: each handler is a small, testable unit, and you can give each one its own tools, prompt, or even a cheaper model. A real classifier is usually a quick model call or a small trained classifier; the dispatch table stays exactly as shown.

6 · Error handling & retries in the loop

The demo works flawlessly; the production version falls over in an hour. The reason is almost never the reasoning — it's that a tool hiccuped. The network blipped, an API returned a 429, a database was mid-failover for two seconds. In a notebook you never see these; at real volume they're constant. An agent that assumes its tools always succeed is an agent that assumes it lives in the demo, and the world it actually runs in is messier than that.

Tools fail. A call raises an exception, times out, or returns junk that does not parse. A naive agent crashes or, worse, feeds the garbage forward. The robust move is to catch the failure, feed the error back to the model as an observation, and let it retry — bounded by a maximum attempt count so a persistently broken tool cannot loop forever.

The phrase “feed the error back” is where an agent does something a plain retry loop can't. Ordinary software retries blindly — same call, same arguments, hope the blip passed. An agent can do better: hand the model the actual error text as an observation and it can reason about it. Told “invalid date format: expected YYYY-MM-DD”, a capable model reformats its argument and the second attempt succeeds — it fixed the cause, not just re-rolled the dice. That's why the error message matters as much as the retry itself; a vague “request failed” teaches the model nothing, while a precise one turns a failure into a hint.

Two mistakes sink naive retry code. The first is no cap: an unbounded retry against a genuinely broken tool — deleted resource, wrong credentials — is an infinite loop that quietly drains your token budget until someone notices the bill, which is exactly why max_attempts below is mandatory, not optional. The second, subtler one is retrying things that will never succeed. Retries are medicine for transient failures — a timeout, a rate limit, a momentary blip. They do nothing for terminal ones: an auth failure or a 404 is wrong on attempt one and wrong on attempt three, so retrying just burns attempts before failing anyway. The skill is telling the two apart and giving up immediately on the terminal kind, as the callout after the lab spells out.

retries.py# Capped retries: catch the failure, feed the error back, try again up to a limit.
# The 'tool' here fails the first two times, then succeeds -- deterministic, no
# randomness or clock. A real agent feeds the error text back to the LLM.

class ToolError(Exception):
    pass

def flaky_tool(state):
    """Fails until it has been nudged twice; then returns a value."""
    if state['attempts'] < 2:
        raise ToolError(f"transient failure #{state['attempts'] + 1}")
    return 'OK: fetched 42 records'

def call_with_retries(tool, max_attempts=3):
    state = {'attempts': 0}
    last_error = None
    for attempt in range(1, max_attempts + 1):
        try:
            result = tool(state)
            print(f'attempt {attempt}: success -> {result}')
            return result
        except ToolError as e:
            last_error = str(e)
            print(f'attempt {attempt}: caught {last_error!r}; feeding back + retrying')
            state['attempts'] += 1        # what the model would learn from the observation
    print(f'giving up after {max_attempts} attempts; last error: {last_error!r}')
    return None

call_with_retries(flaky_tool)

attempt 1: caught 'transient failure #1'; feeding back + retrying
attempt 2: caught 'transient failure #2'; feeding back + retrying
attempt 3: success -> OK: fetched 42 records

The cap is not optional. Without max_attempts a tool that is genuinely broken (bad credentials, a deleted resource) turns your agent into an infinite loop. Feeding the error text back matters too: a good model reads “invalid date format” and fixes its argument on the next try instead of repeating the same mistake.

7 · Which pattern when

The most common mistake with these patterns isn't misusing one — it's reaching for the fanciest one by reflex. Engineers who've just learned ReAct wrap every task in a reasoning loop; teams enamoured with reflection critique-and-revise a one-line lookup. It feels sophisticated and it's almost always wrong. The best agent for a job is the one with the least structure that still makes it reliable — every extra pattern is more model calls, more latency, and more surface area for something to go sideways.

The patterns are not ranked — each fits a shape of problem. Reach for the simplest one that covers the task, and compose them only when the task genuinely needs it.

Here's a way to hold them all in your head. Match the pattern to what the task looks like, not to what's impressive. If one tool answers the question, you don't need a pattern at all — just call it (that's the basic loop from 4.1). If the next step depends on the last result, you need to adapt as you go: that's ReAct. If the path is known and repeatable, decide it once: plan-and-execute. If getting it wrong is expensive, add a quality gate: reflection. If the requests come in different flavours, sort them at the door: routing. And whenever any of these touches a flaky tool, wrap that call in retries — that one is orthogonal, a seatbelt you can add to any of the others.

The last idea is the one that turns a list of patterns into real engineering: they compose. A production agent is rarely “a ReAct agent” or “a routing agent” — it's a stack of patterns, each earning its place. A support system might route to a billing sub-agent, which runs a plan, drops into ReAct for the one open-ended step, reflects before it commits a refund, and retries every tool call underneath. Each layer is there because that part of the task demanded it, not because the pattern was available. The judgment you're building is knowing which layers a given task actually needs — and, just as importantly, which it doesn't.