Claudeエージェントのコンテキスト管理を使い分ける基準

Claudeのエージェントでコンテキストが溢れる原因は1つではない

長時間動くエージェントがコンテキストウィンドウを使い切る要因は、ツール定義・tool_resultの往復・同じ定義の再送・古い会話履歴の4系統に分かれます。原因ごとに効く対処法が違うため、1つの手法だけを入れても改善しないことがあります。ドキュメントは、Tool Search・Programmatic Tool Calling・プロンプトキャッシュ・Context Editingを、圧迫の発生源別の対処法として並べています。

以下は、トークンの行き先を見て対処法を選ぶための判断材料です。

4つは競合しません。同じコンテキスト圧迫という問題の、別々の断面に効くので、条件が重なれば重ねて使えます。ただしキャッシュとContext Editingの組み合わせだけは調整が要ります。

ツール定義が最初から重いならTool Search

GitHub・Slack・Sentry・Grafana・Splunkのような複数サーバー構成では、Claudeが何も作業しない時点でツール定義だけで約5万5千トークンを使います。Tool Searchは、この定義を最初から載せず、必要になったときに検索で呼び出す仕組みです。

導入の目安は、ドキュメントのページによって数字が違います。ツール管理の概説ページは「20個前後を超えたら」とし、Tool Searchの専用ページは「ツールが10個以上、または定義が1万トークンを超える」を使いどきとしています。

2つを並べると、20個は絶対の境界ではないと分かります。説明文が長いツールが並ぶ構成なら、10個でも効きます。逆に定義が合計100トークン未満の小さな構成、または全ツールを毎回使う構成は、Tool Searchなしの通常のツール呼び出しのほうが向くとされています。

使い方で押さえる点は3つです。

• ツール定義はすべてtools配列に渡したまま、後回しにしたいものにdefer_loading: trueを付けます。
• 少なくとも1つは遅延させないツールが必要で、通常は検索ツール自身がそれです。全ツールを遅延させると400エラーになります。
• 使用頻度の高い3〜5個は遅延させず、最初から載せておくよう勧められています。

検索方式はregexとbm25の2種類で、検索結果は既定で最大5件です。ツール名にgithub_やslack_のような接頭辞をそろえておくと、1回の検索でサービス単位のまとまりが見つかります。圧迫のほかに選択精度の面もあり、利用できるツールが30〜50個を超えると、Claudeが適切なツールを選ぶ精度が下がるとされています。実装の手順はAdvanced Tool Useに詳しくあります。

同じツールを何度も呼ぶならProgrammatic Tool Calling

Programmatic Tool Callingは、たとえば5回のtool_use・tool_result往復を、Claudeが書いた1本のスクリプトに置き換えます。スクリプトはAnthropicのコード実行コンテナー内で走り、中間結果は会話履歴に入りません。ツールの定義にallowed_callers: ["code_execution_20260120"]を付けると、そのツールがコードから呼べるようになります。

向くのは、同じ種類の呼び出しが多数並ぶワークロードです。ドキュメントは次を相性の良い例に挙げます。

• 50個のエンドポイントの死活確認のように、多数の対象へ展開する処理
• 大きなtool_resultを、Claudeに渡す前に絞り込んだり集計したりできる処理
• 反復的な検索と、結果の絞り込みが中心になる処理

逆に相性が悪いのは、直前の結果をClaudeが読んで判断しないと次に進めない完全な逐次処理と、小さな呼び出しが数回しかない処理です。後者は、コンテナーの起動とスクリプト生成の固定コストが節約分を上回ることがあります。迷うときは、allowed_callersを付けた場合と付けない場合の課金入力トークンを、代表的なトラフィックで比べるよう案内されています。75ツールのプロジェクト管理エージェントのベンチマークでは、有効化で課金入力トークンがおよそ38%減りました。タスクの精度は変わっていません。効く場合と効かない場合の切り分けは、プログラマティックツールコーリングのコスト削減効果にあります。

制約も導入前に確認する点です。MCPコネクター経由のツールは、プログラムからは呼び出せません。Claude Haiku 4.5は、コード実行ツールのバージョン指定は受け付けますが、Programmatic Tool Callingには対応しません。ゼロデータ保持(ZDR)の対象にもなりません。

Tool Searchとは効く場所が違います。Tool Searchはツール定義の重さに、Programmatic Tool Callingは呼び出しの往復に効きます。ツールが少ない構成でも、同じツールを何度も呼ぶ処理なら、後者の効果が出ます。

毎ターン同じ定義を送っているならプロンプトキャッシュ

プロンプトキャッシュは、コンテキストのトークン数そのものは減らしません。2回目以降のリクエストで、同じ接頭辞を送るコストを下げます。5分TTLの書き込みは基本入力価格の1.25倍、1時間TTLは2倍で、キャッシュヒットは標準で基本価格の0.1倍です。Claude Opus 5.5とSonnet 5.5は0.05倍、Fable 5.1とMythos 5.1は0.025倍と、モデルごとに違います。

