Pemeriksaan prefiks pada blok pemikiran

Setiap permintaan yang mengirimkan kembali “thinking blocks” (blok pemikiran) ke model dengan pemikiran yang dipertahankan menjalani “prefix check” (pemeriksaan prefiks). Pemeriksaan prefiks gagal jika system, tools, atau pesan sebelumnya berubah setelah Claude menghasilkan sebuah blok. Pemeriksaan prefiks juga gagal jika sebuah blok pemikiran yang berada di antara blok lainnya dihilangkan atau dipindahkan.

Gagal dalam pemeriksaan prefiks mungkin menghasilkan error 400 dan mungkin juga tidak, tergantung pada modelnya, jadi tangani kedua kasus.

Siapa yang terpengaruh oleh pemeriksaan prefiks

Anda tidak perlu mengubah apa pun jika salah satu dari hal berikut benar:

• Claude Code, claude.ai, atau Claude Managed Agents mengelola riwayat percakapan Anda.
• Claude Agent SDK mengelola riwayat tersebut, dan prompt sistem yang Anda berikan kepada SDK tetap sama.
• Kode Anda mengikuti tiga kebiasaan integrasi append-only, dan tidak ada yang menulis ulang permintaannya di tengah jalan.
• Anda tidak memanggil model dengan pemikiran yang dipertahankan mana pun.

Jika permintaan Anda melewati sebuah library, proxy, atau gateway, bandingkan apa yang dikirimkannya dengan apa yang Anda kirim. Jika Anda menjalankan salah satunya, lihat Library, proxy, dan gateway untuk mengetahui apa yang harus diteruskan.

Apa yang harus tetap sama, dan mengapa

Jadikan integrasi Anda “append-only” (hanya menambahkan di akhir). Tiga kebiasaan mewujudkannya:

1. Kirim kembali setiap giliran asisten persis seperti yang dikembalikan oleh API, termasuk blok pemikiran yang teksnya kosong.
2. Bangun system dan tools satu kali untuk setiap percakapan, dan kirim salinan tersebut setiap kali.
3. Letakkan setiap pembaruan dalam pesan baru di bagian akhir, dan biarkan tetap di sana.

Penalaran setiap blok pemikiran berkaitan persis dengan apa yang ada sebelumnya: system, tools, dan setiap pesan sebelumnya. Konten tersebut adalah prefiks blok itu, dan itulah yang dibandingkan oleh pemeriksaan prefiks.

Pemeriksaan prefiks mirip dengan caching prompt, bedanya sebuah perubahan membuat pemikiran setelahnya tidak valid, alih-alih hanya tidak mengenai cache.

Ambil contoh aplikasi yang menaruh tanggal hari ini di prompt sistemnya. Pada tengah malam tanggal berubah, begitu pula prefiks dari pemikiran yang sudah ada dalam percakapan. Pemikiran itu menjadi tidak valid, dan permintaan berikutnya dapat gagal. Aplikasi append-only mempertahankan prompt sistem seperti semula, dan menyatakan tanggal baru dalam sebuah pesan di bagian akhir.

Sebuah perubahan hanya membuat pemikiran yang sudah ada setelahnya menjadi tidak valid. Pemikiran sebelum perubahan itu dan pemikiran yang dihasilkan Claude sesudahnya tetap valid.

Jika kode Anda mengubah prompt sistem, alat, atau riwayat

Penyebab lain, seperti melewatkan blok pemikiran yang teksnya kosong atau membangun ulang percakapan yang tersimpan, memiliki perbaikannya sendiri: lihat Ubah alat atau instruksi tanpa gagal dalam pemeriksaan prefiks. Untuk menemukan penyebab Anda, minta agen memeriksa kode Anda.

Apa yang dilakukan setiap model ketika pemeriksaan prefiks gagal

Di Claude API dan beberapa platform cloud, hasil dari gagal dalam pemeriksaan prefiks ketika permintaan tidak menyertakan prefix_mismatch_behavior bergantung pada modelnya:

