Pesan sistem dan perubahan alat di tengah percakapan

Instruksi sistem biasanya berada di field system tingkat atas, di depan setiap pesan dalam percakapan. Posisi itu sangat baik untuk prompt caching (caching prompt): prompt sistem adalah bagian dari prefix yang stabil, sehingga giliran-giliran berikutnya mendapatkan cache hit. Namun posisi itu buruk untuk instruksi yang baru Anda sadari diperlukan di tengah sesi, karena mengedit field system tingkat atas mengubah bagian paling awal dari prompt dan membatalkan cache untuk semua yang mengikutinya.

Pesan sistem di tengah percakapan menutup celah tersebut. Anda menambahkan pesan {"role": "system"} pada titik dalam percakapan di mana instruksi baru menjadi relevan, alih-alih mengedit field system tingkat atas. Prefix yang di-cache tetap sama, sehingga permintaan berikutnya masih membacanya dari cache, dan instruksi baru tetap diterapkan sebagai instruksi sistem, bukan sebagai teks pengguna biasa.

Halaman ini membahas dua fitur: pesan sistem di tengah percakapan, yang tersedia secara umum, dan perubahan alat di tengah percakapan, sebuah beta yang diperkenalkan bersama Claude Opus 5 yang menerapkan pendekatan yang sama pada array tools.



Perubahan alat di tengah percakapan

Array tools berada bahkan lebih awal dalam prefix permintaan yang di-hash dibandingkan field system tingkat atas, sehingga mengeditnya membatalkan cache prompt untuk seluruh percakapan. Perubahan alat di tengah percakapan, sebuah beta yang diperkenalkan bersama Claude Opus 5, adalah padanan untuk alat dari pesan sistem di tengah percakapan. Alih-alih menetapkan daftar alat untuk seumur hidup percakapan, Anda mengubah alat mana yang ditawarkan kepada model di antara giliran: deklarasikan seluruh kumpulan alat di tools di awal, lalu gunakan blok tool_addition dan tool_removal untuk menawarkan alat kepada model, atau menariknya, mulai dari titik tertentu dalam percakapan dan seterusnya. Array tools itu sendiri tidak pernah berubah, sehingga prefix yang di-cache tetap utuh.

tool_addition dan tool_removal adalah blok konten dalam array content dari pesan role: "system", dan keduanya dapat dicampur dengan blok text dalam pesan yang sama. Pesan tersebut mengikuti aturan penempatan yang sama seperti pesan sistem di tengah percakapan lainnya (lihat Keterbatasan), dan perubahan berlaku mulai dari titik tersebut dalam percakapan dan seterusnya. Field tool pada setiap blok mereferensikan sebuah alat, bukan mendefinisikannya: {"type": "tool_reference", "name": "..."} menyebutkan nama alat yang dideklarasikan dalam array tools permintaan, dan alat MCP connector dapat direferensikan secara individual dengan mcp_tool_reference (server_name dan name) atau sebagai satu toolset utuh dengan mcp_toolset_reference (server_name). Mereferensikan nama yang tidak dideklarasikan di tools mengembalikan error 400.

Setiap alat yang dideklarasikan di tools ditawarkan kepada model sejak awal percakapan kecuali jika dideklarasikan dengan defer_loading: true, yang menahannya sampai sebuah blok tool_addition memunculkannya. tool_addition juga menawarkan kembali alat yang sebelumnya ditarik oleh tool_removal.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # Set alat lengkap dideklarasikan di awal dan tidak pernah berubah, sehingga
    # prefiks yang di-cache tetap utuh.
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Say OK.",
        },
        # Tarik get_weather mulai dari titik ini. Blok ini mereferensikan
        # alat berdasarkan nama alih-alih mengedit `tools`, sehingga giliran sebelumnya
        # tetap identik byte demi byte dan cache tetap hit.
        {
            "role": "system",
            "content": [
                {
                    "type": "tool_removal",
                    "tool": {"type": "tool_reference", "name": "get_weather"},
                },
            ],
        },
    ],
)

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

Perubahan alat di tengah percakapan masih dalam tahap beta. Untuk menggunakannya, sertakan header beta mid-conversation-tool-changes-2026-07-01 dalam permintaan Anda. Fitur ini tersedia di Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, dan Claude Opus 5, pada Claude API, Amazon Bedrock, dan Google Cloud.



Kapan menggunakan pesan sistem di tengah percakapan

Prompt caching (caching prompt) melakukan hash pada prefix permintaan secara berurutan: tools, lalu system, lalu messages. Cache hit mengharuskan prefix cocok persis dengan permintaan terbaru, byte demi byte, hingga breakpoint cache.

Urutan tersebut berarti field system tingkat atas berada di dekat bagian paling awal dari prefix yang di-hash. Perubahan apa pun padanya, bahkan menambahkan satu kalimat, menghasilkan hash yang berbeda, dan permintaan tersebut gagal mendapatkan cache untuk prompt sistem dan setiap pesan yang di-cache setelahnya.

