How to Monitor and Debug AI Agents

Your agent works perfectly in dev. Then it ships, and three days later a customer asks why it booked the same meeting four times in a row. You open your logs and find a wall of JSON with no idea where the loop started or why.

Agents are nondeterministic. The same prompt can produce different outputs on different runs, and most failures do not raise exceptions — the agent just does the wrong thing confidently. That is why standard APM tools fall flat. You cannot debug an agent the way you debug a REST API. You need a trace of every decision, not just every HTTP call.

Here is the playbook I use to monitor and debug agents in production.

Step 1: Instrument Every Agent Run as a Trace

What to do: wrap each agent invocation in a parent span, then emit child spans for every LLM call, every tool call, and every retrieval step.

Why it matters: a single user request can fan out into 30+ model calls and tool invocations. Without a parent-child trace hierarchy, you cannot answer "what did the agent actually do?" You will be reading flat log lines and trying to reconstruct causality by timestamp, which never works.

The minimum data per span:

• Span name (e.g., agent.run, llm.completion, tool.call:search_crm)
• Start time, end time, duration in milliseconds
• Parent span ID so you can rebuild the tree
• Input payload (prompt, tool args)
• Output payload (completion, tool result)
• Token counts (prompt, completion, total)
• Model name and provider
• Cost in USD if you can compute it inline
• Status (success, error, truncated)

If you are using LangChain, LangGraph, or the OpenAI Agents SDK, you get most of this automatically by setting one environment variable. If you are rolling your own, use the OpenTelemetry GenAI semantic conventions — they standardize attribute names like gen_ai.request.model, gen_ai.usage.input_tokens, and gen_ai.tool.name so any backend can read your traces. The conventions hit stable status earlier in 2026, which means you can build on them without rework.

Step 2: Define the Metrics That Actually Matter

What to do: pick five to seven metrics that map directly to user experience and cost, and put them on a dashboard you check daily.

Why it matters: most teams either log nothing or log everything. Logging everything is the same as logging nothing — you cannot find signal. The metrics below are the ones that catch real problems before customers do.

The core seven for any production agent:

1. Task success rate — did the agent finish the goal? Score it via an automated judge or a sample of human reviews.
2. Tool call success rate — what percentage of tool invocations return a non-error response? A drop here usually points to schema drift or a flaky API.
3. Steps per run — average number of LLM and tool calls per agent invocation. A sudden spike means the agent is looping.
4. Tokens per run — directly tied to cost. Watch the p95, not just the mean — outliers eat budgets.
5. Latency per run (p50, p95, p99) — agents feel slow at the tail. Tracking the 99th percentile catches the bad sessions users actually remember.
6. Cost per resolved task — divide total spend by successful runs. This is the only metric that tells you if the agent is economically viable.
7. Hallucination rate on tool args — count tool calls that fail because the model invented a parameter or a tool that does not exist.

You do not need all seven on day one. Start with task success, steps per run, and cost per resolved task. Those three catch the majority of regressions.

Step 3: Set Up Alerts for the Failures You Cannot See

What to do: configure alerts on metric thresholds and on specific failure patterns, and route them to the same channel your engineers already check.

Why it matters: agent failures are silent by default. The HTTP 200s back, the customer is unhappy, and nobody knows for two weeks. Alerts close that gap.

The four alerts every production agent needs:

• Loop alert: any single run exceeds your max-steps ceiling (e.g., 25 steps). This catches runaway loops before they burn through your monthly token budget in an afternoon.
• Tool error spike: tool error rate jumps more than 3x over the rolling 1-hour baseline. Usually means an upstream API changed its schema or started rate-limiting you.
• Latency regression: p95 latency increases by more than 50% week-over-week. Often a sign the model rolled to a slower variant or your prompt grew too long.
• Cost anomaly: daily spend exceeds 1.5x the trailing 7-day average. Catches both runaway loops and prompt-injection attempts that try to drain your account.

