How to review AI agent traces before production

Expected outcome

At the end of this protocol, a reviewer should be able to answer five questions from the stored record: What was the agent asked to do? Which policy and configuration governed the run? What did each model and tool step contribute? What changed outside the agent? How would the system recover if the same step failed or ran twice?

The deliverable is not a screenshot of a waterfall. It is a signed review record linked to an immutable run identifier. The record lists release blockers, accepted limitations, corrective actions, and the exact trace fields used as evidence. A second reviewer should reach the same conclusion without asking the original developer to narrate missing context.

This protocol complements the broader agent observability guide and agent evaluation stack. Those articles explain what to measure; this tutorial turns one production candidate trace into a repeatable review unit.

Prerequisites

Choose one bounded workflow with a named owner and a test account. Freeze the agent version, system instructions, model identifier, tool schemas, policy bundle, and environment revision. If any of those inputs can change during the review, comparison between runs becomes unreliable.

Prepare four run classes:

1. A normal successful task with independently checkable external state.
2. A task that requires a human approval before a consequential tool call.
3. A task containing a denied request or an input outside the agent’s scope.
4. A seeded failure such as a timeout, malformed response, revoked credential, or interrupted write.

Define critical data before tracing starts. Credentials, authorization headers, personal data, customer documents, hidden model reasoning, and unrelated tool output should not be copied into a general observability store. Record stable identifiers, hashes, redacted arguments, policy decisions, and protected artifact references instead.

Finally, write the acceptance policy before reading the first trace. Otherwise reviewers tend to reinterpret incomplete evidence as acceptable after seeing an attractive result.

Step 1: establish the trace contract

Use a stable top-level run_id and propagate it across model calls, tool requests, approval events, queues, and the target system. Add task_id for the business unit of work and attempt_id when a run is retried. Do not reuse one run identifier for several attempts; doing so hides duplicate side effects and makes latency totals misleading.

The minimum trace contract is:

Field	Purpose	Release question
run_id, task_id, attempt_id	Correlation and replay boundaries	Can every event be assigned to one attempt?
Agent, model, prompt, policy versions	Configuration provenance	Can the exact decision context be reconstructed?
Actor and tenant identifiers	Authorization boundary	Whose permissions should have applied?
Tool name and schema version	Interface provenance	Was the invoked contract current and permitted?
Sanitized arguments and result reference	Action evidence	What was requested and what came back?
Approval decision and approver role	Human control	Did approval occur before the action?
External object or transaction ID	State verification	Did the claimed change actually occur?
Error class and retry decision	Failure handling	Was recovery bounded and understandable?
Token, time, and cost counters	Operating evidence	Is the run within its budget?

OpenTelemetry trace and span concepts provide a portable envelope, while generative-AI semantic conventions can normalize common model and agent attributes. A vendor-specific trace may include richer fields, but the release contract should remain exportable.

Step 2: reconstruct the task from first principles

Begin with the initial state, not the final answer. Read the authorized objective, permitted tools, forbidden actions, budget, required approvals, and success checks. If the trace does not preserve those inputs or their version identifiers, stop the review: there is no stable standard against which to judge the path.

Build a short event timeline. Mark every model decision, retrieval event, tool call, human interruption, retry, and external write. Concurrent branches need parent-child relationships; a timestamp list alone cannot show whether one branch used stale data from another.

Check the context boundary. Retrieved passages and memory items should show provenance and authorization metadata. The trace must make it possible to tell whether an answer used information that the initiating user was allowed to access. A correct answer generated from unauthorized context is still a failed run.

Step 3: audit tool calls and approvals

For each tool call, compare the tool selected with the policy decision that authorized it. Confirm argument validation occurred before execution and that sensitive values were redacted only after the policy engine saw the real request. A trace that records a masked request but cannot correlate it to the enforcement decision is insufficient.

Review consequential calls in this order:

• Was the tool allowed for this actor, tenant, task, and environment?
• Did the arguments remain within the approved object, amount, recipient, path, or time window?
• If approval was required, was it bound to the exact action rather than a vague task summary?
• Did execution use an idempotency key or another duplicate-prevention mechanism?
• Did the result include a stable external identifier?
• Did the agent verify the resulting state instead of trusting a success-shaped response?

Human approval should be an event with decision, scope, timestamp, approver identity or role, and the hash of the proposed action. If an agent can modify the action after approval, the control is ceremonial.

The agent approval workflow guide provides patterns for binding approval to an action. During trace review, seed a changed argument after approval and confirm the policy blocks it.

Step 4: verify evidence and external state

