Here's a bug report you'll eventually get if you ship an AI agent:

"The refund agent approved a refund for a 7-week-old order. Policy is 30 days. Customer was thrilled. Finance was not."

You open your dashboards. Error rate: normal. p95 latency: normal. HTTP status: 200. The final message to the customer: polite, on-brand, perfectly formatted.

Everything is green, and the agent still did the wrong thing.

This is the core problem of running agents in production. The mistake rarely lives in the final answer. It lives three steps earlier: a bad retrieval, a misread tool result, a policy check that failed and got ignored. Your APM can't see it. Your LLM token dashboard can't see it. Only a trace can.

In this post, we'll cover:

  • What agent observability actually is (and how it differs from APM and LLM monitoring)
  • Why agents fail silently, with a bit of math
  • How to instrument an agent with OpenTelemetry GenAI spans
  • What every span should capture
  • Sampling, redaction and multi-agent trace propagation
  • A 5-question checklist for debugging any failed trace

What is agent observability?

An agent gets a goal ("resolve this refund request") and then works toward it on its own: it plans, calls tools, reads documents, hands off to other agents, and takes real actions.

Agent observability is the ability to reconstruct that whole journey after the fact: what the agent was asked, what it saw, what it decided at each step, which tools it called with which arguments, and what came back.

It rests on four signals:

Signal What it is Example
Traces The full path of one run, split into spans classify → retrieve → check_policy → issue_refund
Metrics Numbers aggregated over many runs Task success rate, cost per task, tool error rate
Logs Step-level events and raw payloads The exact prompt, the retrieved chunks, the raw tool JSON
Evaluations Scores judging if the output was right Groundedness 0.42, policy compliance: fail

The first three are classic observability. Evaluations are the AI-specific addition, because an agent can return 200, finish in two seconds, and still be wrong.

APM vs. LLM monitoring vs. agent observability

Traditional APM LLM monitoring Agent observability
Asks Is the service up and fast? Is the model call healthy and affordable? Why did the agent take this path, and was it right?
Unit A request One model call A whole multi-step run
Signals Uptime, latency, status codes Tokens, latency, cost Plans, tool args, retrieved context, handoffs, eval scores
Blind spot Output quality What happens between calls Requires instrumenting every tool and agent

LLM monitoring isn't wrong. It's just a subset. It covers the model layer; agent observability covers everything around and between model calls.

Why agents fail silently

1. Errors compound across steps

If each step of a 10-step run is right 95% of the time, the whole run is right much less often:

def run_success(step_accuracy: float, steps: int) -> float: return step_accuracy ** steps for steps in (1, 5, 10, 20): print(f"{steps:>2} steps @ 95% each -> {run_success(0.95, steps):.0%} end-to-end") 
 1 steps @ 95% each -> 95% end-to-end 5 steps @ 95% each -> 77% end-to-end 10 steps @ 95% each -> 60% end-to-end 20 steps @ 95% each -> 36% end-to-end 

Small invisible errors early become big visible ones at the end.

2. They're non-deterministic

The same input can take a different path on Tuesday than on Monday. You can't reproduce the bug by replaying the request. You need the trace of the run that failed.

3. Success codes lie

200 OK means the HTTP layer is happy. It says nothing about whether the agent refunded the right amount to the right person under the right policy.

4. Costs run away quietly

A retry loop, or an agent that calls the same search tool eight times, can burn thousands of tokens per task before anyone notices.

5. Inputs can be hostile

Emails, documents, web pages and tool outputs can carry hidden instructions. When the agent goes off-script because of one, the trace is the only record of where that instruction came in.

Instrumenting an agent with OpenTelemetry

You don't need to invent a trace format. OpenTelemetry defines GenAI semantic conventions with dedicated operations for agent work, such as create_agent, invoke_agent and execute_tool.

⚠️ These conventions are still marked Development, not stable. Instrument with OpenTelemetry now so you can switch backends later, but expect attribute names to shift. Wrap them in one helper so a rename is a one-line change.

Setup

pip install opentelemetry-sdk opentelemetry-exporter-otlp 
# telemetry.py from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter provider = TracerProvider( resource=Resource.create({ "service.name": "refund-agent", "deployment.environment": "production", }) ) provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) trace.set_tracer_provider(provider) tracer = trace.get_tracer("refund-agent") 

One run, many spans

Every model call, retrieval, tool call, guardrail check and handoff becomes a span nested under the run:

