工具字段没变，Agent为什么把12元预算放大了？

一个采购资料Agent昨天还能正确筛选报价，今天却把一批超出预算的方案放进了候选名单。工具没有改名，max_price 仍是整数，请求照常成功。

变化藏在说明里：旧工具把金额解释为“分”，新实现改成了“元”。Agent保存的旧调用没有变化，同一串数字却不再代表同一件事。

这不是某个真实产品事故，而是本文的虚构教学场景。它要回答的问题很具体：给Agent升级工具时，为什么“参数仍能通过Schema”远远不够？

AI原创概念插画：两只外形近似的香水瓶与大小不同的量勺，比喻外形一致而含义不同。瓶身、图纸和量勺均为艺术化道具，不是经过校准的仪器，也不代表真实软件事故。

一、结构兼容，可能掩盖语义断裂Copy Anchor Link

假设用户要求：“只整理单价不超过12元的样品报价，不下单。”旧版只读工具叫 find_quotes，文档明确 max_price 使用人民币分，Agent因此保存了这份调用计划：

{"max_price":1200,"category":"sample"}

现在服务端把同一个字段改成“人民币元”，输入Schema仍然接受正整数。旧请求就可能被当成“单价不超过1200元”。这里的金额关系只是单位换算，不是模型或检索效果实测。

工具没有越过“只读”的动作边界，却已经偏离用户的预算边界。若后续报告把候选项统称为“预算内方案”，错误还会继续传播。

这一类问题可以分成三层：

这张表是面向Agent的解释性分层，并非另造一套协议标准。Google的AIP-180正式区分了源码、线缆与语义兼容，并强调：即使程序仍能运行，改变用户合理依赖的可见行为也可能构成破坏性变更。[1] 它是Google API设计指导，主要以Protocol Buffers和JSON为背景，不是所有Agent框架共同遵守的强制规范。

对Agent而言，风险还多了一处：旧含义可能不只写在代码里，也留在对话、少样本示例、计划、记忆或暂停任务中。服务端上线成功，不代表这些消费者已经同时更新。

二、别把三个“默认”混在一起Copy Anchor Link

另一个更安静的变化，是省略字段之后发生什么。

假设报价工具新增了可选的 include_expired，旧行为从不返回已过期报价。若新增字段缺省时却包含过期项，那么旧客户端根本没有发送新字段，结果范围仍然改变了。

这里要分别看：

• 文档里的默认说明：告诉调用者，缺省应当如何解释。
• 校验器的行为：检查输入是否合法，是否另有配置负责补值。
• 服务端的实际缺省行为：执行代码在字段缺失时真正采取什么行动。

JSON Schema官方文档明确说，default 是注解，校验过程不会因此自动填入缺失值。[2] 某些表单生成器、SDK或带扩展配置的校验器可以另行使用它；那是具体工具链行为，不能从Schema中出现了 default 就推定已经生效。

因此，在Schema里写 default: false，不能单独证明服务端真的排除了过期报价。要检查字段缺失时的真实分支，也要区分缺失、显式 false 与 null；后两者是否允许，应由当前契约确定。

AIP-180也要求新增字段的缺省行为保留旧客户端原有待遇，并把资源字段静态默认值的改变视为破坏性变更。[1] 这里不能偷换成“所有动态默认值永远不得变”：该文档对静态资源默认值有明确范围。本文对报价请求的建议，是依据兼容性原则作出的工程判断。

三、重新发现工具，不等于旧计划已经迁移Copy Anchor Link

你也许会说：“让Agent再读一次工具列表不就好了？”

它能解决一部分问题：取得当前名字、描述与参数约束。但重新取得新说明，并不能自动证明三件事：

1. 历史计划中的数字已经按新单位转换；
2. 暂停中的任务已经绑定正确的新旧实现；
3. 尚在执行的旧请求会被安全处理。

MCP的2025-06-18版Tools规范定义了 tools/list，工具包含名字、描述、输入Schema，也可提供输出Schema；声明了相应能力的服务端，在工具列表变化时应发送 notifications/tools/list_changed 通知。[3]

这说明协议提供了发现与变化通知机制，不是说通知会自动完成业务参数迁移、撤销旧计划或锁住服务版本。尤其不能把“没有收到通知”当成语义未变的证据。客户端还要按自己的连接、缓存与失败策略，决定何时重新读取和怎样处理变化。

也不要把MCP协议版本当作某个报价工具的业务版本。同一个协议版本下，服务端仍然可以提供不同的工具集合与业务契约。协议兼容和业务语义兼容，是两份验收。

四、把“保留旧意思”做成可执行的升级方案Copy Anchor Link

针对前面的虚构报价工具，一种可采用的迁移方式是：

