コンテキスト編集

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.

概要

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

コンテキスト編集により、会話履歴の成長に伴い、特定のコンテンツを選択的にクリアできます。コストの最適化と制限内の維持を超えて、これは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ブロックを管理します。この戦略は思考保持に対する制御を提供します。推論の連続性を維持するためにより多くの思考ブロックを保持するか、コンテキストスペースを節約するためにより積極的にクリアするかを選択できます。

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

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

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

コンテキスト編集はサーバー側で発生します

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

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

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

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

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

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

ツール結果クリア使用法

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

高度な設定

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

シンキングブロッククリアリングの使用方法

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

シンキングブロッククリアリングの設定オプション

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

設定オプション	デフォルト	説明
`keep`	`{type: "thinking_turns", value: 1}`	保持する最近のアシスタントターン（シンキングブロック付き）の数を定義します。`{type: "thinking_turns", value: N}`を使用します。ここでNは0より大きい値で、最後のNターンを保持するか、`"all"`を使用してすべてのシンキングブロックを保持します。

設定例：

最後の3つのアシスタントターンからシンキングブロックを保持：

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

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

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

戦略の組み合わせ

シンキングブロッククリアリングとツール結果クリアリングを一緒に使用できます：

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

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

設定オプション	デフォルト	説明
`trigger`	100,000入力トークン	コンテキスト編集戦略がいつアクティブになるかを定義します。プロンプトがこのしきい値を超えると、クリアリングが開始されます。この値は`input_tokens`または`tool_uses`のいずれかで指定できます。
`keep`	3ツール使用	クリアリング後に保持する最近のツール使用/結果ペアの数を定義します。APIは最も古いツール相互作用を最初に削除し、最も最近のものを保持します。
`clear_at_least`	なし	戦略がアクティブになるたびに少なくともクリアされるトークンの最小数を保証します。APIが指定された量以上をクリアできない場合、戦略は適用されません。これはコンテキストクリアリングがプロンプトキャッシュを破る価値があるかどうかを判断するのに役立ちます。
`exclude_tools`	なし	ツール使用と結果がクリアされるべきではないツール名のリスト。重要なコンテキストを保持するのに便利です。
`clear_tool_inputs`	`false`

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

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

Output

{
  "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": [
      // ...
    ]
  }
}

トークンカウント

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

Output

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

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

メモリツールとの組み合わせ

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

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

重要なコンテキストの保存: Claudeはツール結果から重要な情報をメモリファイルに書き込むことができ、その結果がクリアされる前に保存できます
長時間実行されるワークフローの維持: 情報を永続的なストレージにオフロードすることで、コンテキスト制限を超えるエージェントワークフローを有効にします
必要に応じた情報へのアクセス: Claudeは以前クリアされた情報をメモリファイルから検索でき、すべてをアクティブなコンテキストウィンドウに保持する必要がありません

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

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

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

クライアント側の圧縮（SDK）

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

圧縮は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を追加して、トークン使用量が閾値を超えた場合の自動要約を有効にします。

圧縮中に何が起こるか

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

圧縮前（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	いいえ	以下を参照	要約生成のカスタムプロンプト

トークン閾値の選択

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

# More frequent compaction for memory-constrained scenarios
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Less frequent compaction when you need more context
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": """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.""",
}

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

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

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

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

制限事項

サーバー側ツール

圧縮はウェブ検索やウェブフェッチなどのサーバー側ツールを使用する場合、特別な考慮が必要です。

サーバー側ツールを使用する場合、SDKはトークン使用量を誤って計算し、圧縮が間違ったタイミングでトリガーされる可能性があります。

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

Output

{
  "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は要約から再開した後にツール呼び出しを再発行します。

圧縮の監視

圧縮がいつトリガーされるかを理解することは、閾値を調整し、予期された動作を検証するのに役立ちます。

圧縮を使用する場合

適切なユースケース：

多くのファイルまたはデータソースを処理する長時間実行されるエージェントタスク
大量の情報を蓄積する研究ワークフロー
明確で測定可能な進捗を持つ複数ステップのタスク
会話の外で永続化するアーティファクト（ファイル、レポート）を生成するタスク

理想的でないユースケース：

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

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": 16000,
        "messages": [{"role": "user", "content": "Hello"}],
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10000
        },
        "context_management": {
            "edits": [
                {
                    "type": "clear_thinking_20251015",
                    "keep": {
                        "type": "thinking_turns",
                        "value": 2
                    }
                }
            ]
        }
    }'

ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
  type: enabled
  budget_tokens: 10000
messages:
  - role: user
    content: Hello
tools:
  - type: web_search_20250305
    name: web_search
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
YAML

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
                    }
                }
            ]
        }
    }'

ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
messages:
  - role: user
    content: Hello
tools:
  - type: memory_20250818
    name: memory
context_management:
  edits:
    - type: clear_tool_uses_20250919
YAML

概要

サーバー側戦略

ツール結果クリア

思考ブロッククリア

コンテキスト編集はサーバー側で発生します

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

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

ツール結果クリア使用法

高度な設定

シンキングブロッククリアリングの使用方法

シンキングブロッククリアリングの設定オプション

戦略の組み合わせ

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

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

トークンカウント

メモリツールとの組み合わせ

クライアント側の圧縮（SDK）

圧縮の仕組み

圧縮の使用

圧縮中に何が起こるか

設定オプション

トークン閾値の選択

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

カスタム要約プロンプト

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

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

制限事項

サーバー側ツール

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

圧縮の監視

圧縮を使用する場合