loading

Loading

探索与发现

首页 Agent 工程

Agent工具参数模式的兼容包袱怎么背

分类:Agent 工程
字数: (2140)
阅读: (6)
0
摘要:参数字段改名或拆层级,别当纯代码 review。MCP 只要更新 Server 就以为跟进了模型侧,实际它看到的仍是旧结构。加上 Client 缓存截断变化,参数形态校验更靠结构输入。经验是加法优先共存、旧版本登记迁移表、改 schema 就换缓存区,成本都在日志统计与历史回放里。

旧 schema 不会自己退场

每次改工具参数,我都先问一句:线上还有多少 Agent 拿着旧 schema 在跑?上周把 query 拆成 query.text 和 query.filters,上线当天就挂了一批历史工作流——那些工作流把工具 schema 硬编码在了自己的 prompt 里,模型照着旧结构生成参数,新服务端直接返回 400 Unrecognized field。

MCP 在这件事上的设计很直接。Anthropic 在 2024 年 11 月底提出的这个协议,把工具定义、参数 schema 和调用结果都收进一个标准 Server 里,Client 通过 tools/list 拉到当前可用的定义。理论上 Server 改了参数,Client 下次拉取就自动跟上。可问题是,模型侧还在使用那份内容被内联在 system prompt 里的旧 schema 描述。协议层兼容了,提示层没有。

模型和 schema 是一条船上的

Function Calling 的参数生成走的是模型内部的条件分布。工具名、字段名、字段类型、甚至描述文本的措辞,都参与了这个分布。把 query 从字符串改成对象,命名没变,模型生成对象的概率并不天然高于生成字符串。结果就是新 schema 到了,模型仍然吐旧格式,校验层拒掉,触发一次无意义的重试。

所以我在参数演进上用的是“加法优先”:query.text 上线时,query 仍然合法,两者共存;服务端在解析入口做一次归一化,把旧入参转换到内部模型。等某个旧字段的调用量在审计日志里连续一两个月掉到接近零,才从 tools[] 没有那个固定的结构化系统消息槽位,模型看到的 schema 描述其实是由应用自己拼进提示的。这意味着,模型的参数生成实际上由应用层契约决定,协议本身提供的是发现机制和传输管道。两条线要分开看:服务端定义的 schema 决定了模型看到什么,模型看到什么又反过来决定它生成什么。Anthropic 文档里那份 Tool Use (function calling) 指南其实写明了参数描述格式,但真正决定模型行为的是 Client 把它怎么拼进上下文。

自定义 Client 的逻辑收敛

自定义 Client 更典型,它往往只在初始化时拉取一次 tools/list,然后把结果缓存下来。要是 Server 在同一次模型会话里改了参数默认值,这个 Client 直到会话结束都不会知道。我们线上就遇到过这种情况:Server 新加了一个 limit 默认值,但模型从未收到这个变化,仍然按旧习惯生成大结果集,触发了下游分页的三次来回。

改进的方向是限定缓存有效期:Client 每次构造请求前,先看缓存的 schema 是否过期,再决定要不要发起一次轻量校验。Controlat rol 一次握手成本大约 100 到 200 毫秒。

参数值格式是更土但更尖锐的问题

新增字段可以通过并行支持老版本平滑过渡。难的是类型漂移。把 page_size 从数字字符串 \"20\" 换成整数,模型侧不会收到任何可感知的变化。它会根据提示里的残留描述继续生成字符串。这类演化冲突是“静默的”,直到前端做对比对时才暴露。

去年做搜索工具时踩过更丑陋的例子。参数是 namespace,从单值弦改成逗号分隔串——这是一种非法变更,但如果报告给模型的那一侧,Client fall 不校验。结果一个后台 worker 把原始 JSON 不加校验括到应用里,一个上报的错误字段被模型二次组织成了另一个代码补全请求的 payload。我们后来审查 Agent 日志,只在记录时才做参数异常、识别名、补充缺失默认值。

无参无类型带来的问题是排障成本,你很可能看到模型生成一个逻辑看起来合理的对象却被 list 与 list 之间的不匹配给绊倒。后来我把工具入口签名中的形纳入缓存键,请求执行时复用编排后的中间表示。推理侧常见的序列键、、json_schema 这类策略参数,也对这块校验带来微小变化之一。

一种折中做法

折中做法在我手上的权重越来越到了经验量级:

工具定义写在一个外部仓库里,经主分支生成几个内容入口——如果能够写定 limit 取值范围总比空对空描述要好,正确断言权限门禁时要额外等待确认,配合校验拦截假工具。真正的工具治理就是把这件事归到校验和测试里。其实要做到轻(Array、Nullable)就是接受坏输入集永远不能默认信任:Agent 发起成功、无副作用,结果错误响应里不会有那个风险。

我在维护 MCP 时前明确一点:参数演进的成本不在代码库本身而在三件事上:

第一,历史会话与历史工具列表——老的工具 schema 是否还被持久化,在某些工作流引擎里它把原始工具定义保存到执行快照里,没人会重新拉取。清单这类 schema 时把完整的所有者,内容全都要打上版本标记 schema_version,执行旧执行时先根据它触发通知。我们没有为此重构,直接新增一个异步 notice 工具目标接口,输出内容是适配旧协议的参数吗参数迁移的剩余生存期是由代码审计决定并最终移除。

真正做版本演进的代价

转载请注明出处: 皮哈皮阿

本文的链接地址: https://blog.phpat.com/agent-engineering/693.html

手机扫码阅读

微信或手机浏览器扫一扫,随时随地随心阅读与分享

您可能对以下文章感兴趣
1 / 1
预览图