MCP 工具调用的 23.9% 静默失败:38 个真实工具、2,300 次调用,四层校验把错误率压到 2.8%

我们组今年在 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、重试和输出校验,但会把业务数据写成错的。

六、落地清单:如果你下周就要改,按这个顺序

  1. 先加日志,不要先加校验。把每一次调用的原始入参、schema、清洗后参数、返回体全量落盘。我们看到 7.8% 的问题完全无日志,是因为字段在字符串化过程里被吞了。
  2. 网关做无歧义清洗,业务相关的一律不碰。我们的边界是:类型、格式、嵌套结构、多余字段;不碰枚举、不碰语义、不碰业务 ID。
  3. 错误反馈要包含「期望 vs 实收」对,不只是「不合法」。Agent 拿到 stauts→string 和 status→string 的对比,修对率从 18.9% 提到 61.4%。
  4. 重试上限 2 次,之后降级。第 3 次重试的边际收益只有 3.7pp,但每次 1,600 token。
  5. 给关键写操作加业务断言。这一层拦下的量最小,但每条都是「不拦就会出事」。

总结

8 周、38 个工具、2,300 次调用的账:最终错误率从 46.7% 降到 2.8%,四层里成本最低的网关清洗贡献了 18.4 个百分点,最贵的业务断言只贡献 2.8 个百分点,但那 2.8 个百分点全部是语义级错误。工具调用工程的真相是:前六成问题靠规则就能修,后两成必须给模型带信息的重试,最后那 2.8% 你只能承认拦不住,然后把它交给业务侧兜底。

互动提问:你的 Agent 重试是「原样再发一次」还是把 schema 校验错误塞回 prompt?这两者的差距,就是我们那 12.6 个百分点。

互动提问:你有没有给 AI 的写操作加过「业务不可能性」断言?我们最骄傲的一条是「给已完结工单追加操作」——上线当晚就拦下了一次。

分享到:

微博
Twitter
LinkedIn

分享到:

微博
Twitter
LinkedIn

— IMAI 编辑部 | 2026-11-08

发表评论