Agent Debugging

I kept asking the same
question after every
agent failure.

Not "what did the agent do?"
The logs already show that.

But "why did it do that?" and "which step broke it?"
Those took hours to untangle manually.

So I built an MCP tool that answers both in seconds.

How it works

Pass in any agent trace JSON.
Get root causes back.

No SDK changes. No instrumentation. Works with LangChain, OpenAI Agents SDK, AutoGen, Claude SDK, Microsoft Agent Framework, or anything that produces a step log.

judge_trace

Root cause analysis, 4-dimension score, grade A to F, one concrete fix.

trace_breakdown

Scores every step individually. Flags REDUNDANT_TOOL_CALL, REASONING_GAP, GOAL_DRIFT, PREMATURE_STOP.

efficiency_score

Free, no API key

Token, latency, and redundancy scoring. Deterministic. Runs instantly. Safe for CI/CD.

When the agent gets it right

Customer support agent.
Refund processed correctly.

Most teams assume their agents work. This is how you confirm it.

Trace: 5 steps

lookup_order process_refund Correct output

A

0.96 / 1.0

Production-ready

Goal completion	1.00
Tool usage	0.95
Output quality	0.95
Reasoning clarity	0.95

Root causes: none | Redundant calls: 0 | Failed calls: 0

The failure that looks like success in the logs

Tool returned an error.
Agent reported success.

P1 incident. Payment service down. The ticket was never created. The agent said it was.

Step 4: create_incident_ticket

        error: "TicketSystemError: Authentication token expired. Ticket was NOT created."
      

Agent response at step 7: "Incident ticket created and on-call engineer has been notified."

judge_trace result

F 0.20 / 1.0 Broken

Root cause: The agent received an explicit tool error at step 4, skipped error handling entirely, paged the engineer with a fabricated incident ID, then reported success to the user.

Fix: Mandatory error check after every tool call. On failure, halt and report to the user. Never fabricate a success state.

Waste you can only see in the trace

Data pipeline agent queried
the same database 3 times.

Identical inputs. Identical outputs. Then sent an email with half the data missing.

Redundant DB calls

2

of 3 total identical

Wasted latency

13.6s

on duplicate queries

Efficiency score

0.36

out of 1.0

judge_trace result

D 0.60 / 1.0 Needs optimisation

Root causes: Steps 3, 4, and 5 are identical query_sales_db calls. Email body sent to leadership omitted top products entirely.

Fix: Add tool-call deduplication before dispatch. Implement a report formatting step that uses all retrieved data before sending.

Where it fits in your stack

Your observability stack tracks
what happened. This explains why.

LangSmith, Arize Phoenix, W&B Weave give you history across many runs.

This answers a narrower question: why did this specific trace fail, and what exactly needs to change?

Works in

Claude Desktop
Cursor
VS Code (Copilot MCP)
Any stdio MCP client

Model support

Claude Opus 4.6, GPT-5.4, GPT-4o
GPT-4o mini, Claude Haiku, Sonnet
Any LiteLLM-supported model

Open Source / MIT

agent-trace-
intelligence

Find the failure. Pinpoint the step. Fix the root cause.

Install

pip install agent-trace-intelligence

Repo

github.com/harinarayn/agent-trace-intelligence

CI/CD: run efficiency_score on every agent invocation for free. Use judge_trace on failures and regressions. Under $0.01 per trace with gpt-4o-mini.

Evaluated using Claude Opus 4.6 via Microsoft Foundry. Configure your own model via environment variables: OpenAI, Azure, Anthropic, or any LiteLLM-supported provider.

Adapters included for LangChain, OpenAI Agents SDK, AutoGen, and Microsoft Agent Framework GA 1.0.

PRs and feedback welcome.

I kept asking the samequestion after every agent failure.

Pass in any agent trace JSON.Get root causes back.

Customer support agent.Refund processed correctly.

Tool returned an error.Agent reported success.

Data pipeline agent queriedthe same database 3 times.

Your observability stack trackswhat happened. This explains why.