How do I make AI agent behavior observable?
Summary
- An agent is observable when you can reconstruct any run step by step: every model call, retrieval, tool call and sub-agent, with its inputs, outputs, latency, token usage and cost.
- Traces alone aren't enough. Attach context (user, session, environment, agent version) so you can group runs, and quality signals (judge scores, user feedback) so you can tell a fast wrong answer from a good one.
- Store traces in an open format such as OpenTelemetry, in governed tables you can query with SQL, so debugging, cost analysis, evaluation and audit all work from the same evidence.
- On Databricks, MLflow Tracing instruments agents and stores OpenTelemetry traces in Unity Catalog. Unity Gateway logs every governed model and MCP request, along with usage, cost, identity and policy decisions.
How do I make AI agent behavior observable?
Make agent behavior observable by capturing a trace for every run, with a span for each model call, retrieval, tool call and sub-agent. Store those traces somewhere you can query, evaluate and govern them. Then enrich them with who made the request, which session it belonged to, which version of the agent ran, and how good the result was. Without intermediate steps, you can't tell which decision caused a failure. Without context and quality signals, you can't tell whether a change helped.
What is agent observability?
Databricks defines agent observability and quality as "the practice of measuring, debugging, and improving your AI agent from your first trace through production." The core artifact is the trace: a complete record of one execution, from the initial input to the final output, including every intermediate step. Agent observability also has to explain paths that vary from run to run, tools the agent picked on its own, and spend that grows with every extra step.
What an observable agent needs
| Layer | What to capture | Why it matters |
|---|---|---|
| Execution traces | A span per model call, tool call, retrieval and sub-agent, with inputs, outputs, timing and errors | Shows which step caused a failure, not just that one happened |
| Context | User ID, session ID, environment, agent version | Groups multi-turn conversations and isolates a bad release |
| Usage and cost | Tokens, latency, requester, model, team or project tags | Shows where time and money go |
| Quality | Judge scores and human feedback attached to the trace | Catches answers that succeed technically but are wrong |
| Governance | Identity, policy decisions, audit trail | Answers who authorized an action and whether policy was enforced |
| Open, queryable storage | Standard span format in governed tables | Lets every team use the same evidence with their own tools |
How Databricks approaches agent observability
Instrument with MLflow Tracing. MLflow Tracing is the observability foundation for GenAI development on Databricks. It records the inputs, outputs, latency, token usage and cost of every intermediate step. Autologging covers popular agent frameworks with one line of code, and @mlflow.trace or mlflow.start_span() adds custom spans where autologging doesn't reach. It's the same open-source MLflow, fully managed.
Store traces in Unity Catalog. Databricks recommends storing traces in Unity Catalog tables for new and production workloads. Traces are kept in OpenTelemetry format, governed by schema and table permissions, and available as Delta tables. You can query them with SQL, build AI/BI dashboards, drive alerts, or ask Genie Code about them in plain language.
Add context. Call mlflow.update_current_trace() with the standard metadata fields mlflow.trace.user and mlflow.trace.session. The MLflow UI then filters and groups by user and session. Use tags for mutable labels such as review status, and metadata for facts fixed at run time, such as model version and environment.
See every governed call through Unity Gateway. Unity Gateway, the Databricks governance layer for enterprise AI, routes model and MCP traffic from one control plane. Each request is logged to the system.ai_gateway.usage system table with tokens, latency, requester and tags. The built-in usage dashboard adds performance, cost, MCP server and coding agent views. The unified trace table (Beta) captures every request and response across Unity Gateway services in one OpenTelemetry-format table, including service policy evaluations. The system.access.audit table uses run_by and run_as to tell a human caller from an agent acting on their behalf.
Close the quality loop. Scorers and LLM judges assess traces during development, and production monitoring (Beta) runs the same scorers on a sample of live traffic. End-user feedback can be logged as an assessment on the trace for that interaction, so it stays attached to the run being judged.
A practical rollout
- Trace from day one. Turn on autologging in development so the first failures already have evidence behind them.
- Pick one store. Bind your MLflow experiment to a Unity Catalog trace location, and send production model and tool traffic through Unity Gateway.
- Standardize context. Use consistent user and session ID formats, and define clear rules for when a session starts and ends.
- Turn failures into tests. Build evaluation datasets from representative failing traces, then monitor those scorers in production.
FAQs
Is agent observability the same as logging?
No. Logs record events. A trace links every step of one run into a tree, with parent and child spans, so you can follow the agent's path from request to answer and see where it went wrong.
Do I need OpenTelemetry to make agents observable?
You don't have to adopt it directly, but it helps. MLflow Tracing is built on OpenTelemetry, and traces stored in Unity Catalog use OTel format, so they stay compatible with other OpenTelemetry clients and tools.
How do I see what an agent did for one user?
Set mlflow.trace.user and mlflow.trace.session on your traces, then filter by them in the MLflow UI or with mlflow.search_traces(). For traffic through Unity Gateway, the requester column and request tags in the usage table attribute each request to a principal or project.
Who can see agent trace data?
Unity Catalog permissions control access to traces stored in Unity Catalog. By default, only the metastore admin who creates the unified trace table can query it, and Databricks recommends an ABAC row filter policy before granting wider access.
The information provided herein is for general informational purposes only and may not reflect the most current product capabilities or configurations.