Every agent project begins with a demo, and every demo is a small, well-meant lie. Someone types a carefully chosen request into a laptop at the front of a room, the agent searches, reasons, calls three tools and produces something that makes the head of operations sit up. Applause. A budget line appears. Then somebody asks the reasonable question: can we have it in production by next quarter? This book is for the person who has to answer that question honestly.
The demo is not dishonest because anyone cheated. It is dishonest because of what it leaves out. It ran once, on an input its author had tried a dozen times. The data was clean, the APIs were up, the request was unambiguous and the person watching wanted it to work. Nobody asked it to handle a customer who writes in three languages, a database that times out at nine in the morning, a tool that returns an HTML error page instead of JSON, or a request that is technically allowed and obviously unwise. Nobody ran it ten thousand times and counted.
Production asks exactly those questions, and asks them on Monday morning when the queue is full and the person who built the thing is on a train. The gap between demo and production is not a gap in model intelligence. The model in the demo is the same model you will ship. The gap is everything around it: how the agent is given its tools, what it sees, what it remembers, what happens when a step fails, who can stop it, how much it may spend, how you find out what it did, and how you know whether this week's version is better than last week's.
A demo proves that something can happen. Production needs to know how often.
That shift from can to how often is the whole discipline. An agent that succeeds four times in five is a marvel on stage and a liability in a claims department. The fifth case is where your customers live, along with your auditors and, eventually, your lawyers. Your job is to find out what the fifth case looks like, make it rarer, make it cheaper when it happens, and make sure someone notices.
Here is something to do this week. Take whatever agent prototype your organisation is most excited about and write down, in plain sentences, the ten inputs most likely to embarrass it. Not adversarial genius, just ordinary mess: the vague request, the huge attachment, the missing field, the angry customer, the request that needs a human. Run each one. You will learn more from that hour than from the original demo, and you will have the first draft of an evaluation set without having meant to write one. The demo was the trailer. Production is the film, and nobody walks out of the film early because the trailer was good.
Fig 1 · The Demo Is a Liar. What a demo hides, and how ten awkward inputs become a first evaluation set.
Chapter 2 · Part I
Model, Tools, Loop
Definitions in this field are slippery, and slippery definitions produce slippery systems, so let us fix one early. An agent is a model, a set of tools and a loop. The model reads the situation and decides what to do next. The tools let it do things beyond producing text: search, read a record, run code, send a message. The loop feeds the result of each action back to the model and asks again, until the model says it is finished or something outside it says stop.
That is all. It is worth being plain about, because vendor literature and conference talks will offer you agents with personalities, agents with goals, agents with careers. Strip away the adjectives and you find the same three parts. If a system has a model but no tools, it is a chatbot. If it has tools but the path is fixed in code, it is a workflow that happens to call a model. If the model chooses which tool to call next, based on what the last one returned, you have an agent, and you have taken on the particular responsibilities that come with letting software decide its own next step.
Each part fails differently, which is the practical reason for keeping them separate in your head. The model fails by misunderstanding: it picks the wrong tool, invents a parameter, or declares victory too early. The tools fail like any software: timeouts, permissions, malformed data, side effects that cannot be undone. The loop fails by never ending, or by ending at the wrong moment, or by running the same step forty times while a meter spins. When something goes wrong in production, your first diagnostic question is which of the three it was. Most teams instinctively blame the model. Most of the time it was the tools or the loop.
The model is the part you rent. The tools and the loop are the parts you own.
That sentence carries a lot of weight in the chapters ahead. You can choose a better model, and occasionally you should. But you cannot make a vendor's model more reliable by wanting it to be. What you can do is design tools that are hard to misuse, write a loop that knows its limits, and build the scaffolding that catches the model when it stumbles. Those are engineering problems with engineering answers, and they are where your effort compounds.
A useful exercise is to draw any agent you are working on as three boxes. Under the model box, write what it is being asked to decide. Under the tools box, list every action it can take, and mark the ones that change something in the world. Under the loop box, write the conditions that end a run. If any box is hard to fill in, that is where the next incident is quietly waiting. Simple definitions are not a sign of a simple subject. They are how you keep a hard subject from becoming a vague one.
Fig 2 · Model, Tools, Loop. Model, tools and loop each fail in their own way; you rent one and own two.
Chapter 3 · Part I
The Loop Has a Body
It helps to slow an agent down to a single turn and look at it closely, the way a mechanic watches one revolution of an engine. Most people picture the model as the engine. In practice, the model is a single cylinder. The rest of the engine is a program you write, usually called the harness, and it does far more of the work than the diagrams suggest.
A turn begins with the harness assembling a request. It gathers the system prompt, the conversation so far, the definitions of the available tools and any retrieved context, then sends it all to the model. The model replies with either some text or a request to call a tool, expressed as a name and a set of arguments. The model does not call the tool. It cannot. It has no hands. The harness reads that request, checks it, decides whether it is allowed, executes the actual function, captures the result, and appends it to the conversation. Then it sends the whole thing back to the model and the next turn begins.
Look at how many decisions sit with the harness in that description. Whether the tool call is valid. Whether this agent is permitted to make it. Whether it needs a human's approval first. How long to wait for it. What to do if it fails. How much of a huge result to pass back. Whether the run has exceeded its budget. Whether the model's claimed final answer meets the definition of done. Every one of those is code you control, and every one is a place where production reliability is won or lost.
The model proposes. The harness disposes.
This is the most important architectural fact in the book, and it is also a relief. It means you are not at the mercy of a model's mood. A model that wants to delete a production table cannot, unless your harness hands it a tool that deletes tables and then executes the call without question. A model that loops forever cannot, unless your harness forgets to count. The model's freedom is exactly as large as the harness allows, and the harness is ordinary software with ordinary tests.
There is a second consequence. When people say an agent "decided" to do something odd, translate the sentence. The model suggested something odd and the harness let it through. That translation does not excuse the model, but it does point to where the fix usually lives. You can rarely prompt your way to never suggesting something odd. You can almost always code your way to not acting on it.
This week, find the place in your own system where tool calls are executed and read it line by line. Ask what happens if the arguments are malformed, if the tool hangs, if the result is a megabyte of HTML, if the same call arrives twice. If the answer to any of those is "I am not sure", you have found your next small, high-value piece of work. Engines are reliable because of the parts nobody photographs.
Fig 3 · The Loop Has a Body. One turn in detail: the model asks, the harness checks, executes and returns.
Chapter 4 · Part I
Autonomy Is a Dial
Ask a room of engineers whether their system is "really" an agent and you will start an argument that outlasts the coffee. The argument is mostly pointless, because autonomy is not a property a system has or lacks. It is a dial, and you set it per task, per risk and per stage of maturity.
At the lowest setting, the model suggests and a human does everything. Slightly higher, the model drafts and a human edits before anything leaves the building. Higher again, the model acts on reversible things and asks before irreversible ones. Higher still, it acts on everything within a defined scope and reports afterwards. At the top, it runs unattended for hours, choosing its own steps, with humans looking only at summaries and exceptions. Each setting is a legitimate design. None is more advanced in any moral sense. The question is only which setting fits this task, this week.
Three things should move the dial. The first is reversibility. An agent that drafts email replies for a human to send can be wrong often and cheaply; one that issues refunds cannot. The second is verifiability. If the result can be checked automatically, by tests or a validator or a comparison with a known answer, you can let the agent go further because you will catch it. If the only check is a human reading carefully, keep it closer. The third is track record. A new agent earns autonomy the way a new colleague does, by being right in front of witnesses for a while.
Trust is not granted in the design document. It is accumulated in the logs.
The practical mistake is choosing one setting for an entire system. Real agents do many kinds of thing in a single run. A support agent might look up an order, summarise a policy, and offer a goodwill credit. The first two can run at full autonomy. The third probably wants a threshold above which a human signs. Design the dial at the level of individual actions, not the whole agent, and you will find you can ship much sooner, because the risky part is fenced off and the useful part is free to work.
It also pays to make the dial explicit in configuration rather than implicit in code. When a setting lives in a file that says, in effect, refunds under this amount are automatic, above it they wait for approval, the business can read it, auditors can check it, and you can turn it during an incident without a deploy. When the same rule is buried in a prompt, nobody can find it, and the model may decide one Tuesday that it does not apply.
Start this week by listing every action your agent can take and assigning each a setting on the dial. Then look for the gaps between where each action is and where it could safely be. Usually a few can move up and one or two should move down. Autonomy is not a destination. It is a setting you revisit, preferably before something revisits it for you.
Fig 4 · Autonomy Is a Dial. Autonomy set per action, from suggest to unattended, with credits gated by size.
Chapter 5 · Part I
When Not to Build an Agent
The most valuable architectural decision in this book is the one that removes the agent entirely. It sounds like heresy in a guide called Agents in Production, but every experienced practitioner has the same story: a team spent a quarter building an autonomous system for a problem that a well-written function and a single model call would have solved in a week.
Agents are expensive in every currency that matters. Each step is a model call, so they cost more and take longer than a fixed pipeline. They are nondeterministic, so they are harder to test. They choose their own path, so they are harder to explain, audit and debug. They need guardrails, budgets, tracing and evaluation infrastructure that a simpler system would not. These costs are worth paying when the problem genuinely needs them. They are pure overhead when it does not.
So ask, before you build: does this problem require the model to decide what to do next? If the steps are known in advance, you want a workflow, where code decides the path and models handle the fuzzy bits within each step. If there is only one fuzzy bit, you want a single, well-crafted model call with a structured output. If there is no fuzzy bit at all, you want ordinary software, and you should be glad. Classification, extraction, summarisation of a known document, routing a ticket to one of six queues: none of these need a loop.
The best agent is sometimes a function with good manners.
Agents earn their keep when the path is genuinely open. Research across sources whose number and shape you cannot predict. Debugging, where each observation changes what to try next. Customer conversations that wander. Multi-step operations over systems whose state must be inspected before acting. In these, writing every branch by hand would be impossible or absurd, and letting a model choose is the honest solution.
There is also a middle option that teams overlook: build the workflow first, and let the agent emerge from it. Start with fixed steps. Watch where real inputs force awkward branching, where the code fills with special cases, where the fixed path keeps being wrong. Those are the places that want a model's judgement. Hand over decision-making there and only there. You end up with a system that is mostly predictable, with judgement applied where it pays, which is exactly the shape that survives contact with operations teams.
Try it this week. Take your current agent design and, for each step, ask whether a human expert would need to think about what comes next, or would simply follow the procedure. Wherever the honest answer is "follow the procedure", write the procedure in code. You will lose a little elegance on the whiteboard and gain a great deal of sleep. The question is never whether agents are impressive. It is whether this problem needed impressing.
Fig 5 · When Not to Build an Agent. A decision tree for choosing ordinary code, one call, a workflow or an agent.
Chapter 6 · Part I
Defining Done
An agent without a definition of done runs until it is bored, broke or wrong, and it does not get bored. This is one of the oldest failures in the field and still one of the most common: the loop has a start condition and a vague hope where the end condition should be.
The model will, of course, tell you when it thinks it has finished. That is a useful signal and a poor guarantee. Models are inclined to declare success, especially near the end of a long task when the context is crowded and the evidence is thin. They will report that the tests pass when they ran a subset, that the record was updated when the call returned an error they skimmed, that the research is complete when they found two sources and stopped looking. None of this is malice. It is what you get when you ask a system optimised to produce plausible completions whether it has completed something.
So write done down, in a form the harness can check without asking the model's opinion. For a coding agent, done might mean the test suite passes, run by the harness, not reported by the model. For a data-entry agent, done might mean the target record exists with every required field populated and valid. For a research agent, done might mean a report in a defined structure with at least a stated number of cited sources, each of which resolves. For a support agent, done might mean the ticket is in one of a small set of terminal states, each with a reason code.
If only the agent can tell you it has finished, you have not defined finished.
Done also has a negative form, which matters just as much. Define the conditions under which the agent must stop without succeeding: a step limit, a time limit, a spend limit, a repeated failure, a request it is not allowed to handle. Those stops should produce an honest outcome, such as could not complete, escalated, here is what I tried, rather than a silent timeout or a cheerful fabrication. An agent that fails clearly is far more useful than one that succeeds ambiguously.
Two practical habits help. First, make the agent produce a structured final output, not prose, so the harness can validate it the way it would validate any API response. Second, add a verification step after the model claims completion, run by code or by a separate grader, before the result is accepted. It costs a little latency and saves a great deal of embarrassment.
This week, open your agent's loop and find the line that ends it. If the only exit is the model saying I'm finished, add a check that does not depend on the model's self-assessment, and add at least two ways the run can end in a clean, labelled failure. It will feel like you are being unkind to the model. You are being kind to the person who reads the output. The finish line belongs to you, not to the runner.
Fig 6 · Defining Done. A run ends when the harness verifies done, or in a clean, labelled failure.
Chapter 7 · Part I
Nondeterminism Is the Weather
Run the same agent on the same input twice and you may get two different journeys. One run searches first and then reads; the other reads first and never searches. One finishes in four steps, the other in eleven. Both might be correct, or one might be wrong. This is not a bug to be fixed. It is weather, and production engineering is about building houses that do not care whether it rains.
The variability comes from several places at once. Sampling introduces randomness, though lowering it helps less than people hope, because small differences in context still push the model down different paths. Tool results vary from moment to moment: a search returns new pages, a database has new rows, an API is slow. And because each step depends on the previous one, small differences compound. By step eight, two runs that started identically may be in different postcodes.
The first consequence is that a single successful run tells you almost nothing. You need to know the distribution: how often the agent succeeds on this kind of input, how often it takes the long way round, how often it fails outright, and how badly. That means running cases many times and reporting rates rather than anecdotes. A test that passed once is a rumour. A test that passed ninety-four times in a hundred is information.
Do not ask whether it works. Ask how often, and what happens the rest of the time.
The second consequence is design. If you cannot make every run take the same path, make every path safe. Constrain the tools so that no sequence of calls can do something unacceptable. Validate outputs so that wrong answers are caught regardless of how they were produced. Put deterministic code around the parts that must be deterministic: calculations, money, permissions, formatting for downstream systems. Let the model be creative only where creativity is welcome, and fence it with code everywhere else.
The third consequence is cultural. Teams new to agents often respond to a strange run by tweaking the prompt until the strange thing stops. It stops, on that input, for now. Somewhere else a new strangeness appears. This whack-a-mole is exhausting and unscientific. The disciplined alternative is to collect strange runs into a set, measure the failure rate across the set, make a change, and measure again. It is slower per change and much faster per month.
So this week, pick one important input and run your agent on it twenty times. Read the traces side by side. Note how many distinct paths it took and how many reached the right answer. Most teams who do this are surprised, sometimes pleasantly and sometimes not. Either way, they stop arguing about whether the agent works and start measuring how well. You cannot stop the weather. You can stop being surprised by it.
Fig 7 · Nondeterminism Is the Weather. One input takes many paths; make every path safe and count pass rates.
Chapter 8 · Part I
The Harness Is the Product
When an agent system is good, people praise the model. When it is bad, people blame the model. Both are usually wrong. In production, the quality of an agent is mostly the quality of its harness: the code that assembles context, defines tools, executes calls, enforces limits, handles errors, records traces and decides when the run is over.
Consider two teams with access to exactly the same model. The first gives it fifteen loosely described tools, dumps an entire knowledge base into every prompt, executes whatever it asks, and accepts its final answer at face value. The second gives it five carefully designed tools with clear descriptions, retrieves context on demand, validates every call, retries transient failures, caps spending, and checks the final output against a schema and a grader. The second team will have a system several times more reliable, and their colleagues will assume they found a better model.
This is good news, because the harness is the part you can actually improve. Model upgrades arrive on a vendor's schedule, change several behaviours at once, and occasionally break things you relied on. Harness improvements arrive on yours. A better tool description ships on Tuesday. A retry policy ships on Wednesday. A new validation rule ships on Thursday, with a test proving it catches the failure you saw on Monday. Each change is small, testable and reversible, which is the shape of all good engineering progress.
Choose the model carefully. Then spend the rest of your time on everything else.
It also changes how you staff the work. Building a production agent is not primarily a prompt-writing job, though prompts matter. It is a backend engineering job with an unusually opinionated component in the middle. The skills that matter are API design, distributed systems, observability, testing and security, the same skills that make any service reliable, applied with an understanding of how models behave. Teams that hire only for prompt craft tend to produce charming systems that fall over under load.
A good harness also outlives its model. When a new model arrives, a well-built harness lets you swap it in, run the evaluation suite, compare traces and costs, and decide on evidence. A poorly built one has the old model's quirks woven through it in the form of prompt workarounds and special cases, and the migration becomes an archaeology project. Keep model-specific accommodations small, named and documented, so you can find them later.
This week, draw your harness as a diagram: every stage a request passes through between arriving and producing a result. Mark which stages you have tests for, which emit traces, and which can fail without anyone noticing. Most teams find the model call is the best-instrumented part of the system and the tool execution is the least. That is backwards. The model is the clever guest. The harness is the house, and it is the house that has to stand up.
Fig 8 · The Harness Is the Product. The stages a request passes through, and how unevenly each is instrumented.
Chapter 9 · Part I
Monday Morning Is a Test
The subtitle of this book is a joke with a serious edge. Monday morning is when production systems meet the world at its least forgiving. The weekend backlog arrives at once. Downstream services are restarting after maintenance. Users are tired, terse and in a hurry. The engineer who understands the agent best is in a meeting. If your system survives Monday morning, it will probably survive the rest of the week.
Think about what that morning actually contains. Volume first: requests arrive in a burst, and your agent, which happily handled one at a time in testing, now shares rate limits with four hundred colleagues. Then odd inputs: the customer who pasted an entire email thread, the request in a language you did not test, the attachment that is a photograph of a screen. Then stale state: the cache that was correct on Friday, the record another system updated overnight. Then partial outages: the search service is slow, the CRM returns errors for one region, a third-party API has changed a field name without telling anyone.
None of this is exotic. It is ordinary operations, and ordinary software has learned to handle it over decades. The trouble with agents is that they handle it in novel and occasionally creative ways. A traditional service that hits a malformed record throws an error and stops. An agent may decide to work around it, inventing a plausible value, trying a different tool, or giving the customer a confident answer built on an empty search. The creativity that made the demo impressive becomes the thing you most need to contain.
Software fails loudly. Agents can fail politely, which is worse.
So test for Monday deliberately. Before launch, run your agent against a replay of a real busy period, or a synthetic one with realistic volume and mess. Inject failures into its tools: timeouts, errors, empty results, garbage. Watch what it does. You want to see it retry sensibly, report honestly, and escalate when it cannot proceed. You do not want to see it improvise. Every improvisation you find in testing is one fewer you find in an incident review.
Also plan for the absence of the expert. Write the runbook that tells someone else how to see what the agent is doing, how to slow it down, how to stop it, and how to tell whether a strange output is a one-off or a pattern. If that runbook does not exist, the agent is not ready, however good its pass rate. Production readiness includes the ability of a stranger to operate the system at a bad moment.
This week, schedule an hour of what some teams call a game day. Pick one dependency, make it fail in a test environment, and watch your agent through it. Then do the same with a burst of awkward inputs. Write down what surprised you and fix the worst thing. Monday comes every week. You might as well meet it on your own terms.
Fig 9 · Monday Morning Is a Test. The five pressures of Monday morning, and the response you want from an agent.
Chapter 10 · Part I
Reliability Is an Engineering Job
Here is the argument of this book in miniature, so you can decide early whether you agree with it. Prompting shapes what an agent tends to do. Engineering determines what it can do, what happens when it goes wrong, and how you find out. Production reliability lives almost entirely in the second category.
This is not a dismissal of prompting. A clear system prompt, good tool descriptions and well-chosen examples make an enormous difference to how often an agent does the right thing, and later chapters treat them with respect. But a prompt is a request, not a guarantee. It moves probabilities. It cannot make a dangerous action impossible, a lost state recoverable, a cost bounded or an incident visible. Those properties come from code, configuration and process, and they hold whether the model is having a good day or not.
Look at the failures that actually hurt teams. An agent sent the same email to a customer eleven times because a retry was not idempotent. An agent leaked a document because it read an instruction hidden in a web page and had a tool that could send messages anywhere. An agent ran overnight in a loop and consumed a month's budget. An agent's quality slowly declined after a dependency changed, and nobody noticed for six weeks because nothing measured it. Not one of these is fixed by a better prompt. Every one is fixed by an ordinary engineering practice applied to an unusual component.
You cannot instruct your way out of a missing safeguard.
The practices are not new. Least privilege. Idempotency. Timeouts and retries with backoff. Durable state. Input validation. Budgets and quotas. Structured tracing. Regression testing. Staged rollouts. Kill switches. Blameless postmortems. What is new is applying them to a component that makes decisions, which changes some details and none of the principles. The rest of this book is a tour of those practices, each translated for agents.
It is worth naming why teams resist this. Prompting is fast and feels like progress. Change a sentence, rerun the demo, see a better answer, ship it. Engineering is slower and its wins are invisible: the incident that did not happen, the cost that stayed flat, the regression that was caught before release. Organisations reward the visible. Your job, partly, is to make the invisible visible, with dashboards and evaluation scores and incident counts, so that the quiet work gets the credit it deserves.
So here is the first test of your system. For each serious harm your agent could cause, ask what prevents it. If the answer is a sentence in the prompt, write down what code, permission or process could prevent it instead, and put that work on the list. You will not finish the list this week. You will, however, have converted hope into a backlog, which is how every reliable system started. Reliability is not a mood the model is in. It is a property you build.
Fig 10 · Reliability Is an Engineering Job. Four real incidents a prompt could not fix, each mapped to an engineering fix.
Free preview · Part I
Keep reading
You have read the first 10 of 100 chapters of Agents in Production. The full book has every chapter and plate, as PDF and EPUB in English, French, Polish and Spanish.