A support agent at a mid-sized SaaS company closed 18% fewer tickets in June than it had in March. Nobody noticed for nineteen days. The model version was pinned. The prompt hadn’t been touched. What had shifted was a retrieval index that started serving documents from a deprecated knowledge base after a vendor migration, which pushed the agent into longer clarifying loops that still ended in a confident, plausible-sounding wrong answer.
That’s the shape of most agent failures. Not a crash, not a stack trace, but a slow drift that produces garbage with good grammar. Dashboards built for HTTP services won’t catch it. Recording what the agent did, step by step, and being able to interrogate those records later will.
What AI agent observability actually means
Monitoring answers questions you wrote down in advance. Observability lets you ask new ones. With deterministic software you can enumerate failure modes before you ship: the endpoint times out, the queue backs up, the disk fills. Put an LLM in the loop and that list stops being finite. The model chooses tools, decides when it’s done, and writes its own intermediate steps.
The practical definition for agents is narrow and useful: can you reconstruct any single run, step by step, weeks after it happened, and answer a question you didn’t anticipate? “Did the agent read the pricing page before it quoted that discount?” If you can, you have observability. If the only artefact is a chat transcript, you have a screenshot.
A trace is the unit that matters, not a log line
Structure your telemetry as one trace per run and one span per step. A run is a user request from first token to final answer. A step is either an LLM call, a tool call, or a decision to stop. Each span needs enough context to stand alone:
- Run metadata: run ID, session, agent version, model IDs, temperature, and the feature flag state at the time.
- LLM spans: prompt tokens, completion tokens, cached tokens, finish reason, latency, and a prompt hash so you can group identical inputs.
- Tool spans: tool name, sanitised arguments, HTTP status or exception, response size, and latency.
- Decision spans: the plan the agent produced and whether the step advanced the goal or repeated a previous one.
That last field is the one teams skip and then regret. Without it you can see that an agent made fourteen calls, but not that eleven of them were the same search query with slightly different phrasing. If your tools are exposed over HTTP, the AI agent APIs you build with are the natural place for the hook: a small middleware that stamps the run ID onto every outbound call and logs the response envelope.
The four numbers that earn dashboard space
Most agent dashboards die from clutter. Four metrics cover the majority of production surprises.
Cost per completed task
Not cost per token, and certainly not cost per call. One real example: a scheduling agent ran at $0.031 per booking in March. By July it was at $0.19 with the same model. Token prices hadn’t moved. The agent had started re-validating timezone data on every step after a daylight-saving edge case, adding four extra calls per run. Cost per task surfaced it in a day. Token dashboards never would have.
Tool call failure rate, split by tool
A 4% failure rate across all tools hides the fact that your CRM lookup is at 22% and everything else is healthy. Break it out by tool name and by error class: 429s are a capacity conversation, 400s mean the schema changed under you, and repeated 200s with empty bodies mean someone shipped an API version bump.
Steps per run, as a histogram
Loops are the most expensive agent bug and the quietest. Watch the p95. If your meeting-prep agent normally finishes in six steps and the 95th percentile moves from 8 to 21 in a week, something in the world changed even though your code didn’t. Alert on the shape of the distribution, not just the mean.
p95 latency per step type
A slow tool doesn’t just annoy users. It burns your timeout budget, and agents that hit a timeout mid-plan tend to restart the plan from scratch. Split latency by step type so a 9-second retrieval call doesn’t hide behind a fast 400ms classification call.
Capture reasoning without hoarding it
You don’t need full chain-of-thought in your data warehouse. Store the plan, the tool arguments, and the final answer; those three reconstruct almost every incident. Redact emails, phone numbers, and account IDs inside the process before anything leaves the container, not in the pipeline afterwards. Sample aggressively once you trust the pipeline: 100% of runs for the first two weeks, then 10% with 100% of errors and 100% of runs that exceed the step-count p95.
Retention follows the same logic. Hot storage for fourteen days covers debugging. Aggregates, not raw traces, should live for a year so you can answer “was this always slow?” months later.
Alerts that survive week two
Every team mutes a noisy agent alert within a fortnight. Rate-of-change thresholds beat absolute ones because they adapt as your traffic grows. A few that hold up in practice:
- Tool failure rate above 5% for 15 minutes on any single tool.
- Cost per completed task at 2x the trailing 7-day median.
- Step count p95 up 50% week over week.
- Completion rate (runs ending in a delivered answer rather than a bail-out) down 8% day over day.
Route these into the same channel as your other incidents. An agent regression is an outage with better manners, and it deserves the same pager rotation. Pair each alert with a saved trace query so the on-call engineer opens a filtered list of real failures instead of a metric graph.
Instrument before you scale the blast radius
Observability is cheap on one agent with ten users and painful to retrofit onto six agents with ten thousand. The order that works: get the agent running somewhere real, prove it behaves, then watch it. Moving an agent off a laptop changes its network path, secrets handling, and timeout behaviour, which is exactly why the shift from local prototype to hosted service is the moment to have traces flowing, not three weeks later. Before that, testing your agent against real failure cases gives you a baseline to compare production against. Observability without a baseline is just a stream of numbers with no opinion about whether they’re good.
If you’re still choosing the platform underneath all this, check whether it emits traces you can export in a standard format before you commit. An agent builder that traps telemetry inside its own dashboard will cost you the first incident you can’t explain.
Start with one trace and one screen
The version of this that people actually ship in an afternoon: wrap your model client in a function that writes one JSON row per call to a Postgres table, carrying a run ID generated at the top of the request handler. Propagate that ID into every tool call. Build a single page that lists runs sorted by cost, and a detail view that renders the steps in order.
That’s roughly 80% of the value of a commercial observability platform, and it takes about thirty lines of code. Add the step histogram next, then the per-tool failure split. The teams that get burned are rarely the ones missing a fancy trace viewer. They’re the ones who couldn’t answer, nineteen days later, why the agent stopped booking meetings.