工具使用與提示快取

本頁面涵蓋工具定義的「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 會將其套用到最終展開的工具上。



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 標記時適用。未啟用提示快取的請求不會收到自動斷點。



各工具互動表



後續步驟