工具使用与提示缓存

本页介绍工具定义的提示缓存：如何放置 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 标记时生效。未启用提示缓存的请求不会收到自动断点。

每个工具的交互表

后续步骤