Deploy, Observe and Improve

The real business problem

You passed the evaluation from Chapter 8, so you shipped. Then a run went wrong in a way you have never seen. The output looked fine, a client noticed the numbers were off, and now you are staring at a green “success” log with no idea what the agent actually did inside that run.

This is the moment most teams discover they built a black box. The agent produced text, the workflow marked it done, and nothing in between was recorded. You cannot debug what you cannot see, so you are left guessing, re-running the task by hand and hoping the failure repeats so you can catch it live.

Shipping is the start of the work, not the end. A demo runs once under your eye. A deployed agent runs every day on inputs you never tested, and it fails in ways the demo could never show. This chapter gives you the three things that turn a black box into a system you can run with confidence. Observability so you can see each step, cost control so a single bad run cannot drain a budget, and an improvement loop so every real failure makes the next version better. After it, you will be able to read a trace, name the root cause of a broken run, and feed that failure straight back into the tests from the last chapter.

The core idea

A deployed agent needs to be observable, affordable and improvable. Those are three different jobs and you need all three.

Observability means every run leaves a record of what the agent saw, what it decided, which tools it called, what came back and how it finished. Affordability means hard limits on tokens, tool calls and loops so no single run can spin forever or cost a fortune. Improvability means a loop where a real failure becomes a permanent test, so the same bug cannot come back quietly.

Skip observability and you debug by guessing. Skip cost control and one runaway loop teaches you the hard way. Skip the improvement loop and you fix the same failure over and over without ever proving it stays fixed.

A simple model

The unit of observability is the trace. One trace is one full run of the agent, from the goal that came in to the outcome that went out. Inside a trace are spans. A span is a single step, and steps nest. The top span is the whole run. Under it sit the model calls, the tool calls and the results, each with its own inputs, outputs, timing and cost.

TRACE  weekly-summary  run #4821  status: completed  cost: 5,910 tok
|
+- span  plan            model call     in: goal + context   1,020 tok
+- span  get_client      tool call      in: client_id=88     ok, 1 row
+- span  get_transactions tool call     in: from/to dates    ok, 0 rows  # look here
+- span  decide          model call     in: 0 rows returned  1,400 tok
+- span  write_summary   model call     out: final report    3,490 tok
|
+- outcome  “All figures nominal this week.”   (no data was read)

The point of the tree is that it turns “it went wrong” into “it went wrong at this step, for this reason.” You stop arguing about the model and start reading the record.

A concrete example

Take an accounting firm running a weekly client summary agent. It pulls each client’s transactions, works out the movements that matter and writes a short plain-language report. It passed evaluation on twelve sample clients and shipped.

Three weeks in, a client asks why their summary says a quiet week when they had their biggest month ever. The output was confident, well written and completely wrong. Nothing in the plain log explains it. So you open the trace.

Notice what the trace did. It moved the blame off the model, which behaved as instructed, and onto the missing guard around the tool call. That is a fix you can actually make. Reject empty date ranges, make the tool return an explicit error on zero rows for a client that should have activity, and stop the run rather than narrate around a gap.

The implementation pattern

Here is the pattern I use to take an agent from “it runs” to “I can run it every day.”

1. Instrument before you scale, not after. Wrap every model call and every tool call so each writes a span with its inputs, outputs, duration and token count. Most agent frameworks emit this if you turn it on. If yours does not, log it yourself. A run with no trace is a run you cannot defend.
2. Give every run a trace ID and keep the traces. You want to pull up any run by ID weeks later, especially the one a client is asking about. Store enough to reconstruct the step sequence, not just the final answer.
3. Set three budgets per run. A token ceiling, a maximum tool-call count and a maximum loop count. When a run hits a ceiling it stops and escalates instead of grinding on. As an illustrative starting point, you might cap a summary agent at 20,000 tokens, 15 tool calls and 8 loops, then tune from real traces. Those numbers are examples, not targets. Read your own traces to set yours.
4. Add a spend alert above the budgets. Track cost per run and cost per day. Alert a human when a run costs several times the median, or when the daily total crosses a line you set. A runaway loop shows up as one trace with hundreds of spans. You want to hear about that within the hour, not at the end of the month.
5. Watch a few signals, not a dashboard of fifty. Failure rate, escalation rate, median and worst-case cost, and median and worst-case latency. If those four are steady you are fine. When one moves, the traces behind it tell you why.
6. Close the loop into your eval set. This is the step that makes the whole thing compound, so it gets its own section.

The improvement loop

The evaluation set from Chapter 8 is not a launch gate you pass once. It is a living record of every way this agent has been wrong. Production is where you find the cases you could not imagine at the whiteboard.

So every real failure follows the same path. Open the trace, find the root cause, then write a new test case that reproduces it and add it to the eval set. Fix the agent. Re-run the whole set. The new case now guards that bug forever, and every future change has to pass it. The empty-date-range failure above becomes a permanent test with a client who has a blank onboarding field and real transactions, asserting the run stops or errors rather than inventing a quiet week.

Do this for a few months and your eval set stops being a guess about what might break and becomes a map of what actually broke. That is the difference between an agent that drifts and an agent that gets steadily harder to fool.

What breaks

Decision rules

Related lab

The lab hands you the trace of a broken run and asks you to do the real job. You will read the span tree, follow the inputs and outputs step by step, name the exact point where it went wrong and the root cause behind it, then write the eval case that would have caught it. It is the single most useful skill in this chapter, because diagnosing a failure from its trace is what separates running an agent from babysitting one.

Practical checklist

What changes after this chapter

You stop treating deployment as the finish line and start treating it as the point where the real feedback begins. A failed run is no longer a mystery and a source of dread. It is a trace you read, a root cause you name and a test you add. The agent gets more reliable every week instead of quietly drifting, and you can say exactly why, with the record to prove it.

Next: Chapter 10, The AI Operating Layer.