Pesan sistem di tengah percakapan memungkinkan Anda menambahkan instruksi di akhir riwayat pesan sebagai gantinya. Semua yang ada sebelum instruksi baru tidak berubah, sehingga entri cache yang ada masih cocok, dan hanya pesan baru yang diproses sebagai input baru.

Beberapa situasi di mana hal ini penting:

• Perubahan kebijakan atau persona di tengah sesi. Sesi agentik yang panjang memerlukan batasan baru ("mulai sekarang, tulis semua SQL sebagai parameterized query") setelah puluhan giliran yang sudah di-cache. Menambahkannya ke field system tingkat atas akan memproses ulang seluruh riwayat.
• Konteks per giliran yang harus bersifat otoritatif. Anda ingin menyisipkan catatan kesegaran data, tenggat waktu sesi, atau perubahan ketersediaan alat dengan bobot tingkat sistem, dan hal itu terlalu sering berubah untuk ditempatkan di prefix yang di-cache.
• Perubahan status yang diamati aplikasi Anda. Aplikasi Anda mendeteksi sesuatu yang harus diperlakukan Claude sebagai fakta tingkat operator: file berubah di disk, pengguna mengaktifkan pengaturan auto-approve, alat yang tersedia berubah, atau sisa anggaran token turun di bawah ambang batas.
• Input pengguna yang tidak boleh menginterupsi loop agentik. Seorang pengguna mengetik tindak lanjut saat Claude masih mengeksekusi alat untuk permintaan sebelumnya. Meneruskannya sebagai pesan sistem setelah hasil alat berikutnya memungkinkan Claude menggabungkan input baru ke dalam pekerjaan yang sedang dilakukannya, alih-alih memperlakukannya sebagai permintaan baru untuk beralih. Lihat Penempatan setelah hasil alat di bawah.
• Peralihan mode yang memberikan izin tetap. Mode tingkat sesi dapat menggunakan pesan sistem di tengah percakapan untuk memberikan persetujuan tetap terhadap kemampuan yang mahal, seperti meluncurkan alur kerja multiagen secara otomatis, dengan pengingat singkat setiap beberapa giliran dan pemberitahuan keluar saat mode dimatikan. Untuk contoh lengkap, lihat Membangun mode orkestrasi.

Dalam semua kasus ini Anda bisa saja menempatkan instruksi dalam pesan user biasa, dan Claude memang mengikuti instruksi yang datang dalam giliran pengguna. Perbedaannya adalah prioritas: pesan user diperlakukan sebagai berasal dari pengguna akhir, sedangkan pesan system diperlakukan sebagai berasal dari Anda, operator aplikasi. Ketika keduanya bertentangan, instruksi sistem lebih diutamakan, jadi gunakan peran system untuk fakta dan batasan tingkat operator yang harus tetap berlaku meskipun pengguna akhir meminta sesuatu yang berbeda. Pesan sistem di tengah percakapan mempertahankan prioritas tingkat operator tersebut tanpa membayar biaya cache miss akibat mengedit field system tingkat atas.



Cara kerjanya

Tambahkan pesan dengan "role": "system" ke array messages. Gunakan string biasa atau blok konten untuk content, sama seperti giliran user atau assistant. Instruksi berlaku mulai dari titik tersebut dalam percakapan dan seterusnya. Ketika instruksi bertentangan, pesan sistem yang lebih baru lebih diutamakan daripada yang lebih lama, dan pesan sistem di tengah percakapan lebih diutamakan daripada field system tingkat atas untuk giliran-giliran yang mengikutinya.

Anda tetap dapat mengatur field system tingkat atas untuk instruksi yang harus berlaku pada seluruh percakapan. Cadangkan pesan sistem di tengah percakapan untuk instruksi yang baru menjadi relevan belakangan, atau yang ingin Anda tambahkan tanpa membatalkan prefix yang di-cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Caching prompt otomatis: setiap permintaan menyimpan percakapan sejauh ini ke cache,
    # dan permintaan berikutnya membaca prefiks yang tidak berubah dari cache.
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {
            "role": "user",
            "content": "Review process() in utils.py for performance issues.",
        },
        {
            "role": "assistant",
            "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",
        },
        {
            "role": "user",
            "content": "Now review the calling code that invokes process().",
        },
        # Di tengah sesi, peninjau menyadari bahwa semua saran juga harus
        # lolos kebijakan typing ketat milik tim. Menambahkan
        # instruksi di sini menjaga giliran sebelumnya tetap identik byte demi byte, sehingga
        # prefiks yang di-cache oleh permintaan sebelumnya masih terbaca dari cache.
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

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

Contoh ini mengaktifkan caching otomatis dengan field cache_control tingkat atas. Caching prompt bersifat opt-in: jika sebuah permintaan tidak memiliki field cache_control (otomatis atau breakpoint eksplisit), tidak ada yang di-cache dan setiap permintaan membayar harga token input reguler untuk seluruh percakapan. Dengan caching diaktifkan, menambahkan pesan sistem membiarkan giliran-giliran yang sudah di-cache tidak berubah, sehingga permintaan yang membawa instruksi baru tetap membacanya dari cache alih-alih memprosesnya lagi. Caching juga mengharuskan percakapan memenuhi panjang prompt minimum yang dapat di-cache; contoh sependek ini berada di bawahnya, sehingga cache_creation_input_tokens dan cache_read_input_tokens tetap 0 sampai percakapan bertambah panjang.

