メッセージコンテキスト管理

コンテキスト編集

コンテキスト編集を使用して、会話コンテキストの増大に応じて自動的に管理します。

「zero data retention」（ゼロデータ保持）、すなわちZDRがこの機能にどのように適用されるかについては、APIとデータ保持を参照してください。

概要

ほとんどのユースケースでは、サーバーサイドコンパクションが長時間実行される会話のコンテキストを管理するための主要な戦略です。このページの戦略は、どのコンテンツをクリアするかをより細かく制御する必要がある特定のシナリオで役立ちます。

コンテキスト編集を使用すると、会話履歴が増大するにつれて、特定のコンテンツを選択的にクリアできます。コストの最適化や制限内に収めることを超えて、これはClaudeが見るものを能動的にキュレーションすることです。コンテキストは収穫逓減のある有限のリソースであり、無関係なコンテンツはモデルの集中力を低下させます。コンテキスト編集は、そのキュレーションに対するきめ細かいランタイム制御を提供します。コンテキスト管理の背後にあるより広範な原則については、効果的なコンテキストエンジニアリングを参照してください。このページでは以下を扱います。

ツール結果のクリア - 古いツール結果が不要になった、ツール使用の多いエージェント型ワークフローに最適
思考ブロックのクリア - 拡張思考を使用する際の思考ブロックの管理用で、コンテキストの継続性のために最近の思考を保持するオプションがあります
クライアントサイドSDKコンパクション - 要約ベースのコンテキスト管理のためのSDKベースの代替手段（一般的にはサーバーサイドコンパクションが推奨されます）

アプローチ	実行場所	戦略	仕組み
サーバーサイド	API	ツール結果のクリア（`clear_tool_uses_20250919`）思考ブロックのクリア（`clear_thinking_20251015`）	プロンプトがClaudeに到達する前に適用されます。会話履歴から特定のコンテンツをクリアします。各戦略は独立して設定できます。
クライアントサイド	SDK	コンパクション	`tool_runner`を使用する際にPython、TypeScript、Ruby SDKで利用可能です。要約を生成し、完全な会話履歴を置き換えます。クライアントサイドコンパクションを参照してください。

サーバーサイド戦略

コンテキスト編集はベータ版で、ツール結果のクリアと思考ブロックのクリアをサポートしています。有効にするには、APIリクエストでベータヘッダーcontext-management-2025-06-27を使用してください。

この機能に関するフィードバックはフィードバックフォームからお寄せください。

ツール結果のクリア

clear_tool_uses_20250919戦略は、会話コンテキストが設定したしきい値を超えて増大したときにツール結果をクリアします。これは、ツール使用の多いエージェント型ワークフローで特に有用です。古いツール結果（ファイルの内容や検索結果など）は、Claudeが処理した後は不要になります。

アクティブ化されると、APIは最も古いツール結果を時系列順に自動的にクリアします。APIはクリアされた各結果をプレースホルダーテキストに置き換えるため、Claudeは削除されたことを認識できます。デフォルトでは、ツール結果のみがクリアされます。clear_tool_inputsをtrueに設定することで、ツール結果とツール呼び出し（ツール使用パラメータ）の両方をオプションでクリアできます。

思考ブロックのクリア

clear_thinking_20251015戦略は、拡張思考が有効な場合に会話内のthinkingブロックを管理します。この戦略により、思考の保持を制御できます。推論の継続性を維持するためにより多くの思考ブロックを保持するか、コンテキストスペースを節約するためにより積極的にクリアするかを選択できます。

デフォルトの動作: デフォルトはモデルクラスによって異なります。

モデルクラス	以前のすべての思考を保持	最後のターンの思考のみを保持
Opus	Claude Opus 4.5以降	Claude Opus 4.1（非推奨）以前
Sonnet	Claude Sonnet 4.6以降	Claude Sonnet 4.5以前
Haiku	（なし）	Claude Haiku 4.5までのすべてのモデル

デフォルトを上書きするには、この戦略を使用してください。コードが複数のモデルティアにまたがって実行される場合は、モデルごとのデフォルトに依存するのではなく、keepを明示的に設定してください。

