Penggunaan alat dengan caching prompt

Halaman ini membahas 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 akan 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 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 tetap mendapatkan 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 level akan membatalkan level tersebut dan semua yang ada setelahnya:



Hasil alat server di-cache secara otomatis

Ketika permintaan Anda mengaktifkan caching prompt dan Claude menggunakan alat server seperti pencarian web, web fetch, 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 meskipun 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