agents.json 与面向智能体的 OpenAPI

OpenAPI 缺什么。

一份 OpenAPI 文档告诉你有哪些端点、参数是什么、响应是什么。这已经很多。它也几乎不是智能体"用好这份 API"所需的全部。设想一份预订 API 带 POST /search、GET /listings/{id}、POST /reservations、POST /payments。OpenAPI 声明四者存在。它没说的是：一次预订流必须先 search、然后可选地 fetch listing、然后 create reservation、然后针对该 reservation create payment，跳过 reservation 会让 payment 以一条晦涩错误失败。它没说哪些错误可以重试恢复、哪些是终态。它没说 POST /payments 不可逆、需要显式的用户确认。四点都是人类开发者从文档、口耳相传、一两次生产事故里学到的东西。智能体完全没有后两条渠道，而第一条——文档——才是缺失信息藏身处（当它有藏身处时）。

工具发现与文档一文直接命名了这一缺口：模型使用工具的能力，取决于工具的描述而不是签名。OpenAPI 对签名描述精确、对描述描述宽松；宽松的那部分才是智能体最需要的。结果是"把 OpenAPI 给智能体"得到的智能体：发现端点、按看似合理的顺序调用、以看起来像 API 误用其实是编排错误的方式失败。修法不是更强的模型——是输入侧更多结构，本文覆盖的两种约定，就是两种已上线的形状。

agents.json v0.1。

agents.json，由 Wild Card AI 于 2025 年发布、当前 v0.1，是一份放在已有 OpenAPI 规范旁边的 JSON 文档，补上 OpenAPI 所缺、面向智能体所需的信息。它描述 flow——一系列有名的端点序列，智能体应按此完成某项任务——每一步指名端点、输入映射、下一步的输出映射、失败语义。它还带顶层元数据说明服务：智能体该如何称呼它、用哪种鉴权、支持哪些 flow。合规的智能体先读 agents.json，学到预期的 flow，再回到底层 OpenAPI 去构造每步所需的具体 HTTP 请求。

{
  "agentsJson": "0.1.0",
  "info": {"title": "Bookings", "version": "2.3"},
  "sources": [{"path": "./openapi.yaml", "type": "openapi/3.1"}],
  "flows": [
    {
      "id": "book-a-stay",
      "title": "Search, reserve, and pay for a stay.",
      "actions": [
        {"id": "search",   "sourceRef": "openapi:/search",   "responseSchema": "..."},
        {"id": "reserve",  "sourceRef": "openapi:/reservations",
                           "input": {"listingId": "$.search[0].id"}},
        {"id": "pay",      "sourceRef": "openapi:/payments",
                           "input": {"reservationId": "$.reserve.id"},
                           "userConfirmation": "required"}
      ]
    }
  ]
}

格式里两个特性做了有用工作。sourceRef 指针保持 OpenAPI 是签名的真实源——端点定义不复制，OpenAPI 里的 schema 变化不必重新撰写 agents.json。而 payment 步上的 userConfirmation 提示，正是"不可逆动作需同意"的模式形状；合规智能体把这一步作为独立的用户端提示浮出，而不是静默执行支付。v0.1 规范很小——整套语法一页纸——这就是要点；在 OpenAPI 之上捕捉 flow、映射与同意面所需的最小表面积。

仓库层的 AGENTS.md。

2025 年另一约定在不同粒度上运作。AGENTS.md 是一份普通 Markdown 文件，放在代码仓库根目录，为一名智能体操作者——编码智能体、代码评审智能体、部署智能体——记录仓库信息。约定是自发生长的，被 2025 年年中一小群开源项目推广，到 2026 年年中被 GitHub 上 20,000+ 仓库采用。内容是文档形状：如何跑测试、模块布局怎么组织、哪些文件是生成的（不要编辑）、项目遵循哪种提交约定，以及智能体应偏好用而非用标准等价物的项目专有工具。

# AGENTS.md

## Running tests
- Full suite: `pytest -q`
- Fast subset: `pytest -q -m "not slow"`
- Coverage: `pytest --cov=src`

## Layout
- `src/` — library code; treat as source of truth
- `tests/` — mirror `src/` structure
- `docs/generated/` — auto-generated; do not edit

## Commits
Conventional Commits. One logical change per commit.

## Preferred tools
- Formatting: `ruff format` (not `black`)
- Linting: `ruff check --fix`

AGENTS.md 的成功正在其形状：看起来像给人的 README、读起来像给人的 README，但具体内容正是智能体避开典型失败模式所需——跑错测试命令、编辑生成文件、格式化不一致、以项目拒绝的风格提交。它没有 schema。没有版本。除了"文件在仓库根"以外没有发现机制。它的采纳上限因此就是"会去查这份文件"的智能体比例，截至 2026 年年中，本质上每一款正经的编码智能体——Claude Code、Cursor、Aider、Devin、OpenAI Codex CLI——都会读它。文件在项目变化时被编辑，方式和 README 被编辑一模一样；漂移也以同一方式被抓：评审者注意到文件在撒谎。

为何仍需要 MCP。

agents.json 与 AGENTS.md 都有用。都不是 MCP 在做的事。合起来读，它们的局限点出了 MCP 作为一份单独协议存在（而不是作为 OpenAPI 之上的 JSON 覆盖层）的三条具体原因。第一，MCP 编码完整的会话——initialize 握手、会话期间保持存活的工具集、流式状态与在飞调用取消的生命周期。agents.json 描述 flow 但不描述会话；每次智能体调用从 API 视角是无状态的，长时间运行的操作只能被建模为智能体自身逻辑里的轮询循环。第二，MCP 的工具带一份服务进程可在运行时更新的结构化元数据——一个工具的描述可以按租户、按用户、按 feature flag 变化——客户端在会话启动时动态取。agents.json 是静态文件；按租户行为要按租户文件，工具都没帮你把它做容易。

第三，也是最承重的，MCP 定义了两种约定都没提供的控制反转：服务器可以在会话内回调客户端——通过 sampling 借用宿主的模型、通过 elicitation 向用户提问。结构化工具 I/O一文描述了形状；这里的要点是：agents.json 能命名智能体要调用的端点，却不能描述"回调智能体本身"的端点。对一类工具——需要客户端模型起草编辑的代码重构服务器、需要用户先确认再继续的管理服务器——服务器发起的交互就是全部意义所在，OpenAPI 与 agents.json 都不建模它。

务实的读法是：agents.json 与 AGENTS.md 是当你有既存 API 表面、无法重写传输时你交付的东西；MCP 是当你从一开始就为智能体设计时你交付的东西。覆盖层约定会继续扩散——多数 API 不会被重写为 MCP 服务器，agents.json 是让既存 API 对智能体更好用的廉价办法——但"把 OpenAPI 给智能体"这个说法，正是应关掉标签页的那一个。它能跑通 demo。它跑不通生产系统，而上文两种约定正是行业对"它究竟没解决哪些部分"的坦白。