アシスタントの会話ターンには、複数のコンテンツブロック（たとえば、ツールを使用する場合）や複数の思考ブロック（たとえば、インターリーブ思考を使用する場合）が含まれることがあります。

コンテキスト編集はサーバーサイドで行われます

コンテキスト編集は、プロンプトがClaudeに到達する前にサーバーサイドで適用されます。クライアントアプリケーションは、完全で変更されていない会話履歴を保持します。クライアントの状態を編集されたバージョンと同期する必要はありません。通常どおり、完全な会話履歴をローカルで管理し続けてください。

コンテキスト編集とプロンプトキャッシング

コンテキスト編集とプロンプトキャッシングの相互作用は、戦略によって異なります。

ツール結果のクリア: コンテンツがクリアされると、キャッシュされたプロンプトプレフィックスが無効になります。これを考慮して、キャッシュの無効化に見合うだけの十分なトークンをクリアしてください。clear_at_leastパラメータを使用して、毎回最小限のトークン数がクリアされるようにします。コンテンツがクリアされるたびにキャッシュ書き込みコストが発生しますが、後続のリクエストは新しくキャッシュされたプレフィックスを再利用できます。
思考ブロックのクリア: 思考ブロックがコンテキストに保持されている（クリアされていない）場合、プロンプトキャッシュは保持され、キャッシュヒットが可能になり、入力トークンコストが削減されます。思考ブロックがクリアされると、クリアが発生した時点でキャッシュが無効になります。キャッシュパフォーマンスとコンテキストウィンドウの可用性のどちらを優先するかに基づいて、keepパラメータを設定してください。

サポートされているモデル

コンテキスト編集は、サポートされているすべてのClaudeモデルで利用できます。

ツール結果のクリアの使用方法

ツール結果のクリアを有効にする最も簡単な方法は、戦略タイプのみを指定することです。その他のすべての設定オプションはデフォルト値を使用します。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

高度な設定

追加のパラメータを使用して、ツール結果のクリア動作をカスタマイズできます。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # しきい値を超えたらクリアをトリガー
                "trigger": {"type": "input_tokens", "value": 30000},
                # クリア後に保持するツール使用の数
                "keep": {"type": "tool_uses", "value": 3},
                # オプション：少なくともこのトークン数をクリア
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # これらのツールをクリア対象から除外
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

思考ブロックのクリアの使用方法

拡張思考が有効な場合に、コンテキストとプロンプトキャッシングを効果的に管理するために、思考ブロックのクリアを有効にします。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

思考ブロックのクリアの設定オプション

clear_thinking_20251015戦略は、以下の設定をサポートしています。

設定オプション	デフォルト	説明
`keep`	モデル固有	思考ブロックを含む最近のアシスタントターンをいくつ保持するかを定義します。最後のNターンを保持するには`{type: "thinking_turns", value: N}`（Nは0より大きい必要があります）を使用し、すべての思考ブロックを保持するには`"all"`を使用します。Opus 4.5以降およびSonnet 4.6以降: すべてのターン。それ以前のOpus/SonnetおよびすべてのHaiku: 最後のターンのみ。

設定例:

最後の3つのアシスタントターンの思考ブロックを保持します。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

すべての思考ブロックを保持します（キャッシュヒットを最大化）。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

戦略の組み合わせ

思考ブロックのクリアとツール結果のクリアを一緒に使用できます。

複数の戦略を使用する場合、clear_thinking_20251015戦略はedits配列の最初にリストする必要があります。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

ツール結果のクリアの設定オプション

設定オプション	デフォルト	説明
`trigger`	100,000入力トークン	コンテキスト編集戦略がアクティブ化されるタイミングを定義します。プロンプトがこのしきい値を超えると、クリアが開始されます。この値は`input_tokens`または`tool_uses`のいずれかで指定できます。
`keep`	3つのツール使用	クリアが発生した後に保持する最近のツール使用/結果ペアの数を定義します。APIは最も古いツールのやり取りを最初に削除し、最新のものを保持します。
`clear_at_least`	なし	戦略がアクティブ化されるたびに、最小限のトークン数がクリアされることを保証します。APIが指定された量以上をクリアできない場合、戦略は適用されません。これは、コンテキストのクリアがプロンプトキャッシュを破棄する価値があるかどうかを判断するのに役立ちます。
`exclude_tools`	なし	ツール使用と結果を決してクリアしないツール名のリスト。重要なコンテキストを保持するのに役立ちます。
`clear_tool_inputs`	`false`	ツール呼び出しパラメータをツール結果と一緒にクリアするかどうかを制御します。デフォルトでは、Claudeの元のツール呼び出しを表示したまま、ツール結果のみがクリアされます。

