コンパクション

この機能はZero Data Retention（ZDR）の対象です。組織がZDR契約を締結している場合、この機能を通じて送信されたデータは、APIレスポンスが返された後に保存されることはありません。

サーバーサイドコンパクションは、長時間実行される会話やエージェントワークフローにおけるコンテキスト管理の推奨戦略です。最小限の統合作業でコンテキスト管理を自動的に処理します。

「compaction」（コンパクション）は、コンテキストウィンドウの上限に近づいたときに古いコンテキストを自動的に要約することで、長時間実行される会話やタスクの実効的なコンテキスト長を拡張します。これは単にトークン上限を超えないようにするためだけのものではありません。会話が長くなるにつれて、モデルは履歴全体にわたって焦点を維持することが難しくなります。コンパクションは、古くなったコンテンツを簡潔な要約に置き換えることで、アクティブなコンテキストを焦点の定まった高パフォーマンスな状態に保ちます。

長いコンテキストがなぜ劣化するのか、そしてコンパクションがどのように役立つのかについて詳しくは、 Effective context engineeringを参照してください。

これは以下のような場合に最適です。

ユーザーが1つのチャットを長期間使用することを想定した、チャットベースのマルチターン会話
コンテキストウィンドウを超える可能性のある多くのフォローアップ作業（多くの場合ツール使用）を必要とするタスク指向のプロンプト

コンパクションはベータ版です。この機能を使用するには、APIリクエストにベータヘッダー compact-2026-01-12 を含めてください。

対応モデル

コンパクションは以下のモデルでサポートされています。

Claude Fable 5（claude-fable-5）
Claude Mythos 5（claude-mythos-5）
Claude Mythos Preview（claude-mythos-preview）
Claude Opus 4.8（claude-opus-4-8）
Claude Opus 4.7（claude-opus-4-7）
Claude Opus 4.6（claude-opus-4-6）
Claude Sonnet 4.6（claude-sonnet-4-6）

コンパクションの仕組み

コンパクションが有効になっている場合、Claudeは会話が設定されたトークンしきい値に近づくと自動的に会話を要約します。APIは以下を実行します。

入力トークンが指定されたトリガーしきい値を超えたことを検出します。
現在の会話の要約を生成します。
要約を含む compaction ブロックを作成します。
コンパクションされたコンテキストでレスポンスを続行します。

後続のリクエストでは、レスポンスをメッセージに追加します。APIは compaction ブロックより前のすべてのメッセージブロックを自動的に削除し、要約から会話を続行します。

コンパクションプロセスを示すフロー図：入力トークンがトリガーしきい値を超えると、Claudeはコンパクションブロック内に要約を生成し、コンパクションされたコンテキストでレスポンスを続行します

基本的な使用方法

Messages APIリクエストの context_management.edits に compact_20260112 戦略を追加することで、コンパクションを有効にします。

パラメータ

パラメータ	型	デフォルト	説明
`type`	string	必須	`"compact_20260112"` である必要があります
`trigger`	object	150,000トークン	コンパクションをトリガーするタイミング。最低50,000トークンである必要があります。
`pause_after_compaction`	boolean	`false`	コンパクション要約の生成後に一時停止するかどうか
`instructions`	string	`null`	カスタム要約プロンプト。指定された場合、デフォルトのプロンプトを完全に置き換えます。

トリガー設定

trigger パラメータを使用して、コンパクションがトリガーされるタイミングを設定します。

カスタム要約指示

デフォルトでは、コンパクションは以下の要約プロンプトを使用します。

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

instructions パラメータを介してカスタム指示を提供することで、このプロンプトを完全に置き換えることができます。カスタム指示はデフォルトを補完するものではなく、完全に置き換えます。

コンパクション後の一時停止

pause_after_compaction を使用すると、コンパクション要約の生成後にAPIを一時停止できます。これにより、APIがレスポンスを続行する前に、追加のコンテンツブロック（最近のメッセージや特定の指示指向のメッセージの保持など）を追加できます。

有効にすると、APIはコンパクションブロックの生成後に compaction 停止理由を持つメッセージを返します。

合計トークン予算の適用

モデルが多くのツール使用イテレーションを伴う長いタスクに取り組む場合、合計トークン消費量が大幅に増加する可能性があります。pause_after_compaction をコンパクションカウンターと組み合わせることで、累積使用量を推定し、予算に達したらタスクを適切に終了させることができます。

