Compaction sesuai permintaan

Dengan "on-demand compaction" (pemadatan sesuai permintaan), aplikasi Anda yang menentukan kapan percakapan diringkas: Anda mengirim satu permintaan dengan parameter compaction, dan Claude mengembalikan ringkasan sebagai pengganti balasan.

Cara kerja compaction sesuai permintaan

Permintaan compaction terpisah dari giliran percakapan Anda. Anda mengirim percakapan apa adanya dengan parameter compaction, dan respons berisi satu blok compaction. Blok tersebut memuat ringkasan sebagai teks yang dapat Anda baca, serta sebuah tanda tangan (signature). Kirimkan blok itu dalam permintaan berikutnya persis seperti saat diterima.

Sejak saat itu, blok tersebut menggantikan pesan-pesan yang diringkasnya. Blok ditempatkan pertama di messages, pesan-pesan yang diringkas dihapus, dan giliran Anda berikutnya menyusul setelahnya. Claude melihat ringkasan di tempat pesan-pesan tersebut sebelumnya berada.

Meminta ringkasan

Kirim header beta compact-2026-09-04 pada permintaan yang meminta ringkasan dan pada setiap permintaan berikutnya yang membawa blok bertanda tangan. Untuk memeriksa apakah suatu model mendukung compaction sesuai permintaan, panggil Models API dengan header beta dan baca capabilities.compaction dari setiap model. Anda tidak dapat menggabungkan compaction dengan context_management dalam satu permintaan.

Kirim percakapan apa adanya dengan "compaction": {"type": "summarize"}. API meringkas setiap pesan dalam permintaan satu kali, tidak menghasilkan balasan setelahnya, dan hanya mengembalikan blok tersebut dengan stop_reason "compaction". Kirim prompt system dan tools yang sama dengan yang Anda gunakan untuk sisa percakapan. Peringkas membaca keduanya, dan jika Anda mempertahankan giliran setelah blok pada model dengan "preserved thinking" (pemikiran yang dipertahankan), thinking dalam giliran tersebut tetap valid hanya jika system dan tools cocok. Percakapan dalam contoh ini tidak memiliki prompt system maupun alat, sehingga permintaan tidak mengirim keduanya:

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

history: list[BetaMessageParam] = [
    {
        "role": "user",
        "content": "I am building a recipe app. Help me name the main entities in the data model.",
    },
    {
        "role": "assistant",
        "content": "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.",
    },
    {"role": "user", "content": "Good. Now suggest field names for Recipe."},
]

response = client.beta.messages.create(
    model="claude-opus-5-5",
    # max_tokens membatasi seluruh panggilan, termasuk proses thinking, jadi sediakan beberapa ribu token.
    max_tokens=4096,
    betas=["compact-2026-09-04"],
    messages=history,
    compaction={"type": "summarize"},
)
print(f"Stop reason: {response.stop_reason}")

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
      "signature": "EuYBCkQY..."
    }
  ],
  "stop_reason": "compaction",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "iterations": [{ "type": "compaction", "input_tokens": 144, "output_tokens": 276 }]
  }
}

Panggilan peringkasan menggunakan model, system, tools, pengaturan thinking, dan max_tokens dari permintaan. Peringkas membaca definisi alat tetapi tidak pernah menjalankan alat, dan respons tidak membawa thinking. max_tokens membatasi seluruh panggilan, termasuk thinking apa pun yang dilakukan model sebelum menulis ringkasan, jadi sediakan beberapa ribu token. Menghitung penggunaan compaction menunjukkan bagaimana panggilan tersebut ditagih.

Jika giliran assistant terakhir diakhiri dengan panggilan alat yang belum memiliki hasil, API menolak permintaan tersebut. Kirim hasil alat dari giliran itu terlebih dahulu. Selain itu, jangan sertakan stop_sequences, output_config.format untuk structured output, maupun tool_choice bertipe any atau tool. Parameter-parameter tersebut tidak berpengaruh apa pun pada panggilan peringkasan, dan API menolaknya. Percakapan tetap harus muat dalam "context window" (jendela konteks) model, jadi lakukan compaction sebelum percakapan melampauinya, bukan sesudahnya.

