Claudeエージェントのコンテキスト管理を使い分ける基準
Tool Search・Programmatic Tool Calling・プロンプトキャッシュ・Context Editingは圧迫の発生源が違います。導入の判断基準としきい値を扱います。
Claudeのエージェントでコンテキストが溢れる原因は1つではない
長時間動くエージェントがコンテキストウィンドウを使い切る要因は、ツール定義・tool_resultの往復・キャッシュ未活用・古い会話履歴の4系統に分かれます。原因ごとに効く対処法が違うため、1つの手法だけを導入しても改善しないことがあります。公式ドキュメントは、Tool Search・Programmatic Tool Calling・プロンプトキャッシュ・Context Editingの4つを、圧迫の発生源別に整理した対処法として並べています。
結論を先に1文で書きます。ツール定義が重いならTool Search、tool_resultの往復が多いならProgrammatic Tool Calling、ツール構成が安定しているならプロンプトキャッシュ、会話そのものが長いならContext Editing。この記事では、それぞれをいつ導入するかの判断材料を扱います。実装の細部は各機能の専門記事に譲ります。
4つの対処法は圧迫の発生源がそれぞれ違う
早見表にすると、4つの役割分担がはっきりします。
| 対処法 | 削減する対象 | 効くタイミング |
|---|---|---|
| Tool Search | 削減する対象事前ロードされるツール定義 | 効くタイミングツール数が多く、毎ターン全部は使わない構成 |
| Programmatic Tool Calling | 削減する対象tool_resultの往復 | 効くタイミング一連のツール呼び出しを1本のスクリプトにまとめられる |
| プロンプトキャッシュ | 削減する対象繰り返し送るツール定義のコスト | 効くタイミングツール構成が安定して何度もリクエストする |
| Context Editing | 削減する対象会話履歴に積み上がった古いtool_result | 効くタイミング会話が長く、初期の結果がもう不要 |
4つは競合しません。同じコンテキスト圧迫という問題の、別々の断面に効きます。条件が重なれば重ねて使えます。
ツール定義が重いならTool Searchをまず疑う
GitHub・Slack・Sentry・Grafana・Splunkのような典型的な複数サーバ構成では、Claudeが何も作業しない時点でツール定義だけで約55,000トークンを消費します。Tool Searchはこれを85%超削減し、そのターンで実際に必要な3〜5個のツールだけをロードします。
導入の目安は、ツール数がおおよそ20個を超えた時点、またはベースラインのコンテキスト消費が無視できなくなった時点です。20個は絶対の境界ではありません。ツール1個あたりの説明文が長ければ、10個でもTool Searchが効くことがあります。逆に短い説明文が並ぶ構成なら、20個を超えても後回しでかまいません。Tool Search Toolの実装手順そのものはAdvanced Tool Useに譲ります。
tool_resultの往復が多いならProgrammatic Tool Calling
Programmatic Tool Callingは、5回のtool_use・tool_result往復を、Claudeが書いた1本のスクリプトに置き換えます。スクリプトはAnthropicのコード実行サンドボックス内で走り、中間結果は会話履歴に一切入りません。
向くのは、複数のツール呼び出しが依存関係を持って連鎖するワークロードです。1回のツール呼び出しで完結するタスクには効果がありません。導入の判断材料は「同じような小さなツール呼び出しの連鎖を繰り返し見かけるか」です。効くワークロードと効かないワークロードの切り分けはプログラマティックツールコーリングのコスト削減効果で扱っています。
Tool Searchとは効く場所が違う点に注意します。Tool Searchはツール定義そのものの重さに効き、Programmatic Tool Callingは呼び出しの往復に効きます。ツール数が少ない構成でも、同じツールを何度も呼ぶ処理なら後者の効果が出ます。
ツール構成が安定しているならプロンプトキャッシュを初日から
プロンプトキャッシュは、コンテキストのトークン数そのものは減らしません。2回目以降のリクエストで、同じツール定義を送るコストを下げる仕組みです。5分TTLのキャッシュ書き込みは基本入力価格の1.25倍、1時間TTLは2倍のコストがかかりますが、その後のキャッシュヒットは基本価格より大幅に安くなります。
TTLの選び方にも判断基準があります。system promptのように5分より高頻度で呼ばれる構成は5分TTLのままでよく、無料でリフレッシュされ続けます。一方、サブエージェントの処理が5分を超えて続く場合や、ユーザーの応答間隔が5分を超えて空きがちな会話では、1時間TTLに切り替えたほうがキャッシュヒットを保てます。
ツール定義が頻繁に変わらない構成なら、他の3つより先に、初日から有効化しておく価値があります。ここだけは「様子を見てから」ではなく最初に入れてよい対処法です。プロンプトキャッシュとContext Editingを併用する設計はContext editingとmemory toolを併用する長時間エージェント設計で扱った通り、クリアのタイミング次第でキャッシュの効き方が変わります。
会話が長くなるほどContext Editingが必要になる
Context Editingは、古いtool_result(必要ならツール呼び出しのパラメータも)を会話履歴から自動的に消し、プレースホルダーに置き換えます。デフォルトのトリガーは入力トークン100,000、直近3件のtool_use・tool_resultペアは残したまま古いものから消えます。
"context_management": {
"edits": [
{ "type": "clear_tool_uses_20250919" }
]
}トリガーと保持件数以外にも、判断に効くパラメータが2つあります。clear_at_leastは、1回のクリアで最低限消すトークン数を指定するもので、これを満たせない場合はクリア自体が実行されません。プロンプトキャッシュを壊してまでクリアする価値があるかを、この数値で線引きできます。exclude_toolsは、特定のツールの結果だけをクリア対象から外す設定で、web検索の結果のように後段でも参照し続けたい情報を保護するのに使います。
エージェントループが長く回り、初期のツール結果がもう参照されなくなった時点で導入するのが基本です。短いタスクで完結するなら不要です。tool_result側だけでなく、compaction・ノート・サブエージェントまで含めた長時間タスクの設計はAnthropicのContext Engineering論が別の切り口を持っています。
4つを重ねて使うときの導入順
公式ドキュメントが示す出発点は次の順です。
- ツール定義にプロンプトキャッシュを初日から有効化する
- ツール数がおおよそ20個を超えた、またはベースラインのコンテキスト消費が気になり始めたらTool Searchを追加する
- 会話が長く続き、初期の結果が不要になり始めたらContext Editingを追加する
- 同じような小さなツール呼び出しの連鎖を繰り返し見かけたらProgrammatic Tool Callingを検討する
この順序は、発生しやすい圧迫から潰す設計になっています。キャッシュはほぼ確実に得なので最初、残り3つはワークロードの形が見えてから、という考え方です。
プロンプトキャッシュとContext Editingは相性を考えて組む
2つを同時に使うと、片方がもう片方を打ち消す場面があります。Context Editingが古いtool_resultを消すと、その時点でキャッシュされていたプロンプトの接頭辞は無効になります。消す量が少なすぎると、キャッシュの再構築コストに見合わないことがあります。clear_at_leastで最低限クリアするトークン数を確保しておくと、キャッシュを壊す価値がある量だけをまとめて処理できます。クリア後の次のリクエストからは、新しい接頭辞がまた再利用されるため、一度きりのコストで済みます。
一方、プロンプトキャッシュとTool Searchの間には打ち消し合いがありません。defer_loading: trueを付けたツールは初期プロンプトから完全に除外されるため、キャッシュされる範囲そのものに含まれません。したがって、先にキャッシュを効かせてからTool Searchを追加しても、既存のキャッシュヒット率を落とす心配はありません。4つの対処法は互いに独立して足せるものと、足すときに設計の調整が要るものが混在している、という理解が実務では役立ちます。
しきい値は監視して自分で決め直すもの
公式が挙げる「20個」「100,000トークン」という数字は、出発点であって固定値ではありません。ツール1個の説明文の長さでも、実際に消費するトークンは変わります。自分のエージェントのベースラインのコンテキスト消費を実測してから、しきい値を調整するのが実務的です。
4つの対処法を機能名で覚えるより、「何が圧迫の原因か」で覚えておくと、新しい機能が増えたときも同じ枠組みで判断できます。数字はあくまで最初の当たりを付けるための目安であり、実測して調整する前提で使うものです。
まとめ
コンテキストが溢れる長時間エージェントには、ツール定義・tool_resultの往復・キャッシュ未活用・古い履歴という4つの発生源があり、それぞれに対処法が対応します。ツール数が多いならTool Search、ツール呼び出しの連鎖が多いならProgrammatic Tool Calling、構成が安定しているならプロンプトキャッシュを初日から、会話が長いならContext Editing。4つは重ねて使え、公式の出発点はキャッシュ・Tool Search・Context Editing・Programmatic Tool Callingの順です。組み合わせるときはキャッシュとContext Editingの相性だけ意識すれば、あとは足すほど効果が積み上がります。