コンテキスト編集のレスポンス

context_managementレスポンスフィールドを使用して、リクエストに適用されたコンテキスト編集を確認できます。クリアされたコンテンツと入力トークンに関する有用な統計情報も含まれます。

Output

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

ストリーミングレスポンスの場合、コンテキスト編集は最後のmessage_deltaイベントに含まれます。

Streaming Response

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

トークンカウント

トークンカウントエンドポイントはコンテキスト管理をサポートしており、コンテキスト編集が適用された後にプロンプトが使用するトークン数をプレビューできます。

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

Output

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

レスポンスには、コンテキスト管理が適用された後の最終的なトークン数（input_tokens）と、クリアが発生する前の元のトークン数（original_input_tokens）の両方が表示されます。

メモリツールとの併用

コンテキスト編集はメモリツールと組み合わせることができます。会話コンテキストが設定されたクリアしきい値に近づくと、Claudeは重要な情報を保持するための自動警告を受け取ります。これにより、Claudeはツール結果やコンテキストが会話履歴からクリアされる前に、それらをメモリファイルに保存できます。

この組み合わせにより、以下が可能になります。

重要なコンテキストの保持: Claudeは、ツール結果がクリアされる前に、その中の重要な情報をメモリファイルに書き込むことができます
長時間実行されるワークフローの維持: 情報を永続ストレージにオフロードすることで、そうしなければコンテキスト制限を超えてしまうエージェント型ワークフローを実現します
オンデマンドでの情報アクセス: Claudeは、すべてをアクティブなコンテキストウィンドウに保持するのではなく、必要に応じて以前にクリアされた情報をメモリファイルから参照できます

たとえば、Claudeが多くの操作を実行するファイル編集ワークフローでは、コンテキストが増大するにつれて、Claudeは完了した変更をメモリファイルに要約できます。ツール結果がクリアされても、Claudeはメモリシステムを通じてその情報にアクセスでき、効果的に作業を続けることができます。

両方の機能を一緒に使用するには、APIリクエストで有効にします。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

コマンドや例を含むメモリツールの完全なリファレンスについては、メモリツールを参照してください。

クライアントサイドコンパクション（SDK）

AnthropicはSDKコンパクションよりもサーバーサイドコンパクションを推奨します。 サーバーサイドコンパクションは、統合の複雑さが少なく、トークン使用量の計算がより正確で、クライアントサイドの制限がない状態で、コンテキスト管理を自動的に処理します。要約プロセスをクライアントサイドで制御する必要が特にある場合にのみ、SDKコンパクションを使用してください。

compaction_controlパラメータは、Python、TypeScript、Ruby SDKで非推奨となっており、将来のバージョンで削除される予定です。SDKは、有効にすると非推奨の警告を出力します。ツールランナーでサーバーサイドコンパクションを使用するには、リクエストのcontext_managementパラメータにcompact_20260112編集を渡してください。

コンパクションは、tool_runnerメソッドを使用する際にPython、TypeScript、Ruby SDKで利用できます。

コンパクションは、トークン使用量が大きくなりすぎたときに要約を生成することで、会話コンテキストを自動的に管理するSDK機能です。コンテンツをクリアするサーバーサイドのコンテキスト編集戦略とは異なり、コンパクションはClaudeに会話履歴を要約するよう指示し、完全な履歴をその要約に置き換えます。これにより、Claudeはコンテキストウィンドウを超えてしまうような長時間実行されるタスクを継続できます。

コンパクションの仕組み

コンパクションが有効な場合、SDKは各モデルレスポンスの後にトークン使用量を監視します。

