00. Designing agents — First-principles overview¶
Module 15 taught retrieval to think. This module teaches you to architect an agent that acts in the world — and decide what happens when it breaks.
A refund agent at an Indian fintech wakes up at 03:14 IST on a Monday. A customer's message arrives: "refund my ₹68,000 order, it never shipped." The model reads it. The model calls process_refund(amount=680000, account_id=...) — one digit too many, parsed from a copy-paste in the user's message. The tool fires. ₹6,80,000 leaves the company account in 200 milliseconds. By 06:00 the bank is on the phone. By 09:00 the post-mortem is scheduled. The root cause is not the model. The model did exactly what the tool advertised. The root cause is the architecture: a Class-4 irreversible-write tool was reachable on a single model call with no amount threshold, no human approval, and no kill switch.
Every agent reduces to five design surfaces. This module builds each surface from nothing, then constrains it for the real world.
The five primitives¶
Every production agent — from a Slack bot to a multi-agent system processing 50,000 requests per day — is made of exactly five things. Memorise these once. The rest of the module is consequences.
| Primitive | One-liner | Pressure it answers |
|---|---|---|
| The Loop | Agency = think → act → observe → decide (continue or stop) | feedback: how does the agent know it succeeded? |
| The Toolbelt | Capability = reachable actions + how they compose | action-space: more tools = more power but more error surface |
| The State | Continuity = what persists, who owns it, what leaks | durability: crashes lose work, shared state leaks across tenants |
| The Leash | Safety = autonomy constrained proportional to blast radius | blast-radius: powerful agent needs proportional constraint |
| The Lifecycle | Trust = how you earn and maintain permission to run unsupervised | operations: live systems break differently than demos |
In an interview, draw these five boxes. Then derive: "which surface is under-designed in this system?" Every production incident maps to one of these five.
The recurring vocabulary¶
These names appear in every chapter. They are the module's shorthand — five primitives decomposed into working parts.
| Name | Primitive | What it is |
|---|---|---|
| the think step | Loop | reasoning and planning before any tool fires |
| the try | Loop | the actual tool-call execution |
| the check | Loop | reading the result and judging success or failure |
| the give-up rule | Loop | the OR-gate of iteration / token / time / cost caps that stops the loop |
| the toolbelt | Toolbelt | the set of tools the agent can invoke; the action space |
| the memo format | Toolbelt | the standard wire protocol (MCP) that lets agent and tools speak one language |
| the leash | Leash | how much autonomy — single call vs ReAct vs orchestrator vs multi-agent |
| the blast radius | Leash | the worst thing the agent can break in one bad step |
| the understudy | Leash | the human approver who steps in at named gates above named thresholds |
| the budget | Leash | token, time, money, and step caps committed before any prompt is drafted |
| the alarm panel | Lifecycle | signals that tell you the agent is misbehaving |
| the kill switch | Lifecycle | the one-click flag any on-call engineer can flip in under sixty seconds |
| the yardstick | Lifecycle | minimum eval set every new agent must clear before launch |
The journey: build, then constrain¶
This module has two acts. After Act 1 your agent works. After Act 2 it's safe to run unsupervised.
Act 1 — Build the agent (files 01–06). Each file adds one capability. By file 06 the agent can reason, call tools, compose actions, remember, and speak a standard protocol.
Act 2 — Constrain for production (files 07–11). Each file adds one governance layer. The agent doesn't grow; it becomes proportionally safe.
Synthesis (files 12–13). Checklist and honest boundaries.
Memory map¶
| # | File | Primitive | Pressure answered | What it adds |
|---|---|---|---|---|
| 01 | architecture-decision-tree | Loop | autonomy vs predictability | pick the architecture |
| 02 | react-loop-and-stopping | Loop | persistence vs runaway | wire the loop + teach it to stop |
| 03 | tool-contracts | Toolbelt | expressiveness vs correctness | typed tool contracts |
| 04 | tool-composition | Toolbelt | power vs blast radius | composition patterns |
| 05 | mcp-protocol | Toolbelt | integration cost vs flexibility | MCP standard |
| 06 | memory-architecture | State | cost vs grounding | memory + retrieval |
| — milestone: agent is functional — | ||||
| 07 | blast-radius-approval-gates | Leash | speed vs safety | blast radius + approval gates |
| 08 | cost-latency-multi-tenancy | Leash | shared cost vs isolation | economics + multi-tenancy |
| 09 | state-recovery-failure-modes | State | performance vs recoverability | durability + failure topology |
| 10 | observability-eval-gates | Lifecycle | visibility vs overhead | observability + eval gates |
| 11 | rollout-versioning-kill-switch | Lifecycle | velocity vs stability | rollout + versioning |
| — milestone: agent is production-safe — | ||||
| 12 | architect-checklist | Synthesis | completeness | 20-item design/build/launch/run |
| 13 | honest-admission | Boundaries | humility | what design still cannot answer |
Three traversal paths use this map. Prerequisite path — read top to bottom. Failure path — when an incident wakes you at 3 AM, find which primitive is under-designed. Synthesis path — pick two rows from different primitives, ask how they compose (e.g., State + Leash = what happens when a crash leaks tenant data?).
Top resources¶
- Anthropic — Building effective agents — https://www.anthropic.com/engineering/building-effective-agents
- OpenAI — Practical guide to building agents — https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf
- LangGraph docs — https://langchain-ai.github.io/langgraph/
- ReAct paper — https://arxiv.org/abs/2210.03629
- OpenAI function calling guide — https://platform.openai.com/docs/guides/function-calling
- Anthropic tool use overview — https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
- Model Context Protocol intro — https://modelcontextprotocol.io/introduction
- OpenAI Agents SDK docs — https://openai.github.io/openai-agents-python/
What's coming¶
- 01-architecture-decision-tree.md — Single-call vs ReAct vs orchestrator vs multi-agent. The leash length is decision number one.
- 02-react-loop-and-stopping.md — The ReAct loop and the stopping rules that prevent it from running you. The loop is incomplete without its exit.
- 03-tool-contracts.md — Tool schemas and descriptions — one concept: the typed contract.
- 04-tool-composition.md — Parallel calls and chaining. Tool composition patterns.
- 05-mcp-protocol.md — MCP: wire format, primitives, server/client in one pass.
- 06-memory-architecture.md — Memory architecture and retrieval-as-tool. What the agent remembers, who owns it, what leaks.
- 07-blast-radius-approval-gates.md — Blast radius, authority classes, and approval gates. The leash in action.
- 08-cost-latency-multi-tenancy.md — Cost/latency budgets and multi-tenancy. Economics before architecture.
- 09-state-recovery-failure-modes.md — Checkpointing and failure modes by topology. Surviving the crash mid-trajectory.
- 10-observability-eval-gates.md — Observability and eval gates. Wiring the alarm panel at architecture time, not after the fire.
- 11-rollout-versioning-kill-switch.md — Rollout strategy, versioning, and the kill switch.
- 12-architect-checklist.md — Twenty items: design, build, launch, run.
- 13-honest-admission.md — Where the field still has no defensible answer.
Bridge. Before we compose tools, wire memory, or build alarms, we must pick the shape of the agent itself. One tool call? A reasoning loop? An orchestrator with workers? The leash length is decision number one — the entire module sits inside whichever shape you pick. → 01-architecture-decision-tree.md