Compaction at a token threshold

原典: Compaction at a token threshold ／日本語版

一行要約

入力トークンが閾値に達したら API がリクエストの途中で自動的に要約し、compaction ブロックより前の内容をすべて捨てる方式で、呼び出し側がやることは「レスポンスを（compaction ブロックごと）次のリクエストに積み直す」ことだけ。使えるなら要求時方式を使えと概要ページ（compaction）は推している。

要点

プラットフォーム: Claude API / Claude Platform on AWS / Amazon Bedrock / Google Cloud / Microsoft Foundry（いずれも beta）。

対応モデル（原典の frontmatter）: claude-fable-5-1 / claude-mythos-5-1 / claude-fable-5 / claude-mythos-5 / claude-mythos-preview / claude-opus-5-5 / claude-opus-5 / claude-opus-4-8 / claude-opus-4-7 / claude-opus-4-6 / claude-sonnet-5 / claude-sonnet-4-6。要求時方式（compaction-on-demand）と違い、Bedrock でも使える。

Compaction extends the effective context length for long-running conversations and tasks by automatically summarizing older context when approaching the context window limit. It also keeps the active context small: as a conversation grows, response quality degrades, so compaction replaces older content with a concise summary.

compaction は、context window の上限に近づいたときに古い context を自動で要約することで、長時間の会話やタスクの実効的な context 長を延ばす。アクティブな context を小さく保つ役目もある。会話が大きくなるにつれて応答の質は落ちるので、compaction は古い内容を簡潔な要約に置き換える。

動作の4段階

Detects — input token が指定した閾値に達したことを検出する
Generates — 現在の会話の要約を生成する
Creates — 要約を含む compaction ブロックを作る
Continues — compact された context で応答を続ける

On subsequent requests, append the response to your messages. The API automatically drops all content blocks prior to the compaction block, continuing the conversation from the summary.

以降のリクエストでは、その応答をメッセージに追記せよ。API は、compaction ブロックより前のコンテンツブロックをすべて自動的に捨て、要約から会話を続ける。

呼び出し側の責務は1つだけ — レスポンスを（compaction ブロックを含めて）assistant ターンとして次のリクエストに積む。前方の削除は API がやる（元のメッセージを残したままでも、自分で落としてブロック以降だけを送ってもよい）。要求時方式とは向きが逆で、あちらはブロックが要約した範囲の「代わり」に先頭へ来る。

パラメータ

パラメータ	型	既定	説明
`type`	string	必須	`"compact_20260112"`
`trigger`	object	`{"type": "input_tokens", "value": 150000}`	発火条件。`input_tokens` が唯一のトリガー種別。`value` は最低 50,000 トークン
`pause_after_compaction`	boolean	`false`	要約を生成した直後に応答を止めるか
`instructions`	string	`null`	独自の要約プロンプト。指定すると既定のプロンプトを完全に置き換える

既定の要約プロンプトはモデルによって違う。 どれも <summary></summary> の中に、次の context window で作業を続けるのに要る情報を書かせる。Claude 5.1 以降のモデルで instructions を指定すると、要約は見えている会話だけから作られ、それより前の thinking ブロックは要約器の入力に入らない。

thinking は compaction ブロックを越えない（Fable 5.1 / Mythos 5.1 / Opus 5.5 / Sonnet 5.5）

On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, and Claude Sonnet 5.5, thinking blocks from before a compaction block aren’t carried forward, so the summary is all the model has of that earlier work.

Claude Fable 5.1・Claude Mythos 5.1・Claude Opus 5.5・Claude Sonnet 5.5 では、compaction ブロックより前の thinking ブロックは持ち越されない。だから、それ以前の作業についてモデルが持っているのは要約だけになる。

instructions を自分で書くなら、要約に何を残すべきかを明示する。

直近のターンを差し戻すとき（下の pause_after_compaction）も、Fable 5.1・Opus 5.5・Sonnet 5.5 では差し戻す assistant ターンから thinking / redacted_thinking を外すか、thinking-binding-controls-2026-08-01 を付けて thinking.block_binding.prefix_mismatch_behavior: "drop_block" を送る。これらは全履歴があったときに作られたので会話の検査（thinking）に通らず、検査が強制されている環境では 400 になる。 テキストとツールのブロックはそのままでよい。差し戻さずに全部を要約させれば、この問題は起きない。 Sonnet 5.5 では block_binding は thinking: {"type": "adaptive"} のときしか効かないので、between_tools ならブロックを外す（drop_block に頼らない）。

`pause_after_compaction` の使いどころ

true にすると、要約生成の直後に stop_reason == "compaction" で応答が止まる。このときレスポンスには compaction ブロックだけが入っている。呼び出し側はそれを assistant ターンとして積んでから、リクエストを続行する。止まっている間に、直近のメッセージや指示のメッセージを足せる（原典の例は、直前のやりとりと今の user メッセージの3件を要約させずに原文で残す）。

これを使うと総トークン予算の上限を自前で強制できる（SDK のみ）。compaction が起きた回数 × トリガー閾値で消費トークンを見積もり、予算を超えたら「作業をまとめて最終状態を要約せよ」という user メッセージを差し込む。

