エージェントのトークンはどこへ消えるのか：1週間、65,000リクエストの記録

この記事は、Claude Code を実際の仕事に使っている人向けです。内容の大半は、エージェント1体でも10体でも当てはまります。複数のエージェントに関する部分は、そう書いてあります。終わり近くに、私たち自身の環境で何を変えているか、そして私たちが作っている harnsy がどこに関わるかを書きました。その部分は短く、はっきり分けてあります。

数え方

Claude Code がセッションごとに残すトランスクリプトを読みました。1リクエストが1行で、それぞれにトークン数がついています。すべてのリクエストを、そのモデルと、トークンの種類（入力、キャッシュ書き込み、キャッシュ読み取り、出力）ごとの公開されたAPIレートで計算しました。そのうえで、リクエストを3通りに分けました。換算額の項目別、そのステップでのコンテキストの大きさ別、そしてターンを起こしたものの別です。ターンとは、エージェントが1回起こされることで、1つ以上のリクエストからなります。各リクエストは、そのモデルの標準レートで計算しています。Opus 5.5 は $6,147（63,096リクエスト）、Opus 5 は $278（9月23〜24日）、Fable 5.1 は $82、Sonnet 5 は $19、Haiku 4.5 は $1 で、バッチ割引も地域別の倍率もありません。65,487リクエストのうち464件は他のプロバイダーのモデルに向かったもので、合計にはドル額が入っていません。参考までに、同じトランスクリプトの2か月分には143,000リクエストがあり、キャッシュのヒット率は98.8%でした。

Claude Code の使用量の制限は、1つの事実から始まります。ステップのたびに、会話が丸ごと送り直されます

エージェントの1ステップは小さく見えます。ファイルを読む、テストを走らせる、1行書く。けれどステップのたびに、モデルには会話の全体が、最初のメッセージから最後のツールの結果まで、もう一度送られます。モデルは、あなたのようにセッションを覚えているわけではありません。毎回、読み直しているのです。

プロンプトキャッシュが、これをやわらげます。サーバーは会話の冒頭をしばらく保持し、それを読み戻すコストは通常の入力価格の10分の1以下です。サブスクリプションでは、キャッシュは1時間保たれます（サブエージェントは5分）。入力トークンの99%がキャッシュから返されたのは、そのためです。それでも換算額が大きいのも、そのためです。API 価格では1回あたり安い 318,000 トークンの読み取りも、数万回繰り返せば積み上がります。

この週のトークンの換算額は、API 価格で次のとおりです（合計 $6,527）。

目を引く点が2つあります。仕事だと私たちが思っているモデルの出力は、換算額の12%です。会話の読み直しは65%です。しかも、1ステップの平均は318,000トークンのコンテキストを抱えていて、昼までに100回読み直すには大きな量です。

API 価格ではトークン単価がこれほど安いのに、なぜキャッシュ読み取りが最大の項目なのでしょうか。量です。Opus 5.5 では、キャッシュ読み取りは100万トークンあたり $0.20、新しい入力は $4 です。ところがこの週は208億の入力トークンを読み、その99%がキャッシュからでした。ごく小さな単価に、途方もない数を掛ければ、それでも最大の数字になります。

コンテキストの長さがステップのコストを決める：数字で見る Claude Code のコンテキストウィンドウ

ステップごとに、コンテキストが読み直されます。だから会話が長いほど、ステップのコストは増えます。65,487リクエストすべてを、そのステップでのコンテキストの大きさで分けました。

コンテキストが40万〜70万トークンのステップは、10万トークン未満のステップの3.4倍のコストです。40万〜70万の帯だけで $3,042、この週の46.6%にあたり、40万を超えるステップを合わせると全体の55%になります。100万トークンのコンテキストウィンドウには、伸びる余地がたっぷりあります。

セッションも同じように振る舞います。メインのセッション245件のうち、90件が40万トークン以上に達し、その90件が換算額の82%を生みました。そして、コンテキストが縮むことはまれです。この週にエージェントのコンテキストが半分になったのは、コンパクトまたは /clear によるもので、27回だけでした。ほとんどは、そのまま伸び続けました。

教訓は「小さなウィンドウを使え」ではありません。ウィンドウは上限であって、目標ではないのです。大事なのは、誰かが切るまで会話がどれだけ続くかです。話題が変わったら新しいセッションを始める。ウィンドウがいっぱいになってからではなく、タスクが終わったときにコンパクトする。数十万トークンを超えた会話は、ステップごとに重いものとして扱う。実際に重いからです。

エージェントを起こすもの

エージェントのチームでは、ステップの多くはあなたが始めたものではありません。何かがエージェントを起こします。ほかのエージェントからのメッセージ、あなたのプロンプト、起動したサブエージェント。この週のターンを、それを始めたもの別に分けました。

