Compaction pada ambang batas token
Biarkan API meringkas konteks lama secara otomatis, di dalam permintaan biasa, ketika percakapan mencapai ambang batas token yang Anda tetapkan.
"Threshold compaction" (pemadatan berbasis ambang batas) adalah jenis "compaction" (pemadatan) yang otomatis: Anda menetapkan "token threshold" (ambang batas token) pada permintaan biasa Anda, dan API meringkas konteks lama di tengah permintaan begitu ambang batas tersebut tercapai. Fitur ini didukung bersama compaction sesuai permintaan, di mana Anda yang memutuskan kapan ringkasan ditulis (lihat Compaction sesuai permintaan). Untuk memilih di antara keduanya, lihat Pilih cara melakukan compaction.
Compaction memperluas panjang konteks efektif untuk percakapan dan tugas yang berjalan lama dengan meringkas konteks lama secara otomatis saat mendekati batas "context window" (jendela konteks). Compaction juga menjaga konteks aktif tetap kecil: seiring percakapan bertambah panjang, kualitas respons menurun, sehingga compaction menggantikan konten lama dengan ringkasan yang padat.
Ini ideal untuk:
- Percakapan multi-giliran berbasis chat di mana Anda ingin pengguna menggunakan satu chat dalam jangka waktu yang lama
- Prompt berorientasi tugas yang memerlukan banyak pekerjaan lanjutan (sering kali berupa "tool use" (penggunaan alat)) yang mungkin melebihi jendela konteks
Cara kerja compaction
Ketika compaction diaktifkan, Claude secara otomatis meringkas percakapan Anda ketika mencapai ambang batas token yang dikonfigurasi. API akan:
- Mendeteksi ketika token input mencapai ambang batas pemicu yang Anda tentukan.
- Menghasilkan ringkasan dari percakapan saat ini.
- Membuat blok
compactionyang berisi ringkasan tersebut. - Melanjutkan respons dengan konteks yang telah dipadatkan.
Pada permintaan berikutnya, tambahkan respons ke pesan Anda. API secara otomatis membuang semua blok konten sebelum blok compaction, dan melanjutkan percakapan dari ringkasan.
Penggunaan dasar
Aktifkan compaction dengan menambahkan strategi compact_20260112 ke context_management.edits dalam permintaan Messages API Anda.
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"}]},
)
# Tambahkan respons (termasuk blok compaction apa pun) untuk melanjutkan percakapan
messages.append({"role": "assistant", "content": response.content})Parameter
| Parameter | Tipe | Default | Deskripsi |
|---|---|---|---|
type | string | Wajib | Harus berupa "compact_20260112" |
trigger | object | {"type": "input_tokens", "value": 150000} | Kapan compaction dipicu. input_tokens adalah satu-satunya tipe pemicu yang didukung. value harus minimal 50.000 token. |
pause_after_compaction | boolean | false | Apakah akan berhenti sejenak setelah menghasilkan ringkasan compaction |
instructions | string | null | Prompt peringkasan kustom. Sepenuhnya menggantikan prompt default jika diberikan. |
Konfigurasi pemicu
Konfigurasikan kapan compaction dipicu menggunakan parameter 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},
}
]
},
)Instruksi peringkasan kustom
Prompt peringkasan default bervariasi menurut model. Setiap prompt default menginstruksikan Claude untuk menulis ringkasan di dalam tag <summary></summary> yang berisi informasi yang diperlukan untuk melanjutkan tugas dalam jendela konteks berikutnya. Sebagai contoh, beberapa model menggunakan prompt berikut:
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.Anda dapat memberikan instruksi kustom melalui parameter instructions. Instruksi kustom tidak melengkapi prompt default. Instruksi tersebut menggantikannya sepenuhnya:
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.",
}
]
},
)Pada model Claude 5.1 dan yang lebih baru, permintaan dengan instructions kustom hanya meringkas dari percakapan yang terlihat: blok thinking sebelumnya tidak menjadi bagian dari input peringkas.
Berhenti sejenak setelah compaction
Gunakan pause_after_compaction untuk menghentikan sejenak API setelah menghasilkan ringkasan compaction. Ini memungkinkan Anda menambahkan blok konten tambahan (seperti mempertahankan pesan terbaru atau pesan berorientasi instruksi tertentu) sebelum API melanjutkan respons.
Ketika diaktifkan, API mengembalikan pesan dengan stop reason compaction setelah menghasilkan blok 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}]
},
)
# Periksa apakah compaction (pemadatan) memicu jeda
if response.stop_reason == "compaction":
# Respons hanya berisi blok compaction
messages.append({"role": "assistant", "content": response.content})
# Lanjutkan permintaan
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"}]},
)Menerapkan anggaran token total
Ketika model mengerjakan tugas panjang dengan banyak iterasi penggunaan alat, total konsumsi token dapat bertambah secara signifikan. Anda dapat menggabungkan pause_after_compaction dengan penghitung compaction untuk memperkirakan penggunaan kumulatif dan menyelesaikan tugas dengan baik begitu anggaran tercapai.
Contoh ini hanya muncul dalam bahasa SDK: nilainya terletak pada logika pelacakan anggaran di sekitar permintaan. Permintaan mentahnya menggabungkan trigger dari Konfigurasi pemicu dengan pause_after_compaction dari Berhenti sejenak setelah 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})
# Perkirakan total token yang terpakai; minta model menyelesaikan jika melebihi anggaran
if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
messages.append(
{
"role": "user",
"content": "Please wrap up your current work and summarize the final state.",
}
)Bekerja dengan blok compaction
Ketika compaction dipicu, API mengembalikan blok compaction di awal respons asisten.
Percakapan yang berjalan lama dapat menghasilkan beberapa compaction. Blok compaction terakhir mencerminkan status akhir prompt, menggantikan konten sebelumnya dengan ringkasan yang dihasilkan.
{
"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..."
}
]
}Mengirimkan kembali blok compaction
Anda harus mengirimkan kembali blok compaction ke API pada permintaan berikutnya untuk melanjutkan percakapan dengan prompt yang telah dipersingkat. Pendekatan paling sederhana adalah menambahkan seluruh konten respons ke pesan Anda:
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"}]},
)
# Setelah menerima respons yang berisi blok compaction
messages.append({"role": "assistant", "content": response.content})
# Lanjutkan percakapan
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"}]},
)Di Python, gunakan client.beta.messages, seperti yang dilakukan contoh-contoh di halaman ini. Jika Anda memanggil client.messages dan melakukan serialisasi blok sendiri, model_dump() biasa akan menambahkan text: null dan citations: null ke blok compaction. API kemudian menolak permintaan tersebut dengan error 400 (Extra inputs are not permitted). Sebagai gantinya, gunakan to_dict() atau model_dump(exclude_none=True). Melanjutkan dari ringkasan memberikan saran yang sama untuk compaction sesuai permintaan.
Ketika API menerima blok compaction, semua blok konten sebelumnya diabaikan. Anda dapat memilih untuk:
- Mempertahankan pesan asli dalam daftar Anda dan membiarkan API menangani penghapusan konten yang telah dipadatkan
- Membuang pesan yang telah dipadatkan secara manual dan hanya menyertakan blok compaction dan seterusnya
Pada Claude Fable 5.1, Claude Mythos 5.1, dan Claude Opus 5.5, blok thinking dari sebelum blok compaction tidak dibawa ke depan, sehingga ringkasan adalah satu-satunya yang dimiliki model dari pekerjaan sebelumnya tersebut. Jika Anda menulis instructions sendiri, beri tahu model apa yang harus dipertahankan dalam ringkasan; lihat Beri tahu model apa yang harus dipertahankan dalam ringkasan compaction.
Streaming
Blok compaction di-stream secara berbeda dari blok teks. Anda menerima event content_block_start, diikuti oleh satu content_block_delta dengan konten ringkasan lengkap (tanpa streaming bertahap), lalu event 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)
# Dapatkan pesan akhir yang telah terakumulasi
message = stream.get_final_message()
messages.append({"role": "assistant", "content": message.content})Caching prompt
Compaction bekerja dengan baik bersama "prompt caching" (caching prompt). Anda dapat menambahkan breakpoint cache_control pada blok compaction untuk melakukan cache terhadap konten yang telah diringkas.
{
"role": "assistant",
"content": [
{
"type": "compaction",
"content": "[summary text]",
"cache_control": { "type": "ephemeral" }
},
{
"type": "text",
"text": "Based on our conversation..."
}
]
}Memaksimalkan cache hit dengan prompt sistem
Ketika compaction terjadi, ringkasan menjadi konten baru yang perlu ditulis ke cache. Tanpa breakpoint cache tambahan, hal ini juga akan membatalkan "system prompt" (prompt sistem) yang telah di-cache, sehingga prompt tersebut harus di-cache ulang bersama ringkasan compaction.
Untuk memaksimalkan tingkat cache hit, tambahkan breakpoint cache_control di akhir prompt sistem Anda. Ini menjaga prompt sistem tetap di-cache secara terpisah dari percakapan, sehingga ketika compaction terjadi:
- Cache prompt sistem tetap valid dan dibaca dari cache
- Hanya ringkasan compaction yang perlu ditulis sebagai entri cache baru
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"}]},
)Ini menjaga prompt sistem yang panjang tetap di-cache di sepanjang beberapa event compaction selama percakapan.
Memahami penggunaan
Compaction memerlukan langkah sampling tambahan, yang turut diperhitungkan dalam "rate limit" (batas laju) dan penagihan. API mengembalikan informasi penggunaan yang terperinci dalam respons:
{
"usage": {
"input_tokens": 23000,
"output_tokens": 1000,
"iterations": [
{
"type": "compaction",
"input_tokens": 180000,
"output_tokens": 3500
},
{
"type": "message",
"input_tokens": 23000,
"output_tokens": 1000
}
]
}
}Array iterations menunjukkan penggunaan untuk setiap iterasi sampling. Ketika compaction terjadi, Anda akan melihat iterasi compaction diikuti oleh iterasi message utama. input_tokens dan output_tokens tingkat atas sama persis dengan iterasi message dalam contoh ini karena hanya ada satu iterasi non-compaction. Jumlah token pada iterasi terakhir mencerminkan ukuran konteks efektif setelah compaction.
Menggabungkan dengan fitur lain
Alat server
Saat menggunakan server tools (seperti pencarian web), pemicu compaction diperiksa di awal setiap iterasi sampling. Compaction dapat terjadi beberapa kali dalam satu permintaan, tergantung pada ambang batas pemicu Anda dan jumlah output yang dihasilkan.
Penghitungan token
Endpoint penghitungan token (/v1/messages/count_tokens) menerapkan blok compaction yang sudah ada dalam prompt Anda tetapi tidak memicu compaction baru. Gunakan endpoint ini untuk memeriksa jumlah token efektif Anda setelah compaction sebelumnya:
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}")Contoh
Berikut adalah contoh lengkap percakapan yang berjalan lama dengan compaction:
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},
}
]
},
)
# Tambahkan respons (blok compaction otomatis disertakan)
messages.append({"role": "assistant", "content": response.content})
# Kembalikan konten teks
return next(block.text for block in response.content if block.type == "text")
# Jalankan percakapan panjang
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"))
# Terus panggil chat() selama percakapan masih membutuhkannyaPada Claude Fable 5.1 dan Claude Opus 5.5, hapus blok thinking dan redacted_thinking dari setiap giliran asisten yang Anda sisipkan kembali setelah blok compaction, atau kirim thinking.block_binding.prefix_mismatch_behavior: "drop_block" dengan header beta thinking-binding-controls-2026-08-01. Blok-blok tersebut dihasilkan ketika riwayat lengkap masih ada, sehingga tidak lagi lolos pemeriksaan percakapan. Di tempat pemeriksaan tersebut diberlakukan, permintaan lanjutan akan ditolak dengan error 400. Blok teks dan blok alat yang dipertahankan dapat dibiarkan apa adanya. Membiarkan API meringkas semuanya, tanpa menyisipkan kembali giliran sebelumnya, akan menghindari masalah ini.
Berikut adalah contoh yang menggunakan pause_after_compaction untuk mempertahankan pertukaran sebelumnya dan pesan pengguna saat ini (total tiga pesan) secara verbatim alih-alih meringkasnya:
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,
}
]
},
)
# Periksa apakah compaction (pemadatan) terjadi dan dijeda
if response.stop_reason == "compaction":
# Ambil blok compaction dari respons
compaction_block = response.content[0]
# Pertahankan pertukaran sebelumnya + pesan pengguna saat ini (3 pesan)
# dengan menyertakannya setelah blok compaction
preserved_messages = messages[-3:] if len(messages) >= 3 else messages
# Bangun daftar pesan baru: compaction + pesan yang dipertahankan
new_assistant_content = [compaction_block]
messages_after_compaction = [
{"role": "assistant", "content": new_assistant_content}
] + preserved_messages
# Lanjutkan permintaan dengan konteks yang dipadatkan + pesan yang dipertahankan
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"}]},
)
# Perbarui daftar pesan agar mencerminkan compaction
messages.clear()
messages.extend(messages_after_compaction)
# Tambahkan respons akhir
messages.append({"role": "assistant", "content": response.content})
# Kembalikan konten teks
return next(block.text for block in response.content if block.type == "text")
# Jalankan percakapan panjang
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"))
# Terus panggil chat() selama percakapan masih membutuhkannyaKeterbatasan saat ini
-
Model yang sama untuk peringkasan: Model yang ditentukan dalam permintaan Anda digunakan untuk peringkasan. Tidak ada opsi untuk menggunakan model yang berbeda (misalnya, yang lebih murah) untuk ringkasan.
-
Compaction mungkin gagal ketika alat didefinisikan: Ketika permintaan Anda menyertakan
tools, model terkadang memanggil alat selama langkah peringkasan internal alih-alih menulis ringkasan. Ketika hal ini terjadi, respons berisi blokcompactiondengancontent: null. Untuk mencegahnya, aturinstructionske prompt yang secara eksplisit memberi tahu model untuk tidak memanggil alat, misalnya: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.
Langkah selanjutnya
Kelola konteks percakapan secara otomatis seiring pertumbuhannya dengan pengeditan konteks.
Pelajari tentang ukuran jendela konteks dan strategi pengelolaannya.
Jelajahi implementasi praktis yang mengelola percakapan berjalan lama dengan compaction memori sesi instan menggunakan threading latar belakang dan caching prompt.
Compatibility
| Supported models |
|
|---|---|
| Supported platforms |
|
Was this page helpful?