Claude API 对话中途注入工具：不改 tools、不失效提示词缓存

云上的幻象2026-10-017 分钟阅读2,611 字30

100%

结论先行：Claude API 现在支持在对话进行中、通过一条「中途系统消息」动态注入或升级工具定义，而不必重发整个 tools 数组，也不会让已经命中的提示词缓存（Prompt Caching）失效。对长程智能体和需要按阶段逐步开放能力的场景，这能省下大量重复 token 和往返开销。

为什么需要在对话中途注入工具

传统做法里，工具列表在第一次请求时就固定写在 tools 字段里。一旦你想在对话后半段新增一个工具、或者把某个服务端工具的 schema 升级一版，要么重发整段 tools（缓存前缀被打断，命中率掉到 0），要么把工具一股脑全放进去（上下文更贵、模型更易误调用）。 Anthropic 在 2026-09-22 的发布里给出了更优雅的方案。

提示：提示词缓存的命中长期取决于「前缀是否变更」。任何让前缀变化的操作（包括改 tools）都会让缓存失效。 inline tools 的核心价值正是不动前缀。

inline tools 怎么用

在请求里带上 Beta 头 inline-tools-2026-09-15，并在一条「对话中途的系统消息」里用 tool_addition 块携带工具的完整定义。你可以新增工具、修改其 schema，或把一个服务端工具切到更新版本——全程不触碰原来的 tools 字段，缓存前缀保持不变。

curl https://api.anthropic.com/v1/messages \
  -H "anthropic-beta: inline-tools-2026-09-15" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "system": [
      { "type": "text", "text": "你是一个需要逐步获得能力的智能体。" },
      {
        "type": "tool_addition",
        "tool": {
          "type": "tool_definition",
          "definition": {
            "name": "query_orders",
            "description": "按用户 ID 查询订单",
            "input_schema": { "type": "object", "properties": { "user_id": { "type": "string" } }, "required": ["user_id"] }
          }
        }
      }
    ],
    "messages": [ { "role": "user", "content": "帮我查一下订单" } ],
    "max_tokens": 1024
  }'

同一个 Beta 头也支持「按引用增删工具」：你不需要把完整定义再发一遍，直接引用即可。这对多轮里反复开关同一组工具特别省力。

和 MCP 连接器一起用

配合 MCP 连接器的 mcp-client-2026-09-15 Beta 头，tool_addition 里的定义可以是一个 MCP toolset 。响应会用一个 mcp_tool_listing 块记录每个服务端实际拉到的工具清单，你回传时把它固定下来，就能避免每轮重复拉取、也防止服务端工具列表漂移导致的行为不一致。

什么场景最适合用 inline tools？