API 文档即可靠性基础设施：文档如何决定智能体的成功率

大多数工程团队将 API 文档视为开发者体验关注点——一种为了减少支持工单和入职时间而进行的改进。当你的主要消费者是在浏览器中阅读文档的人类时，这种思维方式是有道理的。但现在，这已经不再足够。

当 AI 智能体通过工具调用访问你的 API 时，你的文档就不再仅仅是指南，而是变成了运行时行为。模糊的参数描述不再是 UX 上的不便，而是对模型产生幻觉值的直接指令。缺失的错误代码不再是参考文档中的空白，而是一个模糊信号，可能导致智能体陷入没有退出条件的重试循环。你三年前为人类读者编写的文档，现在正被一个无状态的语言模型解析，无论它是否理解正确，都会自信地执行。

这是一个可靠性问题，而不是文档问题。而且与大多数可靠性关注点不同，它完全在你的控制范围内。

为什么工具调用让文档具有承重作用​

当 LLM 智能体调用工具时，模型不会像人类工程师那样发出 API 请求——即先阅读文档，建立心理模型，然后编写代码。它接收直接注入到其上下文窗口中的结构化模式（通常是 OpenAPI 或 JSON 函数定义），将描述字段解释为指令，并在一次处理中生成参数值。这里没有“我先试试看会发生什么”——第一次尝试就是实时的。

这从结构层面上改变了文档质量的定义。函数模式中的每个 description 字段在功能上都是一条提示词指令。如果你写 "id: string — 用户 ID"，模型几乎无法获取关于哪个用户、什么格式、从哪里获取的信息。相反，如果你写 "id: string — 发起请求的已验证用户的 UUID，可在 /auth/login 返回的会话令牌中找到"，模型就拥有了可导航的指令，可以在第一次尝试时正确执行。

这两种描述之间的性能差距，不在于模型是聪明还是愚蠢，而在于以成功率衡量的文档质量差距。

对工具增强型 LLM 的研究发现，“工具误用”——即以错误的参数、顺序或时机调用正确的工具——是智能体系统中最常见的失败模式。在生产部署中，工具调用失败发生在 3–15% 的调用中，且通常是隐蔽的：智能体收到格式错误的响应，误解了它，然后继续运行而不是发现错误。与注意到 API 响应错误的人类开发者不同，模型将其对该响应的解释视为事实真相（ground truth）。

差劲的文档产生的失败模式​

文档缺失在智能体系统中表现为特定的、可观察的失败模式。理解这些模式有助于你审计自己的 API。

参数幻觉是最常见的。当参数描述过于模糊——或者根本没有描述时——模型会从上下文中推断其值。有时这种推断是正确的，但通常并非如此，结果是一个看起来合理但语义错误的 API 调用。因为调用不会报错（值的类型正确），失败是隐蔽的：错误的资源被更新，错误的过滤器被应用，或者错误的用户被扣费。

模糊的错误语义会产生智能体循环。当 API 返回的错误未能明确指示该情况是瞬时的、永久的还是受限额限制的时，智能体必须猜测是否重试。没有 Retry-After 标头的 429 响应、实际上是验证错误的 500 错误，或者带有 "error": true 正文的 200 响应，都是会导致智能体行为失败的文档缺陷。模糊的反馈是循环的诱因：观察到智能体曾重试同一个失败的调用数百次，因为错误响应没有给它们停止的理由。

隐式状态要求会导致顺序失败。许多 API 的操作只有在存在某些先前状态时才有效——例如，你只能在 /order/confirm 之后调用 /order/ship，只能在创建上传会话后上传文件。对于人类工程师来说，这通常包含在他们已经阅读过的“入门指南”或概念概述中。而从工具模式运行的智能体无法访问这些先前的上下文。如果 /order/ship 的模式没有记录状态前提条件，智能体就会不按顺序调用它，并收到无法解释的错误。

Token 成本累加是一个不那么明显但具有重大财务影响的失败模式。一个拥有 93 个工具且模式定义冗长的 MCP 服务器，仅注入模式每请求就消耗约 55,000 个 token。按照典型的 API 定价，大规模运行时每天会转化为数百美元的支出——这不是因为智能体做了更多工作，而是因为文档结构效率低下。冗余的文字、过多的示例描述以及缺失的结构化类型定义，都是在智能体语境下具有直接成本影响的文档选择。

为什么你不能只靠 Prompt 解决问题​

对文档缺失的直观反应是在系统提示词（system prompt）中添加补偿性指令：“调用支付 API 时，务必确保包含 UUID 格式的客户 ID。” 这在处理你已经诊断出的已知问题时非常有效——但也仅限于那一次。

这种做法无法作为通用策略，原因有三。

首先，你无法预知哪些缺失会导致问题。失败的可能性源于你的文档质量、Agent 将尝试的任务范围，以及模型对你领域的先验知识。大多数文档缺失直到生产环境中的 Agent 在意外的任务上下文中遇到它们时才会暴露。

其次，系统提示词指令会与上下文窗口中的所有其他内容竞争。随着 Agent 会话长度的增加和更多工具调用结果的累积，系统提示词第 47 行中精心设计的指令会被推离模型的注意力中心。这种修复是脆弱的；而文档缺失却是持久的。

第三，这是一个规模化问题。维护一个针对单个内部 API 的 Agent 的团队，或许还能负担得起手动审计缺失并在 Prompt 中打补丁的成本。但一个向第三方 Agent 开发者开放 API 的平台则无法做到。你的文档质量直接被每一个集成你的 Agent 所继承。你的 Schema 中的每一处歧义，都会在整个 Agent 用户群中转化为成倍的失败率。