Agent 为什么会静默失败?
一个横跨 72 万个参数的审计,揭开了 Agent 工具调用最隐蔽的坑
先看一组数字
2026 年,一项叫 SilentProbe 的研究审计了 OpenAPI 文档,规模大得吓人:
2,501 份文档
覆盖 27 家厂商的真实线上接口
721,320 个参数
每一个都做了机器可校验性检查
Live 扰动测试
故意发错参数,看 API 怎么回应
结果很扎心
研究者故意发错参数,然后观察 API 的反应。两种写法,命运天差地别:
"description": "请确保 date 为
ISO 日期格式"
// 结果:61 例中 44 例
// API 返回 HTTP 200 + 正常 body
// Agent 完全不知道自己错了
约束被写成了「客气的请求」,不是硬性边界。
模型发错了日期格式,服务端却照样收下。
返回 200 = "成功"?Agent 认为自己做对了。
这就是静默失败:错了,但没人知道。
写成机器可校验约束(enum / pattern / format)的参数:111 次错误全部诚实报错,无一静默失败。
最戏剧的一组数据
同一批模型、同一批厂商,只改一行 schema,行为天翻地覆:
模型不是不守规矩——是你的 schema 没给它守规矩的机会。约束的形式,决定了 Agent 的可靠性。
热身检查
来,用一个场景验证你抓住重点没有:
你的 Agent 调用了一个天气工具,参数 city 填了「北京」而不是工具期望的 "beijing"。API 返回了 HTTP 200 和一段"暂无该城市数据"的文案。Agent 接下来会怎么做?
Agent 会怎么理解这次调用?
答案就藏在 schema 的写法里。下一模块,我们解剖 schema 本身。
Schema 的解剖学
一个参数定义里的每个部位,各管一件事——搞混了就会出事
Schema 是模型的「合同」
把工具 schema 想象成一份租房合同:它不是给租客的建议清单,而是有法律效力的边界。合同里不同的条款有不同的效力——
type / enum / pattern
硬性条款:机器直接校验,违反就报错。相当于合同里的违约责任。
description
走廊里贴的便条:帮模型理解「这参数是干嘛的」,但没有任何强制力。
逐部位拆解
{
"status": {
"type": "string",
"enum": ["pending", "paid",
"shipped", "closed"],
"description": "订单当前状态"
}
}
type — 基础类型边界:这里只能是字符串,填数字直接被拒。
enum — 价值连城的一行:模型只能四选一,想自由发挥都没门。
description — 语义说明书:告诉模型这参数「是什么意思」,帮它选对值,但不约束它。
约束归机器(enum/pattern/format/minimum),语义归文字(description)。一旦你把约束写进 description,它就从「合同条款」降级成了「走廊便条」。
拖拽挑战:这条要求该写在哪?
你有一句需求:「订单状态只能填 待支付、已支付、已发货、已关闭 之一」。它应该放进 schema 的哪个部位?拖一拖:
「只能是这 4 个词里的一个」
「这个参数代表订单当前所处的阶段」
「日期必须长得像 2026-09-04」
「这个字符串是标准 ISO 日期」
为什么模型会「听便条不听话」?
用聊天动画看模型的内心戏:
看到了吗?整场灾难里没有一个人「违规」——因为根本没有可校验的规则。解药是什么?往下看。
5 条规则,逐条拆解
每条都是「反例 → 正例」的对照,外加一道应用题
枚举优先:能用 enum 就别写 description
还记得模块一的 88/88 → 0/89 吗?这就是它的落地写法:
"status": {
"type": "string",
"description": "订单状态,如已完成、
待支付等"
}
// 模型自由发挥:"completed"
// "paid"、"done" 都可能出现
"status": {
"type": "string",
"enum": ["pending", "paid",
"shipped", "closed"]
}
// 模型只能四选一,
// 想错都没有机会
你在给一个「发送邮件」工具写 schema,priority 参数希望模型填 high / normal / low 之一。怎么写?
priority 参数的正确写法是?
约束下沉:格式写进 pattern/format,别靠「请确保」
"date": {
"type": "string",
"description": "请确保使用
YYYY-MM-DD 格式"
}
// prose 约束是建议,不是边界
"date": {
"type": "string",
"format": "date",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
// 机器可校验:
// 111/111 诚实报错的那一类
看到 description 里有「请确保」「必须」「不能超过」——警报响起:这句话该搬家到机器可校验的字段里去。
一词一义:名字里不许有歧义缩写
{ "name": "get_usr_info",
"parameters": {
"uid": "用户ID或用户名",
"ts": "时间范围或时间戳"
} }
// usr 是 user 还是用户组?
// ts 接受几种形态?模型只能猜
{ "name": "get_user_profile",
"parameters": {
"user_id": "唯一数字ID",
"timestamp": "ISO 8601 时间戳"
} }
// 一词一义,无从猜错
一个参数描述里出现「或」字,就是幻觉参数的温床——模型猜错分支,比猜错值更难排查。
错误设计:报 422 + 结构化错误,别报 200 + 模糊文案
HTTP 200
{ "code": 0,
"msg": "ok",
"data": null }
// agent 无从分支:
// 是没命中,还是没理解?
// 41% 虚报成功率的源头
HTTP 422
{ "error": {
"field": "date",
"constraint": "pattern",
"expected": "YYYY-MM-DD",
"received": "09/04/2026" } }
// agent 拿到修复所需的全部信息
结构化错误是 agent 重试和自我修复的触发信号。「expected vs received」让模型一眼看出差在哪,下一轮就能改对。
描述有界:description 只写语义,不承载约束
"count": {
"type": "integer",
"description": "返回条数,不能超过100,
必须是正数,否则请求无效"
}
// 约束藏在散文里 = 没有约束
"count": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "单页返回条数"
}
// 语义归语义,约束归机器
综合找茬:这段 schema 中的几条毒药?
这是 SilenProbe 风格的真实翻车现场。哪条规则被违反得最致命?
"search_orders": {
"description": "查询订单,date_range 请确保用 YYYY/MM/DD",
"parameters": {
"kw": "关键词或订单号",
"limit": { "type": "integer", "description": "条数,必须在1-50之间" }
}
}
哪一处最可能导致「静默失败」?
从规则到习惯
写完 schema 之后,用「schema-lint 思维」过一遍
把 5 条规则变成一道检查清单
像机场安检一样,每个参数都要过这四道门:
是 → 升级为 enum。是自由文本 → 下一道门。
写进 pattern / format。description 里不许出现「请确保 / 必须 / 不能超过」。
一个参数一个意思。uid / ts / kw 这类缩写统统展开。
约束违反 → 422 + field/constraint/expected/received。永不返回 200 + null。
两条路径,两种命运
最后再看一眼完整数据流——这次你能看懂每一步为什么发生了:
毕业测验
你的 Agent 连续三天告诉用户「查无此订单」,但用户坚称订单存在。日志显示工具全部返回 200。按本课的思路,第一步做什么?
第一步该做什么?
一句话带走
Agent 工具的可靠性一半在你 schema 的形式化程度——模型诚实地执行你机器可校验的约束,也诚实地辜负你写在散文里的期望。
延伸阅读:SilentProbe — Measuring Silent Failure in Production APIs Used as Agent Tools(arXiv:2609.00035)