AI agents are difficult to debug because their failures often happen between model calls, external tools, retries and state changes rather than inside one prompt. A successful HTTP response can conceal a duplicate customer notification; an apparently slow model may actually be waiting on a database. Teams need a trace that can explain what the agent tried, what was allowed, which action completed, and what the user finally saw. That requires an observability design tailored to tool-using systems rather than a dashboard that counts tokens alone.

Follow the whole task, not only the model request

A user request should receive a stable workflow identifier before the first model invocation. Every planning step, retrieval call, tool execution, approval checkpoint and final response can then be connected to that identifier. OpenTelemetry’s evolving generative-AI semantic conventions describe spans for agent invocation and tool execution, providing a vocabulary teams can adapt while keeping their own application-specific attributes. A trace tree should show when a step began and ended, its parent, its retry count and whether it changed external state.

Avoid treating each model response as an independent session. The business action a user cares about may extend across many inferences. An email workflow, for example, can draft a message, request approval, send through an external API and then verify delivery. A latency report that stops at the draft step will measure the wrong journey.

Give each tool action an audit-friendly identity

The most dangerous ambiguity appears when a tool times out after the remote system has committed an action. If the agent retries without recognizing the first attempt, it may issue a second refund or send a duplicate notification. Record an action identifier, idempotency key when supported, requested operation, target type, authorization decision and a redacted outcome reference. Separate transport failure from business failure: a timeout is not evidence that the business operation did not happen.

The execution system should check a durable action ledger before retrying writes. Read-only lookups can have a different policy from irreversible changes. Agent traces are most useful when they can answer the question “did the side effect happen?” rather than merely “what text did the model produce?”.

Keep sensitive content out of the default telemetry path

Observability can create a second privacy problem if raw chat histories, personal documents, secrets, payment details or access tokens are copied into centralized logs. The safe default is structural metadata: operation name, tool class, latency, token usage, truncated error category and opaque identifiers. Capture request or response bodies only for explicitly approved debugging cases with limited access and retention. Redact before data leaves the service; a dashboard display filter is not equivalent to reducing what the collector stores.

A team can still reproduce most failures without saving full conversations. Store a scenario label, sanitized input template, retrieved-document version, model configuration hash, policy version and deterministic test fixture references. If a genuine production incident requires more detail, escalation should be tracked and time-limited.

Connect model quality to infrastructure symptoms

A trace should record more than duration. Useful signals include queue time, time to first token, tool failure rate, total inference cost, number of tool retries and whether a person was asked to intervene. Correlate these with outcome measures such as completed tasks, wrong-target actions and abandoned sessions. A fast response that sent the wrong email is not a performance success. A slightly slower workflow that caught a permission mismatch may be safer and ultimately cheaper.

Segment metrics by task type and risk level. Retrieval-only questions, booking changes and payment actions behave differently. A global p95 latency number hides the fact that a single expensive tool or excessive validation loop is responsible for most perceived delay in one user journey.

Use replay to test policy, not to repeat side effects

Replaying production logs into a live execution environment can recreate the incident and recreate its damage. Instead, build a sandbox that substitutes mock tools, synthetic documents and captured non-sensitive response shapes. The replay should preserve ordering and policy decisions while preventing calls to real payment providers, email recipients or customer records. Changes in model version, prompt policy or tool schema can then be evaluated against the same workload.

Track whether the updated agent reaches the intended decision, whether it requests appropriate human approval, and whether it attempts unauthorized tool calls. The OWASP LLM security guidance highlights excessive agency and information disclosure as meaningful risks; replay tests can make those risks measurable in release reviews without asserting that a checklist eliminates them.

Ship dashboards and incident procedures together

Operators need an explanation they can act on. A useful incident view summarizes the user-visible failure, the first abnormal span, external side-effect status, permission result, affected task count and likely remediation. Keep the original trace available only to authorized investigators. For an incident involving a changed tool interface, the on-call engineer should be able to compare schema versions and determine whether the issue came from the model, the wrapper or the external provider.

Start with three high-value alerts: a spike in side-effect ambiguity, an increase in permission denials and an unexpected rise in tool retries per completed task. Then add cost and latency thresholds specific to each workflow. Observability matures when support teams can explain an incident without opening sensitive conversations or guessing whether actions executed.

Implementation takeaway: create a task-level trace ID, durable action ledger, privacy-safe telemetry schema and side-effect-free replay environment before expanding an agent’s tool privileges. Instrumentation cannot replace permission checks; it should make their operation demonstrable and failures diagnosable.

Sources and technical references

OpenTelemetry: GenAI agent and framework spans; OpenTelemetry semantic conventions; OWASP LLM application risks; NIST AI RMF. The workflow design and examples are an independent technical analysis rather than a reproduction of these documents.