使用提示词缓存的工具

本页面介绍工具定义的提示词缓存：在哪里放置 cache_control 断点、defer_loading 如何保留缓存，以及什么会使其失效。有关一般提示词缓存，请参阅提示词缓存。

工具定义上的 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 工具集中的工具顺序，因此请在 mcp_toolset 条目本身上放置断点，API 会将其应用于最终展开的工具。

defer_loading 和缓存保留

延迟加载的工具不包含在系统提示前缀中。当模型通过工具搜索发现延迟加载的工具时，定义会作为对话历史中的 tool_reference 块内联追加。前缀保持不变，因此提示词缓存得以保留。

这意味着通过工具搜索动态添加工具不会破坏缓存。您可以使用一小组始终加载的工具（已缓存）启动对话，让模型根据需要发现其他工具，并在每一轮中保持相同的缓存命中。

defer_loading 也独立于严格模式的语法构造而起作用。语法从完整工具集构建，无论哪些工具被延迟加载，因此当工具动态加载时，提示词缓存和语法缓存都得以保留。

什么会使缓存失效

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

按工具交互表

后续步骤