Seeing What Agents Do: Observability for AI-Driven Development

The Observability Gap

You can log every database query your system makes. You can trace every HTTP request, measure latency, count errors. Traditional observability is solved. But when an AI agent runs, what do you actually know about what happened?

You know the input. You know the output. You probably know some of the intermediate steps. But you don't know:

• Why the agent chose to call that particular tool
• What context it was using when it made that decision
• Whether it misunderstood the problem or the tool
• Which pieces of the codebase it actually read vs. which it assumed
• Whether the code it generated is actually correct or just statistically likely
• Whether it's getting progressively better or degrading over time

Traditional observability doesn't answer these questions because agents don't execute queries or make HTTP requests in the traditional sense. Agents make decisions. They generate code. They reason through problems. These are different behaviors that need different instrumentation.

This is the observability gap, and it's where development teams get stuck in production. The agent works great in demos. It crashes silently in production because you can't see what it's doing.

Why Traditional Observability Fails for Agents

Let's be specific about why your existing observability stack doesn't cut it.

Logs: Your agent calls a tool. The tool returns a result. You log "tool: read_file, status: success." That tells you what happened, not why. Did the agent read the right file? Did it understand the output? Did it use the information to make a better decision? Logs won't tell you.

Metrics: You measure "tools called per task" and "average tool call latency." These are useful signals, but they don't tell you whether the agent made good decisions. An agent that calls 47 tools and gets the answer wrong is worse than an agent that calls 3 tools and gets it right. Your metrics are measuring activity, not correctness.

Traces: You trace the execution path—function A called function B called function C. But agents don't execute predetermined paths. They decide what to do next based on what they just learned. Tracing gives you the path, not the reasoning. You need to trace the decision-making process, not just the execution.

APM: Application Performance Monitoring is built for deterministic systems. Your code does X, takes 200ms, succeeds or fails. Agents are probabilistic. The same input produces different outputs depending on model state, temperature, and countless other factors. APM assumes failure means "something went wrong with the system." Agent failure means "the model made a decision that didn't solve the problem."

Traditional observability assumes you know what "correct" looks like. For agents, you don't. The agent can follow all the rules and still generate broken code. It can call tools correctly and use the information poorly. It can complete a task in one way or another way, both valid but different. This requires a different observability model.

What Agent-Specific Observability Looks Like

Agent observability has five key components:

1. Decision Tracing

Every time an agent decides to do something, you trace that decision. Not just what tool it called, but why.

Decision: call_read_file
Reasoning: "The user asked for the authentication logic. I need to find the login module first."
Tool: read_file
Path: src/auth/login.py
Latency: 142ms
Result: [file contents]
Interpretation: "Found the login handler. It uses JWT tokens. I need to check the token validation next."

You're capturing the agent's reasoning about what it's trying to do, what tool it chose, what it expected to find, what it actually found, and how it interprets that information. This is hard to instrument because it requires the agent to expose its reasoning, but modern agents (Claude, Gemini, GPT-4) all support structured reasoning output. Good tool design, as covered in Designing Pluggable Tools for Agents, makes decision tracing easier to implement.

Decision tracing lets you answer questions like:

• Did the agent misunderstand the task?
• Did it choose the right tool for what it was trying to learn?
• Did it correctly interpret the results?
• Where did it go off track?

2. Tool Call Monitoring

You track every tool the agent invokes, not just that it happened, but the full context.

Tool: execute_code
Arguments: [python script for parsing logs]
Start Time: 2026-03-04T14:23:18Z
Duration: 2341ms
Status: success
Exit Code: 0
Output: [parsed log lines]
Stderr: (none)
Validation: "Did the agent check the output? Did it validate assumptions?"

• What tool was called and with what arguments
• How long it took
• What the output was
• Whether the agent actually used the output or ignored it
• Whether the agent's interpretation of the output was correct

This is crucial because tool misuse is one of the biggest failure modes for agents. An agent might call a tool correctly but misinterpret the results. Or call a tool with the wrong arguments and not notice the error. You need to see the full lifecycle, not just that the call succeeded.

