Agent 服务的接口文档常常只写了端点和请求体，漏掉了三件真正决定集成成败的事：输出不确定时怎么用、工具调用失败时怎么重试、每次请求到底花多少钱。这篇列出 Agent API 必须写清的七项内容、一份 OpenAPI 骨架和一张错误码表。

💡 你将学到

Agent 服务的接口文档常常只写了端点和请求体，漏掉了三件真正决定集成成败的事：输出不确定时怎么用、工具调用失败时怎么重试、每次请求到底花多少钱。这篇列出 Agent API 必须写清的七项内容、一份 OpenAPI 骨架和一张错误码表。

📜 目录

• 一、Agent API 和普通 API 的四个不同
• 二、必须写清的七项内容
• 三、OpenAPI 骨架
• 四、错误码怎么分
• 五、给机器读的文档
• 六、文档即测试
• 七、常见问题
• 相关文章

AI Agent API Documentation：构建可靠AI Agent的必备实践

Agent 服务的接口文档常常只写了端点和请求体，漏掉了三件真正决定集成成败的事：输出不确定时怎么用、工具调用失败时怎么重试、每次请求到底花多少钱。这篇列出 Agent API 必须写清的七项内容、一份 OpenAPI 骨架和一张错误码表。

一、Agent API 和普通 API 的四个不同

这四个差异决定了文档该写什么：不仅要写"怎么调"，还要写"调完之后会发生什么、可能不一样到什么程度、出错怎么补救"。

二、必须写清的七项内容

1. 鉴权与配额：密钥形式、配额口径（按请求数还是按 token）、超限返回什么
2. 输入 schema：字段、类型、必填项、长度上限、非法值的处理方式
3. 输出 schema 与流式协议：字段含义、可能为空的字段、流式事件的顺序和终止事件
4. 工具清单与权限：Agent 能调用哪些工具、每个工具能碰什么资源、需要什么授权
5. 错误码与重试语义：哪些错误可重试、重试上限、幂等键怎么传
6. 成本与延迟预期：典型请求的 token 用量与费用区间、延迟分位数
7. 确定性与可复现：是否存在随机性、能否固定种子或传版本号锁行为

第 7 项最常被漏掉。凡是缓存、比对、测试都要用到"同样的输入能不能得到同样的输出"，文档里不写清，集成方只能靠猜。

三、OpenAPI 骨架

paths:
  /v1/agent/run:
    post:
      summary: 运行一次 Agent 任务
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [input, tools]
              properties:
                input: {type: string, maxLength: 8000}
                tools: {type: array, items: {type: string}}
                stream: {type: boolean, default: false}
      responses:
        "200":
          description: 成功，返回输出与用量
        "429":
          description: 配额或限流，含 Retry-After

骨架之外，每个字段都要配一句人话解释，说明"什么时候会为空、为空时调用方该怎么做"，而不是复述字段名。

四、错误码怎么分

原则是写清可重试与不可重试的边界。Agent 有副作用，无脑重试可能造成重复下单、重复发信，这是集成事故里最常见的一类。

五、给机器读的文档

除了给人看的文档页，还要准备机器可读的版本：工具描述要写成模型能判断"什么时候该用这个工具、参数怎么填"，通常从 OpenAPI 自动生成工具清单；面向大模型的说明文件可以放一份精简的接口摘要，让别的 Agent 能直接读。同一个接口有多个文档来源时，以代码生成的版本为准，手写的容易和实现对不上。

六、文档即测试

从 OpenAPI 生成请求样例与契约测试，让文档里的示例在 CI 里真的跑一遍。文档与实现不一致，是 Agent 集成方最常见的踩坑来源，而它完全可以用自动化消掉。

七、常见问题

Q：输出不确定，怎么做自动化测试？ A：测行为约束而不是精确文本：schema 校验、必填字段、枚举值、是否调用了预期工具、是否超出预算。把"内容质量"交给定期人工抽样。

Q：流式接口要额外写什么？ A：事件类型、顺序、终止条件、中途断线怎么续。断流后能否从上次位置续传，是集成方最关心的一条。

Q：成本预期怎么写才不算虚？ A：给一个典型请求的 token 区间和延迟分位数，并注明"依输入长度和工具调用次数浮动"。别给单一平均值，掩盖波动会让调用方低估峰值成本。

Q：内部 Agent 也要写文档吗？ A：要，但可以只写三项：输入输出 schema、错误与重试规则、成本口径。这三项没有，第一个接手的人就要读源码。

注：本文讨论的是工程实践，具体接口能力与计费口径以各服务提供方的官方文档为准。

相关文章

• AI Agent Output Schema Validation：构建可靠AI Agent的必备实践
• AI Agent重试机制：API挂了，别直接告诉用户
• AI Agent成本追踪：每个请求花了多少钱一目了然