How should an enterprise trace AI agent decisions, tools, approvals and failures?

AI agent observability is not a transcript archive and it is not a dashboard of successful model requests. A production system needs an evidence chain from the business task through retrieval, model calls, tool execution and human approval to the final operational result. That chain should explain failure, cost, authority and recovery without copying every sensitive payload into the monitoring platform.

Who this is for

This guide is for business, product and operations leaders preparing a customer-service assistant, document review workflow, quotation aid, field-service assistant or another agent that reads enterprise data and acts through business systems.

A demonstration can often survive on developer logs. A production agent cannot. Its result may depend on a model and prompt version, a particular knowledge snapshot, retrieved evidence, tool parameters, an approval decision and one or more retries. A fluent final message can still conceal stale evidence, a skipped approval or a duplicate external action.

Cloudflare's agent tracing documentation models a run as nested agent, model, tool and approval spans. It also states that a trace is not a complete, lossless conversation record and that long payloads can be truncated. This is the right product boundary: a trace is diagnostic and governance evidence; it is not the system of record for the business transaction.

Four evidence layers belong together

Evidence layer	Question it answers	Typical evidence	System of record
Business outcome	Did the task actually complete?	Ticket created, quote sent for review, notification delivered	Operational application
Agent execution	How did the agent reach and act on the result?	Model, retrieval, tool, approval, retry and timing spans	Trace platform
Quality and risk	Was the result acceptable and authorised?	Accuracy, grounding, policy, intervention and user feedback	Evaluation and governance records
Service health	Were the underlying services healthy?	API, database, queue, network and provider failures	Existing observability stack

Use stable identifiers to join them. A service request may have a business task ID, its agent run a trace ID, each operation a span ID and the resulting ticket its own record ID. An investigator should be able to move from a customer-visible result to the run, and from a failed tool call back to the affected business records.

The minimum run record

Task and versions

Capture the task type and business identifier, environment, start and end times, workflow or agent version, prompt version, knowledge version, model and material configuration. “Latest prompt” is not a version that can support an incident review.

Model activity

Record provider, model, call order, duration, finish reason, input and output tokens, cache usage, retries and errors. Keep redacted or sampled inputs and outputs only when the quality investigation needs them. A monitoring vendor should not automatically receive full contracts, health data, credentials or customer histories.

OpenTelemetry's Generative AI semantic conventions define common attributes for providers, models, workflows, conversations, usage, retrieval and tools. A portable vocabulary reduces dependence on one dashboard. It does not justify collecting every optional field: the specification explicitly warns that system instructions, retrieval queries, tool arguments and tool results can contain sensitive information.

Knowledge and retrieval

Capture the data source and version, query, returned document identifiers, rank or score, filters and the evidence actually used. For long or sensitive material, store the authorised document ID, version and content hash, then let permitted investigators open the source in its primary system.

Tools and external actions

Each tool span should distinguish the tool, controlled parameter summary, service identity, target system, timeout, retry, result status and idempotency key. Reading a record, creating a draft, making a final submission, issuing a refund and deleting data are materially different operations. If a network timeout leaves the outcome unknown, query the target before retrying.

Approval and human intervention

Record why approval was requested, the evidence and proposed action shown to the reviewer, reviewer role, decision time, edits, and whether the final submission matched the approved payload. Human intervention is not automatically a failure. It can be a correctly designed control, or it can reveal that the automated scope is too ambitious; the reason code makes the difference visible.

Outcome and failure

End a run with a business state, not a generic technical status. Distinguish completed, business rejection, awaiting human review, partially completed, technical failure, compensating and outcome unknown. Classify the failed stage—such as missing knowledge version, tool permission denied, provider rate limit, approval timeout or uncertain write—so that the alert has an owner and a recovery path.

Measure acceptable tasks, not merely model uptime

A practical scorecard normally covers six groups:

1. Business completion: completion, first-pass completion, business rejection, partial completion and recovery rates.
2. Quality: fact or field accuracy, source traceability, representative evaluation pass rate and user correction rate.
3. Tools: success, validation error, duplicate action, uncertain outcome, timeout, retry and compensation counts.
4. Human collaboration: approval, intervention and edit rates, waiting time and reasons work returns to a person.
5. Experience and economics: end-to-end P50/P95 duration, time to first useful result, tokens, external service charges and cost per accepted task.
6. Risk: attempted overreach, sensitive-data events, malicious input, unapproved action, stale knowledge and safe-stop rate for high-impact tasks.

A 99% model-request success rate says little about operational reliability. One business task may call three models and two tools, then fail to create the ticket because approval expired. Failed retries also consume tokens and service charges, so economics should use an accepted business result—not a model response—as the denominator.

The NIST AI Risk Management Framework calls for evaluation under conditions similar to deployment and continued monitoring of the system and its components in production. In practical terms, the offline evaluation set, production sampling and run telemetry need compatible task and outcome definitions. Three unrelated scores cannot show whether a release improved the product.

