How to Debug AI Agent Failures in Production

The hardest agent bugs you will debug this year will not throw an exception. The service will be up, the model will return a response on every call, and the dashboards will be green — while the agent quietly stops doing its job. Someone from product will ask "is the checkout agent okay? conversion looks soft," and that Slack message will be your only alert.

Debugging that kind of failure with a log search is like debugging a distributed system with print statements. It can be done, but the workflow is wrong for the problem. Agent failures are usually decisions, not exceptions: a wrong path, a mis-parameterized tool call, a retry loop that eventually succeeds, a handoff that adds forty seconds and loses context. Each step is individually valid. The run as a whole is broken.

So the unit of debugging has to change. For a service, you debug a request. For an agent, you debug a run — the full path of prompts, model calls, tool calls, handoffs, and retries — and you judge it against three baselines at once: what this workflow normally looks like, what it normally costs, and what it normally achieves.

A workflow that actually finds root cause

When an agent incident lands, this is the sequence that reliably converges, in our experience, and it's the sequence AnoSys is built around:

flowchart TD
    A["<b>1 · Trace the full run</b><br/>prompts · tools · handoffs · retries"] --> B["<b>2 · Diff against baseline</b><br/>span count · tokens · tool mix"]
    B --> C["<b>3 · Check the evals</b><br/>a constraint, not proof of health"]
    C --> D["<b>4 · Correlate the surroundings</b><br/>deploys · infra · upstream APIs"]
    D --> E["<b>5 · Measure user impact</b><br/>abandon · escalate · convert"]
    E --> F["<b>6 · Route to the owner</b><br/>of the failing step, evidence attached"]
    style A stroke:#4ea3ff,stroke-width:2px
    style D stroke:#f4ae30,stroke-width:2px
    style F stroke:#59ca6f,stroke-width:2px

Trace the run end to end. Not the failing model call — the whole run. The visible symptom (a slow response, a wrong answer) is usually several steps downstream of the cause. In the trace, look for the shape of the run before the content: how many steps, which tools, how many retries, where the time and tokens went.

Diff against baseline. A single trace rarely tells you if something is wrong; a comparison almost always does. Yesterday's checkout runs averaged six spans and 4K tokens; today's average eleven and 13K. That delta is the actual signal, and it immediately narrows where to look — the extra spans have names.

Check the evals, but don't trust them alone. Quality scores catch regressions infrastructure metrics can't see. But an eval that scores answer quality will happily pass a run whose failure is cost, latency, or a downstream business outcome. Treat passing evals as a constraint on your hypothesis, not proof of health.

Correlate with everything around the agent. This is the step most teams can't do with trace-only tooling, and it's where most root causes actually live: a deploy shifted an API's response schema, a queue backed up, a feature flag changed retrieval behavior, a provider silently updated a model. Put the run on the same timeline as releases, infrastructure telemetry, and upstream service health, and the "AI bug" frequently turns out not to be an AI bug at all.

Measure the blast radius in user terms. Before you decide severity, know whether affected sessions abandoned, retried, escalated, or converted less. This is what separates "interesting anomaly" from "revenue incident," and it determines whether the fix ships today or this sprint.

Route to the owner of the failing step. An agent run crosses team boundaries — model, tools, infrastructure, product. The incident should land with whoever controls the step that broke, with the evidence attached, not with whoever happened to be on call for the agent.

What this looks like in AnoSys

AnoSys connects traces, evals, cost, logs, metrics, application events, user behavior, and business KPIs into one timeline, so the workflow above is navigation rather than archaeology. A finished investigation reads like this:

Checkout-agent latency increased because inventory search began retrying after an API schema change. Affected sessions show 3x token cost, lower task completion, and a higher escalation rate.

One sentence, five joined data sources, and — importantly — a named owner: whoever changed the inventory API schema.

Getting your agents to this point starts with two lines of instrumentation. If your agent uses the OpenAI API, the AnoSys SDK auto-instruments every call:

import os
from anosys_sdk_openai import AnosysOpenAILogger

os.environ["ANOSYS_API_KEY"] = "YOUR_ANOSYS_API_KEY"  # from the Console's API tab
AnosysOpenAILogger()  # from here on, every OpenAI call is traced

The same one-liner exists for JavaScript, OpenAI Agents, Anthropic agents, and custom stacks via OpenTelemetry or REST. From there: attach model, tool, cost, eval, and workflow attributes to each run; watch agent health and cost on dashboards; alert on the patterns that precede incidents — retry loops, eval drops, spend anomalies; and use the AI Platform Assistant to summarize the evidence when you need the one-sentence version for the incident channel.

The runbook checklist

When a production agent looks wrong, use a consistent checklist so the incident does not turn into free-form archaeology.

Step	Question	What to inspect
1	Did the shape of the run change?	span count, tool mix, handoffs, retries, duration, token count
2	Did the input population change?	user segment, account, geography, task type, traffic source
3	Did a dependency change?	deploys, prompt versions, tool schema versions, retrieval index updates, provider model versions
4	Did quality actually regress?	eval scores, human feedback, task success, policy checks
5	Did the regression matter?	abandonment, escalation, conversion, SLA breach, cost per outcome
6	Who can fix it?	owner attached to the failing workflow, service, tool, model route, or process unit

The important habit is to avoid debugging the model first by default. Many agent failures are caused by tools, context assembly, retrieval, queues, permissions, or business-rule changes. Start with the run shape and surrounding timeline; let the evidence point to the model only if the model is actually where the behavior changed.

Alerts worth creating first

Not every metric deserves a page. Start with alerts that combine behavior and impact: model or eval regressions tied to a release, latency that reduces completion, refusal spikes, tool or API error-rate increases, user engagement drops, SLA risk, and "successful" runs followed by user abandonment. Routing changes and model escalations are useful diagnostics for the investigation, but they are usually not alert conditions by themselves.

Start with Root Cause Analysis, the AI Agent Debugging solution, and the Alerts documentation.

Create a free account or schedule a demo.