AI agent observability needs trace contracts

AI agent observability needs trace contracts, not screenshots.

That sounds obvious until an internal agent fails in production. A customer success agent updates the wrong account field. A finance assistant pulls numbers from the wrong workspace. A sales operations agent enriches a lead with stale data, then opens a task for the wrong owner. The postmortem starts with a Slack thread full of screenshots: the chat, the final answer, maybe the user complaint. Everyone can see what the agent said. Almost nobody can see what the agent did.

Screenshots and chat logs create visibility theater. They are useful for demos, training examples, and quick support triage. They are not enough for production control because they flatten the run into a conversation. An AI agent is not just a chat box. It receives intent, plans steps, reads context, calls tools, waits for approvals, handles errors, and creates business consequences. If the trace cannot show those movements, the team is not observing the agent. It is watching the shadow it left behind.

A trace contract is the minimum agreement between product, operations, and engineering about what every production run must record. It does not have to be heavy. It does have to be explicit. Before adding more tools, more autonomy, or more agents, audit one production workflow and decide what must be traceable every time.

Screenshots hide the actual risk

The dangerous part of an agent run is rarely the final sentence. It is the path between the user request and the outcome.

A screenshot may show that the agent answered, “I updated the renewal date.” It does not show which account ID was touched, which system accepted the update, which permission scope allowed the call, whether the user approved the action, which fallback was used after an API error, or who owns the incident if the update was wrong.

That gap matters because internal agents sit between systems of record and human decisions. The production question is not “Did the agent sound reasonable?” The question is “Can we reconstruct the run well enough to debug, audit, and assign ownership?”

Langfuse describes LLM application tracing as structured records of a request that can capture prompts, model responses, token usage, latency, tools, retrieval steps, timing, inputs, outputs, and metadata. That is the right direction because observability is about causal structure, not screen capture. See the Langfuse observability documentation for the underlying tracing concepts.

This is also why agent governance cannot stop at permissions. In AI agents need tool permissions, not blanket access, the control question is what an agent is allowed to touch. Observability adds the next question: when the agent used that permission, can the team prove why, when, how, and under whose responsibility?

What should a trace contract include?

A useful trace contract is not a generic log dump. It is a small schema designed around operational questions. When a run fails, a leader should be able to answer seven questions without asking an engineer to replay the whole system from memory.

First, every run needs a run ID. The run ID is the handle that connects the user request, agent steps, tool calls, approvals, errors, output, and follow-up work. Without it, investigation becomes archaeology across logs, dashboards, chat history, and ticket systems.

Second, record the user intent as interpreted at the start of the run. Do not only store the raw prompt. Store the normalized intent the workflow acted on: “update renewal date,” “summarize unpaid invoices,” “draft escalation note,” or “create support ticket.” This lets product and operations compare what the user asked with what the agent believed it was doing.

Third, capture agent steps. Not every token needs to be exposed, and sensitive reasoning may need careful handling. But the operational trace should show the major step sequence: classify request, retrieve account context, call CRM tool, ask approval, write update, notify owner. This is the difference between a transcript and a run record.

Fourth, capture tool calls with inputs, outputs, target systems, permission scope, and status. The Model Context Protocol specification frames tools as functions exposed for an AI model to execute, while resources provide context and data. That distinction is useful for observability: a trace should show when the agent only read context and when it executed an action through a tool. The protocol overview is a helpful reference for teams standardizing agent integration boundaries: Model Context Protocol specification.

Fifth, record approvals. If the workflow includes human-in-the-loop control, the trace should show who approved, what they saw, what changed after approval, and whether the approval was required or optional. “A human was involved” is not enough. Production systems need the exact decision point.

Sixth, record errors and fallback behavior using a shared taxonomy. Timeout, permission denied, ambiguous intent, missing context, unsafe action, duplicate record, low confidence, and policy violation are not the same failure. Treating all of them as “agent failed” leads to blind retries and noisy alerts. This connects directly to AI automation needs failure classes, not retries: observability is only useful if failures are named in a way the organization can act on.

Seventh, record decision impact and escalation owner. Did the agent merely draft text, update a field, trigger a payment workflow, send an external message, or change a customer-facing state? Who owns the run if the outcome is wrong: product, support ops, data, security, finance, or the service owner? A trace without ownership is a museum artifact. It explains the past but does not improve the next run.

How does this change production monitoring?

A trace contract changes monitoring from “is the agent up?” to “is the agent behaving within the operating model?”

Traditional monitoring often starts with latency, error rate, cost, and volume. Those still matter. Agent systems need them too. But they are not sufficient because agents combine probabilistic interpretation with deterministic side effects. A fast run can still be dangerous. A low-error tool call can still represent the wrong business action. A successful completion can still be a governance failure if it bypassed an approval.

Microsoft’s Agent Framework overview highlights capabilities such as agents that process inputs and call tools, workflows with checkpointing and human-in-the-loop support, middleware for intercepting agent actions, telemetry, and state management. The practical lesson is not that every team must use one framework. It is that production agent systems need explicit surfaces where execution can be controlled, observed, and interrupted. See the Microsoft Agent Framework overview for the platform framing.

Once the trace contract exists, dashboards become more useful. Instead of only counting conversations, you can track runs by intent, tool, approval state, fallback state, error class, owner, and impact level. Instead of asking “Which agent produced the most messages?”, you can ask “Which intent produces the most approval overrides?” or “Which tool creates the most manual escalations?”

That is the difference between analytics and operations. Analytics describes usage. Operations changes behavior.

A minimum trace contract for one agent

Start small. Pick one internal agent that already touches a real workflow. Do not begin with the most ambitious multi-agent architecture. Choose a boring production agent: ticket triage, CRM enrichment, invoice explanation, knowledge base drafting, renewal summary, or lead routing.

Write a minimum trace contract with these fields:

• Run ID
• Timestamp and environment
• User or initiating system
• Normalized intent
• Agent version or workflow version
• Model and prompt version, where relevant
• Context sources used
• Tool calls attempted
• Tool call inputs and outputs, with sensitive fields redacted where needed
• Permission scope used
• Approval required, approval requested, approval granted or denied
• Error class and fallback path
• Final output or action
• Business object affected, such as account, ticket, invoice, or lead
• Decision impact level
• Escalation owner
• Retention and access rule for the trace itself

This list is not meant to become bureaucracy. It is meant to force an adult conversation before scale. If the team cannot agree on who owns a bad renewal update, the agent is not ready for broad autonomy. If nobody knows which fields are safe to store in traces, the observability project is exposing a data governance problem, not creating one.

The same logic applies to workflow design. In Agents need queues, not just prompts, the queue creates a visible operating surface for prioritization, retry, and handoff. A trace contract creates the matching evidence surface for each run. The queue says what should happen next. The trace says what actually happened.

Before adding tools, audit one run

The temptation is to solve agent uncertainty by adding another dashboard, another model evaluation, or another tool integration. Sometimes those help. But if the basic trace is missing, every new capability increases the blast radius faster than it increases control.

Run a simple audit this week. Choose one completed production run and ask the team to reconstruct it from the available evidence. What did the user intend? Which context was read? Which tools were called? Which system changed? Was approval required? Who approved? What failed? What fallback ran? What business decision was affected? Who owns the result?

If those answers require screenshots, tribal memory, or direct database digging, the agent is not observable enough. Create the trace contract before expanding the agent’s scope.

AI agent observability is not about collecting prettier logs. It is about making autonomy accountable. A screenshot can show the conversation. A trace contract shows the work.