Jika tabel menyebutkan “Kemungkinan error 400,” ada dua kasus: permintaan yang gagal dalam pemeriksaan prefiks mungkin mendapatkan error 400 atau tidak mendapatkan error. Ketika tidak ada error yang dikembalikan, blok yang gagal dalam pemeriksaan prefiks sampai ke model. Claude membacanya seperti input lainnya, Anda ditagih untuk blok-blok tersebut, dan Claude bekerja berdasarkan penalaran tentang konten yang sejak itu telah berubah.

Pada model-model tersebut, Anda dapat memeriksa kasus mana yang didapatkan sebuah permintaan, tetapi tangani kedua kasus.

Item Message Batches yang tidak menyertakan prefix_mismatch_behavior tidak mendapatkan error, dan API dapat tidak menyertakan blok yang gagal dalam pemeriksaan prefiks.

Tangani kedua kasus

Untuk mendapatkan satu hasil yang sama pada setiap permintaan, jadikan integrasi Anda append-only atau atur prefix_mismatch_behavior. Jika tidak, kode Anda harus menangani kedua perilaku.

• Append-only: dengan tiga kebiasaan tersebut, kode Anda tidak membuat permintaan gagal dalam pemeriksaan prefiks.
• Pengaturan: dengan "error" pada setiap permintaan, setiap kegagalan menjadi error 400, dan Anda menangkapnya dalam kode.
• Kedua perilaku: jika Anda tidak menyertakan pengaturan tersebut, tangkap error 400, dan pantau pemikiran yang gagal dalam pemeriksaan prefiks dan sampai ke Claude.

Setelah error 400, kirim "drop_block" pada permintaan-permintaan berikutnya dalam percakapan itu untuk memulihkannya. Ini memiliki biaya: lihat Biaya tidak menyertakan pemikiran. Jangan mengirimkannya pada semua percakapan Anda untuk menyembunyikan error.

Detail teknis

Cara kerja pemeriksaan prefiks

Model dengan pemikiran yang dipertahankan merekam sidik jari dari prefiks setiap blok pemikiran di dalam signature blok tersebut. Referensi API menyebut pemeriksaan prefiks sebagai pemeriksaan percakapan, dan error 400 menyatakan bahwa blok yang gagal dalam pemeriksaan prefiks is bound to a different conversation.

Model mana yang menjalankan pemeriksaan prefiks

Pemeriksaan prefiks berjalan di Claude API dan di beberapa platform cloud. Pemeriksaan prefiks memeriksa blok pemikiran yang dihasilkan oleh model dengan pemikiran yang dipertahankan, pada permintaan ke salah satu model tersebut. Di Claude API, model lain, seperti Claude Opus 5, tidak menjalankannya, dan pemeriksaan prefiks tidak mencakup blok dari model-model tersebut.

Apa yang dihitung sebagai perubahan

• Setiap blok diperiksa terhadap rekamannya sendiri. API membandingkan apa yang ada sebelum sebuah blok dalam permintaan ini dengan apa yang direkam oleh signature-nya ketika Claude menghasilkannya. Permintaan terakhir Anda tidak berperan. Pemeriksaan prefiks hanya melihat konten, bukan sesi, ID, atau pengguna. Konten yang sama dalam permintaan baru atau dalam fork lolos pemeriksaan prefiks.
• Pemeriksaan prefiks membandingkan apa yang Anda kirim, bukan apa yang dibaca Claude. Compaction pada ambang batas token dan pengeditan konteks hanya mengubah apa yang dibaca Claude, sehingga tidak pernah dihitung. Setelah blok compaction ambang, API hanya membandingkan pesan-pesan mulai dari blok itu dan seterusnya, ditambah system dan tools. Compaction sesuai permintaan memiliki syaratnya sendiri: lihat Syarat agar thinking yang dipertahankan tetap valid. Untuk file yang dikirim melalui URL dan, di Claude API, daftar alat MCP, API membandingkan apa yang diambilnya sebagai gantinya.
• Pemikiran yang Anda kirim harus berupa rangkaian yang tidak terputus. Blok pemikiran tidak dibandingkan sebagai konten. Tetapi setiap blok yang Anda kirim, selain yang pertama, harus memiliki blok pemikiran sebelumnya yang sama seperti ketika Claude menghasilkannya. Jadi Anda dapat menghilangkan yang paling lama, yang paling baru, atau semuanya, tetapi tidak satu blok yang berada di antaranya.

