把多步 API 调用交给 Agent 前，我会先用 Arazzo 写清 workflow

当一个产品的 API 只停留在端点文档层面，真实业务流程往往还散在 README、测试脚本、客服工单和工程师记忆里。登录、创建资源、读取状态、触发删除、校验回执，这些步骤单独看都清楚，连起来交给测试工具或 AI Agent 时，最容易丢掉上下文、顺序和错误处理。

从 OpenAPI 契约到 Arazzo workflow、测试运行器和 Agent 工具网关的流程示意 来源：Codex image generation

OpenAPI Initiative 在 2026-05-17 发布的 Arazzo Specification v1.1.0，正好补上这块空白。它的目标是描述 API 调用序列和依赖关系，并把这些序列表达成面向结果的 workflow。换句话说，OpenAPI 描述“有哪些接口”，Arazzo 描述“怎样把接口连成一件事”。

先把流程从脚本里抽出来

我会把 Arazzo 当成一份 workflow 契约，而非单纯的测试配置。第一层是 sourceDescriptions，指向已有 OpenAPI 描述，让 workflow 不需要重新发明接口定义。第二层是 workflows，对应一个业务结果，比如“创建客户并读取详情”。第三层是 steps，每一步通过 operationId 或 operationPath 绑定到具体接口，再声明 parameters、请求体、successCriteria 和 dependsOn。

这样写的价值在于，流程里的关键数据有了明确位置。上一步响应里抽出的 id，下一步如何使用；某一步失败后是否停止；成功条件应该看 HTTP 状态码、响应字段还是业务状态，这些都可以从口头约定变成可审查文本。

对 Agent 更重要的是边界

把 API 交给 Agent 调用时，风险通常来自两处：它调用了没有授权的操作，或者它把上一步结果错误传给下一步。Arazzo 可以作为工具网关前的一层约束。Agent 只能选择 workflow 中声明过的步骤，运行器负责注入输入、提取响应、执行断言，并把请求、响应和结果写入审计日志。

在团队落地时，我建议从三类流程开始：注册和登录这类高频入口，创建和撤销这类有副作用的路径，以及账单、权限、删除这类需要强断言的路径。每条 workflow 都配一组最小输入样例，CI 中先跑沙箱环境；接入 Agent 前，再加超时、速率、只读模式和危险步骤确认。

小团队也值得现在试

Arazzo 还处在工具生态继续成熟的阶段，但规范已经给出了稳定的协作语言。它让后端、测试、文档和 AI 工具围绕同一份流程文件讨论，不再把“怎么按顺序调用接口”藏在某个脚本里。对 Coriander Lab 这类持续折腾自动化的小团队来说，先选一条最核心 API 流程写成 Arazzo，比一次性改完整套测试平台更容易见效。

来源链接：OpenAPI Arazzo Specification v1.1.0：https://spec.openapis.org/arazzo/latest.html；OpenAPI Arazzo 官方页面：https://www.openapis.org/arazzo-specification；OAI Arazzo Specification GitHub 仓库：https://github.com/OAI/Arazzo-Specification