Agentic Patterns

An agent is a program that decides its own control flow. You give it a goal, a set of tools and a stopping condition, and the model chooses which tool to call next based on what it learned from the last one. That single property - the loop is decided at runtime, not at design time - is what separates an agent from every pipeline you have written before, and it is also the source of every operational and governance problem that follows.

The spectrum, not the label

"Agentic" is a spectrum, not a binary. It is worth being honest about where a system actually sits, because the engineering cost climbs steeply as you move down this table.

Before you build an agent, four questions decide it:

• Complexity - is the task multi-step and genuinely hard to specify in advance? "Extract the invoice total" is not. "Diagnose why this build is flaky" is.
• Value - does the outcome justify the latency and token cost? An agent is roughly an order of magnitude more expensive than the equivalent workflow.
• Viability - is the model actually good at this class of task today? Test before you architect.
• Cost of error - can mistakes be caught and reversed? Tests, review gates and rollbacks are what make autonomy affordable.

If any answer is "no", stay a tier higher. Most production "AI agents" would be better, cheaper and more reliable as a workflow with three deterministic stages.

Core patterns

1. The augmented model

The atom that every other pattern is built from: a model with tools, retrieval and memory attached. One call, one response, possibly one tool use. Everything below is a way of arranging this atom.

2. Prompt chaining

Decompose a task into fixed steps where each step's output feeds the next, with programmatic gates between them.

   outline
      │
      ▼   gate: has at least 3 sections?
   draft
      │
      ▼   gate: passes the style check?
   polish

Use it when the decomposition is stable and known. The gates are the point - they are cheap, deterministic and catch failures before you spend tokens on the next stage.

3. Routing

Classify the input, then dispatch to a specialist path. A refund request, a bug report and a sales enquiry need different prompts, different tools and often different models.

                     ┌──▶ refunds   (payments, orders)
input ──▶ classify ──┼──▶ technical (logs, status page)
                     └──▶ sales     (crm, pricing)

Routing lets you spend capability where it matters. A cheap fast model routes; the expensive one handles only the hard branch.

4. Parallelisation

Two distinct shapes, often confused:

• Sectioning - split the work into independent subtasks, run them concurrently, join the results. Reviewing twelve files, checking six compliance rules, summarising four documents.
• Voting - run the same task several times with different framings and aggregate. Useful when a false negative is expensive: three reviewers each looking for a different class of bug will find more than one reviewer asked to find everything.

Sectioning buys wall-clock time. Voting buys confidence. Do not use voting where the model's errors are correlated - three identical prompts vote three identical wrong answers.

5. Orchestrator-workers

An orchestrator decomposes the task at runtime - the subtasks are not known in advance - and delegates each to a worker with its own fresh context. Workers report back; the orchestrator synthesises.

The real benefit is context isolation. A worker that reads forty files returns a two-paragraph finding, not forty files' worth of tokens, into the orchestrator's window. That is the pattern's main value, more than the parallelism.

The real cost is coordination: each worker re-establishes context, re-explores, and reports back, and the orchestrator then re-reads the report. Delegate for genuinely independent, sizeable tracks - not for work the orchestrator could finish in three tool calls.

6. Evaluator-optimiser

One model produces, another critiques against explicit criteria, the first revises. Loop until the criteria pass or you hit an iteration cap.

generate ──▶ evaluate ──▶ needs work? ──▶ revise ──┐
                 │                                 │
                 └──── passes ──▶ done   ◀─────────┘

This works when you can articulate what "good" looks like as a checkable rubric - "the CSV has a numeric price column for every SKU", not "the analysis is thorough". Vague criteria produce noisy loops that never converge. Always cap the iterations.

A fresh-context evaluator beats self-critique. The generator is anchored on its own reasoning; a separate reviewer that has only seen the output and the rubric is more honest.

7. Reasoning techniques: CoT, ReAct, ToT