ブロックの扱い

長い会話では compaction が何度も起きる。最後のブロックが最終状態で、それより前を置き換える
ストリーミングでは一度に届く。 content_block_start の後に要約の全文を持った content_block_delta が1つだけ来て、content_block_stop で終わる（途中経過は流れない）
Python で client.messages を使ってブロックを自分でシリアライズするなら model_dump() をそのまま使わない。 text: null と citations: null が足され、400（Extra inputs are not permitted）で拒否される。to_dict() か model_dump(exclude_none=True) を使う（client.beta.messages なら問題ない）

usage の読み方（コスト集計を直す必要がある）

compaction が起きたリクエストの usage には iterations 配列が入り、要約生成のための呼び出しと実際のメッセージ生成が別項目として計上される。トップレベルの input_tokens はcompact 後の値（例: 23,000）で、iterations の compaction 項目にcompact 前の値（例: 180,000）が入る。

The top-level input_tokens and output_tokens do not include compaction iteration usage. They reflect the sum of all non-compaction iterations. To calculate total tokens consumed and billed for a request, sum across all entries in the usage.iterations array.

トップレベルの input_tokens と output_tokens は compaction の iteration の使用量を含まない。compaction 以外の iteration の合計である。リクエストで消費・課金されたトークンの総量を出すには、usage.iterations の全項目を合計せよ。

トップレベルの値でコストを追っていたなら、compaction を有効にした時点で集計を iterations の合計に変える。 beta を有効にすると compaction が起きなくても毎回 iterations が付く。compaction 項目が出るのは新しく compaction が起きたリクエストだけで、前のブロックを送り返すだけなら追加の費用はかからない。

併用

prompt caching と併用できる。system prompt の末尾に cache_control を置くと、compaction が起きても system prompt のキャッシュは生き残り、新しく書き込むのは要約だけで済む。compaction ブロックにも cache_control を置ける
server tool（web search など）を使うと、閾値は各サンプリング iteration の頭で検査されるので、1リクエストの中で compaction が何度も起きることがある
token counting エンドポイント（/v1/messages/count_tokens）は、プロンプト中の既存の compaction ブロックは適用するが、新しい compaction は起こさない。過去の compaction 後の実効トークン数を確かめるのに使える

既知の制限

要約するモデルは選べない。 リクエストで指定したモデルがそのまま要約にも使われる。安いモデルに要約させる手は無い
tools を定義していると要約に失敗することがある。 内部の要約ステップでモデルが要約を書かずにツールを呼んでしまい、compaction ブロックの content が null になる。防ぐには instructions に「ツールを呼ぶな、テキストだけで答えよ」と明記する

そのまま使える具体例

最小構成（Python）:

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-5-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
 
# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})

トリガー閾値を指定する:

{
  "context_management": {
    "edits": [
      {
        "type": "compact_20260112",
        "trigger": {
          "type": "input_tokens",
          "value": 150000
        }
      }
    ]
  }
}

要約の指示を差し替える（既定のプロンプトを完全に置き換える点に注意）:

{
  "context_management": {
    "edits": [
      {
        "type": "compact_20260112",
        "instructions": "Focus on preserving code snippets, variable names, and technical decisions."
      }
    ]
  }
}

tools を定義しているときに、要約中のツール呼び出しを防ぐ 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.

pause して続行する:

# Check if compaction triggered a pause
if response.stop_reason == "compaction":
    # Response contains only the compaction block
    messages.append({"role": "assistant", "content": response.content})
 
    # Continue the request
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

総トークン予算を強制する:

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-5-5",
    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})
 
    # Estimate total tokens consumed; prompt wrap-up if over budget
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

レスポンスの形:

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

usage の形（compact 前後が別項目。課金の合計は iterations を足す）:

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

原典で言及されている関連文書

compaction — 3方式の比較と選び方
compaction-on-demand — 要求時 compaction（ブロックの向きが逆）
effective-context-engineering-for-ai-agents — 長い context が劣化する理由と compaction の設計思想
prompt-caching — system prompt の末尾にブレークポイントを置く
thinking — 差し戻したターンの thinking が落ちる会話の検査
context-editing
context-windows

ai-docs

エクスプローラー

Compaction at a token threshold

一行要約

要点

動作の4段階

パラメータ

thinking は compaction ブロックを越えない（Fable 5.1 / Mythos 5.1 / Opus 5.5 / Sonnet 5.5）

`pause_after_compaction` の使いどころ

ブロックの扱い

usage の読み方（コスト集計を直す必要がある）

併用

既知の制限

そのまま使える具体例

原典で言及されている関連文書

目次

バックリンク

ai-docs

エクスプローラー

Compaction at a token threshold

一行要約

要点

動作の4段階

パラメータ

thinking は compaction ブロックを越えない（Fable 5.1 / Mythos 5.1 / Opus 5.5 / Sonnet 5.5）

pause_after_compaction の使いどころ

ブロックの扱い

usage の読み方（コスト集計を直す必要がある）

併用

既知の制限

そのまま使える具体例

原典で言及されている関連文書

目次

バックリンク

`pause_after_compaction` の使いどころ