3. Context Utilization Metrics

You measure what context the agent had available and what it actually used.

Available Context:
- 47 files in the codebase
- 12 files in the user's conversation
- 8 files from the conversation history
- 3 architecture documents
- 2 API references

Used Context:
- src/main.py (read 3 times)
- src/utils.py (read 2 times)
- Architecture docs (referenced once)

Missed Context:
- deployment/docker-compose.yml (relevant, not read)
- tests/integration_tests.py (relevant, not read)

• Is the agent's context window being used efficiently?
• Is it missing important files that would help it make better decisions?
• Is it reading the same file repeatedly when it should be combining information?
• Is it ignoring files that turn out to be important?

Context utilization metrics tell you whether the agent's decision-making is based on complete information or incomplete information.

4. Reasoning Quality Assessment

You measure whether the agent's reasoning is sound, even if the final output is wrong.

Task: "Refactor the authentication module"
Agent Reasoning Steps:
1. Understand current auth structure (read 4 files) ✓
2. Identify problematic patterns (JWT expiration handling) ✓
3. Design new approach (consistent with codebase style) ✓
4. Implement changes (created 2 new files, modified 3) ✓
5. Verify changes don't break tests (ran test suite, 2 failures) ✗

Reasoning Quality: High (correct process, execution issue)
vs.
Reasoning Quality: Low (misunderstood the problem, good luck)

Reasoning quality metrics let you distinguish between:

• Systematic problems (agent consistently reasons poorly)
• External problems (tools are failing)
• Model problems (reasoning capability is degrading)

5. Task Success Measurement

This is harder than it sounds. How do you know if the agent succeeded?

For concrete tasks, it's easier:

• Did the code compile? ✓
• Do the tests pass? ✓
• Does the API respond correctly? ✓

For ambiguous tasks, it's harder:

• Is this a good refactor?
• Did this code review catch the important issues?
• Is this documentation sufficient?

You need multiple signals:

• Automatic checks (compilation, tests)
• Human review (did a person confirm this was good?)
• Behavioral feedback (is the user running this code in production?)
• Outcome metrics (do bugs decrease after the agent's changes?)

Task success should include confidence levels. The agent might complete a task that's 80% correct. You want to measure that, not just "success" or "failure."

Practical Metrics That Actually Matter

Not all metrics are created equal. Here's what you should actually measure:

Tool Call Latency Distribution: Not average latency, but the distribution. If your agent is calling expensive tools, you want to see if that's causing slowdowns. Percentiles matter more than averages (p99 latency tells you about worst-case, average latency doesn't).

Context Retrieval Accuracy: Of the files the agent read, what percentage were actually relevant to the task? Over time, is the agent getting better at picking relevant context or worse?

Decision Quality (A/B Measured): Run the same task multiple times. Do you get the same decision? Similar decisions? Wildly different outputs? High variance in decision-making is a signal that the agent is unstable.

Cost per Task: This matters. If your agent is generating correct code by calling 50 tools, but each tool call costs money, you want to know that. Cost per task tells you whether the agent is efficient.

Time to Completion: Wall-clock time from task start to finish. Not just tool call latency, but the whole pipeline. Slower isn't always worse (more thoughtful is better), but you want to track this.

Error Rate by Error Type: Not "how many tasks failed," but "what types of failures are we seeing?" Tool misuse? Context misunderstanding? Model reasoning errors? Each failure type requires different fixes.

Tool Success Rate: If the agent calls a tool, how often does the tool actually work? If you're seeing failures, are they agent problems or tool problems?

Debugging Agent Failures

