長いエージェントループや長時間の会話では、コンテキストウィンドウが枯渇する問題が必ず発生します。Claude API には複数のコンテキスト管理機能が用意されています。

なぜコンテキスト管理が重要か

コンテキストウィンドウが長くなると、モデルは履歴全体に焦点を維持することが難しくなります。単にトークン上限を超えないようにするだけでなく、「余計な情報でモデルの集中力を下げない」という観点も重要です。

また、Opus 4.5+ / Sonnet 4.6+ では思考ブロックがデフォルトでコンテキストに保持されるようになったため、長い会話では思考ブロックが蓄積してコストが膨れます。

現在使用中のコンテキストトークン数は response.usage.input_tokens で確認できます。Context Editing 適用後の値はサーバーサイドで編集が済んだ後のトークン数を反映するため、削減効果の確認に使えます。

アプローチ1：Compaction（コンパクション）

会話履歴が設定したトークンしきい値に近づいたとき、自動的に会話を要約して圧縮します。ベータ機能です。

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 100000},
            }
        ]
    },
)
# compaction ブロックを含むレスポンスをそのまま messages に追加して続ける
messages.append({"role": "assistant", "content": response.content})

コンパクションが発生すると、アシスタントレスポンスの先頭に compaction ブロックが付きます。後続のリクエストでこのブロックを渡すと、それより前のメッセージは自動的に無視されます。デフォルトのトリガーは 150,000 入力トークンです。

アプローチ2：Context Editing（コンテキスト編集）

古いツール結果や思考ブロックを選択的に削除・置換する機能です。ベータ機能です。

ツール結果クリアは重いツール使用があるエージェントに有効です。古いツール結果（ファイルコンテンツや検索結果など）は Claude が処理した後は不要です。clear_tool_uses_20250919 戦略を使うと、設定したしきい値を超えたタイミングで古いツール結果が自動的にクリアされます。

思考ブロッククリアは clear_thinking_20251015 戦略で思考ブロックの保持数を制御します。デフォルトでは最後の1ターン分の思考のみ保持します。

response = client.beta.messages.create(
    betas=["context-management-2025-06-27"],
    model="claude-opus-4-8",
    max_tokens=8192,
    messages=messages,
    context_management={
        "edits": [
            # clear_thinking は必ず edits の先頭に置く
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
            },
        ]
    },
)
# 適用された編集を確認
print(response.context_management.applied_edits)

複数の戦略を組み合わせる場合は clear_thinking_20251015 を必ず配列の最初に置くという制約があります。この順序が守られないと API エラーになります。

アプローチ3：思考ブロックの手動削除

Context Editing を使わず、クライアント側で思考ブロックを会話履歴から除去することもできます。ただし、ツール使用のターン中は思考ブロックを保持しておく必要があります（推論の連続性を保つため）。ツール呼び出しが完了して最終回答が得られたあと、そのターンの思考ブロックを削除するのが安全なタイミングです。

どのアプローチを選ぶか

ユースケース 推奨アプローチ
長時間のチャット会話 Compaction
大量のツール呼び出しがあるエージェント Context Editing（ツール結果クリア）
拡張思考を使う長いループ Context Editing（思考ブロッククリア）
細かく制御したい クライアント側での手動削除

まとめ

  • Opus 4.5+ / Sonnet 4.6+ では思考ブロックがデフォルトで保持されるため、長い会話では意図的に管理が必要
  • Compaction はシンプルで推奨される方式。サーバーサイドで自動処理される
  • Context Editing は思考ブロックとツール結果を個別に削除できる細かい制御が可能
  • clear_thinking は edits 配列の先頭に置く必要がある（順序制約）
  • ツール使用ループ中は思考ブロックを保持しておかないと推論の継続性が壊れる点に注意