Being a catalogue of the genus Agentum — its architectures, habitats, and abundant failure modes — compiled from specimens collected in production, not from the literature alone.
The specimens catalogued herein were not observed from a safe distance. Every pattern, failure mode, and guardrail on this page was collected in the field; the three expeditions and their evidence are recorded in Plate X. The literature is cited where it is good — Anthropic's pattern catalogue, Willison's lethal trifecta — but the ordering principle of this guide is what survives contact with production.
One deliberate omission: you will find no model names, prices, context-window sizes, or benchmark scores here. Those rot in months; the anatomy below drifts in years. For the volatile layer, see the companion pages: which model to use, what it costs, which coding agent, and open-weight options.
Building alone, on your first agent? Begin with Part One, then learn the organism in Part Two.
Leading a team adopting agents? Read Part One, then go directly to containment in Part Three.
Reviewing someone else's agent for security? Start with Plate VII and Plate VIII.
Deciding whether to fund this at all? Examine Plate II, Plate III, and Plate VIII.
A dichotomous key: match your task's shape to the cheapest architecture that solves it. The canonical pattern names follow Anthropic's catalogue. † Dec 2024, still current Jul 2026
Anthropic's core distinction: workflows orchestrate LLM calls through predefined code paths; agents let the LLM dynamically direct its own process and tool use. Their advice, validated repeatedly in the field: find the simplest solution possible, and add agentic complexity only when simpler solutions fall short. Work down this table and stop at the first row that fits.
| Your task's shape | Reach for | Why | Watch out for |
|---|---|---|---|
| Fully specifiable, fixed steps, structured inputs | A script (L0) | Deterministic, free, debuggable. The null hypothesis. | Sunk-cost agent envy: bolting a model onto a solved problem. |
| One classification, extraction, or transformation | A single LLM call with retrieval and examples | One call is testable and cacheable; most "agent" pitches decompose into this. | Prompt sprawl — if one call needs 12 instructions sets, split the task. |
| A known sequence of LLM steps, each feeding the next | Prompt chaining (workflow) | Each step is simpler than the whole; programmatic gates between steps catch drift early. | Error compounding — validate at the gates, not just at the end. |
| Heterogeneous inputs needing different handling | Routing (workflow) | Classify once, then send each category to a prompt optimized for it. | The "other" bucket — misroutes fail quietly unless you track them. |
| Independent subtasks, or you want multiple attempts | Parallelization (workflow: sectioning or voting) | Concurrency for speed; voting for confidence on judgment calls. | Aggregation is where the bugs live; majority vote needs an odd panel. |
| Subtasks unknowable until runtime | Orchestrator-workers (workflow) | A lead model decomposes dynamically and synthesizes worker results. | Decomposition quality bounds everything; log it and review it. |
| Output quality improves with critique against clear criteria | Evaluator-optimizer (workflow) | One model generates, another critiques, loop until the rubric passes. | Without a crisp rubric it converges on confident mediocrity. |
| Open-ended task; steps depend on what the environment says back | A single agent (L2–L3) | This is the genuine agent use case: tool feedback determines the next step. | Pay the autonomy tax knowingly: latency, cost, variance all rise. |
| Breadth exceeding one context window (research, audits, migrations) | Multi-agent fleet (L4) | Parallel workers with fresh windows cover ground one context can't hold. | Token multiplication; contamination via shared summaries. |
| Recurring task, nobody available at runtime | Standing automation (L5) | Leverage compounds when the human adds no information per run. | Everything in the L5 entry of Plate II. Kill switch first. |
Decision heuristic: if you can draw the flowchart in advance, it's a workflow — build the flowchart. Reserve agents for tasks where the flowchart can only be discovered by doing the task.
Six degrees of delegation, with the guardrails each rung demands. Read bottom-up, as ladders are climbed. Click a rung for its full entry.
The single most useful question in agentic AI is not "which framework?" but "which rung?" Each rung trades reliability for leverage, and each is earned by the guardrails of the rung below it. Most production incidents are a system operating one rung above what its guardrails support — an L4 demo running with L1 discipline.
What it is: an agent invoked by cron, webhook, or queue with nobody watching. Example: a weekly freshness job that re-verifies one dated reference page per run and commits the fix — but does not deploy it.
Earned by: L3's independent verification and L4's tracing, plus a drafts-only write posture: the agent may propose, commit, or draft; a human owns every write to a system of record.
Dominant failure: silent drift — the task, the data, or the model changes and nobody notices for weeks; plus prompt injection with no human in the loop to catch it. See the silent failure and prompt injection.
What it is: a lead agent breaks a task down and spawns workers (Anthropic's orchestrator-workers pattern, made recursive). Example: one worker per cheatsheet spec, with the parent owning all shared files and the batch commit.
Earned by: disjoint ownership (no two agents write the same file), per-agent least-privilege scopes, and per-run traces you can actually read.
Dominant failure: cross-agent contamination and cost multiplication — one polluted summary poisons every downstream worker, and token spend scales with fleet size whether or not quality does. See cross-agent contamination and the runaway loop.
What it is: an agent that treats "done" as a claim to be tested: it builds the page, then loads it in a browser and asserts the console is clean before saying so.
Earned by: a verification step that is independent of the generation step (run the tests, load the page, diff the output) and an eval set that catches regressions when the prompt or model changes.
Dominant failure: hallucinated success — self-grading is the same model marking its own homework; it passes what it wrote because it wrote it. See the hallucinated success.
What it is: the canonical agent per Anthropic's definition — the LLM directs its own tool use based on environmental feedback. Example: a coding agent given read/write on one repo and a test runner, supervised in a terminal.
Earned by: typed, scoped tools; read-only as the default posture; a sandbox for anything that executes.
Dominant failure: the confused deputy — the agent's permissions exceed the task's needs, and an attacker (or an accident) spends the difference. See the confused deputy.
What it is: chat-assisted work — drafting, summarizing, explaining — where the human is the executor. Most real-world AI use lives here, and much of it productively.
Earned by: nothing technical; it's the floor for model use. The discipline is human: outputs get validated against a source of truth before they're acted on.
Dominant failure: ungrounded copy/paste — fluent output pasted into decisions, contracts, and code without verification. See automation bias.
What it is: cron, CI, SQL, a shell script. Example: this site's popularity scores refresh on a schedule via a plain script — no agent involved, because none is needed.
Why it's on the ladder: as the null hypothesis. If the task can be fully specified, L0 beats every rung above it on cost, latency, and reliability — an agent that could be a cron job is a defect, not an achievement.
Dominant failure: brittleness — it breaks loudly on input it wasn't written for. (Loud breakage is a feature; note the contrast with L5's silent drift.) See the silent failure for the more dangerous alternative.
Reading the ladder: climb only when the rung below is boring — L2 when validated chat output becomes repetitive, L3 when supervision becomes rubber-stamping, L4 when one context window can't hold the work, L5 when the human adds no information. Descend at the first unexplained failure.
This ladder measures one agent's autonomy on one task. A second, orthogonal axis measures the practitioner's own role as the fleet scales from one agent to a thousand — see Plate III, The Naturalist's Progress. Both must be climbed, and trust must lead the count on each.
A second axis, orthogonal to the Autonomy Ladder: how the practitioner's own role metamorphoses as the fleet scales by orders of magnitude — and which bottleneck moves next.
Plate II ranks how far you trust one agent on one task. This plate ranks something orthogonal: how many agents you run at once, and what that makes you. As the count climbs by orders of magnitude — one, ten, a hundred, a thousand — your job stops being "write the code" and becomes, in turn, to review it, to engineer the context and trust that make review rare, and finally to choose what gets built at all. The bottleneck migrates with you, and each step up is earned by trust in the loop, never by adding agents. Scale the fleet before the loop is trustworthy and you have not multiplied output — you have multiplied the review queue.
| Fleet | Your role | What it looks like | The bottleneck now | What earns the next order of magnitude |
|---|---|---|---|---|
| ~0 Hortus clausus |
The gated yard — pre-adoption | Access is gated or process-heavy; only older, lighter models are approved; there is no path to host or ship what an agent produces, so outputs die on the local machine. | Legacy security and approval processes; decisions driven by cost-per-token containment rather than outcomes; no technical voice in the room where autonomy is judged. | Executive alignment and a secure, sanctioned launch path — someone accountable clears the blockers and opens a governed door. |
| ~1 Socius par |
The pair — you and one agent | One human, one agent, mostly supervised — a fast pair programmer. One session at a time; you review nearly every change before it merges. A task that used to fill an afternoon now fits between meetings. | Your attention. Low trust means you read everything and never look away; the work is synchronous — you sit and watch it work instead of moving on to the next thing. | A self-verification loop you actually trust — tests, build, lint, end-to-end checks — plus non-blocking permissions, so you can stop watching keystrokes and start reviewing results. |
| ~10 Magister cohortis |
The orchestrator | You run five to ten agents at once, each isolated in its own worktree, jumping between them. Each checks its own work — tests, build, lint, security scan — before you see it. You review final diffs, not keystrokes, and the maintenance backlog starts shrinking. | Review. You hand-write far less code and instead inspect many streams of it; steering and reviewing now fill the hours that writing used to. | Let agents pull their own context (read the code, the docs, the discussions); automate code and security review; break recurring work into named loops and routines. |
| ~100 Praefectus praefectorum |
Manager of managers — an org tree | Agents write nearly all the code. The tree is too deep to babysit. "Did you read the code?" becomes "what context was the model missing, and how do we supply it next time?" Maintenance that used to wait for a spare hour now runs continuously in the background. | Trust in the loop, and your team's decision throughput. The trap: scaling agent count before the loop has earned widespread trust. | Scaled automation of domain-specific work — migrations, fuzzing, feature-building, feedback remediation — with token economics watched deliberately as usage climbs. |
| ~1,000+ Rector intentionis |
Steering by intent | The loop is closed; most agents are kicked off by other agents. Hundreds to thousands run at once; you steer by intent and monitor by exception. A quarter-long migration becomes a workflow you start and check on. | Identifying which work is worth automating, and enforcing the right guardrails for each kind of work. | — the top of this axis. Growth is now in the breadth of automated domains, not the depth of the tree. |
The test that governs every step: "is this something an engineer would have done?" — if yes, it is a candidate to automate; if no, adding an agent will not rescue it. Watch where value migrates: from writing code, to reviewing it, to engineering the context that makes review rare, to deciding what should exist at all. The two ladders interlock — you cannot honestly run a hundred agents (this plate) while each is stuck at hand-held L1–L2 autonomy (Plate II). Climb both; climb the trust before the count.
The five-stage anatomy shared by every member of the genus — and what characteristically breaks at each stage.
"The framework will handle it." Abstractions promise to absorb the hard parts. Understand the loop underneath: frameworks hide the very layers — context, permissions, verification — where failures live.
Strip away the frameworks and every agent is the same organism: a loop that gathers context, plans, acts through tools, verifies, and iterates until done (or stopped). Diagnose failures by stage — each has a signature pathology.
The agent assembles what it needs: instructions, files, search results, memory. Breaks when: context is stale, bloated, or wrong — garbage retrieval yields confident garbage downstream. See context rot. Mitigate: just-in-time retrieval over bulk pre-loading; curate what enters the window as deliberately as what enters a database (see Plate V).
The model decomposes the task and commits to an approach. Breaks when: it overcommits to a bad plan early and spends the whole budget executing it faithfully. See cross-agent contamination. Mitigate: make the plan an inspectable artifact (a written outline, a todo list) that code or humans can review before execution burns tokens.
Tool calls: edit the file, run the query, call the API. Breaks when: tools are over-privileged, non-idempotent, or return errors the model can't interpret. See the confused deputy. Mitigate: least-privilege scopes, idempotent operations where possible, error messages written for the model to act on (see Plate VI).
The claim "done" gets tested. Breaks when: the stage is skipped, or the model grades its own homework. See the hallucinated success. Mitigate: verification must observe independent artifacts — tests pass, the page renders, the file exists with the right contents — never the agent's self-report.
Loop on failure, report on success. Breaks when: the loop has no ceiling (runaway cost) or the report is rosier than the run (hallucinated success). See the runaway loop. Mitigate: iteration and budget caps with a hard stop; summaries that cite artifacts, not adjectives.
The context window is the organism's entire perceptual field. Curating it is the highest-leverage engineering surface in the discipline.
Prompt engineering asks "how do I phrase the instruction?" Context engineering asks the broader question: of everything I could put in the window, what earns its place? (For the prompt-level craft, see the system prompt builder.)
NOTES.md it will re-read after compaction. gotcha — auto-compaction keeps what looks important; your open bug's stack trace may not make the cut. Persist load-bearing state to files.AGENTS.md — the agent re-reads them each run instead of being told each time. gotcha — memory is an unvalidated input; review what gets written or you're executing last week's mistake forever.The tool layer is where the model touches the world — which makes it both the leverage point and the blast radius.
search_records(query, type) instead of six near-identical per-entity search tools. gotcha — overlapping tools make the model dither between equivalents, and you pay for the deliberation.{"status":"conflict","conflicting_id":"INV-2041"} lets the model branch; "something went wrong with the invoice" does not. gotcha — free-text tool output invites the model to "interpret," and interpretation is where fabrication enters."date must be ISO-8601 (got '7/16/26'); retry as 2026-07-16" — the model self-corrects in one turn. gotcha — stack traces make models flail; raw 500s make them retry the identical call.upsert_row(key, values) over append_row(values). gotcha — non-idempotent side effects (send email, charge card) need dedupe keys or confirmation gates, because retries will happen.find_customer_by_invoice beats post_v2_query_endpoint. gotcha — descriptions are prompts; a vague description is an instruction to guess.| Surface | What it is | Use when | Cost / risk |
|---|---|---|---|
| Bespoke function calling | Tools you define and execute in your own harness. | You control the stack and need exact security properties. | You build and maintain everything; no reuse across agent products. |
| MCP servers | Standardized tool servers any MCP-capable agent can consume. † as of Jul 2026 | You want one integration to serve many agent surfaces, or to consume the existing ecosystem. | Each server is a capability grant and attack surface; audit third-party servers like third-party code. |
| Skills (instruction files) | Versioned procedure documents (SKILL.md) the agent loads on demand — knowledge, not executable capability. | The "integration" is know-how: a procedure, checklist, or house style. Portable across vendors as plain text. | Prompts-as-code: needs review, versioning, and linting like code — see skill-lint and the worked examples in agent-skills. |
A worked example of "context is the product": CodeContext exists because the highest-value integration for a coding assistant is often just a disciplined view of the codebase — a CLI/MCP server that turns a repository into model-ready context.
Twelve specimens, pinned. Each caught at least once in the wild by the author. Learn the detection signal before you meet the specimen.
Prompt-patching instead of root cause. Appending "do NOT do X again" is one line and feels like a fix. Diagnose the stage: wrong context, wrong tool contract, or missing verification will not be cured by scolding the model.
The threat model in three legs, and the governance posture that survives an auditor. Summary here; the full framework is a companion volume.
Simon Willison's formulation: an AI system becomes exfiltration-prone when three capabilities combine. LLMs follow any instructions that reach the model — they cannot reliably distinguish operator instructions from attacker text embedded in content. So an attacker who can plant text where your agent reads it can direct the other two capabilities.
The agent can read things worth stealing: files, mail, records, credentials.
Attacker-controlled text can reach the model: web pages, emails, documents, tickets.
The agent can send data out: HTTP requests, emails, messages, commits.
The defense is structural: break a leg. Remove whichever capability the task doesn't need — read-only agents that browse, or browsing-free agents that write, or air-gapped agents that do both. Filtering "malicious" text is not a defense; as of Jul 2026 no reliable filter exists, and the field's consensus is to assume injection will land. †
What you must be able to see before granting autonomy. Seven instruments; skip none.
The expeditions this guide was collected on. Each entry is a case study with a lesson, verifiable by following the link.
Every reference page on this domain — 173 standalone HTML files as of Aug 2026 — is produced by an agentic pipeline governed by a binding written standard: spec first, outline before build, primary-source verification of every volatile fact, browser-based self-verification, and a git audit trail for every change. The pipeline itself is documented publicly, and the full repository is open.
Read the anatomy: How This Site Is Built: A Governed Agentic-AI Pipeline.
Lesson encoded: agents scale output only as far as the standards binding them — the spec, not the model, is the quality ceiling.
A two-month intensive engagement (spring 2026) building an AI platform for ~36 people across 9 departments at a regulated commercial lender: a ten-plugin marketplace, a governance pipeline with a flag-don't-decide auditor, an enrichment service, and ~30 reviewed skills — drafts-only against the systems of record, with an observed impact of 30–80 hours freed weekly at measured adoption.
Read the case study: Founding an AI Delivery Function at a Regulated Commercial Lender.
Lesson encoded: the highest-leverage AI work is not the cleverest agent — it's the platform that lets non-engineers ship reviewed, observable, drafts-only automation without competing with the system of record.
Three open artifacts, each encoding one lesson from the field: skill-lint (a linter for agent skills — prompts-as-code deserve CI), agent-skills (portable skills as plain SKILL.md files — capability that isn't vendor-locked), and CodeContext (a CLI/MCP server that turns a codebase into model-ready context — often the whole integration a coding assistant needs).
Lesson encoded: when a practice matters, extract it into a tool — tools are opinions that compile.
Eighteen terms of art, each with the practical gotcha the marketing copy omits. The quick reference for the rest of the guide.
| Term | Definition | The gotcha it hides |
|---|---|---|
| Agent | A system where the LLM dynamically directs its own process and tool use to accomplish a task (Anthropic's definition). | Autonomy is a cost you pay, not a feature you get — you trade latency, spend, and predictability for flexibility. |
| Workflow | LLM calls and tools orchestrated through predefined code paths — the developer decides the steps. | Most things sold as "agents" are workflows, and that's a compliment: predefined paths are cheaper and more debuggable. |
| Harness | The scaffolding around the model: loop, tools, permissions, context management, retries. | Harness quality dominates model quality for agent reliability — upgrading the model won't fix a leaky harness. |
| Tool / function calling | The model emits a structured call; your code executes it and returns the result to the context. | The model never "runs" anything — your executor does. Every safety property lives in the executor, not the model. |
| MCP | Model Context Protocol — an open standard for connecting tools and data sources to any agent; the de facto interop layer. † as of Jul 2026 | A connector is a capability grant. Treat every MCP server as part of your attack surface and scope it accordingly. |
| Skill | A reusable, versioned instruction file (e.g. SKILL.md) an agent loads to perform a specific procedure. | Skills are prompts, and prompts are code: unreviewed skills are unreviewed code running against your data. |
| Subagent | A child agent spawned with its own fresh context to handle a delegated slice of work. | Isolation is the point — a subagent that shares the parent's full context inherits the parent's confusion. |
| Orchestrator | The lead agent (or plain code) that decomposes work, delegates to workers, and synthesizes results. | The orchestrator is a single point of failure; a bad decomposition wastes the whole fleet's spend. |
| Context window | The model's finite working memory: everything it can currently see, measured in tokens. | It's a budget, not a bucket — effective attention degrades before the hard limit is reached. |
| Compaction | Summarizing a long conversation into a shorter artifact so work can continue in a fresh window. | Compaction is lossy by design. Anything not written to a durable note may silently vanish at the boundary. |
| Memory | State persisted outside the context window — files, databases, vector stores — reloaded on demand. | Memory is an input like any other: stale or poisoned memories are injected confidently into future runs. |
| Eval | A repeatable test suite for model behavior: task in, output scored against expectations. | An eval you run once is a demo. Evals earn their keep as regression suites when prompts and models change. |
| Trace | The full record of one run: every prompt, tool call, result, and token count, inspectable after the fact. | Without traces, every incident report begins with "we think." You cannot debug what you didn't record. |
| Human-in-the-loop | A checkpoint where a person reviews or approves before the system proceeds. | HITL is an architectural property, not a policy memo — if the system can skip the human, eventually it will. |
| Guardrail | A hard constraint enforced outside the model: permission scopes, budget caps, output filters, allowlists. | Instructions are not guardrails. "Please don't delete files" is a wish; a read-only mount is a guardrail. |
| Sandbox | An isolated execution environment (container, VM, worktree) where agent actions can't reach production. | A sandbox with production credentials mounted inside it is a stage set, not a sandbox. |
| System of record | The authoritative store of business state — the ledger, the CRM, the production database. | The one thing an agent platform must never compete with. Agents draft near the record; humans write to it. |
| Kill switch | A tested, documented way to halt an automation immediately. | If you've never actually flipped it, you don't have one — you have a comforting diagram. |
† Volatile facts on this page are tagged inline with their verification date. Pattern names and the workflow/agent distinction follow Anthropic, "Building Effective Agents" (Dec 2024; re-verified Jul 2026). The lethal trifecta follows Simon Willison (Jun 2025). The adoption-curve framing in Plate III adapts Boris Cherny's "Steps of AI Adoption" (2026), generalized away from any single vendor's tooling. Case-study figures are from the linked primary sources.