How to Monitor and Debug AI Agents

Your agent works fine 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 the 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 don't raise exceptions. The agent just does the wrong thing, confidently. That's why standard APM tools fall flat. You can't debug an agent the way you debug a REST API. You need a trace of every decision, not just every HTTP call.

Here's the playbook for monitoring and debugging 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 a child span for every LLM call, every tool call, and every retrieval step.

Why it matters: one user request can trigger several model calls, tool calls, and retrieval steps in sequence. Without a parent-child trace hierarchy, you can't answer "what did the agent actually do?" You end up reading flat log lines and reconstructing causality by timestamp, which doesn't work.

Every span needs at least:

• Span name (for example, 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're using LangChain, LangGraph, or the OpenAI Agents SDK, you get most of this automatically by setting one environment variable. If you're 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 are still under active development, not stable, but they're already the closest thing to a shared schema for LLM traces, and OpenTelemetry says real-world usage is shaping what gets standardized next.

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 actually check every day.

Why it matters: most teams either log nothing or log everything. Logging everything ends up the same as logging nothing: you can't find the signal. The metrics below are the ones that catch real problems before your customers do.

Seven metrics matter for any production agent:

1. Task success rate. Did the agent finish the goal? Score it with an automated judge or a sample of human reviews.
2. Tool call success rate. What share of tool invocations return a non-error response? A drop here usually points to schema drift or a flaky API.
3. Steps per run. The average number of LLM and tool calls per agent invocation. A sudden spike means the agent is looping.
4. Tokens per run. Tied directly 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. Track the 99th percentile and you catch the bad sessions users actually remember.
6. Cost per resolved task. Divide total spend by successful runs. It's the one metric that tells you whether the agent pays for itself.
7. Hallucination rate on tool args. Count tool calls that fail because the model invented a parameter or a tool that doesn't exist.

You don't need all seven on day one. Start with task success, steps per run, and cost per resolved task. Those three catch most 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 200 comes back, the customer is unhappy, and nobody notices for two weeks. Alerts close that gap.

Every production agent needs four alerts:

• Loop alert: any single run exceeds your max-steps ceiling, say 25 steps. This catches runaway loops before they burn through a month's token budget in one afternoon.
• Tool error spike: tool error rate jumps more than 3x over the rolling one-hour baseline. Usually means an upstream API changed its schema or started rate-limiting you.
• Latency regression: p95 latency climbs 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 seven-day average. Catches runaway loops and prompt-injection attempts that try to drain your account.

Push alerts into Slack or PagerDuty. Email gets ignored. 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 takes three logins, two queries, and a JSON viewer, nobody looks at traces until something's 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. The comparison table below breaks down when to pick which.

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 highest-leverage practice in agent engineering. Without it, every prompt change is a coin flip. Fix one bug and you silently introduce three more. With it, debugging stops being a hope-based activity and becomes a measurable 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: 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.

Teams that ship reliable agents run eval-driven development. Teams that skip it 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. Fix them one at a time and you'll be playing whack-a-mole forever. Fix the pattern instead and you remove a whole class of failures at once.

The four failure patterns that show up in nearly every production agent:

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

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 with strict JSON Schema validation, and return error messages that tell the agent how to fix the call instead of just "invalid input."

Hallucinated arguments and tools. The agent invents a tool name or parameter that doesn't exist. Fix: validate every tool call against an allowlist before execution, and 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, and 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. That's 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's open source, vendor-neutral, supports OpenTelemetry, and covers most of what a production agent needs for free.

For more, see How to build production-ready AI agents.

Related Guides

• How to Build a Multi-Agent AI System from Scratch
• What Is Model Context Protocol (MCP)? The Complete 2026 Guide
• Human Approval for Agents: Store and Check the Exact Decision