Sebuah perubahan bisa sekecil satu kata dalam deskripsi alat. Mengubah, menyisipkan, memindahkan, atau menghapus pesan sebelumnya dihitung sebagai perubahan, apa pun perannya. Begitu pula mengubah teks sebelum blok pemikiran di dalam pesannya sendiri.

Apa yang tidak dihitung

Atur prefix_mismatch_behavior

Beta header thinking-binding-controls-2026-08-01 menambahkan pengaturan thinking.block_binding.prefix_mismatch_behavior dan array input_transformations pada respons.

Blok yang gagal dalam pemeriksaan prefiks tetap tidak valid pada setiap permintaan berikutnya yang mengirimkannya, selama perubahan tersebut masih ada. Pengaturan ini berlaku pada satu permintaan yang membawanya. Dengan pemikiran dinonaktifkan ("disabled" atau "between_tools"), mengirimkannya menghasilkan error 400 pada setiap model.

Permintaan berikut mengatur prefix_mismatch_behavior ke "drop_block". Pada giliran pertama tidak ada pemikiran yang perlu dikirim kembali, sehingga input_transformations dikembalikan dalam keadaan kosong:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

Pantau lalu lintas produksi

Tanpa menyertakan prefix_mismatch_behavior, permintaan yang gagal dalam pemeriksaan prefiks mungkin tidak mendapatkan error pada beberapa model. Blok pemikiran yang gagal dalam pemeriksaan prefiks kemudian sampai ke model. Untuk menemukan blok-blok tersebut dalam lalu lintas produksi, kirim beta header thinking-binding-controls-2026-08-01, jangan sertakan pengaturan tersebut, dan catat array input_transformations dari setiap respons. Header tersebut menambahkan array itu dan tidak mengubah apa yang diterima model.

Setiap blok tersebut mendapatkan entri thinking_mismatch_allowed sendiri dalam array itu. Satu entri terlihat seperti ini:

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Untuk menemukan perubahannya, lihat Temukan apa yang diubah kode Anda.

Periksa kasus mana yang Anda dapatkan

Pada beberapa model, permintaan yang gagal dalam pemeriksaan prefiks mungkin mendapatkan error 400 atau tidak mendapatkan error. Pengujian ini menunjukkan mana yang didapatkan sebuah permintaan:

1. Ambil percakapan yang berisi blok pemikiran dari salah satu model tersebut. Ubah atau tambahkan prompt sistem (system). Blok tersebut kemudian gagal dalam pemeriksaan prefiks, karena prompt sistem berubah setelah Claude menghasilkan blok tersebut.
2. Kirimkan ke model yang sama dengan beta header thinking-binding-controls-2026-08-01, dan jangan sertakan prefix_mismatch_behavior.

Responsnya adalah salah satu dari berikut:

• Error 400 yang menyatakan bound to a different conversation: Permintaan mendapatkan error 400.
• Respons 200 yang array input_transformations-nya memiliki entri thinking_mismatch_allowed: Permintaan tidak mendapatkan error. Setiap entri menyebutkan blok pemikiran yang gagal dalam pemeriksaan prefiks dan sampai ke Claude.
• Respons 200 yang array input_transformations-nya kosong: Tidak ada blok yang gagal dalam pemeriksaan prefiks, sehingga pengujian tidak menunjukkan apa pun. Pastikan percakapan tersebut berisi blok pemikiran dari model itu.

Hasilnya menggambarkan satu permintaan tersebut dan tidak menjanjikan apa pun tentang permintaan berikutnya, jadi tulis kode Anda untuk menangani kedua kasus.

Langkah selanjutnya