Appearance
12.10.11 — How Real Agents Are Built
The refund agent began in 12.10.1 as two customers with broken earphones and a loop. Ten pages later, it has tools that check their inputs, a run record that survives restarts, limits, pauses for people, a trace, context management and memory, a router in front of it, guardrails around it, an evaluation set behind it and a budget over it. This last page does two things. It puts all of those pieces into one picture, so you can see how they fit. Then it looks at the agents you are most likely to use or be asked about, coding agents and hosted agent platforms, and shows that they are built from exactly the same pieces.
1. The refund agent, all of it
The figure shows the production refund agent with every part this chapter added. The circled numbers are the page that built each part.
Follow one message through it. Customer A's message passes the input checks and the router, which recognises a refund request. The harness creates a run record, loads her memory (no earlier cases), and starts the loop. Each model call is cached and traced. Each tool request goes through authorize first, and each tool checks that the order is hers. search_policies uses the retrieval system of Chapter 12.9. propose_refund crosses the approval limit, so the run is saved and paused, and a support lead approves it on one screen. The run resumes, the payment is made with an idempotency key, and the reply passes the output checks before she sees it. After the run, the case outcome is written to her memory. Underneath, every step fed the metrics, the trace and the budget.
The thing to notice is the size of the model's box. Almost everything in the figure is ordinary software engineering: databases, queues, policy code, permissions, logging, release processes. That is the real lesson of the chapter, and the reason software engineers make good agent engineers. The model provides judgement; the system around it provides reliability.
2. Inside a coding agent
AI coding agents, the assistants that read and change a software project from a terminal or editor, are the most widely used agents today, and the clearest illustration that real agents are built from the same parts. Take any of the well-known ones apart and you find:
A small set of general tools. Read a file, search the project (by file name and by content), edit a file by replacing exact text, run a shell command, and fetch a web page. With these, an agent can do nearly any programming task. Notice that edit is a dedicated tool even though a shell command could change files too. That is the rule from 12.10.3: actions that need checking, showing or permission get their own tool. A dedicated edit tool can refuse to write to a file that changed since the agent last read it, and it can show the person a clear before-and-after.
A permission system. By default the agent asks before editing files or running commands, and the person can allow categories of action ("you may run the build without asking", "never run anything that deletes"). This is the approval slice of 12.10.8, adjustable per project and per person as trust grows: suggest, act with approval, act and report, the progression from 12.10.1.
Project memory in a file. A file at the project's root, such as CLAUDE.md or AGENTS.md, holds what the agent should always know about this project: how to build it, the conventions, the commands, the things not to touch. It is loaded into every session, which is the long-term memory of 12.10.5 written by people instead of by the agent.
Skills: instructions loaded only when needed. A skill is a folder of instructions, and sometimes scripts, for one kind of task, such as "how to write a database migration in this project". Only its one-line description sits in the agent's context; the agent reads the full instructions when a task calls for them. This keeps the fixed context small while giving the agent deep knowledge on demand, the same idea as loading tools on demand in 12.10.3.
A plan it updates. The visible to-do list ("read the checkout code ✓, find the form submission ✓, fix the field name, verify in the browser") is the revisable plan of 12.10.6, kept in state so that it survives context compaction on long tasks.
Subagents for reading. To answer "where in this large codebase is the payment form submitted?", the agent sends a subagent to search, and gets back three file paths instead of fifty files' worth of search results. This is reading, so it splits well; the edits stay in the main agent, the rule from 12.10.7.
Hooks: rules that run as code. A hook is a script the harness runs at a fixed moment, such as after every file edit or before every shell command, regardless of what the model decides. Teams use hooks to run a formatter after each edit, or to block commands that touch production. They are the "policy in code" slice of 12.10.8 made available to users: things that must always happen are taken out of the model's hands.
Verification against reality. Coding agents have one great advantage over most agents: their work can be checked automatically. The agent builds the project, runs it, and reads the errors, and with tools like the Chrome DevTools server of 12.10.4 it can open the page and click the button. The best coding agents are the ones whose harness makes this checking easy and expected, because an agent that checks its own work recovers from its own mistakes, which raises the per-step reliability that 12.10.1's arithmetic depends on.
Context management for long sessions. When a session's history nears the context limit, it is compacted into a summary, with the project memory file and the plan carried across intact. Some agents also keep checkpoints of the files, so that a person can rewind both the conversation and the code to an earlier point if a direction turns out to be wrong.
Anthropic's Claude Code is built this way, and its harness is available as a library, the Claude Agent SDK, so that you can build an agent on the same loop, tools, permissions, hooks and context management rather than writing them yourself. Other providers and open-source projects offer similar SDKs. Each one is an implementation of the harness of 12.10.2, with years of production experience built in.
3. Hosted agent platforms
The other end of the range is not to run the harness at all. A hosted agent platform runs the agent loop on the provider's servers and gives each run its own sandboxed workspace where tools execute. Your code describes the agent, starts runs, and receives a stream of events. Anthropic's version is called Managed Agents, and its parts map almost one-to-one onto this chapter:
| Platform concept | What it is | Where this chapter built it |
|---|---|---|
| Agent | saved, versioned config: model, prompt, tools, MCP servers, skills | the agent version on every trace (⑨) |
| Session | one run, with its own state and event stream | the run record (②) |
| Environment | a sandboxed container where tools run | the sandbox (⑧) |
| Tool confirmation | the run waits for your approval of an action | approval and pausing (②⑧) |
| Vault | stored credentials, added on the way out of the sandbox | narrow credentials, no secrets in sandboxes (③⑧) |
| Budget | a spending cap that pauses the session | budgets (⑩) |
| Memory store | persistent memory attached to sessions | long-term memory (⑤) |
| Outcome | a rubric a separate grader checks, iterating until it passes | the evaluator loop (⑥) and judges (⑨) |
| Scheduled deployment | runs an agent on a timetable | scheduled workflows (⑥) |
Two details in that table show good design you can copy even if you build your own. Agents are versioned: every change to the prompt or tools creates a new version, and a running session stays on the version it started with. This is what makes "which change caused this?" answerable and lets you roll back a bad change, the release discipline of 12.10.9. And vault credentials are added to requests as they leave the sandbox, so code running inside the sandbox never sees the secret at all. That makes finding 2 of 12.10.8, the agent that printed a database password, impossible by construction.
4. Build, use a framework, or use a platform?
You now know three ways to get an agent into production, and the choice is the same kind of trade-off as in 12.8.7.
| Approach | You own | Choose when |
|---|---|---|
| Your own harness | everything | unusual control, strict data rules, deep integration |
| Agent SDK or framework | tools, prompts, policies | standard loop, own infrastructure |
| Hosted platform | agent config, tools, policies | long tasks in sandboxes, fast start |
Cartwise ended up using all three. The refund agent has its own harness, because it is deeply tied to orders, payments and approvals, and every line of its control code was worth owning. The analytics assistant runs on an agent SDK, because it is a standard loop of reading data, writing code and running it. And a nightly agent that reviews the previous day's failed refund runs and drafts improvement notes for the team runs on a hosted platform with a schedule, a sandbox and a budget, because nobody wanted to operate infrastructure for a once-a-day job.
Whichever approach you choose, the responsibilities that make an agent safe do not move. Tool design, ownership checks, policy code, approvals, evaluation, and the decision of what the agent is allowed to do at all remain yours. A platform can run the loop; it cannot know your refund policy.
5. A checklist before an agent meets customers
Everything in this chapter, condensed into the questions to answer before launch:
- Should this be an agent? Could a workflow do it? Is it worth the cost, are mistakes catchable, are actions undoable or approvable? (12.10.1, 12.10.6)
- Tools: Is each one task-shaped, clearly described, with strict schemas, small results and instructive errors? What is the worst case if the model is fully hostile? (12.10.3)
- Identity: Does every tool check ownership against the session, never the conversation? (12.10.2)
- Limits: Are steps, cost and time capped per run, customer and agent, with alerts? (12.10.2, 12.10.10)
- State: Can a run pause for hours and resume after a restart? Are actions idempotent? (12.10.2)
- Context and memory: Are results small, history managed, rules in the system prompt, memories per user, dated and treated as data? (12.10.5)
- Guardrails: Is there a policy function with default deny, a circuit breaker, approval for what matters, output checks, a sandbox for code, and a tested kill switch? (12.10.8)
- Evaluation: Is there a simulated-world evaluation set with path checks and pass^k, and a release gate? (12.10.9)
- Observability: Is every run traced with its version, and are path, cost and safety metrics on a dashboard? (12.10.9)
- Economics: Is caching on and verified, are cheap models routed easy work, and is cost per resolved case known? (12.10.10)
A team that can answer all ten has built an agent. A team that can answer only the first has built a demonstration.
What the interviewer will push on
"Design a customer-support agent that can issue refunds." This is the classic agent design question, and the figure in section 1 is the answer. Walk it in order:
- A router in front.
- A harness that keeps a record of each run, enforces limits and traces every step.
- Tools shaped around tasks, each checking that the customer owns the order.
- A policy function that says no by default, with money thresholds and a circuit breaker.
- Approval that can pause the run and resume it later.
- Payments that are safe to repeat (idempotent).
- Checks on every output.
- Memory for each customer.
- Evaluation in a pretend world.
- Caching and routing to keep the cost down.
The tell of a strong candidate is spending most of the time on the system around the model.
"How does a coding agent work?" General tools (read, search, edit, shell), a permission system, a project memory file, on-demand skills, a revisable plan, subagents for searching, hooks for rules that must run, verification by building and running, and compaction for long sessions.
"Would you build your own agent framework?" Only if the agent is central enough to justify owning the control code; otherwise use an SDK or a hosted platform, keeping tools, policies and evaluation as your own responsibility either way.
"What do hosted agent platforms give you?" The loop, sandboxed workspaces, event streams, versioned agent configs, credential vaults, budgets and schedules. Knowing the mapping onto run records, sandboxes and approvals shows you understand what they are doing for you.
Something to volunteer: the size of the model's box. In a production agent, the model is one component among a dozen, and most of the reliability comes from the others. Engineers who internalise this build agents that survive real customers.
Recall
- A production agent is a model inside a system. The system has a router, input checks, a harness that records each run and enforces limits and tracing, tools that check ownership, a policy function, approval that can pause and resume, actions that are safe to repeat, output checks, memory, evaluation, budgets, monitoring and a kill switch. The model brings judgement. The system brings reliability.
- Coding agents use the same parts: general tools with a dedicated edit tool, permissions, a project memory file, on-demand skills, a revisable plan, subagents for reading, hooks for rules that must run, verification by building and running, and compaction. Their harness is available as libraries such as the Claude Agent SDK.
- Hosted platforms run the loop and sandbox for you: versioned agents, sessions, environments, tool confirmation, vaults that keep secrets out of sandboxes, budgets, memory stores, graded outcomes, schedules.
- Choose your own harness, an SDK or a platform by how much control you need; tool design, policy, approval and evaluation remain yours regardless.
- Before launch, answer the ten-question checklist: should it be an agent, tools, identity, limits, state, context and memory, guardrails, evaluation, observability, economics.
Self-test: Name the page of this chapter that each of these came from: the idempotency key, the circuit breaker, pass^k, the dual LLM pattern, prompt caching. Why is a coding agent's edit tool separate from its shell tool? Which parts of the refund agent would a hosted platform take over, and which would stay Cartwise's job?
Next: 12.11.1 Prompt, RAG or Fine-Tune? — every system so far has used a model as it comes, shaped by prompts, retrieval and tools; Chapter 12.11 is about changing the model itself, starting with how to decide whether you should.