Three named patterns for how a model works through a problem before or while acting. They are worth knowing by name because most agent writing assumes them.

      CoT              ReAct            ToT

   ┌───────┐       ┌───────┐         ┌───────┐
   │ think │       │ think │◀──┐     │ think │
   └───┬───┘       └───┬───┘   │     └───┬───┘
       ▼               ▼       │     ┌───┼───┐
   ┌───────┐       ┌───────┐   │     ▼   ▼   ▼
   │answer │       │  act  │   │     a   b   c
   └───────┘       └───┬───┘   │     └───┼───┘
                       ▼       │         ▼
                   ┌───────┐   │     ┌───────┐
                   │observe│───┘     │ score │
                   └───────┘         └───┬───┘
                                         ▼
                                     ┌───────┐
                                     │ best  │
                                     └───────┘

Chain of Thought is reasoning before answering. It began as a prompting trick - "let's think step by step" - and is now largely built into models as extended or adaptive thinking, so you rarely hand-write it. What you choose today is how much, via an effort or thinking setting. The modern caveat matters: on current models, instructing a model to think step by step often adds nothing and sometimes hurts, because it already does.

ReAct interleaves reasoning with tool calls - think, act, observe, think again. You have already seen it: the loop in the next section is ReAct. The property that makes it work is that the model sees the result of each action before choosing the next one, so it can recover from a surprise instead of following a plan into a wall.

Its counterpart is plan-and-execute: produce a complete plan up front, then carry it out. Fewer model calls and easier to review, but the plan was written before any evidence came in. The useful hybrid is to plan first for shape and cost, then let ReAct handle each step.

Tree of Thoughts explores several reasoning branches, scores them, and keeps the best. It is the most expensive of the three by a wide margin - you pay for every branch you discard.

For most production agents, ToT is not the right tool. Evaluator-optimiser (#6) or voting (#4) captures much of the benefit at a fraction of the cost, and both are easier to debug.

8. The autonomous loop

The core agent pattern, and the simplest to write. This is ReAct in code - think, act, observe, repeat:

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()
const messages: Anthropic.MessageParam[] = [
  { role: 'user', content: userRequest },
]

while (true) {
  const response = await client.messages.create({
    model: 'claude-opus-5',
    max_tokens: 16000,
    thinking: { type: 'adaptive' },
    output_config: { effort: 'high' },
    tools,
    messages,
  })

  if (response.stop_reason === 'end_turn') break

  // Preserve the full content - tool_use blocks must survive the round trip
  messages.push({ role: 'assistant', content: response.content })

  const toolResults = await Promise.all(
    response.content
      .filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use')
      .map(async (block) => ({
        type: 'tool_result' as const,
        tool_use_id: block.id,
        content: await execute(block.name, block.input),
      })),
  )

  // All results go back in ONE user message
  messages.push({ role: 'user', content: toolResults })
}

Three details in that loop are load-bearing and routinely got wrong:

• Push back response.content in full, not just the text. Dropping the tool_use blocks breaks the next turn.
• Return every tool_result in a single user message. Splitting them across messages quietly teaches the model to stop making parallel tool calls.
• On failure, return a tool_result with is_error: true and a useful message. Do not drop it and do not throw - the model can recover from an error it can read.

In practice you rarely hand-write this. The SDK's tool runner (client.beta.messages.toolRunner) drives the same loop, and still yields each turn so you can gate, log, intercept or modify results before they go back.

9. Reflection and self-verification

Modern models verify their own work without being told, and instructions like "double-check your answer" now cause over-verification rather than accuracy. If you carried a verification step over from an older model, measure whether removing it changes anything - often it does not, and you save the tokens.

Where explicit verification still earns its place: long autonomous runs, where you want the agent to establish a checking harness up front and run it on a cadence against the original specification.

10. Human-in-the-loop

Not a fallback - a first-class pattern. Three placements, each with different ergonomics:

Per-action gating is where the tool surface design pays off - see below.

11. Memory

Three horizons, three mechanisms:

• Working memory is the conversation itself. Manage it with context editing (prune stale tool results) and compaction (summarise when approaching the window).
• Episodic memory is what happened in past sessions - previous runs, prior decisions, corrections.
• Semantic memory is durable knowledge - conventions, preferences, learned lessons.

The cheapest useful implementation of the latter two is a directory of markdown files the agent reads and writes. One fact per file, a one-line summary at the top, and an index. Tell the agent where it lives, tell it to consult it, and give it a format - agents perform noticeably better when they have somewhere to write things down.

Capability

Patterns arrange the loop. Capability determines what the loop can actually do.

Tool surface design

Your tool surface is your control surface. The model emits tool calls; your harness handles them. The shape of those calls determines what the harness can enforce.

A bash tool gives enormous leverage and almost no control - every action arrives as the same opaque string. Promoting an action to a dedicated tool gives the harness typed arguments it can intercept, gate, render, audit and schedule.

Promote an action to its own tool when you need to:

• Gate it. send_email is trivial to put behind a confirmation. bash -c "curl -X POST ..." is not.
• Enforce an invariant. A dedicated edit tool can reject a write if the file changed since it was last read. Bash cannot.
• Render it. Asking the user a question as a tool call lets you draw a real modal instead of parsing prose.
• Parallelise it. A read-only grep can be marked parallel-safe. Through bash, the harness cannot distinguish grep from git push, so it must serialise everything.

Rule of thumb: start with bash for breadth, promote for control.

Writing tool descriptions

Descriptions are prompt, not documentation. Be prescriptive about when to call, not only what it does:

{
  "name": "search_orders",
  "description": "Search customer orders by email, order ID or date range. Call this whenever the user asks about order status, delivery, refunds or purchase history - do not answer from prior conversation context, since order state changes.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": { "type": "string", "description": "Customer email, exact match" },
      "order_id": { "type": "string", "description": "Order ID, e.g. ORD-4182" }
    },
    "required": []
  }
}

