工具使用与提示缓存

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



各工具交互表



后续步骤