搭配提示快取的工具使用

本頁說明工具定義的「prompt caching」（提示快取）：cache_control 斷點應放置於何處、defer_loading 如何保留您的快取，以及哪些變更會使其失效。關於一般的提示快取，請參閱提示快取。



工具定義上的 cache_control

將 cache_control: {"type": "ephemeral"} 放在 tools 陣列中的最後一個工具上。這會快取整個工具定義前綴，從第一個工具一直到標記的斷點：

{
  "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" }
    }
  ]
}

對於 mcp_toolset，cache_control 斷點會落在該集合中的最後一個工具上。您無法控制 MCP 工具集內的工具順序，因此請將斷點放在 mcp_toolset 項目本身，API 會將其套用至最終展開的工具。

電腦使用與瀏覽器使用工具集項目遵循相同規則：將 cache_control 放在工具集項目本身，斷點便會落在該工具集定義之後。它不能放在成員的 configs 項目內，因為工具集的成員會作為單一定義載入。在批次動作中，該輪次任何成員 tool_use 或 tool_result 區塊上的 cache_control 標記都會被接受，並在該批次結束時生效，因此同一批次中的多個標記會作為單一斷點運作。每個標記仍會計入請求的四個斷點上限，因此每輪請使用一個。



defer_loading 與快取保留

延遲載入的工具不會包含在系統提示前綴中。當模型透過工具搜尋發現延遲載入的工具時，其定義會以 tool_reference 區塊的形式內嵌附加至對話歷史中。前綴保持不變，因此提示快取得以保留。

這表示透過工具搜尋動態新增工具不會破壞您的快取。您可以用一小組始終載入的工具（已快取）開始對話，讓模型視需要發現其他工具，並在每一輪都維持相同的快取命中。

defer_loading 的運作也獨立於嚴格模式的文法建構。無論哪些工具被延遲載入，文法都會從完整工具集建構，因此當工具動態載入時，提示快取與文法快取都會被保留。



哪些變更會使您的快取失效

快取遵循前綴階層（tools → system → messages），因此某一層級的變更會使該層級及其之後的所有內容失效：



伺服器工具結果會自動快取

當您的請求已啟用提示快取，且 Claude 使用了伺服器工具（例如網頁搜尋、網頁擷取或程式碼執行）時，API 會在執行代理迴圈的下一次迭代之前，自動在伺服器工具結果上放置快取斷點。這讓同一請求中後續的迭代能從快取讀取不斷增長的前綴，而不必重新處理。

此自動斷點一律使用預設的 5 分鐘 TTL，與您在自己的 cache_control 標記上設定的任何 TTL 無關。在回應的 usage 中，這些寫入會出現在 cache_creation.ephemeral_5m_input_tokens 之下，因此即使您設定的每個 cache_control 都使用 1 小時 TTL，您仍可能看到 5 分鐘的快取寫入。

此行為僅在您的請求已至少包含一個 cache_control 標記時適用。未使用提示快取的請求不會獲得自動斷點。



各工具互動對照表



後續步驟