Trigger conditions in the description measurably improve should-call rate. Keep the set focused - too many tools degrades selection.

Structured outputs

When downstream code parses the output, constrain it rather than hoping:

const response = await client.messages.create({
  model: 'claude-opus-5',
  max_tokens: 16000,
  output_config: {
    format: {
      type: 'json_schema',
      schema: {
        type: 'object',
        properties: {
          category: { type: 'string', enum: ['refund', 'technical', 'sales'] },
          urgency: { type: 'integer' },
          summary: { type: 'string' },
        },
        required: ['category', 'urgency', 'summary'],
        additionalProperties: false,
      },
    },
  },
  messages,
})

The same guarantee is available on tool inputs with strict: true on the tool definition. Between the two, most "the model returned malformed JSON" bugs stop existing.

Retrieval

Retrieval in an agentic system is a tool, not a preprocessing step. The old shape - embed the query, stuff the top-k chunks into the prompt, answer - assumes you know what is relevant before you start. An agent that can search, read a result, and search again based on what it found will outperform it on anything non-trivial.

Give it several ways in, because different questions need different lookup shapes and the agent will pick:

The two failure modes are worth naming. Retrieval that returns nothing useful is usually a chunking problem - chunks too small lose the context that made them meaningful, too large and the signal drowns. Retrieval that returns too much is a ranking problem, and a reranking pass over the top ~50 results costs little and helps a lot.

Evaluate retrieval separately from the agent. If you only measure the final answer you cannot tell a reasoning failure from the agent never having seen the right document. Score recall on a fixed set of questions with known answers; that number moves independently of everything else, and when it drops you know exactly where to look.

Learning and adaptation

Agents that get better over time are mostly not doing what the phrase implies. Almost nothing in production updates model weights; what improves is the context the model is given. Three mechanisms, in the order they are worth trying:

