An agent that works in a demo and an agent fleet that works in production are different engineering problems. The demo problem is whether the agent can complete the task. The production problem is whether you can tell, at nine in the morning, which of your agents is quietly degrading and which run from last night needs a human.
That second problem is observability, and it is where most agent deployments are thinnest.
Observability is not the audit trail
AI agent observability is the operator’s live view of a running fleet: health, throughput, failure shape and the ability to reconstruct any individual run. An AI audit trail is the compliance record of who authorised a specific action and what it changed. Same underlying storage, entirely different consumer.
The distinction is worth holding because it drives different design decisions. An audit trail optimises for immutability, retention and per-action lookup: it answers “show me the authorisation for this invoice write in March”. Observability optimises for aggregation and recency: it answers “escalation rate on the triage agent doubled this week, why”. If you are designing the compliance record, that is covered separately in AI agent audit trails; this article is about the operator’s view.
What a run trace must contain
A run trace is useful when it lets you reconstruct what happened without re-running the agent. That requires storing observations, not conclusions.
Per step, store five fields:
| Field | Why it is load-bearing |
|---|---|
| Reasoning text | Shows what the agent believed before it acted, which is where wrong decisions originate |
| Tool selected | Distinguishes “picked the wrong tool” from “picked the right tool and got bad data” |
| Parameters proposed | The only way to reproduce the call; also the only record of what a suggest-mode agent wanted to do |
| Observation returned | The actual tool output. Not the agent’s paraphrase of it |
| Timestamp | Lets you attribute a slow run to a slow tool rather than a slow model |
Per run, store the exit reason as a distinct value rather than a boolean. Success and failure is two states; real agent runs end in many more. Oneop’s AI agents store nine: goal reached, out of steps, out of tokens, out of time, no progress, blocked by a guardrail, tool error, escalated to a human, or out of credits. A billing stop and a provider outage are deliberately different answers, because the operator response to each is completely different.
One ordering detail decides whether the trace exists at all when you most need it. In Oneop the run row is written before the first billed step, at status running, and then updated in place on the way out through success and through failure alike. A run that dies mid-flight is therefore visible as a row still sitting at running, rather than absent.
The signals that predict a bad run
Four fleet-level signals, in the order they move.
Steps-to-completion, as a distribution. This is the earliest indicator. An agent that used to finish in three steps and now averages five is being made to work harder by something — a tool returning less useful data, a record shape that changed, a prompt edit. It is still succeeding, so nothing has alerted, and it is already costing you more per run.
Exit-reason mix. A healthy agent has a stable distribution. A shift toward no progress means the agent is repeating itself; a shift toward out of steps means the task got harder; a shift toward tool error is an integration problem wearing an AI costume.
Escalation rate. The proportion of runs that end needing a person. This is the number to put on a dashboard, because it is the direct measure of how much human work the agent is generating rather than removing. Rising escalation rate with flat volume means the agent is losing ground.
Cost per completed goal. Not cost per run. An agent whose cost per run is flat while its success rate falls is getting more expensive at the thing you actually wanted. Track it per agent rather than per fleet, because one expensive agent averages away inside a healthy fleet number.
Alert on rates, never on single runs
A single failed agent run is not an incident. Agents fail individual runs by design; that is what ceilings are for. Alerting per failure trains your team to ignore the channel within a week.
Alert on change in rate, over a window that contains enough runs to be meaningful. Three useful alerts:
- Escalation rate for one agent exceeds its own trailing baseline by a set margin.
- Any exit reason that was rare becomes common. No progress going from near-zero to a few percent is a strong signal of a looping agent.
- Zero runs from an agent that normally runs daily. Silence is a failure mode, and it is the one that no error-rate alert will ever fire on.
That last one deserves emphasis. An agent that stopped being started is indistinguishable from a healthy agent in every error metric you have.
The failure case: the agent that succeeded at nothing
A lead-qualification agent reads a new contact, checks the CRM for prior deals, enriches from the web, scores the lead and updates a field. It runs hundreds of times a week. Every run returns goal reached. Latency is flat, error rate is zero, cost is stable. Every dashboard is green.
Then the enrichment tool starts returning empty results — a credential expired upstream, and the tool handles it gracefully by returning nothing rather than raising. The agent reads the empty result, reasons that there is no external signal available, scores on CRM data alone, and writes the field. Goal reached. No error anywhere.
Two months of leads are scored on half the inputs, and nothing in conventional monitoring can see it, because technical success and semantic success diverged and only one of them was instrumented.
What catches this is not an error alert. It is the trace: the observation field for that tool went from populated to empty across the whole fleet on a specific day, and a distribution check on observation content would have fired. Which is the argument for storing observations verbatim instead of storing the agent’s summary. The summary said “no additional signal found”, and that sentence is true, unalarming, and useless.
Debugging a run after the fact
When a specific run went wrong, work backwards through four questions in order.
- How did it end? The exit reason narrows the search space immediately. Out of time points at a slow tool; no progress points at a loop; blocked by a guardrail points at the input.
- Where did the reasoning diverge from reality? Read step by step, comparing the reasoning text against the observation that preceded it. The failure is almost always one step earlier than the step that looks wrong.
- Was the tool choice available? An agent asking for a tool it was not granted is refused rather than improvised, so a run full of refusals is a configuration problem, not a model problem.
- Was anything actually written? In suggest mode the proposed action and its parameters are still recorded even though nothing changed, so “what would it have done” is answerable without re-running it.
Two honest limits on reconstruction, worth knowing before you rely on it. Refusals are the weak spot across the industry and in Oneop specifically: a prompt stopped by the injection filter or a call stopped at a credit ceiling is refused before the execution record is written, so it reaches your error handling but not your AI history. And the model recorded against an Oneop run is the one the agent was configured to use — if the router fell back through its chain of Gemini models, that field does not reflect it. Both are named on the AI governance page rather than left for an auditor to find.
Where observability sits next to the other controls
Observability tells you what happened. Guardrails decide what is allowed to happen in the first place, and the two are not substitutes — a fleet with perfect dashboards and no input controls is a fleet that watches its own incidents in high resolution. The input-side controls are covered in AI agent guardrails, and the catalogue of what actually goes wrong is in AI agent failure modes.
If you are still at the stage of deciding what to put into production at all rather than how to watch it, the staged approach is set out under deploying AI agents safely.
If you take one thing from this: instrument the exit reason before you instrument anything else. It is one column, it costs nothing, and it converts “the agent failed” into a sentence an operator can act on.