Claude API 内联工具：对话中途动态添加工具

Claude API 的 beta 版内联工具定义（inline tool definitions）允许开发者在一段对话进行到中途时，通过一条 system 消息动态添加、调整或升级工具，同时保留 prompt cache 的命中收益。这一能力打破了传统上「工具集必须在会话开始前固定」的限制，为需要多轮能力扩展的 Agent 应用提供了更灵活的编排方式。

核心机制：用一条 system 消息声明新工具

传统做法里，工具的 JSON schema 需要放在请求开头的 tools 字段中，一旦会话开始，中途想加新工具只能重置会话，导致已缓存的前缀失效、token 成本上升。内联工具把这个动作变成了对话的一部分：在消息流中插入一条 system 消息，内部声明新工具或覆盖已有工具的定义，模型在后续轮次即可调用。

据原始来源说明，这种方式的关键优势是「keep the prompt cache」——新工具声明以增量形式进入上下文，而非重写整个请求前缀，因此原有的缓存片段仍可复用。对于长会话、多阶段任务（例如先检索、再计算、最后写入）的场景，这能显著降低重复计费并缩短首 token 延迟。

Prompt cache（提示缓存） 是 Anthropic API 提供的一项成本优化机制：当请求前缀（如 system prompt、工具定义、历史消息）与之前请求完全一致时，服务端会复用已缓存的计算结果，从而降低 token 计费并减少首 token 延迟。缓存通常以请求前缀的连续匹配为条件，一旦前缀中任何部分发生变化（例如在开头插入新工具定义），后续内容便无法命中缓存。内联工具定义之所以能“保留缓存”，是因为它将新工具声明作为对话流中新增的 system 消息插入，而不是修改请求开头的 tools 字段，因此原有前缀未被破坏，缓存片段仍可复用。理解这一点对评估成本模型至关重要。

三种典型用法：新增、重塑与升级

原文把内联工具的价值归纳为三个动作，它们对应不同的工程需求：

• 新增（define）：会话初期只需要基础工具，进入特定子任务时再挂载专用工具，避免一开始就把巨大的工具集塞进上下文。
• 重塑（reshape）：当同一工具的参数结构需要随上下文变化（例如查询从宽松模式切到严格模式），可中途重写定义，而不是新建一个语义重复的工具。
• 升级（upgrade）：工具版本迭代时，在会话中平滑切换到新 schema，让模型继续用同一工具名完成任务，减少编排层的分支判断。

这三种用法共同点是：工具集的演化被显式写进对话轨迹，而不是隐藏在外部状态机里。这意味着调试时可以直接从消息记录还原模型当时可用的工具集合，对可观测性有实际帮助。

工具定义（tool definition） 在 Claude API 中通常以 JSON Schema 形式描述，包括工具名称、功能描述以及输入参数的字段与类型。模型依据这些信息决定是否调用工具以及如何构造参数。内联工具定义允许在对话中途通过 system 消息重新声明工具，其效果是覆盖或扩展模型当前可用的工具集合。需要注意的是，工具定义本身也消耗上下文 token，且模型对工具的理解依赖于描述的清晰度。动态变更时，应确保新定义与旧定义在语义上平滑过渡，避免模型混淆。

对 Agent 架构的影响

内联工具把「工具注册」从请求级配置下沉为对话级事件，这对 Agent 设计有几点现实意义。其一是上下文预算管理更精细：工具 schema 本身也占 token，按需挂载能把有限的上下文留给真正的内容。其二是工具权限可以随会话阶段收紧或放宽，比如敏感操作工具只在用户确认后注入，降低误调用的面。

需要提醒的是，这仍是 beta 特性，原文给出的实现以「code included」的方式提供示例代码。生产环境采用前应验证两件事：动态变更工具定义后，模型对工具名与参数的理解是否稳定；以及缓存复用在多次插入 system 消息后是否仍符合预期。这两点直接决定成本模型是否成立。

实践建议

把内联工具与传统静态工具集混用时，建议给每次工具变更定义明确的触发条件，并在 system 消息中写清工具的适用边界，避免模型在旧工具已失效的情况下继续尝试调用。同时保留一份会话级的工具变更日志，便于回放与计费核对。对成本敏感的团队，可以先在非关键链路做 A/B，对比缓存命中率与工具调用准确率的变化，再决定是否扩大使用范围。

总体来看，内联工具是 Claude API 向「可演进会话」方向的一次务实补充：它没有改变工具调用的基本原理，但把工具集的生命周期管理交还给了对话本身，为多阶段 Agent 提供了更细粒度的控制手段。