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 Caching prompt.



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 ditempatkan pada alat terakhir dalam set tersebut. Anda tidak mengontrol urutan alat di dalam toolset MCP, jadi tempatkan breakpoint pada entri mcp_toolset itu sendiri dan API akan menerapkannya pada alat terakhir yang diperluas.

Entri toolset computer use dan browser use mengikuti aturan yang sama: tempatkan cache_control pada entri toolset itu sendiri, dan breakpoint akan ditempatkan setelah definisi toolset. cache_control tidak diterima di dalam entri configs milik anggota, karena anggota toolset dimuat sebagai satu definisi. Di dalam batch action, penanda cache_control pada blok tool_use atau tool_result anggota mana pun dalam giliran tersebut diterima dan berlaku di akhir batch itu, sehingga beberapa penanda dalam satu batch bertindak sebagai satu breakpoint. Setiap penanda tetap dihitung terhadap batas permintaan sebanyak empat breakpoint, jadi gunakan satu per giliran.



defer_loading dan pelestarian cache

Alat yang ditangguhkan (deferred) tidak disertakan dalam prefiks prompt sistem. Ketika model menemukan alat yang ditangguhkan melalui tool search, 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 tool search 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 strict mode. 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 ada setelahnya:



Hasil server tool di-cache secara otomatis

Ketika permintaan Anda mengaktifkan caching prompt dan Claude menggunakan server tool seperti web search, web fetch, atau code execution, API secara otomatis menempatkan breakpoint cache pada hasil server tool 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