サブエージェントで、トークンが一瞬で溶ける

「ちょっと調べておいて」が、高くつく

エージェントに調べ物を頼んだら、数分で上限がごっそり減っていた——という経験があるかもしれません。管理人にもあります。

調べ物を頼んだ直後にこうなったなら、犯人はサブエージェントかもしれません。 しかもやっかいなのは、自分で呼んだ覚えがなくても立ち上がることです。「このプロジェクトの構成を調べて」と頼んだだけで、エージェントが自分の判断で別働隊を何本も走らせます。

知らないと事故ります。 ここだけ押さえておけば避けられるので、まとめておきます。

サブエージェントは、別働隊

サブエージェントは、本体とは別に立ち上がる、もう一人のエージェントです。調べ物や下読みを任せて、結果だけ受け取る、という使い方をします。

肝心なのはここです。Anthropic公式のドキュメントにこう書かれています。

Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.

（サブエージェントはそれぞれ、独自のコンテキストウィンドウ、独自のシステムプロンプト、限定された道具、独立した権限のもとで動く）

「独自のコンテキストウィンドウ」——ここが全部の理由になります。

本体の会話は、たしかにきれいに保たれる

まず良い面から。大量のファイルの中身が、本体の会話に流れ込まなくなります。

50個のファイルを読ませて調べさせると、普通ならその中身が全部あなたの会話に積まれます。そして会話は毎回まるごと読み直されるので、そのあとの発言が一発ずつ高くなります。

サブエージェントに投げれば、読んだ中身はサブエージェント側の文脈に残り、返ってくるのは要約だけです。 本体の会話は短いままです。これは実際に消費を減らします（AIエージェントのトークン消費を減らすコツでも、節約策のひとつとして挙げています）。

それでも、総量は減りません

問題は、節約されるのは「本体の文脈」であって、「使ったトークンの合計」ではないことです。

サブエージェント自身もトークンを使います。 向こう側で50個のファイルを読んでいるのは事実で、そのぶんは消費されています
並列に何本も立ちます。 公式の例にも「認証・データベース・APIの3つを、別々のサブエージェントで並行して調べる」という使い方が載っています。3本走れば、3本分です
使う人からは見えにくい。 本体の画面には要約しか表示されないので、裏でどれだけ読まれたかが分かりません

つまりサブエージェントは、本体の会話を汚さないための道具であって、総消費を減らすための道具とは限りません。

⚠️ しかも、本体と同じモデルで走ります

ここが肝心です。組み込みの調査役（Explore）について、Anthropic公式のドキュメントにこう書かれています。

As of v2.1.198, Explore inherits the main conversation’s model instead of always running on Haiku.

（v2.1.198以降、Exploreは常にHaikuで動くのではなく、本体の会話のモデルを引き継ぐようになった）

以前は調査だけ軽いモデルで走っていたのが、本体に合わせるようになった、ということです。

つまり——本体を重いモデルにしていると、調べ物も重いモデルで走ります。 難所だからとモデルを上げて、そのまま調査を頼んだ、というのが溶けるパターンです。しかも選んだモデルは次のセッションにも引き継がれるので、上げたことを忘れているとなお危ないです。

ただし、Opusで打ち止めになります

「同じモデルで走る」には上限があります。同じAnthropic公式のドキュメントの、さきほどの文のすぐ次に書かれています。

On the Claude API, the inherited model is capped at Opus: a main conversation on a higher tier runs Explore on Opus, and a main conversation on Sonnet or Haiku runs Explore on that same model.

（Claude APIでは、引き継ぐモデルはOpusが上限になる。本体がそれより上位のモデルなら、ExploreはOpusで走る。本体がSonnetやHaikuなら、Exploreも同じモデルで走る）

本体をOpusより上のモデルにしていても、調査役はOpusまでしか上がりません。 「同じモデルで走る」が文字どおり同じになるのは、Opus以下のときです。

ただし、これはExploreについて書かれた話で、上限が適用されるのもClaude APIで使っているときだけです。同じ段落に、Bedrockなど他の経路ではExploreも本体のモデルをそのまま引き継ぐ、と続きます。自分で定義したサブエージェントには、この上限の記述はありません。

対策：調査役だけ、軽いモデルに固定する

これは設定で止められます。Anthropic公式のドキュメントにこうあります。

A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to keep exploration on a lower-cost model

（ユーザー用またはプロジェクト用のサブエージェントをExploreという名前で定義すると組み込みのものを上書きでき、model: haikuと書けば調査を安いモデルのままにできる）

~/.claude/agents/Explore.md に、こういうファイルを置くだけです。

---
name: Explore
description: コードベースやファイルを調べる
model: haiku
---

調査に徹してください。ファイルの変更はしません。

書式を覚える必要はありません。 設定ファイルはエージェントに書いてもらうのがいちばん早いので、「調査用のサブエージェントをHaikuで動くように作って」と頼めば済みます。

~/.claude/agents/ に置くとどのプロジェクトでも使えるようになり、プロジェクトの中の.claude/agents/に置くとそのプロジェクトだけになります。

全部まとめて軽くしたいとき

Exploreに限らずサブエージェント全部を軽いモデルに寄せたい場合は、環境変数CLAUDE_CODE_SUBAGENT_MODELがあります。同じドキュメントに、サブエージェントのモデルはこの環境変数 → 呼び出しごとの指定 → 定義ファイルのmodel → 本体の会話のモデルの順で決まる、と書かれています。環境変数が一番強いので、これをhaikuにすれば全部そこに寄ります。

ただし及ぶ範囲が広すぎます。 査読役のように賢いモデルで走ってほしいサブエージェントまで軽くなるので、ふだんは上のファイルを置く方法のほうが向いています。

使いどころと、使わないどころ

向いているのは、読む量が多くて結論が短い仕事です。

「このプロジェクトがどういう構成か調べて」
「この不具合に関係しそうなファイルを探して」
「ドキュメントを読んで、使い方をまとめて」

向いていないのは、使う人が経過を見ていたい仕事です。サブエージェントの作業は要約されて返るので、途中で「そっちじゃない」と言えません。 方向がずれていても、終わってから分かります。

まとめ

サブエージェントは別働隊。それぞれが自前の文脈を持つ
本体の会話は守られるが、総消費は減らない。 むしろ並列に立つぶん増えうる
調査役は本体のモデルを引き継ぐ。 重いモデルのまま調べ物を頼むと溶ける。ただしClaude APIではOpusが上限で、それより上に上げても調査役はOpusまで
Exploreをmodel: haikuで上書きしておけば、そこは止められる
裏で何が起きているか見えないのが本質的な弱点。 見ていたい作業には使わない

消費そのものを減らす話はAIエージェントのトークン消費を減らすコツへ、モデルの選び方はトークン節約のためのモデル選びへどうぞ。