Saat Anda melakukan streaming respons, blok tiba secara utuh. Anda mendapatkan satu event content_block_start yang membawa blok lengkap, lalu content_block_stop, tanpa event content_block_delta. Event ping dapat tiba sebelum atau di antara keduanya.

Melanjutkan dari ringkasan

Dalam riwayat Anda, ganti pesan-pesan yang Anda kirim dengan pesan assistant yang dikembalikan. Pertahankan blok compaction persis seperti yang dikembalikan API, termasuk signature-nya. Giliran apa pun yang diambil setelah Anda mengirim permintaan compaction menyusul blok tersebut tanpa perubahan, dan hal inilah yang menjadi dasar Compaction di latar belakang. Kirim blok tersebut di urutan pertama pada setiap permintaan berikutnya, dengan header beta:

{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "compaction",
          "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
          "signature": "EuYBCkQY..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "For Recipe, use title, description, servings, prep_minutes, and cook_minutes. Add created_at and updated_at timestamps."
    },
    { "role": "user", "content": "Now do the same for Ingredient." }
  ]
}

Contoh ini melanjutkan sampel permintaan, yang berakhir pada giliran user; diagram menunjukkan kasus yang lebih sederhana, di mana tidak ada giliran yang diambil selama ringkasan ditulis. Di sini pesan assistant kedua adalah balasan untuk giliran user terakhir yang diringkas. Pesan itu tiba saat ringkasan sedang ditulis, sehingga tidak termasuk dalam pesan-pesan yang diringkas. Dua pesan assistant berturut-turut tidak menjadi masalah di sini, karena blok tetap berada di urutan pertama.

API menempatkan ringkasan di posisi blok dan meneruskan setiap pesan berikutnya ke Claude tanpa perubahan. Ikuti aturan berikut:

• Tempatkan blok di urutan pertama dalam messages, baik sebagai pesan assistant tersendiri maupun sebagai blok konten pertama dari pesan pertama, entah itu pesan user atau assistant.
• Hapus pesan-pesan yang diringkas. Jika ada yang masih tersisa di depan blok, permintaan mengembalikan error 400 (compaction_block_misplaced).
• Kirim tepat satu blok compaction per permintaan, pada setiap permintaan berikutnya.

Compaction ambang batas bekerja sebaliknya: bloknya mengikuti pesan-pesan yang diringkasnya, dan API menghapus pesan-pesan tersebut untuk Anda. Lihat Mengirimkan kembali blok compaction.

Di Python, gunakan client.beta.messages, seperti yang dilakukan sampel di halaman ini. Jika Anda memanggil client.messages dan menyerialisasi blok sendiri, gunakan to_dict() atau model_dump(exclude_none=True): model_dump() biasa menambahkan citations: null dan text: null ke blok, dan API menolaknya.

Jika Anda mempertahankan giliran setelah blok dan mengirim kembali blok thinking-nya, syarat-syarat yang menjaga thinking tersebut tetap valid dijelaskan di Compaction dan pemikiran yang dipertahankan.

Melakukan compaction lagi

Untuk melakukan compaction pada percakapan yang sudah diawali dengan sebuah blok, kirim compaction lagi. Blok baru meringkas ringkasan lama beserta semua yang ada setelahnya. Sejak saat itu, kirim hanya blok terbaru.

Compaction dalam loop

Setelah setiap giliran, loop menjumlahkan token input dan output dari respons terakhir, karena permintaan berikutnya juga mengirim balasan tersebut. Ketika total itu melewati batas dan masih ada giliran lain yang akan datang, loop mengirim permintaan compaction dengan model dan prompt system yang sama, memeriksa stop_reason, mengganti riwayatnya dengan pesan yang dikembalikan, dan mencetak giliran yang didahului oleh compaction tersebut. Batas sampel sebesar 2.500 token sengaja dibuat rendah, agar percakapan yang singkat pun mengalami compaction. Atur batas Anda mendekati anggaran input Anda yang sebenarnya.

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

# Atur nilai ini mendekati anggaran input Anda yang sebenarnya. Di sini sengaja rendah agar percakapan singkat pun dipadatkan.
COMPACT_AT_TOKENS = 2500
SYSTEM = "You help design a recipe app's data model. Keep answers short."