• Written lessons. The agent records what it learned - a correction, a convention, an approach that worked - and reads them back on later runs. This is the memory pattern above used deliberately, and it is by far the highest return for the effort.
• Growing example sets. Keep the cases the agent got right, and retrieve the closest few as examples for a new task. This is few-shot prompting where the shots are chosen per request rather than fixed.
• Feedback loops into evals. Every production failure becomes a test case, and the prompt or tool surface changes until it passes. Slower, but it is the only one that compounds.

Fine-tuning is a fourth option, and mostly the wrong first move: it is a slow loop, it bakes in what you knew at training time, and it is hard to undo. Reach for it when you need a behaviour that prompting cannot produce reliably, not to teach an agent facts.

Two things to watch. Anything written by the agent and replayed later is untrusted content by the next session's standards - a lesson learned from a poisoned web page is now a persistent instruction. And unbounded memory degrades: without pruning, contradictory or stale lessons accumulate until they are worse than nothing.

Context management

Context is the scarcest resource in a long-running agent, and the failure is silent: quality degrades before anything errors.

Long-running agents typically use all of these at once.

Prompt caching

Caching is a prefix match: any byte change anywhere in the prefix invalidates everything after it. Render order is tools → system → messages.

The architecture matters far more than the cache markers:

• Keep the system prompt frozen. A timestamp or user ID interpolated into it means nothing ever caches.
• Do not change the tool set or the model mid-conversation - tools render at position zero.
• Serialise deterministically. An unsorted JSON.stringify over an object with unstable key order is enough to break it.
• Put volatile content last, after the final breakpoint.

Verify with usage.cache_read_input_tokens. If it is zero across repeated requests with the same prefix, something upstream is mutating the bytes.

Where the loop runs

Three deployment shapes, distinguished by who owns the harness and who owns the infrastructure:

Start with the tool runner. Move to a managed runtime when you want someone else to own the sandbox, session state, scheduling and persistence.

Operations

An agent in production is a distributed system whose most important component is non-deterministic. Operate it accordingly.

Evaluations come first

You cannot tune what you cannot measure, and with agents you cannot eyeball it either - the same prompt gives different traces on different runs. Build the eval set before you build the agent.

Three layers, all necessary:

• Unit - does each tool do the right thing given the right arguments? Ordinary tests.
• Trajectory - did the agent take a sensible path? Did it call the tools it should have, in a reasonable order, without flailing?
• Outcome - is the final artefact correct? This is what actually matters, and it needs a rubric with checkable criteria.

Twenty representative cases drawn from real traffic beat two hundred synthetic ones. Add every production failure to the set - that is how the suite earns its keep.

An LLM judge is a reasonable outcome grader when the rubric is explicit. Validate the judge against human labels before you trust its numbers, and keep it in a separate context from the generator.

Observability

An agent trace has structure a normal APM span does not: nested tool calls, retries, delegation, token accounting. Instrument for it.

Capture per run: the full message history, every tool call with arguments and results, token usage per turn (input, output, cache read, cache write), latency per turn, stop reasons, and the final outcome. Tag with a request ID, a user ID and a version identifier for the prompt and the tool set.

The questions you will actually need to answer at 2am:

• Which tool call went wrong, and what did it return?
• How many turns did this take, and where did it start looping?
• Which prompt version was live?
• What did it cost, and which turn was expensive?

Version your prompts and tool definitions like code. "It got worse last Tuesday" is unanswerable without them.

Cost and latency

Both are dominated by turn count, not by per-token price. A 40-turn agent at a cheap model is more expensive than a 6-turn agent at an expensive one, and it is slower and worse.

Levers, roughly in order of effect:

1. Reduce turns. Give the full task specification up front rather than dribbling it out across interactive turns. A well-specified opening prompt is the single biggest saving available.
2. Effort control. Modern models expose an effort dial (low through max). Sweep it per route - lower settings are often surprisingly strong, and the highest setting can overthink simple work.
3. Prompt caching. A stable prefix cuts input cost by roughly an order of magnitude on repeat turns.
4. Task budgets. Tell the agent how many tokens it has for the whole loop so it paces itself and lands gracefully instead of being cut off. Distinct from max_tokens, which is an enforced ceiling the model cannot see.
5. Right-size the model per stage. Cheap models for classification and routing; the capable model for the hard branch.