A worked hypothetical

The following is a design example, not a client case or measured result. Imagine an equipment company using an agent to assist with service requests:

1. A customer provides a serial number, fault description and photographs; the application creates a business task ID.
2. The agent retrieves the matching product manual and active warranty terms, recording their versions and document IDs.
3. A read-only tool checks purchase and ownership data through a dedicated identity and returns only necessary fields.
4. The agent proposes a fault category and ticket draft. Low confidence, conflicting evidence or compensation exposure moves the task to human approval.
5. After approval, one controlled write service creates the ticket with an idempotency key.
6. The trace connects timing, model and tool status, approval evidence and the final ticket ID.
7. If submission times out, the run becomes outcome unknown and checks for an existing ticket before any retry.

Acceptance now covers more than prose quality. The company can verify that a ticket leads back to approved evidence and actions, missing information is recognised, an uncertain write does not create duplicates, and authorised staff can reconstruct an incident.

Design privacy, access and retention before rollout

Agent telemetry can be more sensitive than ordinary application logs because it may combine user input, system instructions, retrieved documents, tool parameters and approval details. The OpenAI Agents SDK exposes a control for whether model and tool inputs and outputs are included in traces. This illustrates an important architectural choice: keep the execution structure while limiting raw content.

A sensible policy is to:

• retain identifiers, versions, states, timings, charges and error classes by default;
• collect, truncate, redact or hash prompts, attachments, retrieved text and tool results according to need;
• separate access and retention for debugging, sampled quality review, audit evidence and operational records;
• audit who views, exports or deletes production traces;
• have data and compliance owners approve scope and location for personal, confidential or regulated information.

“Log everything” is not a safe default. It expands exposure and cost. Logging too little leaves the enterprise unable to explain a high-impact action. The target is sufficient evidence for diagnosis and accountability, with high-sensitivity source content retained in its primary business system.

Production acceptance checklist

• A business task ID resolves to its complete agent run and final operational record.
• Model, prompt, knowledge, agent and tool versions are traceable.
• Model calls, retrieval, tools, approvals and business writes have separate timing and result states.
• Write tools have a service identity, validated parameters, an idempotency key and an uncertain-outcome procedure.
• Completed, rejected, awaiting review, partial, failed and compensating states remain distinct.
• Metrics use business tasks and accepted outcomes, segmented by scenario, version and risk level.
• Production samples can feed evaluation without uncontrolled retention of sensitive fields.
• Every alert points to an owner and recovery procedure, not merely a token spike or provider error.
• Tests cover stale knowledge, tool timeout, insufficient permission, rejected approval, duplicate request and provider change.
• A release comparison shows changes in quality, latency, cost and risk together.

Common mistakes and ongoing ownership

Buying a trace viewer and declaring observability complete. A platform can display spans; it cannot define business success, risk tiers, approval ownership or compensation rules for the organisation.

Treating the transcript as the only evidence. It cannot prove a database write, external outcome or approval state, and it may be incomplete by design.

Watching averages only. A small number of exceptionally slow, expensive or repeatedly retried tasks disappear inside an average. Use percentiles, outliers and cost per accepted task.

Changing only the prompt after an incident. The cause may be a stale knowledge version, permission, integration, retry or approval defect. Remediation should target the failed stage shown by the trace.

Keeping every input and output indefinitely. Trace payloads, operational records and audit evidence require separate retention and access policies.

Every change to a model, knowledge source, tool permission or approval boundary should advance a version and trigger relevant regression samples and alert review. Mature observability is not a large volume of logs. It is the ability to answer, quickly and credibly: which business tasks were affected, what changed their outcome, whether authority was exceeded or an action duplicated, how to recover, and how the same failure will be detected earlier next time.

If the broader production architecture is still open, begin with What components does a production enterprise AI agent need?. When representative acceptance cases are the next priority, use How should a non-technical buyer accept an AI customer-service or business assistant? to define outcomes and failure classes.

Sources

• Cloudflare Agents: Tracing supports the agent, model, tool and approval span structure and documents the limits of traces as conversation records. (Updated 4 August 2026; accessed 18 September 2026.)
• OpenTelemetry: Generative AI semantic conventions informs the common provider, workflow, conversation, retrieval, tool and usage fields and their sensitive-data cautions. (Accessed 18 September 2026; the conventions continue to evolve.)
• OpenAI Agents SDK: Running agents documents run-level trace identity, grouping, metadata and controls for including sensitive model and tool payloads. (Accessed 18 September 2026.)
• NIST AI RMF Core supports continued evaluation, documented metrics and production monitoring of an AI system and its components. (Accessed 18 September 2026.)

Provider fields, pricing and retention facilities change. A final design should be based on the deployed agent architecture, data classification, operational systems of record, current provider documentation and the organisation's risk tolerance.