agenttrace

agenttrace

一次 Agent 运行可能会触发数十次工具调用。运行结束后，最值得了解的问题其实很简单：哪些工具完成了工作，哪些调用失败了以及原因是什么，时间花在哪里，总共消耗了多少令牌。agenttrace 根据你已有的跟踪记录回答这些问题。你提供事件信息——每次调用的工具名称、开始时间、运行时长、结束状态是 ok 还是 error，以及可选的错误消息和输入、输出令牌数——agenttrace 就会返回摘要。它不会记录、代理或获取任何内容；它只根据你传入的信息进行计算。

摘要分为三部分。第一部分是每个不同工具对应的一条统计记录，按工具首次出现在跟踪记录中的顺序排列：调用次数、失败次数、错误率、总时长、平均时长、最长时长以及令牌总数。第二部分是按跟踪记录顺序排列的失败调用列表，其中包含每次调用在跟踪记录中的位置、所用工具和错误消息；如果失败调用没有消息，则为 null。第三部分是跟踪记录的总计：事件数、运行过的不同工具数、错误总数和总体错误率、累计时长、从最早开始到最晚结束的墙钟时间跨度，以及令牌总数。

错误率（按工具和总体）固定保留四位小数；平均时长使用 Math.round 四舍五入为最接近的整数，因此平均值为 100.5 时会报告为 101。令牌字段为可选；未提供令牌数的调用按零令牌计算。开始时间可以使用任意纪元，因为只有它们之间的差值会用于计算墙钟时间跨度。

格式错误的输入——事件列表缺失、为空或不是数组；事件不是对象；工具名称缺失、为空或不是字符串；开始时间、时长或令牌数为负数或小数；状态不完全等于 "ok" 或 "error"；或错误信息不是字符串——会导致验证错误，并指出出错路径，例如 events[2].status must be "ok" or "error"，且不会返回部分结果。未知的额外字段会被忽略，包括事件中的额外字段。

CLI

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

args.json 包含完整的参数对象：

{
  "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
    }
  ]
}

摘要以 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
  }
}

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/agenttrace mcp

MCP 客户端配置：

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

工具

• summarize_trace — 汇总调用方提供的 Agent 工具调用跟踪记录：按工具统计调用、错误、时长和令牌，列出失败调用，并给出跟踪记录总计。

  • events（数组，必填，至少 1 项）— 要汇总的工具调用事件，按跟踪记录顺序排列；每项包含：
    • tool（字符串，必填，非空）— 被调用工具的名称
    • started_at_ms（整数，必填，至少为 0）— 调用开始时间，单位为毫秒（纪元由调用方任意选择；只使用时间差）
    • duration_ms（整数，必填，至少为 0）— 调用时长，单位为毫秒
    • status（字符串，必填）— 调用结果：必须为 "ok" 或 "error"
    • error（字符串，可选）— 失败调用的错误消息
    • input_tokens（整数，可选，至少为 0）— 调用消耗的输入令牌数；未提供时为 0
    • output_tokens（整数，可选，至少为 0）— 调用生成的输出令牌数；未提供时为 0

  返回 {tools, errors, totals}，其中 tools 按首次出现顺序为每个不同工具包含一条 {tool, calls, errors, error_rate, total_duration_ms, avg_duration_ms, max_duration_ms, input_tokens, output_tokens} 记录；errors 按输入顺序为每次失败调用包含一条 {index, tool, error} 记录；totals 为 {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

开发

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