AI Agent 工具调用怎么避免参数漂移：版本快照、字段校验与失败回放

线上订单助手最近多了一类很难排查的失败：模型明明调用了正确的工具，却把上一版的 user_id 传回来了，而当前工具只接受 account_id。如果只看最后一条错误日志，往往只能得到“参数不合法”，很难判断是模型理解错了、工具描述过期，还是服务端部署了不同版本。

把工具定义和实际调用绑定成可追踪的版本快照，在入口做严格字段校验，并保存足够的失败上下文，参数漂移就能从“偶发玄学”变成可回放、可定位的问题。

先把工具契约当成需要保护的资产

Agent 系统里最容易被忽略的资产不是模型，而是“模型以为自己能调用什么”。工具描述通常来自注册表或系统提示，服务端却可能已经升级了参数。两边只要有一个字段名不同，调用链就会在最后一公里断掉。

我更建议把一次调用拆成三份数据保存：模型看到的工具快照、模型实际提交的参数、服务端最终采用的校验 Schema。三份数据都带同一个 tool_version，后面才能回答“模型当时依据的是什么”。

参数漂移通常沿着三条路径发生

第一条是字段改名。比如工具从 user_id 改成 account_id，描述更新了，但长连接中的会话还握着旧工具清单。

第二条是类型收窄。旧版本允许数字或数字字符串，新版本只接受整数。模型给出的值看起来没问题，严格校验却会拒绝。

第三条是嵌套结构变化。原来的 filters.status 是字符串，后来变成数组。错误发生在深层字段，简单打印顶层参数很难看出来。

先分级，再决定要不要让模型重试

未知字段和缺少必填字段属于契约错误，应该先记录并终止本次工具执行。盲目重试只会让同一份错误参数重复进入系统，还可能重复触发有副作用的工具。

类型错误可以在边界层做有限归一化，例如把明确的数字字符串转成整数，但必须记录 coercion_applied。如果字段名不认识，不要猜测它是不是旧字段，更不要根据相似度自动改名。

业务拒绝则是另一层问题：参数已经符合 Schema，但订单不存在或权限不足。把它和契约错误分开，模型才知道是换参数、换工具，还是向用户说明情况。

用版本快照锁住模型看到的那一刻

工具注册表可以给每个定义一个不可变版本号。组装上下文时，把工具名、版本号和 Schema 摘要写进本次会话记录；模型发起调用时，要求请求中带回这个版本号，服务端再核对它是否仍然可用。

type ToolCallAudit struct {
    CallID       string
    ToolName     string
    ToolVersion  string
    SchemaDigest string
    Arguments    []byte
    ResultCode   string
}

如果版本已经下线，返回“工具版本不可用”比返回笼统的“参数错误”更有价值。对于读操作，可以让编排层重新拉取工具定义后发起一次新的模型决策；对于写操作，应该先停住，避免旧参数被转换成错误动作。

字段校验要留下可读的失败证据

校验器至少要输出路径、期望类型、实际类型和规则版本。例如 filters.status 缺失与 filters.status 类型错误，排查方向完全不同。

{
  "path": "filters.status",
  "kind": "type_mismatch",
  "expected": "array[string]",
  "actual": "string",
  "tool_version": "orders.search@2026-08-24.2"
}

日志中可以保存经过脱敏的参数摘要，但不要把完整身份证号、访问令牌或用户私密内容直接写进回放库。审计记录的目标是复现契约判断，不是复制生产数据。

失败回放要复现旧契约，而不是追最新版本

回放任务需要同时保存 call_id、工具版本、Schema 摘要、模型原始参数、校验结果和脱敏后的上下文。处理人员先用旧快照重现原错误，再切换到当前版本验证修复是否有效。

一个实用的回放顺序是：确认原始参数未被改写；按旧版本执行纯校验；记录失败路径；最后才用新版本做对照。这样不会把“工具已经修复”误判成“模型从未出错”。

上线前用四组案例验收

• 旧字段：提交 user_id，确认被识别为未知字段且不会自动改名。
• 类型边界：提交数字字符串、空字符串和真正的数字，确认归一化规则与审计字段一致。
• 嵌套结构：让 filters.status 分别传字符串、数组和缺失值，核对错误路径。
• 版本下线：使用已撤回的工具版本，确认读写工具拥有不同的停机策略。

验收结果不要只看 HTTP 状态码。至少把 tool_version、schema_digest、validation_kind 和 replayable 作为断言字段。只要其中一个字段缺失，后续排障仍会回到猜测。

常见问题

参数漂移时能不能让模型自动猜字段名？

不建议。相似字段可能代表不同权限或业务含义。更稳妥的做法是返回明确的契约错误，让编排层刷新工具快照后重新决策。

只记录请求参数够不够回放？

不够。没有工具版本和 Schema 摘要，就无法确认当时的校验规则；没有脱敏上下文，也无法判断模型为什么选择了这个字段。

所有工具都要保存完整原始上下文吗？

不必。按数据敏感等级保存最小可复现片段即可。对于支付、身份和内部检索工具，优先保存哈希、字段路径与规则结果，并把原文留在受控审计系统。

把漂移问题收敛成一张检查清单

工具定义有不可变版本，模型调用携带版本信息，入口校验拒绝未知字段，错误结果区分契约与业务，回放任务固定使用旧快照，日志对敏感参数做了最小化处理。做到这几项，Agent 的参数漂移不再依赖某次模型“碰巧理解正确”，而会成为一条能验证、能回滚、能复盘的工程链路。