書き込みの25%増しは、同じ接頭辞が2回目に読まれた時点で取り戻せます。そのため、ツール定義が安定しているなら初日から有効化する価値があります。様子を見てから入れる他の対処法と違い、最初から入れてよいのはこれです。

cache_controlは、tools配列の最後のツールに置きます。そこまでのツール定義がまとめてキャッシュ対象になります。キャッシュはtools、system、messagesの順に積まれる階層で、上流を変えると下流もまとめて無効になります。

ツール定義を毎リクエスト書き換える構成は、キャッシュがほぼ効きません。会話の途中でtool_choiceを切り替えるなら、切り替え位置より前にブレークポイントを置いておくと、手前のキャッシュを残せます。

TTLの選び方にも基準があります。system promptのように5分より高頻度で呼ばれる部分は、5分TTLのままで使うたびに無料で延長されます。サブエージェントの処理が5分を超える場合や、ユーザーの応答間隔が5分を超えがちな会話では、1時間TTLのほうがヒットを保てます。

会話が長くなるほどContext Editingが効く

Context Editingは、古いtool_result(必要ならツール呼び出しのパラメーターも)を会話履歴から自動で消し、プレースホルダーに置き換えます。ベータ機能で、リクエストにanthropic-beta: context-management-2025-06-27ヘッダーが要ります。

"context_management": {
  "edits": [
    {
      "type": "clear_tool_uses_20250919",
      "trigger": { "type": "input_tokens", "value": 100000 },
      "keep": { "type": "tool_uses", "value": 3 },
      "clear_at_least": { "type": "input_tokens", "value": 5000 },
      "exclude_tools": ["web_search"]
    }
  ]
}

パラメーターを省くと、トリガーは入力100,000トークン、保持は直近3組のtool_use・tool_result、clear_at_leastとexclude_toolsは無指定です。clear_tool_inputsは既定でfalseなので、消えるのは結果だけで、Claudeが出した呼び出しは履歴に残ります。

判断に効くのはclear_at_leastとexclude_toolsです。clear_at_leastは、1回のクリアで最低限消すトークン数で、満たせないときはクリア自体が実行されません。キャッシュを壊してまでクリアする価値があるかを、この数値で線引きできます。exclude_toolsは、web検索のように後段でも参照し続けたい結果を、クリア対象から外します。

どれだけ消えたかは、レスポンスのcontext_management.applied_editsに返ります。項目はcleared_tool_usesとcleared_input_tokensです。思考ブロックは別の方式clear_thinking_20251015で扱い、こちらはkeepで残すターン数を決めます。

エージェントループが長く回り、初期のツール結果がもう参照されなくなったら導入します。短いタスクで完結するなら不要です。tool_resultだけでなく、compactionやノート、サブエージェントまで含めた設計は別の話です。AnthropicのContext Engineering論が、その切り口を扱っています。

4つを重ねるときの導入順

ドキュメントが示す出発点は次の順です。

キャッシュが先頭に来るのは、ワークロードの形を見なくても入れられるためです。残りは、形が見えてから足します。

重ねたときに足を引っ張り合う組み合わせ

4つは足せますが、組み合わせによって設計の調整が要ります。

Tool Search側にも制約があります。defer_loading: trueを付けたツールにはcache_controlを付けられず、付けると400エラーです。ブレークポイントは、遅延させないツールに置きます。

Context Editing側は、clear_at_leastで最低限のクリア量を確保しておくと、キャッシュを壊す価値がある量だけをまとめて消せます。クリアのたびに書き込みが1回発生しますが、次のリクエストからは新しい接頭辞が再利用されます。

プロンプトキャッシュとContext Editingの併用は、Context editingとmemory toolを併用する長時間エージェント設計にも詳しくあります。

しきい値は計測して決め直す

20個や100,000トークンという数字は出発点であって、固定値ではありません。ツール1個の説明文の長さで、実際の消費は変わります。ツール管理の概説とTool Search専用ページでも、目安は10個・20個と幅があります。

測る場所は、機能ごとに決まっています。

• プロンプトキャッシュ:レスポンスのusageにあるcache_creation_input_tokensとcache_read_input_tokens。読み取りが育っているかを見ます。
• Context Editing:applied_editsのcleared_input_tokens。トリガーに届く前の履歴の大きさも合わせて見ます。
• Programmatic Tool Calling:allowed_callersあり・なしの課金入力トークンの比較。
• Tool Search:Claudeがどのツールを見つけているか。見つからないツールは、説明文に一般的なキーワードを足すと見つけやすくなります。

4つの対処法を機能名で覚えるより、「トークンがどこに積まれているか」で覚えておくと、新しい機能が増えても同じ枠組みで判断できます。

まとめ

次に足す対処法は、usageなどの指標で、トークンが定義・往復・履歴のどこに積まれているかを測って決めます。20個や100,000トークンは出発点です。キャッシュとContext Editingを重ねるなら、clear_at_leastで調整します。