agenttrace

agenttrace

エージェントの実行では数十件ものツール呼び出しが発生することがあります。実行後に知りたいことは、どのツールが処理を行ったのか、どの呼び出しが失敗し、その理由は何か、どこに時間がかかったのか、合計で何トークン消費したのか、といったシンプルなことです。agenttrace は、すでにあるトレースからこれらの疑問に答えます。 イベントを渡すだけで、agenttrace が概要を返します。各呼び出しについて、ツール名、開始時刻、実行時間、ok で終了したか error になったか、そして任意でエラーメッセージと入出力トークン数を指定します。記録、プロキシ処理、取得は一切行わず、渡された情報に基づいて計算します。

概要は3つの部分で構成されます。1つ目は、トレース内で最初に登場した順に並ぶ、各ツール固有の統計情報です。呼び出し回数、失敗回数、エラー率、合計・平均・最大実行時間、トークン合計が含まれます。2つ目は、トレース順に並ぶ失敗した呼び出しの一覧です。それぞれに、トレース内での位置、ツール、エラーメッセージが含まれます。失敗した呼び出しにメッセージがない場合は null になります。3つ目は、トレース全体の合計情報です。イベント数、実行されたツールの種類数、エラー数と全体のエラー率、実行時間の合計、最も早い開始時刻から最も遅い終了時刻までの経過時間、入出力トークンの合計が含まれます。

丸め方は2つに固定されています。ツールごとおよび全体のエラー率は小数点以下4桁に丸めます。平均実行時間は Math.round を使って最も近い整数に丸めるため、平均が100.5の場合は101になります。トークン数のフィールドは省略可能です。省略された呼び出しのトークン数は0として扱われます。開始時刻には任意のエポックを使用できます。経過時間の計算には時刻の差だけを使うためです。

入力に不備がある場合、つまりイベントリストが存在しない、空、または配列ではない場合、イベントがオブジェクトではない場合、ツール名が存在しない、空、または文字列ではない場合、開始時刻、実行時間、トークン数が負の値または小数の場合、ステータスが厳密に "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 — 呼び出し元から渡されたエージェントのツール呼び出しトレースを要約します。ツールごとの呼び出し、エラー、実行時間、トークンの統計情報、失敗した呼び出しの一覧、トレース全体の合計情報を返します。

  • 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