agenttrace

agenttrace

An agent run can fire dozens of tool calls, and afterwards the interesting questions are simple ones: which tools did the work, which calls failed and why, where did the time go, and how many tokens did it all cost. agenttrace answers those questions from a trace you already have. You supply the events — for each call, the tool name, when it started, how long it ran, whether it ended ok or in error, and optionally the error message and the input and output token counts — and agenttrace hands back the summary. It records nothing, proxies nothing, and fetches nothing; it computes over the facts you pass in.

The summary has three parts. First, one statistics entry per distinct tool, in the order the tools first appear in your trace: how many calls it took, how many of them failed, its error rate, its total, average, and maximum duration, and its token totals. Second, the list of failed calls in trace order, each with its position in the trace, its tool, and its error message — null when a failed call carried no message. Third, the trace totals: the event count, how many distinct tools ran, the total error count and overall error rate, the summed duration, the wall-clock span from the earliest start to the latest finish, and the overall token totals.

Two roundings are pinned. Error rates — per tool and overall — are rounded to four decimal places, and the average duration is rounded to the nearest integer with Math.round, so a mean of 100.5 reports as 101. Token fields are optional; a call that omits them counts as zero tokens. The start times can use any epoch you like, because only their differences feed the wall-clock span.

Malformed input — a missing, empty, or non-array event list, an event that is not an object, a missing, empty, or non-string tool name, a negative or fractional start time, duration, or token count, a status that is not exactly "ok" or "error", or a non-string error — is a validation error naming the offending path, such as events[2].status must be "ok" or "error", with no partial result. Unknown extra fields are ignored, including inside events.

CLI

npx @reneturcios/agenttrace summarize --input args.json
npx @reneturcios/agenttrace --version

args.json contains the full arguments object:

{
  "events": [
    {
      "tool": "search",
      "started_at_ms": 1000,
      "duration_ms": 120,
      "status": "ok",
      "input_tokens": 300,
      "output_tokens": 80
    },
    {
      "tool": "fetch",
      "started_at_ms": 1120,
      "duration_ms": 450,
      "status": "error",
      "error": "connection timed out",
      "input_tokens": 120,
      "output_tokens": 0
    },
    {
      "tool": "search",
      "started_at_ms": 1600,
      "duration_ms": 90,
      "status": "ok",
      "input_tokens": 280,
      "output_tokens": 64
    }
  ]
}

The summary is printed as JSON:

{
  "tools": [
    {
      "tool": "search",
      "calls": 2,
      "errors": 0,
      "error_rate": 0,
      "total_duration_ms": 210,
      "avg_duration_ms": 105,
      "max_duration_ms": 120,
      "input_tokens": 580,
      "output_tokens": 144
    },
    {
      "tool": "fetch",
      "calls": 1,
      "errors": 1,
      "error_rate": 1,
      "total_duration_ms": 450,
      "avg_duration_ms": 450,
      "max_duration_ms": 450,
      "input_tokens": 120,
      "output_tokens": 0
    }
  ],
  "errors": [
    {
      "index": 1,
      "tool": "fetch",
      "error": "connection timed out"
    }
  ],
  "totals": {
    "total_events": 3,
    "distinct_tools": 2,
    "total_errors": 1,
    "overall_error_rate": 0.3333,
    "total_duration_ms": 660,
    "wall_clock_ms": 690,
    "total_input_tokens": 700,
    "total_output_tokens": 144
  }
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/agenttrace mcp

MCP client config:

{
  "mcpServers": {
    "agenttrace": {
      "command": "npx",
      "args": ["-y", "@reneturcios/agenttrace", "mcp"]
    }
  }
}

Tools

• summarize_trace — Summarize a caller-supplied agent tool-call trace: per-tool call, error, duration, and token statistics, the list of failed calls, and trace totals.

  • events (array, required, at least 1 item) — the tool-call events to summarize, in trace order; each item:
    • tool (string, required, non-empty) — name of the tool that was called
    • started_at_ms (integer, required, at least 0) — call start time in milliseconds (any epoch the caller chooses; only differences are used)
    • duration_ms (integer, required, at least 0) — call duration in milliseconds
    • status (string, required) — call outcome: exactly "ok" or "error"
    • error (string, optional) — error message for a failed call
    • input_tokens (integer, optional, at least 0) — input tokens consumed by the call; absent means 0
    • output_tokens (integer, optional, at least 0) — output tokens produced by the call; absent means 0

  Returns {tools, errors, totals}, where tools holds one {tool, calls, errors, error_rate, total_duration_ms, avg_duration_ms, max_duration_ms, input_tokens, output_tokens} per distinct tool in first-appearance order, errors holds one {index, tool, error} per failed call in input order, and totals is {total_events, distinct_tools, total_errors, overall_error_rate, total_duration_ms, wall_clock_ms, total_input_tokens, total_output_tokens}.

Docker

docker run -i ghcr.io/cloudcorprecords/agenttrace
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/agenttrace summarize --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios