01

Agent 为什么会静默失败?

一个横跨 72 万个参数的审计,揭开了 Agent 工具调用最隐蔽的坑

先看一组数字

2026 年,一项叫 SilentProbe 的研究审计了 OpenAPI 文档,规模大得吓人:

📄

2,501 份文档

覆盖 27 家厂商的真实线上接口

🔢

721,320 个参数

每一个都做了机器可校验性检查

🧪

Live 扰动测试

故意发错参数,看 API 怎么回应

结果很扎心

研究者故意发错参数,然后观察 API 的反应。两种写法,命运天差地别:

约束写在描述文字里

"description": "请确保 date 为
  ISO 日期格式"
 
// 结果:61 例中 44 例
// API 返回 HTTP 200 + 正常 body
// Agent 完全不知道自己错了
            
PLAIN ENGLISH

约束被写成了「客气的请求」,不是硬性边界。

模型发错了日期格式,服务端却照样收下。

返回 200 = "成功"?Agent 认为自己做对了。

这就是静默失败:错了,但没人知道。

💡
对比组

写成机器可校验约束(enum / pattern / format)的参数:111 次错误全部诚实报错,无一静默失败。

最戏剧的一组数据

同一批模型、同一批厂商,只改一行 schema,行为天翻地覆:

🤖
模型
🗄️
API 服务端
点击「下一步」开始
💡
核心洞察

模型不是不守规矩——是你的 schema 没给它守规矩的机会。约束的形式,决定了 Agent 的可靠性。

热身检查

来,用一个场景验证你抓住重点没有:

场景

你的 Agent 调用了一个天气工具,参数 city 填了「北京」而不是工具期望的 "beijing"。API 返回了 HTTP 200 和一段"暂无该城市数据"的文案。Agent 接下来会怎么做?

Agent 会怎么理解这次调用?

答案就藏在 schema 的写法里。下一模块,我们解剖 schema 本身。

02

Schema 的解剖学

一个参数定义里的每个部位,各管一件事——搞混了就会出事

Schema 是模型的「合同」

把工具 schema 想象成一份租房合同:它不是给租客的建议清单,而是有法律效力的边界。合同里不同的条款有不同的效力——

📋

type / enum / pattern

硬性条款:机器直接校验,违反就报错。相当于合同里的违约责任。

💬

description

走廊里贴的便条:帮模型理解「这参数是干嘛的」,但没有任何强制力。

逐部位拆解

SCHEMA

{
  "status": {
    "type": "string",
    "enum": ["pending", "paid",
             "shipped", "closed"],
    "description": "订单当前状态"
  }
}
            
各管什么

type — 基础类型边界:这里只能是字符串,填数字直接被拒。

enum — 价值连城的一行:模型只能四选一,想自由发挥都没门。

description — 语义说明书:告诉模型这参数「是什么意思」,帮它选对值,但不约束它。

🔑
分工原则

约束归机器(enum/pattern/format/minimum),语义归文字(description)。一旦你把约束写进 description,它就从「合同条款」降级成了「走廊便条」。

拖拽挑战:这条要求该写在哪?

你有一句需求:「订单状态只能填 待支付、已支付、已发货、已关闭 之一」。它应该放进 schema 的哪个部位?拖一拖:

enum 数组
description 文字
pattern 正则
format 声明

「只能是这 4 个词里的一个」

拖到这里

「这个参数代表订单当前所处的阶段」

拖到这里

「日期必须长得像 2026-09-04」

拖到这里

「这个字符串是标准 ISO 日期」

拖到这里

为什么模型会「听便条不听话」?

用聊天动画看模型的内心戏:

看到了吗?整场灾难里没有一个人「违规」——因为根本没有可校验的规则。解药是什么?往下看。

03

5 条规则,逐条拆解

每条都是「反例 → 正例」的对照,外加一道应用题

规则 1

枚举优先:能用 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 参数的正确写法是?

规则 2

约束下沉:格式写进 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 里有「请确保」「必须」「不能超过」——警报响起:这句话该搬家到机器可校验的字段里去。

规则 3

一词一义:名字里不许有歧义缩写

❌ 反例

{ "name": "get_usr_info",
  "parameters": {
    "uid": "用户ID或用户名",
    "ts": "时间范围或时间戳"
  } }
// usr 是 user 还是用户组?
// ts 接受几种形态?模型只能猜
            
✅ 正例

{ "name": "get_user_profile",
  "parameters": {
    "user_id": "唯一数字ID",
    "timestamp": "ISO 8601 时间戳"
  } }
// 一词一义,无从猜错
            

一个参数描述里出现「或」字,就是幻觉参数的温床——模型猜错分支,比猜错值更难排查。

规则 4

错误设计:报 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」让模型一眼看出差在哪,下一轮就能改对。

规则 5

描述有界: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之间" }
  }
}

哪一处最可能导致「静默失败」?

04

从规则到习惯

写完 schema 之后,用「schema-lint 思维」过一遍

把 5 条规则变成一道检查清单

像机场安检一样,每个参数都要过这四道门:

1
词汇是有限的吗?

是 → 升级为 enum。是自由文本 → 下一道门。

2
有格式要求吗?

写进 pattern / format。description 里不许出现「请确保 / 必须 / 不能超过」。

3
名字有「或」吗?

一个参数一个意思。uid / ts / kw 这类缩写统统展开。

4
报错会说人话吗?

约束违反 → 422 + field/constraint/expected/received。永不返回 200 + null。

两条路径,两种命运

最后再看一眼完整数据流——这次你能看懂每一步为什么发生了:

🤖
Agent
🗄️
你的 API
点击「下一步」开始

毕业测验

最终场景

你的 Agent 连续三天告诉用户「查无此订单」,但用户坚称订单存在。日志显示工具全部返回 200。按本课的思路,第一步做什么?

第一步该做什么?

一句话带走

🎯

Agent 工具的可靠性一半在你 schema 的形式化程度——模型诚实地执行你机器可校验的约束,也诚实地辜负你写在散文里的期望。

延伸阅读:SilentProbe — Measuring Silent Failure in Production APIs Used as Agent Tools(arXiv:2609.00035)