換算額のおよそ4分の3は、別のエージェントが始めたターンにあり、起こされたエージェントは415,000トークンのコンテキストを抱えていました。「了解です」のような、1〜3リクエストの短い返信ターンが5,486回、$1,146で、換算額の18%を占めました。

ここには下限があります。415,000トークンを抱えたエージェントを起こすと、返事が1語でも、Opus 5.5 のAPI 価格で少なくとも $0.08 かかります。1回なら何でもありません。5,000回なら大きな数です。これはマルチエージェントの作業の話で、1つのセッションなら、起こされる回数はずっと少なくなります。

どうすればよいでしょうか。報告することがあるときだけ答えるよう、エージェントに頼みます。大きなコンテキストを持つエージェントへの受領の返事は、コストが丸ごとかかるステップです。更新は、たくさんに分けず、1通のメッセージにまとめて送ります。そして、ちょっとした質問には、もっと軽い置き場所を用意します。コンテキストが平均100,000トークンのサブエージェントなら、415,000トークンを抱えたエージェントを起こさずに、小さな質問を引き受けられます。

アイドル時間、キャッシュ、そして Claude Code の使用量の制限

キャッシュは期限切れになります。この週、エージェントが1時間を超えて待機したのは166回でした。そのたびにキャッシュが切れ、次のステップでは約396,000トークンを書き直す必要があり、合計で $475、換算額の7.3%、1回あたり約 $2.90 でした。

1時間のキャッシュは、API 価格で上乗せされるコストに見合っています。書き込みにかかったのは、5分のキャッシュより約 $454 多い額です（測定したトークンに、価格の差を掛けたもの）。キャッシュが5分しか保たれなかったとして、5分から1時間の待機1,498回のあとにコンテキストを書き直すと、約 $2,960、およそ6.5倍かかったと見積もっています。1時間の書き込みが5分の書き込みの1.6倍、制限を使うというのは、私たちの仮定です。API 価格ではそうなります。実用的なルールは短いものです。長く待機する前に、仕事を引き継ぐか /compact を実行して、待っているのが400,000トークンの会話ではなく、短い会話になるようにします。

待機が悪いと言いたいわけではありません。エージェントは、ビルドやレビューやあなたを待ちます。コストが生まれるのは、大きなコンテキストを抱えたまま待ち、そして再開するときです。短いコンテキストなら、キャッシュが切れたあとでも、書き直しは軽く済みます。

この換算額は、週間の制限にどう対応するのでしょうか。Anthropic は式を公開していないので、これはあくまで推定です。API 価格で約 $30 分の作業で、週間の制限が1%動くのを見ました（2つのアカウント、1つは Max アカウント、もう1つはプランを記録していません。1日分）。同じログインの別の使い方でもパーセントは動くので、1%あたりの本当の額は、少なくとも約 $30 です。

ツールの出力とスクリーンショットは、コンテキストに残る

ツールは、動かすのは軽く、抱えておくのは重いものです。ツールの結果55,277件、合計で約1億700万文字を数えました。結果の12.5%は5,000文字を超え、全体の量の61%を占めます。エージェントは画像も2,349枚取り込んでいて、そのほとんどがスクリーンショットです。

その出力を書くコストは、ほぼゼロです。コストが生じるのは、そのあとです。出力は会話に残り、続くステップのたびに、そのときのコンテキストの大きさに応じたコストで読み直されます。いくつかの習慣で、これを避けられます。

• 長いコマンドの出力は tail か head に通すか、要約を1行だけ頼む。
• 全体の diff の前に、git show --stat を実行する。
• ファイルは、全部ではなく offset と limit を付けて読む。
• 大きなログはサブエージェントに渡し、要約を持ち帰らせる。
• スクリーンショットは、テキストで足りないときだけ、小さく撮る。

スクリーンショットは、別に触れておく価値があります。自分のインターフェースの作業を確かめるエージェントは、たくさん撮って、すべて残すことがあります。そしてそれぞれが、テキストと同じように会話に残ります。確認に必要なのが1枚なら、1枚だけ、問いに答えられる大きさで撮ってください。

モデルは、見かけほど効かない

まず軽いモデルに手が伸びるのは自然なことです。私たちの数字では、モデルは効きますが、コンテキストの長さほどではありません。

8月14日から9月24日（上の週ではなく、約6週間）に Opus 5 で動いた64,999リクエストを取り、同じトークンを Opus 5.5 の公開レートで計算し直しました。$12,321 が $6,166 になりました。キャッシュ読み取りは Opus 5.5 で60%安く、ほかの項目はすべて20%安くなります。変わったのは価格表だけで、トークンは変わっていません。Anthropic は、Opus 5.5 は medium の effort で、複数ステップのコードに約半分のトークンしか使わないと言っているので、実際の節約はもっと大きいかもしれません。

