コンテキスト管理

コンテキスト編集

コンテキスト編集を使用して、会話コンテキストが増大するにつれて自動的に管理します。

概要

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

コンテキスト編集を使用すると、会話履歴が増大するにつれて特定のコンテンツを選択的にクリアできます。コストの最適化やリミット内に収めることだけでなく、Claudeが見るものを積極的にキュレーションすることでもあります。コンテキストは収穫逓減を伴う有限のリソースであり、無関係なコンテンツはモデルのフォーカスを低下させます。コンテキスト編集により、そのキュレーションに対するきめ細かいランタイム制御が可能になります。コンテキスト管理の背後にある広範な原則については、Effective context engineeringを参照してください。このページでは以下を説明します：

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

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

サーバーサイド戦略

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

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

ツール結果のクリア

clear_tool_uses_20250919 戦略は、会話コンテキストが設定されたしきい値を超えた場合にツール結果をクリアします。これは重いツール使用を伴うエージェントワークフローに特に役立ちます。Claudeがそれらを処理した後は、古いツール結果（ファイルの内容や検索結果など）は不要になります。

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

思考ブロックのクリア

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

デフォルトの動作： clear_thinking_20251015 戦略を設定せずに拡張思考を有効にした場合、APIは最後のアシスタントターンの思考ブロックのみを自動的に保持します（keep: {type: "thinking_turns", value: 1} と同等）。

キャッシュヒットを最大化するには、keep: "all" を設定してすべての思考ブロックを保持してください。

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

コンテキスト編集はサーバーサイドで実行される

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

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

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

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

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

コンテキスト編集は以下で利用可能です：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

高度な設定

追加のパラメーターでツール結果クリアの動作をカスタマイズできます：

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ],
        "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"]
                }
            ]
        }
    }'

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [/* ... */],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

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

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

設定オプション	デフォルト	説明
`keep`	`{type: "thinking_turns", value: 1}`	思考ブロックを持つ最近のアシスタントターンをいくつ保持するかを定義します。最後のNターンを保持するには `{type: "thinking_turns", value: N}`（Nは0より大きい必要があります）を使用するか、すべての思考ブロックを保持するには `"all"` を使用します。

設定例：

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

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

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

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

戦略の組み合わせ

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

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

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[...],
    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},
            },
        ]
    },
)

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

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

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

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

Response

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // `clear_thinking_20251015` を使用する場合
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // `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": [
      // ...
    ]
  }
}

トークンカウント

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

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

Response

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

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

メモリツールとの使用

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

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # その他のツール
    ],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

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

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

コンパクションは、tool_runner メソッドを使用する場合にPythonおよびTypeScript 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 を追加します：

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report.",
        }
    ],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"使用トークン数: {message.usage.input_tokens}")

final = runner.until_done()

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

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

コンパクション前（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以上のやり取り ...
]

トークンがしきい値を超えると、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	いいえ	以下を参照	サマリー生成のカスタムプロンプト

トークンしきい値の選択

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

# メモリ制約のあるシナリオでより頻繁なコンパクション
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# より多くのコンテキストが必要な場合はより少ない頻度のコンパクション
compaction_control = {"enabled": True, "context_token_threshold": 150000}

サマリーに別のモデルを使用する

サマリー生成に高速または低コストのモデルを使用できます：

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

カスタムサマリープロンプト

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

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """これまでに実施した調査を要約してください。以下を含めてください：
- 参照したソースと主要な発見
- 回答された質問と残っている未知の事項
- 推奨される次のステップ

サマリーを <summary></summary> タグで囲んでください。""",
}

デフォルトのサマリープロンプト

組み込みのサマリープロンプトは、Claudeに以下を含む構造化された継続サマリーを作成するよう指示します：

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

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

制限事項

サーバーサイドツール

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

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

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

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

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

回避策：

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

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

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

コンパクションの監視

コンパクションが発生するタイミングを追跡するためにログを有効にします：