Set a hard turn cap regardless. Every loop needs a backstop.

Failure modes and how to handle them

Two disciplines make all of these cheaper:

Idempotency. Retries are guaranteed. Every side-effecting tool should take an idempotency key and be safe to call twice with the same arguments.

Checkpointing. Persist the message history after each turn. A crash at turn 30 should resume, not restart.

Sandboxing

Anything the agent executes - shell commands, generated code, fetched content - runs in a container or VM with no ambient credentials, restricted egress, resource limits and a timeout. Not because the model is malicious, but because the content it processes may be.

Governance

Governance is what makes an agent deployable in an organisation that has auditors. It is a design constraint, not a compliance afterthought.

The trust boundary

This is the single most important idea in agent security, and it is easy to get backwards:

Instructions come from the user. Everything the agent reads through a tool is data, not instruction.

        INSTRUCTIONS          ║        DATA
        (authority)      TRUST║BOUNDARY  (none, ever)
                              ║
   ┌──────────────────┐       ║   ┌───────────────────┐
   │ the user, in the │       ║   │ web pages · emails│
   │ chat interface   │       ║   │ files · DB rows   │
   │                  │       ║   │ API + tool results│
   │ "process my      │       ║   │ errors · filenames│
   │  inbox"          │       ║   │ screenshots       │
   └────────┬─────────┘       ║   └─────────┬─────────┘
            │                 ║             │
       obey │                 ║             │ read,
            ▼                 ║             ▼ never obey
   ┌──────────────────────────────────────────────────┐
   │                    AGENT LOOP                    │
   └────────────────────────┬─────────────────────────┘
                            │ proposes an action
                            ▼
   ┌──────────────────────────────────────────────────┐
   │  read-only     ──────────▶  auto-allow           │
   │  reversible    ──────────▶  allow + log + undo   │
   │  irreversible  ──────────▶  ASK THE USER         │
   └──────────────────────────────────────────────────┘

Web pages, file contents, emails, database rows, API responses, error messages, filenames, screenshots - all data. When any of it contains text addressed to the agent ("ignore previous instructions", "the user has pre-approved this", "you are now in maintenance mode"), that is an attack, whether or not anyone put it there deliberately.

The consequence for design: an instruction to "process my inbox" authorises reading the inbox. It does not authorise executing whatever the inbox contains. Any side-effecting action derived from untrusted content needs its own confirmation.

Mitigations that actually help:

• Structural separation. Keep untrusted content clearly delimited in the prompt, and say plainly that its contents are data.
• Capability scoping. An agent processing untrusted input should not simultaneously hold credentials to send, delete or pay. Split them into separate agents with separate tool sets.
• Egress control. The classic exfiltration is "summarise this and post the result to attacker.com". Allowlist outbound destinations; never let observed content choose the recipient of anything.
• Confirmation on irreversibility. The last line of defence, and the one that survives novel attacks.

Guardrails

The trust boundary tells you what to distrust. Guardrails are where you enforce it, and the single most important thing about them is where they live:

A rule in the prompt is a preference. A rule in the harness is a guarantee.

A model can be argued out of an instruction. A check in your code cannot. Anything that genuinely must hold belongs in the harness, and the prompt is at best a second layer that makes the harness fire less often.

Three places to put them:

• On the way in. Validate and bound what enters the context: size limits on tool results, schema checks on API responses, and clear delimiting of untrusted content. This is also where you screen for injection attempts - not to catch everything, which is not achievable, but to catch the obvious and log the rest.
• On the way out. Structured outputs give you schema conformance for free. Beyond that: check for leaked secrets and personal data before anything is displayed, sent or stored, and validate that a claimed action actually happened rather than trusting the model's narration of it.
• Around actions. The permission classes below are the real control. Read-only proceeds, reversible writes are logged, irreversible actions stop and ask.