from opentelemetry.trace import Status, StatusCode from telemetry import tracer VERSIONS = { "app.prompt.version": "refund-v14", "app.kb.version": "policies-2026-11-01", "app.tool.version": "payments-api-3.2", } def handle_refund(request): with tracer.start_as_current_span("invoke_agent refund-agent") as run: run.set_attributes({ "gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": "refund-agent", "gen_ai.request.model": "your-model-id", **VERSIONS, }) intent = classify(request) chunks = retrieve_policy(intent) decision = check_policy(request, chunks) if decision.allowed: return execute_tool("issue_refund", order_id=request.order_id, amount=request.amount) return escalate(request, reason=decision.reason) def check_policy(request, chunks): with tracer.start_as_current_span("guardrail check_policy") as span: result = policy_engine.evaluate(request, chunks) span.set_attributes({ "app.policy.rule": result.rule_id, "app.policy.outcome": result.outcome, # pass | block | flag "app.order.age_days": request.order_age_days, }) if result.outcome != "pass": span.set_status(Status(StatusCode.ERROR, result.reason)) return result def execute_tool(name, **args): with tracer.start_as_current_span(f"execute_tool {name}") as span: span.set_attributes({ "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": name, "app.tool.args": redact_json(args), # redact BEFORE it leaves the process }) response = TOOLS[name](**args) span.set_attribute("app.tool.response", redact_json(response)) return response 

Now picture the refund bug as a trace:

invoke_agent refund-agent 2.31s ✅ ├── chat classify_intent 0.42s ✅ intent=refund_request ├── retrieval policy_search 0.18s ✅ 3 chunks ├── guardrail check_policy 0.01s ❌ rule=refund_window_30d outcome=flag │ order.age_days=49 ├── chat draft_reply 0.97s ✅ └── execute_tool issue_refund 0.36s ✅ amount=89.00 

Every span but one is green. The failed policy check at step four, followed by a refund anyway, is the whole story. No dashboard would have shown you this.

What every span should capture

Category Capture Why
Inputs / outputs Prompt, retrieved chunks, tool args, raw tool response So you can see what the agent saw
Identity / versions Agent name, model, prompt version, tool version, KB version So you can tie a failure to a release
Timing / cost Duration, input/output tokens, cost So slow or expensive steps stand out
Decisions Branch taken, policy rule fired, guardrail pass/block/flag So ignored checks are visible
Links One trace ID across sub-agents, MCP servers, downstream services So one run stays one trace

The versions row is the one teams skip and regret. Without prompt.version and model on every span, you can't tell if a failure came from your change or your provider's.

Sampling and redaction

Agents generate many spans per task, and storage costs add up. Don't sample uniformly. Keep everything that matters, and sample the boring stuff.

A tail-sampling policy in the OpenTelemetry Collector:

# otel-collector.yaml processors: tail_sampling: decision_wait: 10s policies: - name: keep-errors type: status_code status_code: { status_codes: [ERROR] } - name: keep-high-risk-tools type: string_attribute string_attribute: key: gen_ai.tool.name values: [issue_refund, send_email, reset_password, delete_record] - name: keep-escalations type: string_attribute string_attribute: { key: app.outcome, values: [escalated] } - name: sample-the-rest type: probabilistic probabilistic: { sampling_percentage: 10 } 

Rules of thumb:

  • 100% of errors, escalations, payments, data changes and anything from a brand-new release
  • A lower rate (5–20%) for routine successful runs
  • Redact personal data at capture, not after storage. Once PII is in your trace backend, it's in your backups, exports and vendor's logs too.
import re, json EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+") CARD = re.compile(r"\b(?:\d[ -]?){13,16}\b") def redact_json(obj) -> str: s = json.dumps(obj, default=str) s = EMAIL.sub("[email]", s) s = CARD.sub("[card]", s) return s 

Multi-agent systems: keep one story

When a planner hands work to a researcher, which hands off to a writer, which goes to a reviewer, a wrong output could come from any of them, or from a handoff between them.

Three practices:

1. Propagate one trace ID across every hop, including remote agents and MCP servers:

from opentelemetry.propagate import inject, extract # caller headers = {} inject(headers) # adds W3C traceparent httpx.post(RESEARCH_AGENT_URL, json=task, headers=headers) # callee ctx = extract(request.headers) with tracer.start_as_current_span("invoke_agent research-agent", context=ctx): ... 

2. Log the handoff itself: what one agent asked the next to do, with which context and permissions. A surprising number of failures are miscommunication: the task that arrived is not the task that was sent.

3. Attribute outcomes per agent role: success, cost and error rate for each agent, not just the system total, so you can see which one drags quality down.

Treat MCP calls with the same care. A poisoned tool description or tool output can steer an agent without any other agent being involved.

The 5-question checklist for any failed trace

Next time an alert fires, open the trace and walk through this:

  1. What did the agent think the task was? Check the classification or planning span.
  2. What did it see? Check retrieved chunks and tool responses for missing, stale or planted content.
  3. Where did the path change? Find the first span where the agent did something the task didn't need.
  4. Did a check fire and get ignored? A failed guardrail span followed by a normal action is a red flag.
  5. Is this one run or a pattern? Query for other traces with the same failing span to size the blast radius.

Question 5 is where traces pay for themselves twice: the query you write to size the problem becomes the alert that catches it next time.

TL;DR

  • Monitoring says something broke. Observability says why.
  • Agents fail upstream of the answer, and 200 OK hides it.
  • Instrument with OpenTelemetry GenAI spans; expect attribute names to evolve.
  • Put versions on every span, keep 100% of risky traces, redact at capture.
  • Propagate one trace ID across every agent and MCP hop.

In Part 2, we'll turn traces into signal: which metrics and alerts actually matter, how to catch agent drift when nothing in your code changed, how to detect hallucinated actions with a cheap claim-vs-trace check, and how observability fits with evals and red teaming.

This post is adapted from BotGauge's AI Agent Observability: The Complete Guide.

What's the weirdest thing you've found in an agent trace? Share it in the comments. 🔍