Penggunaan alat dengan prompt caching

Halaman ini membahas "prompt caching" (caching prompt) untuk definisi alat: di mana menempatkan breakpoint cache_control, bagaimana defer_loading mempertahankan cache Anda, dan apa yang membatalkannya. Untuk caching prompt secara umum, lihat Prompt caching.



cache_control pada definisi alat

Tempatkan cache_control: {"type": "ephemeral"} pada alat terakhir dalam array tools Anda. Ini meng-cache seluruh prefiks definisi alat, dari alat pertama hingga breakpoint yang ditandai:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": {
          "timezone": { "type": "string" }
        },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

Untuk mcp_toolset, breakpoint cache_control jatuh pada alat terakhir dalam set tersebut. Anda tidak mengontrol urutan alat dalam toolset MCP, jadi tempatkan breakpoint pada entri mcp_toolset itu sendiri dan API akan menerapkannya pada alat terakhir yang diperluas.



defer_loading dan pemeliharaan cache

Alat yang ditangguhkan tidak disertakan dalam prefiks prompt sistem. Ketika model menemukan alat yang ditangguhkan melalui pencarian alat, definisinya ditambahkan secara inline sebagai blok tool_reference dalam riwayat percakapan. Prefiks tidak tersentuh, sehingga caching prompt tetap terjaga.

Ini berarti menambahkan alat secara dinamis melalui pencarian alat tidak merusak cache Anda. Anda dapat memulai percakapan dengan sekumpulan kecil alat yang selalu dimuat (di-cache), membiarkan model menemukan alat tambahan sesuai kebutuhan, dan mempertahankan cache hit yang sama di setiap giliran.

defer_loading juga bekerja secara independen dari konstruksi grammar untuk mode ketat. Grammar dibangun dari toolset lengkap terlepas dari alat mana yang ditangguhkan, sehingga caching prompt dan caching grammar keduanya tetap terjaga ketika alat dimuat secara dinamis.



Apa yang membatalkan cache Anda

Cache mengikuti hierarki prefiks (tools → system → messages), sehingga perubahan pada satu tingkat membatalkan tingkat tersebut dan semua yang setelahnya:



Hasil alat server di-cache secara otomatis

Ketika permintaan Anda mengaktifkan caching prompt dan Claude menggunakan alat server seperti pencarian web, pengambilan web, atau eksekusi kode, API secara otomatis menempatkan breakpoint cache pada hasil alat server sebelum menjalankan iterasi berikutnya dari loop agentik. Ini memungkinkan iterasi selanjutnya dalam permintaan yang sama membaca prefiks yang terus bertambah dari cache alih-alih memprosesnya ulang.

Breakpoint otomatis ini selalu menggunakan TTL default 5 menit, terlepas dari TTL apa pun yang Anda tetapkan pada penanda cache_control Anda sendiri. Dalam usage respons, penulisan ini muncul di bawah cache_creation.ephemeral_5m_input_tokens, sehingga Anda mungkin melihat penulisan cache 5 menit bahkan ketika setiap cache_control yang Anda tetapkan menggunakan TTL 1 jam.

Perilaku ini hanya berlaku ketika permintaan Anda sudah memiliki setidaknya satu penanda cache_control. Permintaan tanpa caching prompt tidak menerima breakpoint otomatis.



Tabel interaksi per alat



Langkah selanjutnya