次に、同じステップでの Sonnet 5.5 と Opus 5.5 の比較です。入力と出力の価格は半分です（100万トークンあたり $2 と $10、Opus は $4 と $20）。それでも、合計の減少は平均で約16%、リードのロールでは約10%にとどまります。理由は、キャッシュ読み取りが私たちの週の換算額の65%（ロール別では40〜81%）を占め、どちらのモデルも同じ100万トークンあたり $0.20 で計算しているからです。16%は、それ以前の期間の約3,000リクエスト（すべて Opus 5.5）から、ステップ数が同じと仮定して出したもので、測定ではなく、過去のステップに対する計算です。ロールごとにモデルを変える試験は9月29日に始まり、一部のロールは Sonnet 5.5 で動いていますが、まだ結果はありません。16%より大きな意味を持つ事実が、1つあるかもしれません。Opus と Sonnet は制限が別々で（Anthropic によれば、それぞれそのモデルファミリーへのリクエストにだけ適用され、大きさは公開されていません）、Sonnet のロールは Opus の制限を使いません。

では、モデルの選び方はどうなるのでしょうか。軽いモデルは役に立ちますが、その節約はキャッシュ読み取りの項目に頭を押さえられていて、この項目はほとんど動きません。価格表は変わります。より確かな習慣は、価格やモデルを変えるたびに、価格表を信じるのではなく、自分のトランスクリプトを見ることです。

私たちの環境で変えていること（仮説）

コンテキストの長さが掛け算の倍率だとすれば、打つ手は、それを短く保つことです。私たち自身の変更は、ロールを70万トークン（ウィンドウの70%）まで走らせず、30万〜40万トークン（100万ウィンドウの30〜40%）で新しいエージェントに引き継ぐことです。

これは仮説であって、結果ではありません。私たちの週でモデル化すると、引き継ぎによって換算額の約30〜35%が減ります（30万で35%、40万で30%）。70万では約13%です。このモデルは、その週のすべてのメインセッションで引き継ぎを数え、後任が6万から始まると仮定しています。実際の節約は、モデルの半分程度と見ています。代償もあります。引き継ぎが増えるのです。70万で週に約45回のところ、30万では約190回になるので、引き継ぎのメモが良くなければなりません。実際に検証してはいません。

もっと早く引き継がないのはなぜでしょうか。引き継ぎにもコストがかかります。新しいエージェントは書かれたメモから始め、必要なことを読み直さなければなりません。判断が抜け落ちる引き継ぎは、節約したトークンより高くつきます。この手を慎重に扱う理由であり、成果と呼ぶ前に測る理由です。

自分で数える

あなた自身の数字も確かめられます。Claude Code は、すべてのリクエストを ~/.claude/projects/*/*.jsonl に書き込みます。アシスタントの各メッセージには message.usage オブジェクトがあり、input_tokens、cache_creation_input_tokens、cache_read_input_tokens、output_tokens が入っています。落とし穴が2つあります。1つのリクエストが、トランスクリプトの複数行に現れることがあります（ストリーミング）。メッセージ ID で重複を除かないと、合計が膨らみます。また cache_creation_input_tokens には5分と1時間の書き込みが混ざっていて、その内訳は cache_creation.ephemeral_5m_input_tokens と ephemeral_1h_input_tokens にあります。サブエージェントは */subagents/*.jsonl に書きます。トークンをセッションごとに足し、種類ごとに公開価格を掛けて、セッションを最大のコンテキストの順に並べてください。長いものが上に来ます。

ここから持ち帰ること

この記事から5行だけ持ち帰るなら、次のとおりです。

• まず、コンテキストの長さを見る。それがすべてのステップのコストに掛かります。
• 待つ前に切る。長く待つ前に、引き継ぐか /compact を実行する。
• ツールの出力は短く。大きなログはサブエージェントに送る。
• エージェント間のメッセージは、少なく、短く。
• モデルは、価格表ではなく、自分のトランスクリプトで比べる。

harnsy が関わるところ

harnsy は、Claude Code、Codex、OpenCode のエージェントを、ロールを持つ1つのチームにつなぐローカルのアプリです。トークンを自動で減らすわけではありませんが、上の数字から導かれる機能がいくつかあります。

• エージェントのコンテキストが高くなると、リードに知らせます。しきい値はロールごとに設定でき、v0.7.0 の既定はウィンドウの40%で、ダッシュボードは30万〜40万トークンを勧めます。
• 引き継ぎは、書かれたメモで行います。エージェントがメモを書き、リードが新しいエージェントを席に就かせ、新しいエージェントが確認を返します。仕事はコンテキストウィンドウより長く続きます。無限の記憶ではありません。
• v0.7.0 から、ロールごとに、ハーネス、モデル、推論の effort を持てます。
• エージェントが待機していると、リードに知らせます。

インストールの方法と、あなたのマシンの何が変わるかは、インストールのページにあります。