コンテキスト編集

概要

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

コンテキスト編集を使用すると、会話履歴が増大するにつれて特定のコンテンツを選択的にクリアできます。これにより、コストを最適化し、コンテキストウィンドウの制限内に収めることができます。このページでは以下を説明します：

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

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

サーバーサイド戦略

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

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

ツール結果のクリア

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.5（claude-sonnet-4-5-20250929）
Claude Sonnet 4（claude-sonnet-4-20250514）
Claude Haiku 4.5（claude-haiku-4-5-20251001）

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

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

詳細設定

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

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

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

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

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

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

トークンカウント

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

Response

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

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

メモリツールとの併用

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

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

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

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

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

クライアントサイドコンパクション（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 を追加します：

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

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

コンパクション前（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": """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レスポンスは以下のように表示される場合があります：

{
  "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)

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

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

適したユースケース：

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

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

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

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

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

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 = 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"}
        ]
    }
)

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"Tokens used: {message.usage.input_tokens}")

final = runner.until_done()

概要

サーバーサイド戦略

ツール結果のクリア

思考ブロックのクリア

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

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

サポートされるモデル

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

詳細設定

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

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

戦略の組み合わせ

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

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

トークンカウント

メモリツールとの併用

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

コンパクションの仕組み

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

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

設定オプション

トークンしきい値の選択

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

カスタム要約プロンプト

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

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

制限事項

サーバーサイドツール

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

コンパクションの監視

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