When something goes wrong, traditional debugging doesn't work. You can't step through an agent's reasoning. You can't inspect its internal state (not directly—it's inside a model).

Agent debugging requires different techniques:

Replay the Agent's Steps: Given what the agent had available (the input, the context, the tools), can you reproduce why it made the decision it made? This is where decision tracing becomes essential. You can read through the agent's reasoning and spot the error.

Isolate Variables: Did the agent fail because:

• The context was incomplete?
• The tool was broken?
• The reasoning was flawed?
• The task was ambiguous?

You isolate each variable:

• Rerun with complete context → does it fix it?
• Rerun the tool manually → does it work?
• Show the agent the reasoning path that failed → does it notice the error?
• Clarify the task description → does it understand now?

Comparative Analysis: Run the same task with a different agent or a different model. If Agent A fails and Agent B succeeds, the problem is specific to Agent A. If both fail, it's likely the task or context.

Human-in-the-Loop Investigation: Some failures need human judgment. Did the agent generate code that's technically correct but architecturally wrong? You need a human to assess that. Build observability that makes it easy for humans to review agent decisions.

OpenTelemetry for Agent Workflows

OpenTelemetry is the standard for instrumentation, and it's starting to be applied to agent workflows.

A basic OTel trace for an agent looks like:

Span: task_execution
  Attribute: task_id = "auth_refactor_001"
  Attribute: model = "claude-opus-4.6"

  Span: decision_step_1
    Attribute: decision = "read src/auth/login.py"
    Attribute: reasoning = "understand current structure"

    Span: tool_call_read_file
      Attribute: file = "src/auth/login.py"
      Attribute: duration_ms = 142
      Attribute: success = true

  Span: decision_step_2
    Attribute: decision = "read src/auth/tokens.py"
    ...

The challenge is that agent-specific OTel instrumentation is still emerging. Most agent frameworks don't have built-in OTel support. You're likely building custom instrumentation.

Building Agent Observability Dashboards

What should you actually look at?

Task Overview: What tasks ran, which succeeded, which failed, why did they fail?

Agent Performance: For each agent or model you're running, what's the success rate, average cost, average duration? Are some models consistently better than others?

Tool Health: Which tools are most frequently used? Which have the highest failure rate? Which are taking the longest?

Context Efficiency: On average, how much context does an agent use? Is it reading files it doesn't need? Missing files it should read?

Cost Breakdown: Where's your money going? Tool calls? Token usage? Inference? This matters if you're paying per API call.

Degradation Alerts: Is the success rate declining? Is cost per task increasing? Has latency changed? Set up alerts for these trends, not just for individual failures.

The best dashboards show you both the current state (what's happening right now) and trends (is it getting better or worse?). Agents improve or degrade over time. You need to track that.

The Role of Observability in Production

Observability isn't just about debugging. In production, observability lets you:

1. Detect Problems Early: Before an agent silently generates bad code, your observability should flag degradation. Success rate drops? You know immediately.
2. Route Work Intelligently: If Agent A is better at feature development and Agent B is better at refactoring, route tasks accordingly.
3. Optimize Costs: You can see which agents and tools are expensive and decide whether they're worth it.
4. Build Trust: When you understand why an agent made a decision (through decision tracing), you trust it more. When you don't understand, you trust it less.
5. Improve Models and Workflows: You see what patterns lead to success and failure. This guides which agents to use, what context to provide, how to structure tasks.

How Bitloops Improves Observability

Bitloops' context engine provides observability at the context layer. Instead of observing individual agents operating in isolation, you observe the shared context model. This means:

1. Cross-Agent Visibility: You see what context was used across multiple agents. This gives you a unified picture instead of separate views per agent.
2. Context Lineage: You trace how context evolved—what data was read, when, by which agent, and how subsequent agents used it. This is essential for debugging multi-agent workflows.
3. Decision Correlation: When multiple agents are working on the same problem, you see how their decisions correlate and whether they're using consistent information.

Observability at the context layer gives you insight that you can't get by observing agents independently.

FAQ

Primary Sources

• Standard library for instrumentation and monitoring in distributed systems and applications. OpenTelemetry Documentation
• Practical guide to measuring and improving system observability for production reliability. Observability Engineering
• Anthropic's API documentation covering structured output formats for reliable agent interactions. Anthropic Structured Outputs
• Foundation paper on teaching language models to select and use tools during inference execution. Toolformer Paper
• ReAct framework combining reasoning and acting for enhanced agent task completion accuracy. ReAct Paper
• Standard specification for connecting agents to tools via the Model Context Protocol framework. MCP Specification