Why the final answer is not enough to observe an AI agent

Scope

Use this guide when an agent can call tools, retrieve evidence, retry work, or affect an external system. A single-turn text assistant with no tools still benefits from model, prompt, latency, token, and outcome records, but the run envelope becomes essential once several components can change the result.

Why it happens

Teams often begin with an application log containing the user request and the generated answer. That seems adequate during a demo because a person can watch the interaction. In production, the answer hides the path that produced it. Two identical answers may have used different evidence, model versions, tools, policies, or amounts of computation. A polished answer may follow a failed write, and a poor answer may come from correct reasoning over incomplete data.

The opposite reaction—logging every prompt, document, and tool payload—creates a security and privacy liability without guaranteeing useful diagnosis. Observability requires a designed record, not indiscriminate capture.

Diagnosis

Take one failed run and ask whether the current telemetry can answer these questions:

1. Which user, tenant, workflow, agent, model, prompt, policy, and tool versions were active?
2. What outcome was requested, and how was success determined?
3. Which evidence items were retrieved, admitted, rejected, or unavailable?
4. Which decisions changed the execution path?
5. Which tool calls were attempted, authorized, retried, committed, or rolled back?
6. What latency, token, request, and monetary costs accumulated by step?
7. Why did the run stop, escalate, abstain, or declare success?
8. Can an investigator reproduce the important queries without exposing hidden content?

Every unanswered question is an observability gap. Rank gaps by operational consequence rather than by how easy the field is to add.

Solution

Create a run envelope with one stable run_id and child operation identifiers. Record immutable version references for the agent, model, prompt template, policy bundle, retrieval index, tool contract, and evaluator. Represent tool attempts separately from tool effects so a timeout cannot be mistaken for a failed write or a successful retry for two independent effects.

Use structured evidence references. A reference should identify the source, version or retrieval time, query, access boundary, and relevance decision. Keep evidence lineage separate from the model’s summary of that evidence.

Record outcome at more than one level: execution completed, output passed a grader, tool effect was confirmed, and the user or business objective was achieved. These are not synonyms.

Finally, apply data minimization. Prefer classifications, hashes, counts, and pointers to protected stores. Treat prompt and completion content as potentially sensitive payloads with separate access and retention controls.

Artifact

Download the versioned Agent Run Envelope JSON Schema. Use it as a boundary object between agent runtime, telemetry pipeline, incident tooling, and offline evaluation. Extend it under a namespaced field rather than silently changing existing meanings.

Common mistakes

• Logging only the final response and calling the product observable.
• Treating a tool return value as proof that the intended external effect occurred.
• Storing raw prompts everywhere because structured fields were not designed first.
• Reusing one identifier for a user request, an agent attempt, and a tool transaction.
• Reporting average latency and cost without outcome, model, or task cohorts.
• Changing field meanings without a schema version or migration rule.