QUESTIONS = [
    "What are the main entities in the data model?",
    "Which fields should Recipe have?",
    "Which fields should Ingredient have?",
    "Which fields should RecipeIngredient have?",
    "Which fields should Step have?",
    "Which indexes should these tables have?",
    "Which fields should be required?",
    "Which fields should have default values?",
]

history: list[BetaMessageParam] = []
for turn, question in enumerate(QUESTIONS, start=1):
    history.append({"role": "user", "content": question})
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=8192,
        system=SYSTEM,
        betas=["compact-2026-09-04"],
        messages=history,
    )
    history.append({"role": "assistant", "content": response.content})

    # Permintaan berikutnya juga mengirim balasan ini, jadi ikut hitung.
    conversation_tokens = response.usage.input_tokens + response.usage.output_tokens
    if conversation_tokens > COMPACT_AT_TOKENS and turn < len(QUESTIONS):
        summary = client.beta.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,
            system=SYSTEM,
            betas=["compact-2026-09-04"],
            messages=history,
            compaction={"type": "summarize"},
        )
        if summary.stop_reason == "compaction":
            history = [{"role": "assistant", "content": summary.content}]
            print(f"Compacted before turn {turn + 1}")

Pemeriksaan stop_reason dilakukan sebelum kode mencari blok; Menangani ringkasan yang tidak ada atau error menjelaskan alasannya. Riwayat diganti, bukan ditambahkan: pesan yang dikembalikan menggantikan setiap pesan yang dibawa permintaan, sesuai aturan di Melanjutkan dari ringkasan. Ketika tidak ada ringkasan yang dikembalikan, loop mempertahankan riwayatnya dan meminta lagi setelah giliran berikutnya.

Tool runner SDK di Python, TypeScript, C#, Go, dan Java dapat mengirim permintaan compaction untuk Anda. Saat Anda memutuskan untuk melakukan compaction, panggil compact_before_next_turn() pada runner (compactBeforeNextTurn() di TypeScript dan Java, CompactBeforeNextTurn() di C# dan Go). Setelah giliran saat ini beserta panggilan alatnya selesai, runner mengirim permintaan compaction dan mengganti riwayatnya dengan pesan yang dikembalikan. Buat runner dengan beta compact-2026-09-04, karena runner tidak menambahkannya. Runner menyusun permintaan dari parameternya sendiri dan tidak menyertakan context_management. Jika parameter tersebut mencakup stop_sequences, tool_choice bertipe any atau tool, atau output_config.format untuk structured output, API menolak permintaan dengan error 400. Meminta ringkasan menjelaskan alasannya. Runner menolak melakukan compaction selama context_management-nya memiliki edit compaction, jadi gunakan satu jenis compaction saja pada sebuah runner.

Kapan melakukan compaction

Anda dapat mengirim permintaan compaction setelah giliran mana pun yang telah selesai, sehingga kode Anda yang menentukan kapan.

Untuk memperkirakan seberapa besar permintaan berikutnya, jumlahkan input_tokens dan output_tokens dari usage respons terakhir, seperti yang dilakukan loop. Dengan "prompt caching" (caching prompt), input_tokens hanya menghitung token setelah cache breakpoint terakhir, jadi tambahkan juga cache_read_input_tokens dan cache_creation_input_tokens. Anda juga dapat mengirim pesan yang sama ke endpoint penghitungan token.

Bandingkan angka tersebut dengan batas yang Anda pilih, di bawah jendela konteks model.

Menulis prompt peringkasan Anda sendiri

Tanpa instructions, API menggunakan prompt peringkasannya sendiri. String instructions yang tidak kosong (hingga 16.384 karakter) menggantikan prompt tersebut sepenuhnya. Sebagai contoh:

{
  "compaction": {
    "type": "summarize",
    "instructions": "Summarize this recipe app design conversation. Preserve every entity and field name agreed so far, and the user's latest open request. Do not call tools; respond with the summary text only."
  }
}

Peringkas membaca seluruh percakapan, termasuk thinking sebelumnya, baik dengan maupun tanpa instructions. Dalam instructions Anda, sebutkan apa yang harus dipertahankan oleh ringkasan dan minta model untuk tidak memanggil alat. Panggilan peringkasan berjalan di bawah perlindungan yang sama seperti permintaan lainnya.