Pesan sistem di tengah percakapan harus langsung mengikuti giliran user (atau giliran assistant yang diakhiri dengan hasil alat server), dan harus menjadi entri terakhir di messages atau langsung diikuti oleh giliran assistant. Pesan user yang membawa blok tool_result termasuk: dalam loop agentik Anda dapat menempatkan pesan sistem tepat setelah hasil alat, sebelum giliran Claude berikutnya. Posisi lain mana pun, termasuk di antara blok tool_use milik assistant dan tool_result yang menjawabnya, mengembalikan error 400.



Penempatan setelah hasil alat

Dalam loop agentik, pesan sistem ditempatkan setelah pesan user yang menyampaikan hasil alat. Di sinilah juga aplikasi Anda dapat meneruskan input yang diketik pengguna saat Claude sedang bekerja, sehingga konteks baru diserap tanpa memulai ulang giliran:

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

Susun konten sistem sebagai konteks, bukan sebagai perintah yang menimpa pengguna. Nyatakan faktanya ("input baru tiba dari pengguna: X", "sisa anggaran token sekarang Y") dan biarkan Claude bertindak berdasarkan itu. Claude dilatih untuk menolak instruksi yang tampak bekerja melawan pengguna, dan perlindungan itu tetap berlaku untuk peran sistem, sehingga bahasa seperti "abaikan apa yang dikatakan pengguna" kurang efektif dibandingkan menyatakan apa yang berubah.

Pola ini untuk meneruskan input dari pengguna akhir percakapan itu sendiri. Jangan gunakan untuk meneruskan output alat, dokumen yang diambil, atau konten pihak ketiga lainnya; simpan konten tersebut dalam blok tool_result (lihat Keterbatasan).



Menggabungkan dengan caching prompt

Pesan sistem di tengah percakapan dan prompt caching (caching prompt) dirancang untuk digunakan bersama:

• Aktifkan caching secara eksplisit. Caching hanya terjadi ketika permintaan menyertakan cache_control, baik field caching otomatis tingkat atas maupun breakpoint eksplisit pada blok konten. Pesan sistem di tengah percakapan tidak membuat entri cache dengan sendirinya, dan tanpa caching diaktifkan tidak ada penghematan yang perlu dipertahankan.
• Cache prefix yang stabil seperti biasa. Tempatkan cache_control pada blok terakhir yang tetap sama di seluruh permintaan, baik itu akhir dari field system tingkat atas, akhir dari definisi alat Anda, atau titik stabil dalam riwayat pesan.
• Tambahkan pesan sistem setelah breakpoint. Karena berada setelah prefix yang di-cache, pesan tersebut tidak mengubah hash prefix dan cache tetap mendapatkan hit.
• Pesan sistem di tengah percakapan itu sendiri dapat di-cache. Setelah berada dalam percakapan, pesan tersebut menjadi bagian dari riwayat yang stabil. Pada giliran berikutnya Anda dapat memindahkan breakpoint cache Anda melewatinya (atau mengandalkan caching otomatis untuk melakukannya) dan pesan sistem dibaca dari cache seperti giliran lainnya.

Hindari mengedit atau menghapus pesan sistem di tengah percakapan yang sudah dikirim. Seperti perubahan lain pada pesan-pesan sebelumnya, hal itu membatalkan cache mulai dari titik tersebut dan seterusnya. Jika instruksi perlu berkembang, tambahkan pesan sistem baru alih-alih menulis ulang yang lama. Pesan sistem yang berurutan diterima dan diperlakukan sebagai satu bagian sistem tunggal, yang mengikuti aturan penempatan yang sama secara keseluruhan.



Keterbatasan

• Bukan untuk pesan pertama. Pesan system tidak boleh menjadi entri pertama di messages. Gunakan field system tingkat atas untuk instruksi yang berlaku sejak awal.
• Penempatan dibatasi. Pesan system harus langsung mengikuti giliran user (termasuk giliran user yang membawa blok tool_result) atau giliran assistant yang diakhiri dengan hasil alat server, dan harus mendahului giliran assistant atau mengakhiri array. Pesan tersebut tidak boleh berada di antara blok tool_use dan tool_result-nya. Menempatkannya di tempat lain mengembalikan error 400.
• Bukan tempat untuk konten yang tidak tepercaya. Claude memperlakukan konten sistem sebagai instruksi operator dan mengikutinya. Jangan menempatkan teks dari luar percakapan, seperti output alat mentah, dokumen yang diambil, atau konten web, langsung dalam pesan sistem; melakukannya memberikan teks tersebut otoritas tingkat operator. Simpan data tersebut dalam blok tool_result dan tetap ikuti Mitigasi jailbreak dan injeksi prompt.



Terkait