Push alerts into Slack or PagerDuty. Email gets ignored. And include the offending trace ID in the alert payload so the on-call engineer can click straight into the failed run.

Step 4: Build a Debug Surface You Will Actually Use

What to do: pick one observability platform as your primary debug surface, and make sure every engineer on the team can open a trace in under 10 seconds.

Why it matters: the speed of your debug loop determines how fast you can ship fixes. If opening a trace requires three logins, two queries, and a JSON viewer, nobody will look at traces until something is on fire.

A good debug surface shows, on one screen:

• The full input that triggered the run
• The agent's reasoning at each step (if you log chain-of-thought)
• Every tool call with its arguments and response, expandable inline
• Token and cost totals per step
• Errors highlighted in red with the stack trace inline
• A "rerun this trace" button

LangSmith, Langfuse, Braintrust, Helicone, Arize Phoenix, and Datadog LLM Observability all give you this surface to varying degrees. The exact pick matters less than committing to one and making it the team's source of truth. I cover when to pick which in the comparison table below.

Step 5: Run Replay and Eval-Driven Debugging

What to do: when a trace fails, save it as a test case. Build a regression suite from real production failures and run it on every prompt or model change.

Why it matters: this is the single highest-leverage practice in agent engineering. Without it, every prompt change is a coin flip — you fix one bug and silently introduce three others. With it, you turn debugging from a hope-based activity into a scientific one.

The replay loop:

1. Catch a failed trace in production.
2. Export the inputs (user message, conversation history, tool outputs) into your eval set.
3. Write an assertion describing what success looks like — could be exact match, regex, an LLM-as-judge rubric, or a function check on the final tool call.
4. Add the case to your regression suite.
5. When you change the prompt, swap models, or update a tool, run the full suite and compare scores.
6. Block the deploy if scores regress.

The teams that ship reliable agents in 2026 all run eval-driven development. The ones that do not are still debugging in production with print statements.

Step 6: Iterate on the Failure Patterns You See Most

What to do: every two weeks, look at the top three failure categories in your traces and fix the systemic cause, not just the individual bug.

Why it matters: agent bugs cluster. If you fix them one at a time, you will be playing whack-a-mole forever. Fix the pattern and you remove a whole class of failures at once.

The four failure patterns I see in nearly every production agent:

Infinite loops. The agent calls the same tool with the same arguments because it keeps getting an ambiguous response and re-tries instead of escalating. Fix: add a max-steps ceiling, detect duplicate consecutive tool calls, and force the agent to summarize and exit if it loops twice.

Tool misuse. The agent calls the right tool with the wrong arguments — a string where an integer goes, the wrong enum value, an out-of-range date. Fix: tighten your tool schemas using strict JSON Schema validation, and return descriptive error messages that tell the agent how to fix the call rather than just "invalid input."

Hallucinated arguments and tools. The agent invents a tool name or parameter that does not exist. Fix: validate all tool calls against an allowlist before execution. Return a structured error listing the available tools and their schemas so the agent can self-correct on the next step.

Silent context drift. The agent's behavior degrades as the conversation gets longer because the system prompt is buried under 40 turns of history. Fix: monitor input token count per step. When it crosses a threshold, summarize older turns and reset.

Each of these patterns is easier to spot in a tracing UI than in raw logs — which is why Step 1 matters so much. The instrumentation is what makes the diagnosis possible.

How the Top Agent Observability Platforms Compare

Pick one based on where your stack lives today and how much eval automation you need.

The pattern most mature teams settle on: one tool for tracing and operational monitoring (LangSmith, Langfuse, or Datadog) and one for evaluation and quality scoring (Braintrust or Arize). If you only pick one, pick Langfuse — it is open source, vendor-neutral, supports OpenTelemetry, and covers 80% of what you need for free.

For more on related topics, see How to build production-ready AI agents and The complete guide to AI agent architecture.