工具使用与 prompt caching

跨轮次缓存工具定义，了解什么会导致缓存失效。

本页介绍工具定义的 prompt caching：在哪里放置 cache_control 断点，defer_loading 如何保护你的缓存，以及什么会导致缓存失效。有关一般 prompt caching，参见 Prompt caching。

工具定义上的 cache_control

在 tools 数组的最后一个工具上放置 cache_control: {"type": "ephemeral"}。这会缓存整个工具定义前缀，从第一个工具到标记的断点：

{
  "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 toolset 内的工具顺序，因此将断点放在 mcp_toolset 条目本身上，API 会将其应用到最后展开的工具。

defer_loading 与缓存保护

延迟加载的工具不包含在系统提示前缀中。当模型通过 tool search 发现延迟工具时，定义作为 tool_reference 块内联追加到对话历史中。前缀未被修改，因此 prompt caching 得以保留。

这意味着通过 tool search 动态添加工具不会破坏你的缓存。你可以从一小组始终加载的工具（已缓存）开始对话，让模型根据需要发现额外工具，并在每一轮保持相同的缓存命中。

defer_loading 也独立于 strict mode 的语法构建而工作。语法从完整工具集构建，无论哪些工具被延迟，因此 prompt caching 和语法缓存在工具动态加载时都得以保留。

什么会导致缓存失效

缓存遵循前缀层次结构（tools -> system -> messages），因此一个层级的更改会使该层级及之后的所有内容失效：

各工具交互表

下一步