Python

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # 消費トークンの合計を推定し、予算超過なら終了を促す
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

コンパクションブロックの操作

コンパクションがトリガーされると、APIはアシスタントレスポンスの先頭に compaction ブロックを返します。

長時間実行される会話では、複数のコンパクションが発生する場合があります。最後のコンパクションブロックがプロンプトの最終状態を反映し、それより前のコンテンツを生成された要約に置き換えます。

Output

{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

コンパクションブロックの返送

短縮されたプロンプトで会話を続行するには、後続のリクエストで compaction ブロックをAPIに返す必要があります。最も簡単な方法は、レスポンスコンテンツ全体をメッセージに追加することです。

APIが compaction ブロックを受信すると、それより前のすべてのコンテンツブロックは無視されます。以下のいずれかの方法を選択できます。

元のメッセージをリストに保持し、コンパクションされたコンテンツの削除をAPIに任せる
コンパクションされたメッセージを手動で削除し、コンパクションブロック以降のみを含める

ストリーミング

コンパクションを有効にしてレスポンスをストリーミングする場合、コンパクションが開始されると content_block_start イベントを受信します。コンパクションブロックはテキストブロックとは異なる方法でストリーミングされます。content_block_start イベントを受信し、その後に完全な要約コンテンツを含む単一の content_block_delta（中間ストリーミングなし）、そして content_block_stop イベントを受信します。

プロンプトキャッシング

コンパクションはプロンプトキャッシングと適切に連携します。コンパクションブロックに cache_control ブレークポイントを追加して、要約されたコンテンツをキャッシュできます。元のコンパクションされたコンテンツは無視されます。

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

システムプロンプトによるキャッシュヒットの最大化

コンパクションが発生すると、要約はキャッシュに書き込む必要がある新しいコンテンツになります。追加のキャッシュブレークポイントがない場合、これによりキャッシュされたシステムプロンプトも無効化され、コンパクション要約とともに再キャッシュする必要が生じます。

キャッシュヒット率を最大化するには、システムプロンプトの末尾に cache_control ブレークポイントを追加します。これにより、システムプロンプトが会話とは別にキャッシュされるため、コンパクションが発生した場合でも以下のようになります。

システムプロンプトのキャッシュは有効なままで、キャッシュから読み取られます
コンパクション要約のみが新しいキャッシュエントリとして書き込まれる必要があります

このアプローチは、長いシステムプロンプトに特に有益です。会話全体で複数のコンパクションイベントが発生しても、システムプロンプトはキャッシュされたままになります。

使用量の理解

コンパクションには追加のサンプリングステップが必要であり、これはレート制限と課金に影響します。APIはレスポンスで詳細な使用量情報を返します。

Output

{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

iterations 配列は、各サンプリングイテレーションの使用量を示します。コンパクションが発生すると、compaction イテレーションの後にメインの message イテレーションが表示されます。この例では、非コンパクションイテレーションが1つしかないため、トップレベルの input_tokens と output_tokens は message イテレーションと正確に一致します。最後のイテレーションのトークン数は、コンパクション後の実効コンテキストサイズを反映しています。

トップレベルの input_tokens と output_tokens には、コンパクションイテレーションの使用量は含まれません。これらはすべての非コンパクションイテレーションの合計を反映しています。リクエストで消費され課金される合計トークン数を計算するには、usage.iterations 配列のすべてのエントリを合計してください。

これまでコスト追跡や監査のために usage.input_tokens と usage.output_tokens に依存していた場合、コンパクションが有効なときは usage.iterations 全体を集計するように追跡ロジックを更新する必要があります。iterations 配列は、リクエスト中に新しいコンパクションがトリガーされた場合にのみ設定されます。以前の compaction ブロックを再適用しても追加のコンパクションコストは発生せず、その場合はトップレベルの使用量フィールドが正確なままです。

他の機能との組み合わせ

サーバーツール

サーバーツール（Web検索など）を使用する場合、コンパクショントリガーは各サンプリングイテレーションの開始時にチェックされます。トリガーしきい値と生成される出力量に応じて、単一のリクエスト内でコンパクションが複数回発生する場合があります。

トークンカウント

トークンカウントエンドポイント（/v1/messages/count_tokens）は、プロンプト内の既存の compaction ブロックを適用しますが、新しいコンパクションはトリガーしません。以前のコンパクション後の実効トークン数を確認するために使用してください。

例

以下は、コンパクションを使用した長時間実行される会話の完全な例です。

以下は、pause_after_compaction を使用して、直前のやり取りと現在のユーザーメッセージ（合計3つのメッセージ）を要約せずにそのまま保持する例です。

現在の制限事項

要約に同じモデルを使用： リクエストで指定されたモデルが要約に使用されます。要約に別の（たとえば、より安価な）モデルを使用するオプションはありません。
ツールが定義されている場合、コンパクションが失敗する可能性があります： リクエストに tools が含まれている場合、モデルは内部の要約ステップ中に要約を書く代わりにツールを呼び出すことがあります。これが発生すると、レスポンスには content: null を持つ compaction ブロックが含まれます。これを防ぐには、instructions に、モデルにツールを呼び出さないよう明示的に指示するプロンプトを設定してください。例：
```
Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
```

次のステップ

セッションメモリコンパクションクックブック

バックグラウンドスレッディングとプロンプトキャッシングを使用した即時セッションメモリコンパクションで長時間実行される会話を管理する実践的な実装を探索します。

コンテキストウィンドウ

コンテキストウィンドウのサイズと管理戦略について学びます。

コンテキスト編集

ツール結果のクリアや思考ブロックのクリアなど、会話コンテキストを管理するための他の戦略を探索します。

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# 会話を継続するためにレスポンス（圧縮ブロックを含む）を追加します
messages.append({"role": "assistant", "content": response.content})

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# コンパクションが一時停止をトリガーしたか確認
if response.stop_reason == "compaction":
    # レスポンスにはコンパクションブロックのみが含まれます
    messages.append({"role": "assistant", "content": response.content})

    # リクエストを続行
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# 圧縮ブロックを含むレスポンスを受信した後
messages.append({"role": "assistant", "content": response.content})

# 会話を続ける
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

        elif event.type == "content_block_delta":
            if event.delta.type == "compaction_delta":
                print(f"Compaction complete: {len(event.delta.content or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # 最終的に蓄積されたメッセージを取得
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-4-8",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # レスポンスを追加（圧縮ブロックは自動的に含まれます）
    messages.append({"role": "assistant", "content": response.content})

    # テキストコンテンツを返す
    return next(block.text for block in response.content if block.type == "text")


# 長い会話を実行
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... 必要なだけ続ける

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # コンパクションが発生して一時停止したかを確認
    if response.stop_reason == "compaction":
        # レスポンスからコンパクションブロックを取得
        compaction_block = response.content[0]

        # 直前のやり取りと現在のユーザーメッセージ（3件）を保持
        # コンパクションブロックの後にそれらを含めることで実現
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # 新しいメッセージリストを構築：コンパクション + 保持したメッセージ
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # コンパクション済みコンテキストと保持したメッセージでリクエストを続行
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-8",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # コンパクションを反映するようにメッセージリストを更新
        messages.clear()
        messages.extend(messages_after_compaction)

    # 最終レスポンスを追加
    messages.append({"role": "assistant", "content": response.content})

    # テキストコンテンツを返す
    return next(block.text for block in response.content if block.type == "text")


# 長い会話を実行
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# ... 必要なだけ続行

対応モデル

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

基本的な使用方法

パラメータ

トリガー設定

カスタム要約指示

コンパクション後の一時停止

合計トークン予算の適用

コンパクションブロックの操作

コンパクションブロックの返送

ストリーミング

プロンプトキャッシング

システムプロンプトによるキャッシュヒットの最大化

使用量の理解

他の機能との組み合わせ

サーバーツール

トークンカウント

例

現在の制限事項

次のステップ

対応モデル

コンパクションの仕組み

基本的な使用方法

パラメータ

トリガー設定

カスタム要約指示

コンパクション後の一時停止

合計トークン予算の適用

コンパクションブロックの操作

コンパクションブロックの返送

ストリーミング

プロンプトキャッシング

システムプロンプトによるキャッシュヒットの最大化

使用量の理解

他の機能との組み合わせ

サーバーツール

トークンカウント

例

現在の制限事項

次のステップ