结合提示缓存的工具使用

本页介绍针对工具定义的 "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 标记时适用。未启用提示缓存的请求不会获得自动断点。



各工具交互表



后续步骤