ai-docs

Compaction

Properties1
tagscontext, api, agents, compaction, prompt-caching

6 min read

一行要約

会話が閾値に達したら API 側が自動で要約し、compaction ブロックより前の内容をすべて捨てるサーバサイド機構で、呼び出し側がやることは「レスポンスを（compaction ブロックごと）次のリクエストに積み直す」ことだけ。

要点

beta header: compact-2026-01-12

動作の4段階

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

On subsequent requests, append the response (including the compaction block) to your messages. The API automatically drops all content blocks prior to the compaction block, continuing from the summary. 以降のリクエストでは、その応答（compaction ブロックを含む）をメッセージに追記せよ。API はcompaction ブロックより前のコンテンツブロックをすべて自動的に捨て、要約から続きを進める。

呼び出し側の責務は1つだけ — レスポンスを（compaction ブロックを含めて）assistant ターンとして次のリクエストに積む。前方の削除は API がやる。

パラメータ

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

保持されるもの / 捨てられるもの

扱い
compaction ブロックとその後の内容保持。要約がタスクの文脈を引き継ぐ
compaction ブロックより前の全コンテンツブロックAPI が自動的に削除
直近メッセージを手元で残したい場合pause_after_compaction で止めて、メッセージリストを組み直す（例: 直近3件を要約の後ろに置き直す）

対応モデル

claude-fable-5 / claude-mythos-5 / claude-mythos-preview / claude-opus-5 / claude-opus-4-8 / claude-opus-4-7 / claude-opus-4-6 / claude-sonnet-5 / claude-sonnet-4-6

pause_after_compaction の使いどころ

true にすると、要約生成の直後に stop_reason == "compaction" で応答が止まる。このときレスポンスには compaction ブロックだけが入っている。呼び出し側はそれを assistant ターンとして積んでから、リクエストを続行する。

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

usage の読み方

compaction が起きたリクエストの usage には iterations 配列が入り、要約生成のための呼び出しと実際のメッセージ生成が別項目として計上される。

トップレベルの input_tokens はcompact 後の値（例: 23,000）で、iterations の compaction 項目にcompact 前の値（例: 180,000）が入る。

併用

  • prompt caching と併用できる。system prompt に cache_control を付けてキャッシュヒットを最大化する
  • token counting エンドポイント（/v1/messages/count_tokens）も context_management を受け付ける

そのまま使える具体例

最小構成（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",
    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."
      }
    ]
  }
}

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",
        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",
    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 前後が別項目）:

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

curl で有効化する:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: compact-2026-01-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "Help me build a website"}],
    "context_management": {"edits": [{"type": "compact_20260112"}]}
  }'

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

未取得の派生リンク

グラフビュー

バックリンク