Agent Analyzer
Analyze a Run

Documentation

AI Agent Debugging: Find Cost, Latency and Tool Call Problems

Agent Analyzer runs six deterministic detectors against your trace to surface the most likely inefficiencies. This page explains what each detector looks for, when it triggers, and what to do about it.

The debugging workflow

When an agent run is unexpectedly slow, expensive, or produces incorrect results, traces are your primary diagnostic tool. A practical workflow:

  1. 1

    Capture a trace

    Instrument your agent to record each step with startTime, endTime, status, and optionally inputTokens, outputTokens, cost, and model.

  2. 2

    Validate the trace

    Paste it into Agent Analyzer. The parser will report the exact field and step index if anything is malformed.

  3. 3

    Read the executive summary

    Check total cost, total tokens, total duration, and the issue count at a glance.

  4. 4

    Find the highest-priority issue

    The "Fix This First" section identifies the single most impactful detected issue and its recommendation.

  5. 5

    Inspect the relevant step

    Use the step breakdown table to find the specific step flagged by the issue — check its cost, token count, and duration.

  6. 6

    Apply the recommendation

    Each detected issue includes a concrete recommendation. Adjust your agent's prompt, context strategy, caching, or tool logic accordingly.

  7. 7

    Trace again

    Re-run the agent and compare the new trace to confirm the issue is resolved.

Important limitation

Agent Analyzer detects structural and performance issues in a trace. It cannot determine whether the agent's outputs are semantically correct, whether the model produced hallucinations, or whether the reasoning strategy was optimal. These require human review of the actual model outputs.

All six issue detectors

Expensive step

HIGH

Triggers when

A single step accounts for ≥ 30% of total run cost

Recommendation

Inspect prompt size and output length. Consider a cheaper model or smaller context for this step.

Rapid context growth

HIGH / MEDIUM

Triggers when

inputTokens of the last LLM step ÷ first LLM step ≥ 3×. HIGH if ratio ≥ 5×.

Recommendation

Summarize context between LLM calls or use a sliding-window strategy.

Excessive LLM calls

HIGH / MEDIUM

Triggers when

Run contains ≥ 6 LLM steps. HIGH if ≥ 8.

Recommendation

Consider combining intermediate LLM calls or replacing some with deterministic logic.

Repeated tool calls

MEDIUM

Triggers when

The same tool name appears ≥ 2 times in tool steps

Recommendation

Review whether results from this tool can be cached for the duration of the run.

Retry detected

LOW

Triggers when

A step with status "error" is followed by another step with the same name and status "success"

Recommendation

Add robust error handling and circuit-breaker logic. Log the error response to diagnose root cause.

Slow step

LOW

Triggers when

Step duration > (mean × 2.5) AND > 1000ms

Recommendation

Profile whether latency is from the LLM provider, tool latency, or network overhead.

Issue severity

Issues are classified into three severity levels:

HIGH

Likely causing significant cost or performance problems. Address these first.

MEDIUM

Worth investigating. May be causing inefficiency at scale or in repeated runs.

LOW

Informational. Retries and slow steps that may or may not need action.

Detector execution order

Issues are collected in this order — the same order they appear in the results:

// From analyzer.ts — analyze()
const issues = [
  ...detectExpensiveSteps(steps, totalCost),   // HIGH
  ...detectContextGrowth(steps),               // HIGH / MEDIUM
  ...detectExcessiveLLMCalls(steps),           // HIGH / MEDIUM
  ...detectRepeatedToolCalls(steps),           // MEDIUM
  ...detectRetries(steps),                     // LOW
  ...detectSlowSteps(steps),                   // LOW
]

All analysis runs deterministically in your browser. No trace data is sent to a server.

Related articles

AI Agent Traces

Trace format, required fields, step types

AI Agent Cost Analysis

How cost is calculated and how the expensive step detector works

AI Agent Token Usage

Input/output tokens and context growth detection

AI Agent Latency

Step-level latency and the slow step detector

Debug your agent trace

Paste a trace and see all six detectors run instantly on your own data.

Analyze a trace →