AI Observability Is Decision Reconstruction

An agent changed the wrong configuration.

The dashboard shows that the run lasted eleven minutes, used 84,000 tokens, called six tools, and ended with a successful status. None of those facts explains why the agent believed the configuration was the right one.

The answer may be somewhere in a transcript. An old runbook was retrieved ahead of the current service definition. A tool response was truncated. A planner made an assumption that an implementer inherited as fact. The agent noticed a conflict, chose one source, and never exposed that choice in the final answer.

Traditional metrics can tell us that the system was busy, slow, expensive, or broken. Agent systems add a harder question: what representation of the world produced this decision?

That is why AI observability cannot be only logs with token counts attached. Its real job is decision reconstruction.

After a consequential run, an operator should be able to rebuild the path from goal to context, from context to action, and from action to observed effect. Not every private thought needs to be preserved. The evidence and transitions that shaped behavior do.

A Transcript Is Not a Trace

A transcript is useful raw material. It records messages, tool calls, and responses in order. It is also a poor operational model.

Long transcripts mix instructions, speculation, evidence, abandoned plans, retries, and summaries. Important tool output may be truncated. Context may have been assembled from sources the transcript does not identify. A later model invocation may receive only a compacted version of the earlier conversation.

Reading the transcript asks an operator to replay the entire experience and infer which details mattered. That can work for one short failure. It collapses when workflows last hours, delegate to several workers, or execute thousands of times.

A trace should expose the structure the transcript hides. Which goal was active? Which step owned the decision? What context was assembled for that step? Which sources carried authority? What action was proposed, permitted, attempted, and verified? Which artifact moved to the next worker?

The transcript tells a story. The trace should expose the causal skeleton.

Begin With the Unit of Work

Observability becomes noisy when every model call is treated as an isolated event.

The useful top-level object is the goal or operation the system is trying to complete. Under it sit plans, steps, model invocations, tool calls, approvals, artifacts, retries, and verification. Each event carries stable identifiers so the team can follow one piece of work across processes and time.

This matters when a run resumes. The worker that finishes a deployment may not be the worker that planned it. A browser session may expire and restart. A queue may redeliver a step. Without shared operation identity, the monitoring system displays several unrelated traces where the business experienced one workflow.

The operation also gives cost and latency meaning. Eighty thousand tokens may be excessive for a routine classification and entirely reasonable for a difficult migration. Eleven minutes may indicate a loop or a deliberate verification stage. Metrics need the purpose of the work before they can describe its health.

Instrument the goal first. Model calls are events inside it.

Record the Context That Actually Ran

When behavior changes, teams often ask which prompt version was deployed. That is only one input.

The effective context may include system policy, repository instructions, retrieved documents, memory, tool definitions, user messages, summaries, and artifacts produced earlier in the workflow. Selection, ranking, truncation, and compaction can change the result even when the prompt template remains identical.

An observable context interface records the manifest of what the model received:

• source identifiers and versions
• authority and content type
• retrieval query and rank
• freshness at the time of use
• truncation or summarization boundaries
• applicable policy and tool definitions
• model and inference configuration

Sensitive content does not need to be copied into a permanent log. A trace can retain hashes, references, classifications, and access-controlled snapshots. The requirement is that an authorized investigator can determine which representation influenced the run.

“We think the model saw the new policy” is not an observable state.

Capture Decisions at the Boundaries

Logging every token does not automatically reveal the important decision.

The most useful events occur where the workflow crosses a boundary: evidence becomes a conclusion, a plan becomes a tool call, an acknowledgement becomes a completion claim, or one worker hands an artifact to another.

At those points, ask the system to produce a compact decision record:

• the decision being made
• the alternatives considered when they matter
• the evidence used
• unresolved uncertainty
• the policy or approval that permits the next action
• the expected result and verification method

This is not a demand for hidden chain-of-thought. Operators do not need a verbatim record of every internal token. They need the explicit rationale the system used to justify a consequential transition.

Structured decision records are easier to compare than prose transcripts. If failed runs repeatedly cite stale documentation, the problem becomes visible. If successful runs gather an independent source before acting, that pattern can become part of the harness.

Observability should capture the reasons the runtime is willing to stand behind.

Tool Calls Have Two Sides

Many traces record a tool name, arguments, duration, and returned value. That describes the request. Consequential tools also need the resulting effect.

An agent can receive a timeout after a tool completed successfully. It can receive an acknowledgement before the effect becomes visible. It can call the right tool with the wrong operation identity and create a duplicate. The trace needs to distinguish the attempt from the state change.

For each consequential action, record the intended operation, authorization, canonical parameters, attempt history, provider response, reconciliation result, and completion evidence. The idempotency contract supplies the identity that holds those events together.

This creates a clean operational question: did the agent merely ask for the action, or did the system observe the intended state afterward?

Tool observability should also expose what the model could not see. Was output truncated? Did the connector filter fields? Was the result served from cache? Did permission policy remove part of the response? A model's reasoning may be coherent relative to an incomplete tool result.

The trace should make incompleteness impossible to mistake for absence.

Policy Decisions Belong Beside Model Decisions

When an agent attempts an action and the platform refuses it, that refusal is not infrastructure noise. It is part of the behavior of the AI system.