しきい値チェック: SDKは合計トークンをinput_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokensとして計算します。
要約の生成: しきい値を超えると、要約プロンプトがユーザーターンとして挿入され、Claudeは<summary></summary>タグで囲まれた構造化された要約を生成します。
コンテキストの置き換え: SDKは要約を抽出し、メッセージ履歴全体をそれに置き換えます。
継続: 会話は要約から再開され、Claudeは中断したところから作業を続けます。

コンパクションの使用方法

トークン使用量がしきい値を超えたときに自動要約を有効にするには、tool_runner呼び出しにcompaction_controlを追加します。

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

コンパクション中に何が起こるか

会話が増大するにつれて、メッセージ履歴が蓄積されます。

コンパクション前（100kトークンに近づいている状態）:

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

トークンがしきい値を超えると、SDKは要約リクエストを挿入し、Claudeが要約を生成します。その後、履歴全体が置き換えられます。

コンパクション後（約2〜3kトークンに戻る）:

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claudeは、この要約を元の会話履歴であるかのように扱い、作業を続けます。

設定オプション

パラメータ	型	必須	デフォルト	説明
`enabled`	boolean	はい	-	自動コンパクションを有効にするかどうか
`context_token_threshold`	number	いいえ	100,000	コンパクションがトリガーされるトークン数
`model`	string	いいえ	メインモデルと同じ	要約の生成に使用するモデル
`summary_prompt`	string	いいえ	デフォルトの要約プロンプトを参照	要約生成用のカスタムプロンプト

トークンしきい値の選択