Menangani ringkasan yang tidak ada atau error

Ringkasan hanya dihasilkan ketika panggilan peringkasan berakhir secara normal dengan teks dan tanpa panggilan alat. Jika tidak, respons tetap berstatus 200 dengan content kosong, jadi periksa stop_reason sebelum Anda mencari blok. Panggilan tersebut tetap ditagih dan dilaporkan di usage.iterations, dengan penggunaan nol jika tidak ada panggilan yang dapat dilakukan. stop_reason adalah alasan berhentinya panggilan peringkasan. Dalam setiap kasus, Anda dapat melanjutkan tanpa ringkasan dan melakukan compaction nanti.

Panggilan peringkasan tunduk pada perlindungan yang sama seperti permintaan Anda yang lain. Setelah "refusal", stop_details mengidentifikasi kategori kebijakan yang mendasarinya.

Error

Permintaan compaction, atau permintaan yang membawa blok, juga dapat gagal sepenuhnya. Sebagian besar error 400 memiliki pesan yang menyebutkan apa yang harus dihapus atau dikirim ulang. Beberapa juga membawa error.details.error_code yang diawali dengan compaction_. Error parameter, seperti field yang tidak dapat digabungkan dengan compaction, hanya membawa pesan.

Menghitung penggunaan compaction

Panggilan peringkasan ditagih dan dikenai "rate limit" (batas laju) seperti permintaan lainnya, dan usage.iterations melaporkannya sebagai entri compaction. input_tokens dan output_tokens tingkat atas bernilai nol karena tidak ada balasan yang dihasilkan. Untuk menghitung apa yang dikonsumsi sebuah percakapan, jumlahkan seluruh usage.iterations, bukan field tingkat atas. Mengirim kembali blok pada permintaan berikutnya tidak menambah biaya compaction.

Anda kini memiliki loop yang berfungsi untuk melakukan compaction pada percakapan dan menangani ringkasan yang tidak ada. Dua halaman mengubah cara loop tersebut berjalan, dan Anda dapat menggabungkan keduanya: Compaction yang mempertahankan giliran terbaru mempertahankan giliran terakhir kata demi kata, dan Compaction di latar belakang memungkinkan percakapan berlanjut selama ringkasan ditulis. Compaction dan pemikiran yang dipertahankan berlaku jika Anda mengirim kembali blok thinking dan melakukan salah satu dari keduanya.

Batasan dan interaksi dengan fitur lain

• Compaction ambang batas dan pengeditan konteks. Anda tidak dapat mengirim compaction dan context_management dalam permintaan yang sama. Compaction ambang batas (compact_20260112) tidak dapat berjalan pada permintaan yang membawa blok bertanda tangan.
• Caching prompt. cache_control pada blok menempatkan breakpoint setelah ringkasan.
• Pesan sistem dan perubahan alat di tengah percakapan. Pesan role: "system" di dalam rentang yang diringkas juga ikut diringkas, sehingga instruksi teksnya tidak lagi berlaku setelah blok menggantikannya. Jika suatu instruksi masih penting, nyatakan kembali dalam pesan role: "system". Kirim pesan tersebut tepat setelah giliran user baru Anda berikutnya, dan biarkan pesan itu tetap ada di riwayat Anda sejak saat itu. Untuk perubahan alat, dan untuk posisi pesan tersebut ketika Anda mempertahankan giliran setelah blok, lihat Mengubah prompt sistem atau alat.
• Anggaran tugas. Jangan kirim nilai remaining dari anggaran tugas (output_config.task_budget.remaining) bersama compaction atau pada permintaan yang membawa blok. Melakukannya akan mengembalikan error 400.
• Penghitungan token. Endpoint penghitungan token mengabaikan parameter compaction.
• Konten yang tidak dapat dibawa oleh ringkasan. Gambar, dokumen, blok container_upload, dan URL yang diambil di dalam pesan yang diringkas akan hilang setelah blok menggantikannya. Nyatakan ulang atau unggah ulang apa pun yang masih dibutuhkan oleh giliran berikutnya.

Compatibility