Record which policy applied, what resource and operation it evaluated, why the request passed or failed, and what authority was active at the time. For human approvals, bind the decision to the artifact, scope, and expiration that execution actually used.

This helps distinguish several very different failures. The model may have proposed an unsafe action and been correctly contained. The model may have proposed a safe action that an overly broad rule blocked. The platform may have applied the wrong tenant policy. A human may have approved one artifact while the agent executed another.

Aggregating all four into “tool error” prevents improvement.

Policy traces also show whether controls are meaningful. If reviewers approve everything in seconds, or agents repeatedly probe alternate tools after a denial, the architecture has learned something important even when no incident occurs.

Security and reliability live in these rejected paths as much as in successful ones.

Make Handoffs Observable

Multi-agent work often fails in the space between competent workers.

A researcher discovers a constraint but omits it from the handoff. A planner labels an assumption as a requirement. An implementer produces an artifact without stating what remains unverified. The next worker receives polished prose and cannot tell which claims came from primary evidence.

Treat every handoff as a typed event. Record the sending step, receiving step, artifact version, claims, source references, open questions, and acceptance criteria. The receiver should acknowledge what it accepted and reject a handoff that lacks required evidence.

This is especially important in parallel workflows. A timestamped tree of ownership and artifacts is more useful than a flat list of messages from several agents. It lets an operator see where conclusions diverged and which branch supplied the version that eventually executed.

The AI-native team is a feedback loop. Handoff traces reveal whether that loop is carrying state or merely passing summaries.

Design for Comparison, Not Just Inspection

The first observability milestone is being able to understand one bad run. The more powerful capability is comparing runs.

Why does one model succeed where another fails? Which context source appears in expensive loops? Do retries cluster around a particular tool outcome? Did the new retrieval policy improve grounded answers while increasing latency? Which human corrections recur across different tasks?

Answering these questions requires stable event schemas and semantic labels. If every workflow records “custom step 4” and a free-form blob, analysis becomes another manual reading exercise. Capabilities, decisions, policy outcomes, verification states, and failure classes need names that remain comparable across versions.

Do not force unlike workflows into one giant taxonomy. A research system and a deployment system have different domain events. Give them a small shared spine—goal, step, context, decision, action, effect, evidence—and let domain-specific traces extend it.

Observability earns its cost when repeated failures become patterns rather than anecdotes.

Connect Traces to Evals

A production trace should have a path back into the delivery system.

When an operator identifies the decision that caused a failure, preserve a sanitized version as a regression case. Recreate the relevant context conditions, tool outcome, policy state, and expected behavior. Then run that case against proposed changes to the model, prompt, retrieval policy, or harness.

This closes the loop described in Evals Are the AI Delivery Pipeline. Observability discovers behavior under real conditions. Evals make the lesson repeatable before the next release.

The link should work in both directions. An evaluation failure should produce the same trace shape as production, so engineers can debug it with the same tools. A release should record which evaluation version justified it, so an incident can be compared with the behavior the team believed it was shipping.

Without that connection, dashboards describe the past and test suites describe an imaginary system.

Preserve Privacy Without Destroying Evidence

Agent traces can become a second copy of everything sensitive the system touches.

They may contain user requests, retrieved documents, model outputs, tool arguments, secrets, customer records, and internal policy. Logging everything forever is not observability. It is uncontrolled data replication.

Classify trace fields at creation. Redact or tokenize sensitive values. Keep secrets out entirely. Store content references when a governed source of truth can supply the original under proper access. Separate operational metadata from restricted payloads so most debugging does not require exposure to raw data.

Retention should follow purpose. High-level performance events may remain useful for long-term comparison. Detailed content snapshots may need shorter windows, stronger access controls, and auditable retrieval. Deletion obligations must propagate to trace stores and evaluation cases derived from them.

The goal is sufficient evidence, not maximum capture.

Alerts Should Describe Broken Invariants

Token spikes and latency thresholds are useful symptoms. The best alerts identify a workflow invariant that stopped being true.

The agent executed without a valid approval. A consequential tool has no verification event. Two workers hold the same operation lease. Retrieved evidence was stale at execution time. A handoff referenced an artifact that no longer exists. The model claimed completion while the required test failed.

These signals are closer to user and business risk than model activity alone.

They are also actionable. An operator can pause the operation, reconcile the external state, restore the missing artifact, or route the decision for review. “Token use increased 37 percent” may deserve investigation. “The system cannot prove whether the customer was refunded” demands one.

Build alerts around the promises the workflow makes.

Observe the System You Need to Trust

AI observability is sometimes treated as a temporary aid for unpredictable models. As models improve, the argument goes, we will need less of it.

Better models will reduce some failures. More capable agents will also take longer tasks, use more tools, cross more systems, and receive more authority. The distance between request and outcome will grow. Reconstruction will matter more, not less.

Instrument the goal. Record the context that actually ran. Capture explicit decisions at consequential boundaries. Connect tool attempts to observed effects. Trace policy, approval, and handoffs. Protect sensitive content while preserving enough evidence to compare behavior and build regression cases.

The purpose is not to watch a model think.

It is to understand why a system acted, prove what changed, and make the next run better than the last one.