しきい値は、コンパクションが発生するタイミングを決定します。しきい値が低いほど、より小さなコンテキストウィンドウでより頻繁にコンパクションが行われます。しきい値が高いほど、より多くのコンテキストが許容されますが、制限に達するリスクがあります。

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    # 値を小さくするとコンパクト化の頻度が上がります。タスクでより多くのコンテキストが必要な場合は150000に上げてください
    compaction_control={"enabled": True, "context_token_threshold": 50000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

要約に別のモデルを使用する

要約の生成には、より高速または安価なモデルを使用できます。

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "model": "claude-haiku-4-5",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

カスタム要約プロンプト

ドメイン固有のニーズに合わせてカスタムプロンプトを提供できます。プロンプトでは、Claudeに要約を<summary></summary>タグで囲むよう指示する必要があります。

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

デフォルトの要約プロンプト

組み込みの要約プロンプトは、以下を含む構造化された継続用の要約を作成するようClaudeに指示します。

タスクの概要: ユーザーの中心的なリクエスト、成功基準、制約。
現在の状態: 完了した内容、変更されたファイル、生成された成果物。
重要な発見: 技術的な制約、行われた決定、解決されたエラー、失敗したアプローチ。
次のステップ: 必要な具体的なアクション、ブロッカー、優先順位。
保持すべきコンテキスト: ユーザーの好み、ドメイン固有の詳細、行われた約束。

この構造により、Claudeは重要なコンテキストを失ったり、ミスを繰り返したりすることなく、効率的に作業を再開できます。

制限事項

サーバーサイドツール

ウェブ検索やウェブフェッチなどのサーバーサイドツールを使用する場合、コンパクションには特別な考慮が必要です。

サーバーサイドツールを使用する場合、SDKがトークン使用量を誤って計算し、コンパクションが誤ったタイミングでトリガーされる可能性があります。

たとえば、ウェブ検索操作の後、APIレスポンスには以下のように表示される場合があります。

Output

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDKは合計使用量を63,000 + 0 + 270,000 + 1,400 = 334,400トークンとして計算します。しかし、cache_read_input_tokensの値には、サーバーサイドツールが行った複数の内部API呼び出しからの累積読み取りが含まれており、実際の会話コンテキストではありません。実際のコンテキスト長は63,000のinput_tokensだけかもしれませんが、SDKは334kと認識し、コンパクションを早期にトリガーしてしまいます。

回避策:

トークンカウントエンドポイントを使用して、正確なコンテキスト長を取得する
サーバーサイドツールを多用する場合はコンパクションを避ける

ツール使用のエッジケース

ツール使用のレスポンスが保留中の状態でSDKがコンパクションをトリガーすると、要約を生成する前にメッセージ履歴からtool_useブロックが削除されます。Claudeは、要約から再開した後、必要であればツール呼び出しを再発行します。

コンパクションの監視

コンパクションがいつトリガーされるかを理解することで、しきい値の調整や期待される動作の検証に役立ちます。

Python SDKは、コンパクションイベントをINFOレベルでログに記録します。anthropic.lib.toolsロガーを有効にしてください。

Python

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# ログには以下のように表示されます:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

コンパクションを使用すべき場合

適したユースケース:

多くのファイルやデータソースを処理する長時間実行されるエージェントタスク
大量の情報を蓄積するリサーチワークフロー
明確で測定可能な進捗を持つマルチステップタスク
会話の外部に永続する成果物（ファイル、レポート）を生成するタスク

あまり適さないユースケース:

会話の初期の詳細を正確に思い出す必要があるタスク
サーバーサイドツールを多用するワークフロー
多くの変数にわたって正確な状態を維持する必要があるタスク

次のステップ

コンパクション

ほとんどのユースケースで推奨される戦略である、サーバーサイドコンパクションで長い会話を管理します。

プロンプトキャッシング

プロンプトプレフィックスをキャッシュすることでコストとレイテンシを削減し、コンテキスト編集がキャッシュとどのように相互作用するかを学びます。

Was this page helpful?

メッセージコンテキスト管理

コンテキスト編集

コンテキスト編集を使用して、会話コンテキストの増大に応じて自動的に管理します。

「zero data retention」（ゼロデータ保持）、すなわちZDRがこの機能にどのように適用されるかについては、APIとデータ保持を参照してください。

概要

ツール結果のクリア - 古いツール結果が不要になった、ツール使用の多いエージェント型ワークフローに最適
思考ブロックのクリア - 拡張思考を使用する際の思考ブロックの管理用で、コンテキストの継続性のために最近の思考を保持するオプションがあります
クライアントサイドSDKコンパクション - 要約ベースのコンテキスト管理のためのSDKベースの代替手段（一般的にはサーバーサイドコンパクションが推奨されます）

アプローチ	実行場所	戦略	仕組み
サーバーサイド	API	ツール結果のクリア（`clear_tool_uses_20250919`）思考ブロックのクリア（`clear_thinking_20251015`）	プロンプトがClaudeに到達する前に適用されます。会話履歴から特定のコンテンツをクリアします。各戦略は独立して設定できます。
クライアントサイド	SDK	コンパクション	`tool_runner`を使用する際にPython、TypeScript、Ruby SDKで利用可能です。要約を生成し、完全な会話履歴を置き換えます。クライアントサイドコンパクションを参照してください。

サーバーサイド戦略

この機能に関するフィードバックはフィードバックフォームからお寄せください。

ツール結果のクリア

思考ブロックのクリア

デフォルトの動作: デフォルトはモデルクラスによって異なります。

モデルクラス	以前のすべての思考を保持	最後のターンの思考のみを保持
Opus	Claude Opus 4.5以降	Claude Opus 4.1（非推奨）以前
Sonnet	Claude Sonnet 4.6以降	Claude Sonnet 4.5以前
Haiku	（なし）	Claude Haiku 4.5までのすべてのモデル

コンテキスト編集はサーバーサイドで行われます

コンテキスト編集とプロンプトキャッシング

コンテキスト編集とプロンプトキャッシングの相互作用は、戦略によって異なります。

ツール結果のクリア: コンテンツがクリアされると、キャッシュされたプロンプトプレフィックスが無効になります。これを考慮して、キャッシュの無効化に見合うだけの十分なトークンをクリアしてください。clear_at_leastパラメータを使用して、毎回最小限のトークン数がクリアされるようにします。コンテンツがクリアされるたびにキャッシュ書き込みコストが発生しますが、後続のリクエストは新しくキャッシュされたプレフィックスを再利用できます。
思考ブロックのクリア: 思考ブロックがコンテキストに保持されている（クリアされていない）場合、プロンプトキャッシュは保持され、キャッシュヒットが可能になり、入力トークンコストが削減されます。思考ブロックがクリアされると、クリアが発生した時点でキャッシュが無効になります。キャッシュパフォーマンスとコンテキストウィンドウの可用性のどちらを優先するかに基づいて、keepパラメータを設定してください。

サポートされているモデル

コンテキスト編集は、サポートされているすべてのClaudeモデルで利用できます。

ツール結果のクリアの使用方法

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

高度な設定

追加のパラメータを使用して、ツール結果のクリア動作をカスタマイズできます。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # しきい値を超えたらクリアをトリガー
                "trigger": {"type": "input_tokens", "value": 30000},
                # クリア後に保持するツール使用の数
                "keep": {"type": "tool_uses", "value": 3},
                # オプション：少なくともこのトークン数をクリア
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # これらのツールをクリア対象から除外
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

思考ブロックのクリアの使用方法

拡張思考が有効な場合に、コンテキストとプロンプトキャッシングを効果的に管理するために、思考ブロックのクリアを有効にします。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

思考ブロックのクリアの設定オプション

clear_thinking_20251015戦略は、以下の設定をサポートしています。

設定オプション	デフォルト	説明
`keep`	モデル固有	思考ブロックを含む最近のアシスタントターンをいくつ保持するかを定義します。最後のNターンを保持するには`{type: "thinking_turns", value: N}`（Nは0より大きい必要があります）を使用し、すべての思考ブロックを保持するには`"all"`を使用します。Opus 4.5以降およびSonnet 4.6以降: すべてのターン。それ以前のOpus/SonnetおよびすべてのHaiku: 最後のターンのみ。

設定例:

最後の3つのアシスタントターンの思考ブロックを保持します。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

すべての思考ブロックを保持します（キャッシュヒットを最大化）。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

戦略の組み合わせ

思考ブロックのクリアとツール結果のクリアを一緒に使用できます。

複数の戦略を使用する場合、clear_thinking_20251015戦略はedits配列の最初にリストする必要があります。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

ツール結果のクリアの設定オプション

設定オプション	デフォルト	説明
`trigger`	100,000入力トークン	コンテキスト編集戦略がアクティブ化されるタイミングを定義します。プロンプトがこのしきい値を超えると、クリアが開始されます。この値は`input_tokens`または`tool_uses`のいずれかで指定できます。
`keep`	3つのツール使用	クリアが発生した後に保持する最近のツール使用/結果ペアの数を定義します。APIは最も古いツールのやり取りを最初に削除し、最新のものを保持します。
`clear_at_least`	なし	戦略がアクティブ化されるたびに、最小限のトークン数がクリアされることを保証します。APIが指定された量以上をクリアできない場合、戦略は適用されません。これは、コンテキストのクリアがプロンプトキャッシュを破棄する価値があるかどうかを判断するのに役立ちます。
`exclude_tools`	なし	ツール使用と結果を決してクリアしないツール名のリスト。重要なコンテキストを保持するのに役立ちます。
`clear_tool_inputs`	`false`	ツール呼び出しパラメータをツール結果と一緒にクリアするかどうかを制御します。デフォルトでは、Claudeの元のツール呼び出しを表示したまま、ツール結果のみがクリアされます。

コンテキスト編集のレスポンス

Output

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

ストリーミングレスポンスの場合、コンテキスト編集は最後のmessage_deltaイベントに含まれます。

Streaming Response

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

トークンカウント

response = client.beta.messages.count_tokens(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

Output

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

メモリツールとの併用

この組み合わせにより、以下が可能になります。

重要なコンテキストの保持: Claudeは、ツール結果がクリアされる前に、その中の重要な情報をメモリファイルに書き込むことができます
長時間実行されるワークフローの維持: 情報を永続ストレージにオフロードすることで、そうしなければコンテキスト制限を超えてしまうエージェント型ワークフローを実現します
オンデマンドでの情報アクセス: Claudeは、すべてをアクティブなコンテキストウィンドウに保持するのではなく、必要に応じて以前にクリアされた情報をメモリファイルから参照できます

両方の機能を一緒に使用するには、APIリクエストで有効にします。

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

コマンドや例を含むメモリツールの完全なリファレンスについては、メモリツールを参照してください。

クライアントサイドコンパクション（SDK）

コンパクションは、tool_runnerメソッドを使用する際にPython、TypeScript、Ruby SDKで利用できます。

コンパクションの仕組み

コンパクションが有効な場合、SDKは各モデルレスポンスの後にトークン使用量を監視します。

しきい値チェック: SDKは合計トークンをinput_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokensとして計算します。
要約の生成: しきい値を超えると、要約プロンプトがユーザーターンとして挿入され、Claudeは<summary></summary>タグで囲まれた構造化された要約を生成します。
コンテキストの置き換え: SDKは要約を抽出し、メッセージ履歴全体をそれに置き換えます。
継続: 会話は要約から再開され、Claudeは中断したところから作業を続けます。

コンパクションの使用方法

トークン使用量がしきい値を超えたときに自動要約を有効にするには、tool_runner呼び出しにcompaction_controlを追加します。

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

コンパクション中に何が起こるか

会話が増大するにつれて、メッセージ履歴が蓄積されます。

コンパクション前（100kトークンに近づいている状態）:

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

トークンがしきい値を超えると、SDKは要約リクエストを挿入し、Claudeが要約を生成します。その後、履歴全体が置き換えられます。

コンパクション後（約2〜3kトークンに戻る）:

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claudeは、この要約を元の会話履歴であるかのように扱い、作業を続けます。

設定オプション

パラメータ	型	必須	デフォルト	説明
`enabled`	boolean	はい	-	自動コンパクションを有効にするかどうか
`context_token_threshold`	number	いいえ	100,000	コンパクションがトリガーされるトークン数
`model`	string	いいえ	メインモデルと同じ	要約の生成に使用するモデル
`summary_prompt`	string	いいえ	デフォルトの要約プロンプトを参照	要約生成用のカスタムプロンプト

トークンしきい値の選択

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    # 値を小さくするとコンパクト化の頻度が上がります。タスクでより多くのコンテキストが必要な場合は150000に上げてください
    compaction_control={"enabled": True, "context_token_threshold": 50000},
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

要約に別のモデルを使用する

要約の生成には、より高速または安価なモデルを使用できます。

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "model": "claude-haiku-4-5",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

カスタム要約プロンプト

Python

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[read_file],
    messages=[{"role": "user", "content": "What's in config.json?"}],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,
        "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
    },
)