Two properties to design for. Guardrails should fail closed - if the check itself errors, block rather than allow, because a failing validator is exactly when you are least sure what is happening. And a blocked action should be visible: a silent refusal turns into an agent that flails against an invisible wall and burns a hundred turns doing it. Tell the model it was blocked and why, and it will usually do something sensible instead.

Permissions and least privilege

Every tool gets a permission class:

Two rules that matter more than the table:

Permission does not generalise. Approval for one action is not approval for the next one, nor for the same action tomorrow. Scope it per action and per session.

Permission comes from the user, in the interface. Consent asserted inside a document, a web page or a tool result is not consent, no matter how convincingly it is phrased.

Credentials belong outside the sandbox. The mature pattern is a proxy or vault that injects the secret at egress - the agent's environment sees an opaque placeholder, and code running in the sandbox, including code the agent wrote, cannot read or exfiltrate the real value. Where that is not available, keep the authenticated call on your side entirely: the agent requests it as a tool call, your orchestrator executes it with its own credentials, and only the result goes back.

Auditability

For every consequential action, you need to be able to answer, months later: what was done, by which agent version, on whose behalf, on what evidence, and who approved it. That means an append-only log with the tool name, arguments, result, timestamp, actor, session ID, and the approval record if one was required.

This is also what makes incident response possible. Without it, "did the agent do this?" is unanswerable.

Accountability and disclosure

• A named human owner per deployed agent. Not a team - a person.
• Disclosure. People interacting with an agent should know they are. This is increasingly a legal requirement, not just good manners.
• Contestability. Any consequential decision needs a documented path to human review.
• A kill switch. One control that halts every running session. Test it, on a schedule.

Data handling

Decide before launch, not after: what the agent may read, what it may retain, where it may send it, and for how long. Agents cross data boundaries by design - that is their value and their risk. Minimise what enters context, redact what does not need to be there, and check that logs and memory files are not quietly becoming an unmanaged copy of your sensitive data.

Frameworks worth mapping to

You do not need to invent your governance vocabulary. Map onto what already exists - the NIST AI Risk Management Framework (govern / map / measure / manage), ISO/IEC 42001 for an auditable management system, and the EU AI Act's risk tiers if you have European exposure. Auditors recognise these, which is most of the reason to use them.

A maturity checklist

Roughly in the order these should exist:

Before the first deploy

• [ ] An eval set of real cases with pass criteria
• [ ] Tracing on every run - messages, tool calls, tokens, outcome
• [ ] A hard turn cap and a total token budget
• [ ] Irreversible actions behind explicit confirmation
• [ ] Guardrails enforced in the harness, not only in the prompt
• [ ] Execution sandboxed, no ambient credentials
• [ ] Prompts and tool definitions versioned

Before it handles anything that matters

• [ ] Untrusted content treated as data, with tests that prove it
• [ ] Idempotency keys on every side-effecting tool
• [ ] Checkpoint and resume
• [ ] Audit log with approval records
• [ ] A named owner and a tested kill switch
• [ ] Cost and latency dashboards with alerts

Before you scale it

• [ ] Regression evals in CI on every prompt change
• [ ] Per-route effort and model tuning
• [ ] Prompt caching verified by cache-read metrics
• [ ] Context strategy for long runs - editing, compaction, memory
• [ ] Documented data retention and disclosure

What to take away

The patterns are simple. Almost every production agent is a loop, some routing, a bit of parallelism, an evaluator and a human gate on the dangerous parts. There is no secret architecture.

The difficulty is entirely in the surrounding engineering: a tool surface shaped so the harness can control it, evals that tell you when you have regressed, traces that let you debug a non-deterministic system, and a trust boundary you can state in one sentence and defend in code.

Build the simplest thing that works, measure it honestly, and add autonomy only where you have earned it.