---
title: 搭配提示快取的工具使用
url: https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-use-with-prompt-caching
description: 跨輪次快取工具定義，並了解哪些情況會使您的快取失效。
---
本頁說明工具定義的「prompt caching」（提示快取）：`cache_control` 斷點應放置於何處、`defer_loading` 如何保留您的快取，以及哪些情況會使其失效。關於一般的提示快取，請參閱[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)。
## 工具定義上的 cache\_control
將 `cache_control: {"type": "ephemeral"}` 放在 `tools` 陣列中的最後一個工具上。這會快取整個工具定義前綴，從第一個工具一直到標記的斷點：
```json
{
"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 會將其套用至最終展開的工具。
[電腦使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool)與[瀏覽器使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/browser-use-tool)工具集項目遵循相同規則：將 `cache_control` 放在工具集項目本身，斷點便會落在該工具集定義之後。它不接受放在成員的 `configs` 項目內，因為工具集的成員會作為單一定義載入。在[批次動作](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#batch-actions)中，該輪次任一成員 `tool_use` 或 `tool_result` 區塊上的 `cache_control` 標記都會被接受，並在該批次結束時生效，因此同一批次中的多個標記會作為單一斷點運作。每個標記仍會計入請求的[四個斷點](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#when-to-use-multiple-breakpoints)上限，因此每輪次請使用一個。
## defer\_loading 與快取保留
延遲載入的工具不會包含在系統提示前綴中。當模型透過[工具搜尋](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-search-tool)發現延遲載入的工具時，其定義會以 `tool_reference` 區塊的形式內嵌附加至對話歷史中。前綴保持不變，因此提示快取得以保留。
這表示透過工具搜尋動態新增工具不會破壞您的快取。您可以用一小組永遠載入的工具（已快取）開始對話，讓模型視需要發現其他工具，並在每一輪次都維持相同的快取命中。
`defer_loading` 的運作也獨立於[嚴格模式](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/strict-tool-use)的文法建構。無論哪些工具被延遲載入，文法都會從完整工具集建構，因此當工具動態載入時，提示快取與文法快取都會被保留。
## 哪些情況會使您的快取失效
快取遵循前綴階層（`tools` → `system` → `messages`），因此某一層級的變更會使該層級及其後的所有內容失效：
| 變更 | 失效範圍 |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 修改工具定義 | 整個快取（tools、system、messages） |
| 切換網頁搜尋或引用 | system 與 messages 快取 |
| 變更 `tool_choice` | messages 快取 |
| 變更 `disable_parallel_tool_use` | messages 快取 |
| 切換圖片存在／不存在 | messages 快取 |
| 變更思考參數 | messages 快取一律失效；在會將思考設定呈現於工具與系統快取之前的模型上，工具與系統快取也會失效（[詳細資訊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-prompt-caching)） |
| 變更 `output_config.effort` | 與思考參數相同；明確設定模型的預設值等同於省略它 |
如果您需要在對話中途變更 `tool_choice`，請考慮將快取斷點放在變更點之前。
## 伺服器工具結果會自動快取
當您的請求已啟用提示快取，且 Claude 使用了[伺服器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/server-tools)（例如網頁搜尋、網頁擷取或程式碼執行）時，API 會在執行代理迴圈的下一次迭代之前，自動在伺服器工具結果上放置一個快取斷點。這讓同一請求中後續的迭代可以從快取讀取不斷增長的前綴，而不必重新處理。
此自動斷點一律使用預設的 5 分鐘 TTL，與您在自己的 `cache_control` 標記上設定的任何 TTL 無關。在回應的 `usage` 中，這些寫入會出現在 `cache_creation.ephemeral_5m_input_tokens` 之下，因此即使您設定的每個 `cache_control` 都使用 1 小時 TTL，您仍可能看到 5 分鐘的快取寫入。
此行為僅在您的請求已至少包含一個 `cache_control` 標記時適用。未使用提示快取的請求不會獲得自動斷點。
## 各工具互動表
| 工具 | 快取注意事項 |
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [網頁搜尋](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/web-search-tool) | 啟用或停用會使 system 與 messages 快取失效 |
| [網頁擷取](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/web-fetch-tool) | 啟用或停用會使 system 與 messages 快取失效 |
| [程式碼執行](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/code-execution-tool) | 容器狀態獨立於提示快取 |
| [工具搜尋](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-search-tool) | 發現的工具以 `tool_reference` 區塊載入，保留前綴快取 |
| [電腦使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool) | 螢幕截圖的存在與否會影響 messages 快取；`cache_control` 放在工具集項目上（請參閱[工具定義上的 cache\_control](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)） |
| [瀏覽器使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/browser-use-tool) | 螢幕截圖的存在與否會影響 messages 快取；`cache_control` 放在工具集項目上（請參閱[工具定義上的 cache\_control](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)） |
| [文字編輯器](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/text-editor-tool) | 標準用戶端工具，無特殊快取互動 |
| [Bash](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/bash-tool) | 標準用戶端工具，無特殊快取互動 |
| [記憶](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/memory-tool) | 標準用戶端工具，無特殊快取互動 |
## 後續步驟
了解完整的提示快取模型，包括 TTL 與定價。
按需載入工具而不破壞您的快取。
瀏覽所有可用工具及其參數。