for message in runner:
    print(f"Tokens used: {message.usage.input_tokens}")

デフォルトの要約プロンプト

組み込みの要約プロンプトは、以下を含む構造化された継続用の要約を作成するようClaudeに指示します。

タスクの概要: ユーザーの中心的なリクエスト、成功基準、制約。
現在の状態: 完了した内容、変更されたファイル、生成された成果物。
重要な発見: 技術的な制約、行われた決定、解決されたエラー、失敗したアプローチ。
次のステップ: 必要な具体的なアクション、ブロッカー、優先順位。
保持すべきコンテキスト: ユーザーの好み、ドメイン固有の詳細、行われた約束。

この構造により、Claudeは重要なコンテキストを失ったり、ミスを繰り返したりすることなく、効率的に作業を再開できます。

制限事項

サーバーサイドツール

ウェブ検索やウェブフェッチなどのサーバーサイドツールを使用する場合、コンパクションには特別な考慮が必要です。

たとえば、ウェブ検索操作の後、APIレスポンスには以下のように表示される場合があります。

Output

{
  "usage": {
    "input_tokens": 63000,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

回避策:

トークンカウントエンドポイントを使用して、正確なコンテキスト長を取得する
サーバーサイドツールを多用する場合はコンパクションを避ける

ツール使用のエッジケース

コンパクションの監視

コンパクションがいつトリガーされるかを理解することで、しきい値の調整や期待される動作の検証に役立ちます。

Python SDKは、コンパクションイベントをINFOレベルでログに記録します。anthropic.lib.toolsロガーを有効にしてください。

Python

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# ログには以下のように表示されます:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

コンパクションを使用すべき場合

適したユースケース:

多くのファイルやデータソースを処理する長時間実行されるエージェントタスク
大量の情報を蓄積するリサーチワークフロー
明確で測定可能な進捗を持つマルチステップタスク
会話の外部に永続する成果物（ファイル、レポート）を生成するタスク

あまり適さないユースケース:

会話の初期の詳細を正確に思い出す必要があるタスク
サーバーサイドツールを多用するワークフロー
多くの変数にわたって正確な状態を維持する必要があるタスク

次のステップ

コンパクション

ほとんどのユースケースで推奨される戦略である、サーバーサイドコンパクションで長い会話を管理します。

プロンプトキャッシング

Was this page helpful?

概要

サーバーサイド戦略

ツール結果のクリア

思考ブロックのクリア

コンテキスト編集はサーバーサイドで行われます

コンテキスト編集とプロンプトキャッシング

サポートされているモデル

ツール結果のクリアの使用方法

高度な設定

思考ブロックのクリアの使用方法

思考ブロックのクリアの設定オプション

戦略の組み合わせ

ツール結果のクリアの設定オプション

コンテキスト編集のレスポンス

トークンカウント

メモリツールとの併用

クライアントサイドコンパクション（SDK）

コンパクションの仕組み

コンパクションの使用方法

コンパクション中に何が起こるか

設定オプション

トークンしきい値の選択

要約に別のモデルを使用する

カスタム要約プロンプト

デフォルトの要約プロンプト

デフォルトプロンプトの全文を表示

制限事項

サーバーサイドツール

ツール使用のエッジケース

コンパクションの監視

コンパクションを使用すべき場合

次のステップ

概要

サーバーサイド戦略

ツール結果のクリア

思考ブロックのクリア

コンテキスト編集はサーバーサイドで行われます

コンテキスト編集とプロンプトキャッシング

サポートされているモデル

ツール結果のクリアの使用方法

高度な設定

思考ブロックのクリアの使用方法

思考ブロックのクリアの設定オプション

戦略の組み合わせ

ツール結果のクリアの設定オプション

コンテキスト編集のレスポンス

トークンカウント

メモリツールとの併用

クライアントサイドコンパクション（SDK）

コンパクションの仕組み

コンパクションの使用方法

コンパクション中に何が起こるか

設定オプション

トークンしきい値の選択

要約に別のモデルを使用する

カスタム要約プロンプト

デフォルトの要約プロンプト

デフォルトプロンプトの全文を表示

制限事項

サーバーサイドツール

ツール使用のエッジケース

コンパクションの監視

コンパクションを使用すべき場合

次のステップ

概要

サーバーサイド戦略

ツール結果のクリア

思考ブロックのクリア

コンテキスト編集はサーバーサイドで行われます

コンテキスト編集とプロンプトキャッシング

サポートされているモデル

ツール結果のクリアの使用方法

高度な設定

思考ブロックのクリアの使用方法

思考ブロックのクリアの設定オプション

戦略の組み合わせ

ツール結果のクリアの設定オプション

コンテキスト編集のレスポンス

トークンカウント

メモリツールとの併用

クライアントサイドコンパクション（SDK）

コンパクションの仕組み

コンパクションの使用方法

コンパクション中に何が起こるか

設定オプション

トークンしきい値の選択

要約に別のモデルを使用する

カスタム要約プロンプト

デフォルトの要約プロンプト

制限事項

サーバーサイドツール

ツール使用のエッジケース

コンパクションの監視

コンパクションを使用すべき場合

次のステップ

概要

サーバーサイド戦略

ツール結果のクリア

思考ブロックのクリア

コンテキスト編集はサーバーサイドで行われます

コンテキスト編集とプロンプトキャッシング

サポートされているモデル

ツール結果のクリアの使用方法

高度な設定

思考ブロックのクリアの使用方法

思考ブロックのクリアの設定オプション

戦略の組み合わせ

ツール結果のクリアの設定オプション

コンテキスト編集のレスポンス

トークンカウント

メモリツールとの併用

クライアントサイドコンパクション（SDK）

コンパクションの仕組み

コンパクションの使用方法

コンパクション中に何が起こるか

設定オプション

トークンしきい値の選択

要約に別のモデルを使用する

カスタム要約プロンプト

デフォルトの要約プロンプト

制限事項

サーバーサイドツール

ツール使用のエッジケース

コンパクションの監視

コンパクションを使用すべき場合

次のステップ