molecule-core/docs/blog/2026-04-23-tool-trace-observability/index.md

title	date	slug	description	og_title	og_description	tags	keywords	canonical	og_image
AI Agent Observability Without the Overhead	2026-04-23	ai-agent-observability-without-overhead	Tool Trace gives every A2A response a structured record of every tool call — inputs, output previews, run_id-paired parallel traces. No sampling, no sidecar, no guesswork.	AI Agent Observability Without the Overhead	See every tool your agent called — inputs, outputs, timing — in every A2A response. Parallel traces handled correctly. No sampling overhead.	observability tool-trace debugging devops platform-engineering a2a claude	AI agent observability tool trace debugging Claude agent debugging agent audit trail parallel tool call trace run_id pairing AI agent monitoring DevOps agent observability	https://docs.molecule.ai/blog/ai-agent-observability-without-overhead

AI Agent Observability Without the Overhead

Debugging a running agent in production is still, for most platforms, an exercise in inference. You get the final output. You don't get the tool calls that produced it — the Write that created the file, the Bash that ran the build, the Grep that found the bug. When something breaks, you're working backward from the symptom instead of forward from the cause.

Tool Trace changes that. Every A2A response from Molecule AI now includes a tool_trace array in Message.metadata — a structured, chronological record of every tool the agent invoked, the inputs passed to it, and a preview of the output. No sampling. No sidecar collector. No guesswork.

What Tool Trace Captures

Each trace entry contains:

• tool — the tool name (e.g. Write, Bash, Grep)
• input — the exact parameters passed to the tool call
• output_preview — the first ~200 characters of the result, keeping traces readable at scale
• run_id — groups start/end events so concurrent calls are traced independently

Entries are written to activity_logs.tool_trace as JSONB, making them queryable in your existing log infrastructure.

{
  "metadata": {
    "tool_trace": [
      {
        "tool": "Bash",
        "input": {
          "command": "go build ./... && go test ./...",
          "description": "Build and test full Go project"
        },
        "output_preview": "ok      auth    0.314s\nok      config  0.201s\nok      server  0.487s\n--- PASS: TestIntegration (12.3s)"
      },
      {
        "tool": "Write",
        "input": {
          "file_path": "/workspace/coverage/report.json",
          "content": "{\"total\": 94.2, \"files\": {...}}"
        },
        "output_preview": "Wrote 2.1 KB to /workspace/coverage/report.json"
      },
      {
        "tool": "Read",
        "input": {
          "file_path": "/workspace/coverage/report.json"
        },
        "output_preview": "Read 2.1 KB from /workspace/coverage/report.json"
      }
    ],
    "run_id": "01HXKM3T8PRQN4ZW7XYVD2EJ5A"
  }
}

The trace is capped at 200 entries per response. For most agent turns, that's more than enough. For long-running tasks that generate hundreds of tool calls, the cap ensures payload size stays predictable.

Parallel Calls: Traced Correctly

The hardest part of agent observability isn't capturing one tool call — it's capturing several that happened at the same time without losing track of which did what.

Tool Trace handles parallel calls via run_id pairing. When the agent fires two or more tool calls concurrently in a single turn, each entry carries the same run_id. Start and end events are matched by that identifier. The result is an independent, unambiguous trace for each concurrent call rather than a merged log line that obscures which tool returned what.

This matters when you're debugging an agent that called Bash and Write simultaneously and one of them failed silently. With run_id-paired traces, you can isolate exactly which call failed and what it received as input.

Built In, Not Bolt-On

Most observability solutions for AI agents require instrumentation — a tracing SDK, a sidecar collector, a log aggregation pipeline. Tool Trace ships in the A2A response itself. If you're already receiving A2A responses from your agent, you already have the trace. No new infrastructure, no sampling configuration, no agent restart.

For platform engineering teams that need to monitor agent behavior across a fleet — which tools are being called, which inputs are being passed, which outputs are being produced — Tool Trace provides the raw material without the operational overhead.

Enterprise-Grade Auditability

Combined with the org-scoped API key audit trail from Phase 30, Tool Trace closes the last gap in agent observability: you can now trace a production incident from the org API key that authorized the call, through the workspace and agent that executed it, to every tool that ran and what it returned.

Tool Trace is available on all Molecule AI plans. It is enabled by default — check Message.metadata.tool_trace in your A2A responses.

---

Get Started

• Inspect Message.metadata.tool_trace in any A2A response
• Query activity_logs.tool_trace JSONB for historical traces
• Combine with org API key attribution for complete fleet observability
• Read the A2A protocol documentation
• Govern agent behavior with Platform Instructions — system-prompt level policy

---

Molecule AI is open source. Tool Trace shipped in Phase 34 (2026-04-23).