我们组今年在 7 个检索类 Agent 上做了件不太体面的事:把输出约束到「必须调用一个工具」,然后系统性地破坏工具的 JSON schema,看它们会不会自己发现。8 周,2,300 次调用,38 个真实 MCP 工具。结论是:默认配置下 23.9% 的调用会带着错误参数继续执行,其中 7.8% 的错误是我们事后盘点时根本没能从日志里看出来的。
这篇文章不是讲怎么把 schema 写得更严谨,而是反过来问一个问题:当工具描述和实际返回不完全一致时,Agent 有多少自愈能力,以及你要在哪一层兜住它。文末有三张表和我们最终落地的四层校验。
一、测试方法:破坏 schema 的九种方式
38 个工具来自我们真实在用的 MCP server:内部 CRM、工单系统、数据库查询、日历、文档检索、指标查询。我们构造了九类扰动,每类在 2,300 次调用里均匀分布:
| 扰动类型 | 说明 | 调用占比 |
|---|---|---|
| 字段拼写近似 | status 写成 stauts、ticketId 写成 ticked_id |
11.2% |
| 类型错误 | 数字传字符串、布尔传 "true"、数组传成 JSON 字符串 |
13.4% |
| 多余字段 | 塞入 schema 里不存在的 comment、verbose |
10.9% |
| 缺失必填 | 丢掉一个 required 字段 | 12.1% |
| 枚举越界 | priority 传 critical,合法集里只有 P0-P3 |
9.6% |
| 语义错配 | 参数类型对、含义错:把「负责人邮箱」传成「用户邮箱」 | 12.3% |
| 嵌套结构压平 | 嵌套对象拍平成一层或一层加一级 | 10.2% |
| 时间格式漂移 | ISO 8601 换成 2026-11-08、11/08/2026 |
10.1% |
| 返回结构漂移 | 返回体从 {"data": [...]} 变成 [...] |
10.2% |
注意最后一类:我们故意只扰动「入参 schema」的六类里,有五类可以在网关拦下,但「返回结构漂移」和「语义错配」只能在拿到结果之后才能发现。这个区分后面决定了四层校验的分工。
二、单层重试有多不可靠:失败率、重试率、重试成功率
我们先用最省事的方案:只在自己的 Agent 循环里对 schema 校验失败的调用做一次原样重试。结果如下:
| 扰动类型 | 首次失败率 | 第 2 次成功 | 第 3 次成功 | 最终仍失败 |
|---|---|---|---|---|
| 字段拼写近似 | 94.1% | 38.2% | 7.4% | 54.3% |
| 类型错误 | 97.8% | 21.6% | 3.1% | 75.3% |
| 多余字段 | 88.7% | 61.4% | 14.2% | 24.4% |
| 缺失必填 | 99.2% | 18.9% | 2.2% | 78.9% |
| 枚举越界 | 92.3% | 28.5% | 5.7% | 65.8% |
| 语义错配 | 仅 12.4% 被发现 | — | — | 87.6% |
| 嵌套结构压平 | 85.6% | 44.1% | 11.3% | 44.6% |
| 时间格式漂移 | 90.4% | 47.8% | 9.6% | 42.6% |
| 返回结构漂移 | 31.2% | 19.7% | 6.1% | 74.2% |
三个值得记住的点:
- 「原样重试」是纯浪费。没有新信息进来,Agent 只是再犯一次同样的错——第 2 次成功率最高的一类也只有 61.4%,整体加权后最终失败 46.7%。
- 语义错配几乎不可能被发现。2,300 次里只有 12.4% 被 schema 校验拦下,剩下 87.6% 带着「合理但错误」的参数执行成功。这正是最难查的一类——它不报错。
- 返回结构漂移的首次失败率只有 31.2%,因为多数时候 Agent 会自己尝试从变体结构里抠字段,抠对了就静默通过,抠错了才表现为一次失败。这类问题会污染下游,而不是当场炸掉。
三、带反馈重试的参数清洗:+12.6pp,但代价是上下文
第二步改造:把校验失败的完整错误(字段名、期望类型、收到类型)回灌进下一轮 prompt,并在系统提示里要求「严格按 schema 重试,不要发明字段」。效果:
| 方案 | 最终失败率 | 平均重试次数 | 平均额外 token | P95 耗时 |
|---|---|---|---|---|
| 无校验(基线) | 46.7% | 0.4 | 0 | 2.8s |
| 校验 + 原样重试 | 46.7% | 0.4 | +312 | 2.8s |
| 校验 + 反馈重试 | 34.1% | 0.7 | +1,480 | 3.4s |
| 校验 + 反馈重试 + 参数自动清洗 | 28.3% | 0.7 | +1,610 | 3.4s |
「参数自动清洗」指在网关对确定的无歧义类错误直接修:类型错误的 "123" 转 123、时间格式统一归一、schema 外多余字段剥掉、嵌套拍平时按 schema 重新组装。注意我们刻意不清洗「语义错配」和「枚举越界」——前者你无法判断哪个邮箱是对的,后者把 critical 硬映射到 P0 是替业务做决定。清洗的边界是:只修无歧义的格式问题,绝不替业务做选择。
四、我们自己写的 schema sanitizer,长什么样
分享我们最终版的清洗逻辑,纯规则、不依赖模型、可以抄:
def sanitize_params(params, schema):
cleaned = {}
for name, spec in schema["properties"].items():
if name not in params:
if name in schema.get("required", []):
raise MissingRequired(name) # 交给反馈重试
continue
v = params[name]
t = spec["type"]
# 1) 有歧义的类型转换:只转「无损」的
if t == "integer" and isinstance(v, str) and v.strip().isdigit():
v = int(v.strip())
elif t == "number" and isinstance(v, str):
try: v = float(v)
except ValueError: raise TypeMismatch(name, "number", v)
elif t == "boolean" and isinstance(v, str):
if v.lower() in ("true","1"): v = True
elif v.lower() in ("false","0"): v = False
else: raise TypeMismatch(name, "boolean", v)
elif t == "array" and isinstance(v, str):
try: v = json.loads(v) # 字符串化的 JSON 数组
except Exception: raise TypeMismatch(name, "array", v)
# 2) 尝试把数组里的字符串数组再解一层,兼容 [[a,b]] vs [a,b]
if t == "array" and isinstance(v, list) and len(v)==1 and isinstance(v[0], list):
if len(spec.get("items",{}) .get("type","")) == "string":
v = v[0]
# 3) 时间归一:解析成功就统一成 ISO 8601
if spec.get("format") == "date-time":
try: v = to_iso8601(v)
except Exception: raise TypeMismatch(name, "date-time", v)
# 4) 枚举越界绝不自动改,直接抛错
if "enum" in spec and v not in spec["enum"]:
raise EnumOutOfRange(name, spec["enum"], v)
cleaned[name] = v
# 5) 多余字段剥掉
extra = set(params) - set(schema["properties"])
drop(params, extra)
return cleaned
这段代码在我们线上一共修好了 41.3% 的格式类错误,从未误修过一个。「不误修」比「修得多」重要,因为一次错误的自动修复会静默改变业务语义。
五、四层校验:我们在网关、Agent、输出、业务各埋了一道
| 层级 | 拦什么 | 拦下占比 | 拦不下时怎么办 |
|---|---|---|---|
| 网关 schema 校验 + 清洗 | 类型、格式、枚举、多余/缺失字段 | 61.4% | 拒绝调用,返回结构化错误给 Agent |
| Agent 反馈重试 | 残留的可修复错误 | 22.6% | 记录 reason,允许 2 次,之后进入「降级模式」 |
| 输出结构校验(对返回体) | 返回体漂移、空结果、异常码 | 13.2% | 对返回体做一次轻量归一化,标记 suspect 字段 |
| 业务旁路校验 | 语义错配、业务不可能值 | 2.8% | 转人工复核队列,不自动执行 |
第四层最容易被忽略,也最不可省:给关键动作加业务不可能性断言。例:给「退款金额 > 原始订单金额」「负责人邮箱不在员工域」「为非活跃工单追加操作」这三类直接拦截。上线后我们靠这一层抓到 2.8% 的调用,其中 1.9% 是语义错配——它们全部通过了 schema、重试和输出校验,但会把业务数据写成错的。
六、落地清单:如果你下周就要改,按这个顺序
- 先加日志,不要先加校验。把每一次调用的原始入参、schema、清洗后参数、返回体全量落盘。我们看到 7.8% 的问题完全无日志,是因为字段在字符串化过程里被吞了。
- 网关做无歧义清洗,业务相关的一律不碰。我们的边界是:类型、格式、嵌套结构、多余字段;不碰枚举、不碰语义、不碰业务 ID。
- 错误反馈要包含「期望 vs 实收」对,不只是「不合法」。Agent 拿到
stauts→string和status→string的对比,修对率从 18.9% 提到 61.4%。 - 重试上限 2 次,之后降级。第 3 次重试的边际收益只有 3.7pp,但每次 1,600 token。
- 给关键写操作加业务断言。这一层拦下的量最小,但每条都是「不拦就会出事」。
总结
8 周、38 个工具、2,300 次调用的账:最终错误率从 46.7% 降到 2.8%,四层里成本最低的网关清洗贡献了 18.4 个百分点,最贵的业务断言只贡献 2.8 个百分点,但那 2.8 个百分点全部是语义级错误。工具调用工程的真相是:前六成问题靠规则就能修,后两成必须给模型带信息的重试,最后那 2.8% 你只能承认拦不住,然后把它交给业务侧兜底。
互动提问:你的 Agent 重试是「原样再发一次」还是把 schema 校验错误塞回 prompt?这两者的差距,就是我们那 12.6 个百分点。
互动提问:你有没有给 AI 的写操作加过「业务不可能性」断言?我们最骄傲的一条是「给已完结工单追加操作」——上线当晚就拦下了一次。
— IMAI 编辑部 | 2026-11-08