False success is a high-priority defect. An agent may receive HTTP 200 while a background job later fails, may write a draft without publishing it, or may report that tests passed after running the wrong command. The trace review must compare the claim with the system of record.

Select an observable final-state assertion: a database row, immutable artifact hash, deployment identifier, ticket state, message ID, or read-back request. Preserve the assertion result and its timestamp. If eventual consistency applies, record the polling window and terminal condition rather than inserting an unexplained delay.

For research and answer workflows, verify that cited evidence was actually retrieved and supported the claim made. The trace should not expose private hidden reasoning, but it should show source identifiers, retrieval scores where meaningful, content versions, and the relationship between source evidence and the final response.

Step 5: classify failures and recovery

Assign every abnormal event to one primary class: input ambiguity, retrieval, model decision, tool contract, authorization, external dependency, concurrency, infrastructure, reviewer, or evaluator. Secondary tags can capture consequences, but one accountable layer must own the correction.

Then test the recovery invariant. A read may be retried safely; a write requires idempotency or reconciliation. An interrupted operation must distinguish “not attempted,” “attempted with unknown outcome,” and “confirmed complete.” Blind retries after an unknown outcome can duplicate messages, payments, deployments, or records.

Record the maximum retry count, backoff, timeout, escalation path, and terminal state. A run that loops until its budget expires is not resilient. A safe agent stops with an actionable status and preserves enough evidence for an operator.

Use the AI incident response playbook when a trace reveals data exposure, unauthorized action, or an unbounded external effect.

Step 6: score completeness and release readiness

Score separate dimensions rather than averaging them into one number:

Dimension	Pass condition
Trace completeness	Every consequential event is correlated and ordered
Authorization	Actor, resource, policy, and decision are reconstructable
Evidence support	Claims and state changes have inspectable proof
Approval integrity	Approval precedes and binds the exact action
Recovery	Seeded failures reach a bounded, non-duplicating terminal state
Privacy	Stored trace data follows minimization, access, and retention rules
Operability	An independent reviewer can diagnose and route a failure
Economics	Successful and failed runs stay inside declared budgets

Treat authorization, privacy, unreviewed irreversible actions, and false-success results as hard gates. Do not let excellent latency compensate for a missing permission decision. Weighted scores are useful only after hard gates pass.

Copyable review record

trace_review:
  run_id: ""
  task_id: ""
  attempt_id: ""
  agent_revision: ""
  model_revision: ""
  policy_revision: ""
  reviewer: ""
  reviewed_at: ""
  run_class: success | approval | refusal | recovery
  hard_gates:
    authorization: pass | fail
    approval_binding: pass | fail | not_applicable
    external_state_verified: pass | fail
    sensitive_data_minimized: pass | fail
    duplicate_side_effect_prevented: pass | fail
  findings:
    - severity: blocker | major | minor
      event_id: ""
      owner: ""
      evidence: ""
      corrective_action: ""
  decision: release | remediate | reject
  regression_case_id: ""

Store the record beside the evaluation case, not inside an individual reviewer’s notes. Link findings to trace event IDs and regression tests so the next release can prove the defect stayed fixed.

Failure modes

Final-answer bias: reviewers start from a polished result and overlook an unauthorized or wasteful path. Counter it by reading the objective, policy, and event timeline before the answer.

Unbounded telemetry: complete prompts and tool payloads are retained “for debugging,” creating a second sensitive-data system. Define allowlisted fields, protected payload references, access roles, and deletion checks.

Missing external correlation: model and tool spans exist, but the target system has no shared identifier. Add transaction or object IDs and verify state through read-back.

Approval without binding: a person approves a summary while the eventual arguments change. Sign or hash the proposed action and reject mismatches.

Retry ambiguity: the trace shows two attempts but not whether the first write succeeded. Model unknown outcomes explicitly and reconcile before retrying.

Dashboard dependence: the review cannot be exported or repeated without one vendor UI. Preserve a portable trace subset and the signed decision record.

Acceptance criteria

Release only when all four run classes have review records and every hard gate passes. At least one reviewer who did not build the workflow must reconstruct a run and locate the external-state proof. Every blocker and major defect must have an owner, regression case, and verified correction.

The trace store must enforce access and retention appropriate to its most sensitive permitted field. Export one sampled trace and confirm its identifiers, ordering, redactions, approvals, and state evidence survive outside the primary dashboard.

Finally, repeat the protocol after any material change to model, system instructions, tool schema, authorization policy, memory design, or retry behavior. A trace review is release evidence for a versioned system, not a permanent certificate.

Next step

Use the companion agent observability tools comparison to choose a collection and review surface without confusing the platform with the control. Then add the accepted trace fields to the agent evaluation stack so every confirmed failure becomes a regression case.