# エージェントの「出力」コストを正しく測る（usage 複製の二重計上と、thinking が7割という現実） 会話ログを JSONL で保存する AI コーディングエージェント（Claude Code など）で、 **出力トークンのコストを集計するときに必ず踏む2つの罠**と、そこから導かれる 「品質を落とさない唯一の削減レバー」をまとめた指示書。 実測して分かったこと（ある1台・7日分）: - 自作のコストダッシュボードが出力トークンを **2.27倍に水増し**していた（19,770k → 実際は 8,834k） - そのため委譲率が **21.7% と表示されていたが実際は 35.9%** - 出力の **70% が extended thinking**（ログに本文が保存されないので按分では見えない） - 独立したツール呼び出しを2個以上まとめられていたのは **6.1% だけ** --- ## 0. 結論から 1. **`usage` はレコードごとに複製される。`message.id` で束ねないと出力トークンが2倍以上に膨らむ。** 2. **thinking は本文が保存されない。按分ではなく「実出力 − 可視ブロック推定」の残差で測る。** 3. **thinking が7割なら、削るべきは「思考の深さ」ではなく「思考の回数」＝レスポンス数。** --- ## 1. 罠その1: `usage` がレコードごとに複製される 多くのエージェントは1回のAPIレスポンスを **content ブロックごとに複数レコード（行）へ分割**して書く。 このとき **`message.usage` を各レコードに丸ごと複製する**実装がある。 ```bash # まず実物を確認する。message.id ごとの行数と、その中の output_tokens を並べる cat <ログ.jsonl> | jq -c 'select(.message.usage) | {id:.message.id, out:.message.usage.output_tokens}' \ | sort | uniq -c | sort -rn | head ``` 実測の分布（7日・1モデル）: | 1つの `message.id` が持つレコード数 | 件数 | |---|---:| | 1 | 3,623 | | 2 | 4,315 | | 3 | 2,393 | | 4以上 | 211 | そして **複数レコードを持つ 6,980件のうち 6,906件(99%)で `output_tokens` が全レコード同一**だった。 つまり `for (row of records) total += row.usage.output_tokens` と書くと **2.27倍**になる。 ### 検証コード（これを最初に走らせる） ```js // 同一 message.id 内で output_tokens が同じか違うかを数える const g = new Map(); for (const row of records) { const id = row.message?.id; if (!id || !row.message?.usage) continue; if (!g.has(id)) g.set(id, []); g.get(id).push(Number(row.message.usage.output_tokens) || 0); } let same = 0, distinct = 0, sumAll = 0, sumOnce = 0; for (const outs of g.values()) { sumAll += outs.reduce((a, b) => a + b, 0); sumOnce += Math.max(...outs); if (outs.length > 1) (new Set(outs).size === 1 ? same++ : distinct++); } console.log({ same, distinct, sumAll, sumOnce, inflation: sumAll / sumOnce }); ``` `inflation` が 1.0 より大きければ、あなたの集計は水増しされている。 ### 正しい集計ルール - **出力トークン / モデル別内訳 / キャッシュ統計は `message.id` ごとに1回だけ数える。** 同一 id 内で値が食い違う場合（実測1%）は**最大値**を採る。 - **`uuid` は重複除去に使えない**（レコードごとに一意なので全件通ってしまう）。 - **ブロックから導く値（編集行数など）は合算のままでよい。** ブロックは複製ではなく *分割*されているため、行数は重複しない。ここを一緒に dedupe すると今度は過少になる。 ### さらに踏みやすい派生の罠 **ツール呼び出しの個数もレコード単位で数えてはいけない。** 分割されているので どのレコードも `tool_use` を1個しか持たず、「並列呼び出しは常に0件」と誤判定する。 実際にこれを踏んで「バッチ率0%」という誤った結論を出した。正しくは **id で束ねてから数える**と 6.1% だった。 --- ## 2. 罠その2: thinking は本文が保存されない 拡張思考（extended thinking）を使うエージェントでは、`thinking` ブロックがログに **署名だけ、または空文字で保存される**ことがある。すると: - ブロックの文字数で出力トークンを按分すると、**thinking の取り分がほぼ0になる** - 逆に「thinking しか無いレコード」に出会うと、そのレスポンスの出力を**丸ごと thinking に計上**してしまう どちらも実態と合わない。実測では、可視ブロック（`text` と `tool_use` の input JSON）から 推定できるトークンは実出力の **28%** しかなく、**残り72%が本文の無い思考**だった。 ### 正しい帰属方法（残差方式） ```js // message.id 単位で全ブロックを結合したあとに計算する const visibleEst = toolUseBlocks.reduce((s, b) => s + JSON.stringify(b.input ?? '').length / 3.2, 0) + textBlocks.reduce((s, b) => s + String(b.text ?? '').length / 3.6, 0); const thinking = Math.max(0, out - visibleEst); // ← 保存されない思考の実測推定 const scale = visibleEst > out ? out / visibleEst : 1; // 推定が実出力を超えたら比例縮小 // text / tool_use にはそれぞれの推定 × scale を割り当てる ``` これで初めて「thinking が出力の何%か」が言える。実測は **70%**（従来の按分表示は34%だった）。 --- ## 3. ここから導かれる削減レバー thinking が7割を占めるなら、コストは概ね **「1回の思考の深さ」×「思考の回数」** で決まる。そして重要なのは: > **thinking は1レスポンスにつき1パス課金される。** だから選択肢は2つある。 | 手段 | コスト | 品質 | |---|---|---| | 思考の**深さ**を削る（reasoning effort を下げる） | 下がる | **下がる** | | 思考の**回数**を削る（レスポンス数を減らす） | 下がる | **変わらない**（往復が減る分むしろ有利） | **回数を削る方を選ぶ。** 具体的には: 1. **依存関係のないツール呼び出しを1レスポンスにまとめる。** 「まず A を見て、次に B を見て」と刻むと、刻んだ回数だけ思考パスが課金される。 実測でまとめられていたのは **6.1%** だけだった＝ここに大きな余地がある。 2. **まとまった探索は専任のサブエージェントに委譲し、親は1レスポンスで結果を受け取る。** 「結果は200字以内・コード本体は含めない」のように**返す量を指定する**のが要点 （指定しないと親の context が太って [別の指示書のテーマである入力コスト] が悪化する）。 3. **実装本体は定額枠のコード生成 CLI へ出す。** 監督役は設計・分解・指示・レビュー・検証に絞る。 ### 計測して続ける 削減を主張する前に、次の2つを定点観測する。 ``` responses : message.id のユニーク数 batchRate : ツール呼び出しが2個以上のレスポンス ÷ responses readOnlyStreaks : read-only ツール呼び出しが連続した鎖の長さの分布 ``` `batchRate` が上がり `responses` が下がっていれば、深さを削らずにコストが下がっている。 ### 自動で気づかせる（任意） read-only の調査コマンドが**N回連続**したら警告を出すフックを入れると、刻み癖が可視化される。 実測の鎖の分布は「2回が133本 / 3〜4回が47本 / 5回以上が17本」だったので、 **4連続で発火**させると週17回程度＝鬱陶しくない頻度になった。 フックを書くときの注意: - **ブロック（deny）ではなく警告に留める。** 調査自体は正当な作業なので止めてはいけない。 - 一度警告したらカウンタを0に戻す（毎回出ると読まれなくなる）。 - 状態ファイルはセッションIDをキーにし、**古いキーを読み込み時に掃除**する。 - 例外時は必ず正常終了させる（フックの失敗でユーザー操作を止めない）。 --- ## 4. 指標を「達成不能な目標」にしない このやり方で測り直すと、**トークン比の委譲率には構造的な上限がある**ことが分かる。 可視の成果物が出力の3割弱しかないなら、実装を100%外部へ出しても トークン比は4割程度で止まる。ここに「50%」という目標を置くと、 達成する唯一の道が **「思考を削る」＝品質を落とす** ことになってしまう。 **指標は「測りたい行動」と一致させる。** 「実装を自分で手打ちしていないか」を見たいなら、トークンではなく **追加・削除された行数の比**（外部CLIが書いた行 ÷ 全実装行）で測る方が素直で、 実測でも 64% と現実的な値になった。トークン比は**併記して可視化するだけ**にし、 強制判定には使わない。 --- ## チェックリスト - [ ] `message.id` で束ねてから出力トークンを数えているか（`inflation` を測ったか） - [ ] `uuid` を重複除去に使っていないか - [ ] 行数などブロック由来の値を誤って dedupe していないか - [ ] ツール呼び出しの個数を id で束ねてから数えているか - [ ] thinking を按分ではなく残差で測っているか - [ ] 削減策が「深さ」ではなく「回数」を狙っているか - [ ] 指標の理論上限を確認し、達成不能な目標を掲げていないか ---