トークンしきい値でのコンパクション
会話が設定したトークンしきい値に達したときに、通常のリクエスト内でAPIに古いコンテキストを自動的に要約させます。
「threshold compaction」（しきい値コンパクション）は、自動的な種類の「compaction」（コンパクション）です。通常のリクエストにトークンしきい値を設定すると、しきい値に達した時点で、APIがリクエストの途中で古いコンテキストを要約します。これは、要約を書き込むタイミングを自分で決めるオンデマンドコンパクションと並んでサポートされています（オンデマンドコンパクションを参照してください）。どちらを選ぶかについては、コンパクション方法の選択を参照してください。
コンパクションは、「context window」（コンテキストウィンドウ）の上限に近づいたときに古いコンテキストを自動的に要約することで、長時間実行される会話やタスクの実効コンテキスト長を拡張します。また、アクティブなコンテキストを小さく保ちます。会話が長くなるにつれて応答の品質は低下するため、コンパクションは古いコンテンツを簡潔な要約に置き換えます。
これは次のような場合に最適です：
- ユーザーに1つのチャットを長期間使用してもらいたい、チャットベースのマルチターン会話
- コンテキストウィンドウを超える可能性のある、多くのフォローアップ作業（多くの場合「tool use」（ツール使用））を必要とするタスク指向のプロンプト
コンパクションの仕組み
コンパクションが有効になっている場合、Claudeは会話が設定されたトークンしきい値に達すると、会話を自動的に要約します。APIは次の処理を行います：
- 入力トークンが指定したトリガーしきい値に達したことを検出します。
- 現在の会話の要約を生成します。
- 要約を含む
compactionブロックを作成します。 - コンパクションされたコンテキストで応答を続行します。
後続のリクエストでは、応答をメッセージに追加します。APIはcompactionブロックより前のすべてのコンテンツブロックを自動的に削除し、要約から会話を続行します。
基本的な使い方
Messages APIリクエストのcontext_management.editsにcompact_20260112戦略を追加して、コンパクションを有効にします。
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"}]},
)
# 会話を続けるため、レスポンス（compaction ブロックを含む）を追加します
messages.append({"role": "assistant", "content": response.content})パラメータ
| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
type | string | 必須 | "compact_20260112"である必要があります |
trigger | object | {"type": "input_tokens", "value": 150000} | コンパクションをトリガーするタイミング。input_tokensがサポートされている唯一のトリガータイプです。valueは50,000トークン以上である必要があります。 |
pause_after_compaction | boolean | false | コンパクション要約の生成後に一時停止するかどうか |
instructions | string | null | カスタムの要約プロンプト。指定した場合、デフォルトのプロンプトを完全に置き換えます。 |
トリガーの設定
triggerパラメータを使用して、コンパクションがトリガーされるタイミングを設定します：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
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": 150000},
}
]
},
)カスタム要約指示
デフォルトの要約プロンプトはモデルによって異なります。各デフォルトは、将来のコンテキストウィンドウでタスクを続行するために必要な情報を含む要約を<summary></summary>タグ内に書くようClaudeに指示します。たとえば、一部のモデルは次のプロンプトを使用します：
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パラメータを通じてカスタム指示を提供できます。カスタム指示はデフォルトのプロンプトを補足するものではありません。デフォルトのプロンプトを完全に置き換えます：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
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",
"instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
}
]
},
)Claude 5.1以降のモデルでは、カスタムinstructionsを含むリクエストは、表示されている会話のみから要約します。以前の思考ブロックは要約処理の入力には含まれません。
コンパクション後の一時停止
pause_after_compactionを使用すると、コンパクション要約の生成後にAPIを一時停止できます。これにより、APIが応答を続行する前に、追加のコンテンツブロック（最近のメッセージや特定の指示指向のメッセージの保持など）を追加できます。
有効にすると、APIはコンパクションブロックの生成後にcompaction停止理由を含むメッセージを返します：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
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", "pause_after_compaction": True}]
},
)
# compaction（コンパクション）によって一時停止が発生したかを確認します
if response.stop_reason == "compaction":
# レスポンスには compaction ブロックのみが含まれます
messages.append({"role": "assistant", "content": response.content})
# リクエストを続行します
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"}]},
)合計トークン予算の適用
モデルが多数のツール使用の反復を伴う長いタスクに取り組む場合、合計トークン消費量が大幅に増加する可能性があります。pause_after_compactionとコンパクションカウンターを組み合わせることで、累積使用量を推定し、予算に達したらタスクを適切に終了させることができます。
この例はSDK言語でのみ掲載されています。この例の価値は、リクエストを取り巻く予算追跡ロジックにあるためです。生のリクエストは、トリガーの設定のtriggerとコンパクション後の一時停止のpause_after_compactionを組み合わせたものです。
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-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})
# 消費トークンの合計を見積もり、予算を超えた場合はまとめに入るよう促します
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ブロックを返します。
長時間実行される会話では、複数回のコンパクションが発生する場合があります。最後のコンパクションブロックはプロンプトの最終状態を反映し、それより前のコンテンツを生成された要約で置き換えます。
{
"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に返す必要があります。最も簡単な方法は、応答コンテンツ全体をメッセージに追加することです：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
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"}]},
)
# compaction ブロックを含むレスポンスを受信した後
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-5-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)Pythonでは、このページのサンプルと同様にclient.beta.messagesを使用してください。client.messagesを呼び出してブロックを自分でシリアライズする場合、単純なmodel_dump()ではcompactionブロックにtext: nullとcitations: nullが追加されます。その場合、APIは400エラー（Extra inputs are not permitted）でリクエストを拒否します。代わりにto_dict()またはmodel_dump(exclude_none=True)を使用してください。要約から続けるでも、オンデマンドコンパクションについて同じアドバイスをしています。
APIがcompactionブロックを受け取ると、それより前のすべてのコンテンツブロックは無視されます。次のいずれかを選択できます：
- 元のメッセージをリストに残し、コンパクションされたコンテンツの削除をAPIに任せる
- コンパクションされたメッセージを手動で削除し、コンパクションブロック以降のみを含める
Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5では、compactionブロックより前の思考ブロックは引き継がれないため、要約がモデルにとってその以前の作業に関する唯一の情報となります。独自のinstructionsを書く場合は、要約に何を保持する必要があるかをモデルに伝えてください。コンパクションの要約で保持すべき内容をモデルに伝えるを参照してください。
ストリーミング
コンパクションブロックは、テキストブロックとは異なる方法で「streaming」（ストリーミング）されます。content_block_startイベントを受信し、続いて完全な要約コンテンツを含む単一のcontent_block_delta（中間的なストリーミングなし）を受信し、その後content_block_stopイベントを受信します。
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
with client.beta.messages.stream(
betas=["compact-2026-01-12"],
model="claude-opus-5-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
for event in stream:
match event.type:
case "content_block_start":
block = event.content_block
match block.type:
case "compaction":
print("Compaction started...")
case "text":
print("Text response started...")
case "content_block_delta":
delta = event.delta
match delta.type:
case "compaction_delta":
print(f"Compaction complete: {len(delta.content or '')} chars")
case "text_delta":
print(delta.text, end="", flush=True)
# 蓄積された最終メッセージを取得します
message = stream.get_final_message()
messages.append({"role": "assistant", "content": message.content})プロンプトキャッシング
コンパクションは「prompt caching」（プロンプトキャッシング）と適切に連携します。コンパクションブロックにcache_controlブレークポイントを追加して、要約されたコンテンツをキャッシュできます。
{
"role": "assistant",
"content": [
{
"type": "compaction",
"content": "[summary text]",
"cache_control": { "type": "ephemeral" }
},
{
"type": "text",
"text": "Based on our conversation..."
}
]
}システムプロンプトでキャッシュヒットを最大化する
コンパクションが発生すると、要約はキャッシュに書き込む必要がある新しいコンテンツになります。追加のキャッシュブレークポイントがない場合、これによりキャッシュされた「system prompt」（システムプロンプト）も無効になり、コンパクション要約とともに再キャッシュする必要が生じます。
キャッシュヒット率を最大化するには、システムプロンプトの末尾にcache_controlブレークポイントを追加します。これにより、システムプロンプトが会話とは別にキャッシュされるため、コンパクションが発生したときに次のようになります：
- システムプロンプトのキャッシュは有効なままで、キャッシュから読み取られます
- 新しいキャッシュエントリとして書き込む必要があるのはコンパクション要約のみです
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5-5",
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"}]},
)これにより、会話全体を通じて複数回のコンパクションイベントが発生しても、長いシステムプロンプトがキャッシュされたまま維持されます。
使用量の理解
コンパクションには追加のサンプリングステップが必要であり、これは「rate limit」（レート制限）と課金に影響します。APIは応答で詳細な使用量情報を返します：
{
"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反復と完全に一致します。最後の反復のトークン数は、コンパクション後の実効コンテキストサイズを反映します。
他の機能との組み合わせ
サーバーツール
サーバーツール（ウェブ検索など）を使用する場合、コンパクショントリガーは各サンプリング反復の開始時にチェックされます。トリガーしきい値と生成される出力の量によっては、1回のリクエスト内でコンパクションが複数回発生する場合があります。
トークンカウント
トークンカウントエンドポイント（/v1/messages/count_tokens）は、プロンプト内の既存のcompactionブロックを適用しますが、新しいコンパクションはトリガーしません。以前のコンパクション後の実効トークン数を確認するために使用してください：
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
betas=["compact-2026-01-12"],
model="claude-opus-5-5",
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-5-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 100000},
}
]
},
)
# レスポンスを追加します（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"))
# 会話が必要とする限り chat() を呼び出し続けますClaude Fable 5.1およびClaude Opus 5.5では、コンパクションブロックの後に再挿入するアシスタントターンからthinkingブロックとredacted_thinkingブロックを削除するか、thinking-binding-controls-2026-08-01 ベータヘッダーとともにthinking.block_binding.prefix_mismatch_behavior: "drop_block"を送信してください。これらのブロックは完全な履歴が存在する状態で生成されたため、会話チェックに合格しなくなります。チェックが適用される場合、継続リクエストは400エラーで拒否されます。保持されたテキストブロックとツールブロックはそのままで構いません。以前のターンを再挿入せずにAPIにすべてを要約させれば、この問題を回避できます。
pause_after_compactionを使用して、直前のやり取りと現在のユーザーメッセージ（合計3つのメッセージ）を要約せずにそのまま保持する例を次に示します：
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-5-5",
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-5-5",
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"))
# 会話が必要とする限り chat() を呼び出し続けます現在の制限事項
-
要約には同じモデルを使用： リクエストで指定したモデルが要約に使用されます。要約に別の（たとえば、より安価な）モデルを使用するオプションはありません。
-
ツールが定義されている場合、コンパクションが失敗する可能性がある： リクエストに
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.
次のステップ
コンテキスト編集を使用して、会話の拡大に合わせて会話コンテキストを自動的に管理します。
コンテキストウィンドウのサイズと管理戦略について学びます。
バックグラウンドスレッドとプロンプトキャッシングを使用した即時のセッションメモリコンパクションにより、長時間実行される会話を管理する実践的な実装を紹介します。
Compatibility
| Supported models |
|
|---|---|
| Supported platforms |
|
Was this page helpful?