Pesan sistem dan perubahan alat di tengah percakapan

Instruksi sistem biasanya berada di field system tingkat atas, sebelum setiap pesan dalam percakapan. Posisi tersebut sangat baik untuk caching prompt: prompt sistem adalah bagian dari prefiks yang stabil, sehingga giliran berikutnya akan mengenai cache. Namun, posisi ini kurang ideal 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. Prefiks 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 lebih awal lagi dalam prefiks permintaan yang di-hash dibandingkan field system tingkat atas, sehingga mengeditnya akan 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 secara permanen selama masa percakapan, Anda mengubah alat mana yang ditawarkan kepada model di antara giliran: deklarasikan set alat lengkap 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 prefiks yang di-cache tetap utuh.

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

Setiap alat yang dideklarasikan dalam tools ditawarkan kepada model sejak awal percakapan kecuali jika dideklarasikan dengan defer_loading: true, yang membuatnya tetap ditahan hingga 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 secara byte dan cache tetap kena.
        {
            "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

Caching prompt melakukan hash pada prefiks permintaan secara berurutan: tools, lalu system, lalu messages. Cache hit mengharuskan prefiks cocok persis dengan permintaan terbaru, byte demi byte, hingga titik henti cache.

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

Pesan sistem di tengah percakapan memungkinkan Anda menambahkan instruksi di akhir riwayat pesan. 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 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, tenggat waktu sesi, atau perubahan ketersediaan alat dengan bobot tingkat sistem, dan hal tersebut terlalu sering berubah untuk ditempatkan di prefiks yang di-cache.
• Perubahan state 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 anggaran token yang tersisa turun di bawah ambang batas.
• Input pengguna yang tidak boleh menginterupsi loop agentik. 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 yang harus dialihkan. 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 kapabilitas yang mahal, seperti meluncurkan alur kerja multiagen secara otomatis, dengan pengingat singkat setiap beberapa giliran dan pemberitahuan keluar ketika mode dimatikan. Untuk contoh yang lebih rinci, 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 role system untuk fakta dan batasan tingkat operator yang harus tetap berlaku bahkan jika 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 awal, 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 untuk seluruh percakapan. Simpan pesan sistem di tengah percakapan untuk instruksi yang baru menjadi relevan kemudian, atau yang ingin Anda tambahkan tanpa membatalkan prefiks yang di-cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Caching prompt otomatis: setiap permintaan meng-cache percakapan sejauh ini,
    # 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().",
        },
        # Peninjau menyadari di tengah sesi bahwa semua saran juga harus
        # mematuhi kebijakan typing ketat tim. Menambahkan instruksi
        # di sini menjaga giliran sebelumnya tetap identik per byte, sehingga
        # prefiks yang di-cache oleh permintaan sebelumnya tetap dibaca 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 permintaan tidak memiliki field cache_control (otomatis atau titik henti 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 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 bawah batas tersebut, sehingga cache_creation_input_tokens dan cache_read_input_tokens tetap 0 hingga 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 dalam messages atau langsung diikuti oleh giliran assistant. Pesan user yang membawa blok tool_result juga dihitung: dalam loop agentik, Anda dapat menempatkan pesan sistem tepat setelah hasil alat, sebelum giliran Claude berikutnya. Posisi lain apa pun, termasuk di antara blok tool_use assistant dan tool_result yang menjawabnya, akan mengembalikan error 400.



Penempatan setelah hasil alat

Dalam loop agentik, pesan sistem ditempatkan setelah pesan user yang mengirimkan hasil alat. Ini juga merupakan tempat di mana 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 mengesampingkan pengguna. Nyatakan faktanya ("input baru tiba dari pengguna: X", "anggaran token yang tersisa sekarang Y") dan biarkan Claude bertindak berdasarkan itu. Claude dilatih untuk menolak instruksi yang tampak bekerja melawan pengguna, dan perlindungan tersebut tetap berlaku untuk role sistem, sehingga bahasa seperti "abaikan apa yang dikatakan pengguna" kurang efektif dibandingkan menyatakan apa yang berubah.

Pola ini ditujukan 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 Batasan).



Menggabungkan dengan caching prompt

Pesan sistem di tengah percakapan dan 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 titik henti eksplisit pada blok konten. Pesan sistem di tengah percakapan tidak membuat entri cache dengan sendirinya, dan tanpa caching diaktifkan, tidak ada penghematan yang dapat dipertahankan.
• Cache prefiks 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 titik henti. Karena pesan tersebut datang setelah prefiks yang di-cache, ia tidak mengubah hash prefiks dan cache tetap mengenai.
• Pesan sistem di tengah percakapan itu sendiri dapat di-cache. Setelah berada dalam percakapan, ia menjadi bagian dari riwayat yang stabil. Pada giliran berikutnya, Anda dapat memindahkan titik henti 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 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, yang mengikuti aturan penempatan yang sama secara keseluruhan.



Batasan

• Bukan untuk pesan pertama. Pesan system tidak boleh menjadi entri pertama dalam 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 ini tidak boleh berada di antara blok tool_use dan tool_result-nya. Menempatkannya di tempat lain akan 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; melakukan hal itu memberikan teks tersebut otoritas tingkat operator. Simpan data tersebut dalam blok tool_result dan tetap ikuti Mitigasi jailbreak dan injeksi prompt.



Terkait