先固定旧入口。 旧 find_quotes 继续把 max_price 当作分，不能悄悄换成元。内部可以改实现，但适配层必须保留旧语义和范围。

再提供明确的新契约。 新入口可以叫 find_quotes_v2，使用 max_price_minor 与 currency，把金额解释为相应币种的最小单位，并明确支持哪些币种、精度、边界和换算规则。换个字段名并不自动使设计正确；不支持的币种或精度，应当明确拒绝而不是猜。

最后决定旧任务走哪条路。 若旧入口仍可靠可用，旧任务可以按原语义继续。若必须迁移，应先把保存的预算还原成明确的业务量，再转换为新输入，重新核对用户约束。如果历史记录只剩 1200，却没有任何可信依据说明其单位，就应当停止该步骤，标记“无法确定金额语义”，不能仅因当前文档写着元就直接套用。

这套版本名与字段名是教学设计，不是MCP标准字段，也不是本文已部署的API。

在运行层，可以保存一份很小的“调用契约记录”：

{
  "tool_identity":"trusted-quotes/find_quotes",
  "business_contract":"quotes-v1",
  "amount_unit":"CNY_minor",
  "arguments":{"max_price":1200,"category":"sample"},
  "intent":"read_only_budget_filter"
}

它用于让恢复程序知道旧调用原本是什么意思；字段本身不产生信任或权限。可信服务标识、版本到实现的路由，以及执行前校验都要由应用真正实现。给Schema算个哈希可以发现文档字节变化，却不能证明服务端代码、默认行为或授权策略没有变化。

迁移也不能随意改已提交调用的幂等身份。若动作涉及外部写入，先确认旧动作是否生效，再讨论新版本输入；“升级”不是重复发送的理由。本例刻意使用只读报价筛选，只解释语义升级，不演示支付或订单执行。

五、测试要断言含义，而不仅是“没有报错”Copy Anchor Link

下面是建议建立的测试表，尚未执行，不是测试通过报告，也没有调用模型或报价服务。

对于金额例子，断言应当落实到筛选后的业务集合：超过12元的项目不能被标成预算内。只断言HTTP成功、JSON可解析、返回条数非零，都没有检查到这件事。

如果新工具改变了候选召回质量，还要另外做真实数据评测；兼容性夹具不能证明模型更准确。若后台只是修复了明显违背原文档的缺陷，也应记录修复的影响，不把“兼容”理解为必须永远保留所有错误。关键是把预期、受影响消费者和迁移安排讲清楚。

六、给工具升级留一份短检查单Copy Anchor Link

发布前，可以按这份清单逐项核对：

• 不只比较字段类型，也比较单位、时区、范围、排序、缺省与错误语义。
• 确认注解、SDK补值与服务端真实行为一致，单测字段缺失和显式值。
• 枚举旧消费者：运行中的任务、暂停计划、示例、记忆与适配层，不只查新代码。
• 对破坏性变化选择旧语义适配、明确新入口或显式迁移；不要只改说明后原地替换。
• 规划记录与执行检查能识别可信工具及业务契约；识别失败时不猜版本。
• 输入和输出都测，未知状态、未知枚举与不完整结果有明确处理。
• 保留旧路由的期限和退出条件，观测仍在使用旧契约的任务；回退不自动撤销已发生效果。
• 动作权限、用户确认、幂等与结果验收仍单独成立，不被“版本正确”替代。

工具契约不是一张永远静止的参数表。对Agent系统，它还是模型理解、保存计划与后端执行之间的接缝。升级真正要守住的，不是“旧JSON还能发出去”，而是“旧意图不会被新实现悄悄改写”。

来源、日期与阅读范围Copy Anchor Link

本文由AI创作。报价、金额、字段和契约记录均为虚构教学材料；未运行Agent、模型、MCP服务、报价API或迁移测试。文中的测试表是建议，不是实测结果。

资料检索截止：2026年10月23日15:33 UTC。以下来源只支撑兼容性与协议机制，不构成本文方案的上线证明。

1. Google AIP-180：Backwards compatibility。实际阅读Guidance、Semantic changes、静态默认值及Changelog相关正文；页面所列最新变更为2025-10-21，未将其当成本次新公告。该指导的适用背景及有限消费者场景限制见原文。
2. JSON Schema：Annotations。实际阅读该短页，重点为 default、说明与注解；动态说明页，未核实独立原始发布日期或锁定发布版本。
3. MCP Tools规范，2025-06-18版。实际阅读工具发现、列表变化通知、Tool类型、输出Schema及安全要求相关章节。本文刻意固定该版，不声称它是当前最新版本，也不把协议通知扩写为业务迁移保证。