import logging

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

# Logs will show:
# 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ベースの代替手段（一般的にはサーバーサイドコンパクションが推奨）

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

サーバーサイド戦略

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

ツール結果のクリア

思考ブロックのクリア

キャッシュヒットを最大化するには、keep: "all" を設定してすべての思考ブロックを保持してください。

コンテキスト編集はサーバーサイドで実行される

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

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

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

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

コンテキスト編集は以下で利用可能です：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for recent developments in AI"
            }
        ],
        "tools": [
            {
                "type": "web_search_20250305",
                "name": "web_search"
            }
        ],
        "context_management": {
            "edits": [
                {"type": "clear_tool_uses_20250919"}
            ]
        }
    }'

高度な設定

追加のパラメーターでツール結果クリアの動作をカスタマイズできます：

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ],
        "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"]
                }
            ]
        }
    }'

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

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [/* ... */],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

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

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

設定オプション	デフォルト	説明
`keep`	`{type: "thinking_turns", value: 1}`	思考ブロックを持つ最近のアシスタントターンをいくつ保持するかを定義します。最後のNターンを保持するには `{type: "thinking_turns", value: N}`（Nは0より大きい必要があります）を使用するか、すべての思考ブロックを保持するには `"all"` を使用します。

設定例：

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

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

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

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

戦略の組み合わせ

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

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

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[...],
    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},
            },
        ]
    },
)

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

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

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

Response

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // `clear_thinking_20251015` を使用する場合
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // `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": [
      // ...
    ]
  }
}

トークンカウント

curl https://api.anthropic.com/v1/messages/count_tokens \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-4-6",
        "messages": [
            {
                "role": "user",
                "content": "Continue our conversation..."
            }
        ],
        "tools": [...],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {
                        "type": "input_tokens",
                        "value": 30000
                    },
                    "keep": {
                        "type": "tool_uses",
                        "value": 5
                    }
                }
            ]
        }
    }'

Response

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

メモリツールとの使用

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

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

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

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    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 SDKで利用可能です。

コンパクションの仕組み

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

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

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

tool_runner 呼び出しに compaction_control を追加します：

import anthropic

client = anthropic.Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[
        {
            "role": "user",
            "content": "Analyze all the files in this directory and write a summary report.",
        }
    ],
    compaction_control={"enabled": True, "context_token_threshold": 100000},
)

for message in runner:
    print(f"使用トークン数: {message.usage.input_tokens}")

final = runner.until_done()

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

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

コンパクション前（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以上のやり取り ...
]

トークンがしきい値を超えると、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	いいえ	以下を参照	サマリー生成のカスタムプロンプト

トークンしきい値の選択

# メモリ制約のあるシナリオでより頻繁なコンパクション
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# より多くのコンテキストが必要な場合はより少ない頻度のコンパクション
compaction_control = {"enabled": True, "context_token_threshold": 150000}

サマリーに別のモデルを使用する

サマリー生成に高速または低コストのモデルを使用できます：

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

カスタムサマリープロンプト

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """これまでに実施した調査を要約してください。以下を含めてください：
- 参照したソースと主要な発見
- 回答された質問と残っている未知の事項
- 推奨される次のステップ

サマリーを <summary></summary> タグで囲んでください。""",
}

デフォルトのサマリープロンプト

組み込みのサマリープロンプトは、Claudeに以下を含む構造化された継続サマリーを作成するよう指示します：

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

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

制限事項

サーバーサイドツール

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

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

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

回避策：

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

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

コンパクションの監視

コンパクションが発生するタイミングを追跡するためにログを有効にします：

import logging

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

# Logs will show:
# 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）

コンパクションの仕組み

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

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

設定オプション

トークンしきい値の選択

サマリーに別のモデルを使用する

カスタムサマリープロンプト

デフォルトのサマリープロンプト

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

制限事項

サーバーサイドツール

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

コンパクションの監視

コンパクションを使用する場面