By 黄金金枪鱼 
Agent 工具设计的三种契约范式：JSON Schema、OpenAPI 与 MCP 怎么选
2024 年底 Anthropic 推出 Model Context Protocol（MCP）后，「Agent 工具描述」这一原本被各家 SDK 各自实现的细节，开始有了工业级标准的迹象。但 MCP 并非银弹——在它出现之前，OpenAPI 3.1 和 JSON Schema 已经在企业级 API 体系里跑了十余年。本文用工程视角拆解三种范式的差异、适用场景与选型决策。
核心事件
2024 年 11 月，Anthropic 联合 MCP 团队发布 Model Context Protocol 开源协议，把 Agent 与工具之间的双向、长连接、有状态的交互抽象为 JSON-RPC 2.0 之上的一组原语（resources、tools、prompts、sampling）。半年后，OpenAI 在 OpenAI 的工具调用文档中宣布支持 MCP 服务器，2025 年下半年起，VS Code、Cursor、Claude Code、Replit 等 IDE 与编辑器原生集成 MCP。工具描述从「各家框架各自定」走向「协议化」的趋势基本确立。
技术解析
Agent 调用工具，本质上是让 LLM 生成结构化输出（JSON），再由运行时把 JSON 路由到对应函数。这里的「结构化」必须事先用某种 schema 描述清楚，三种范式的差异就出现在「用什么 schema 描述」上。
JSON Schema（json-schema.org）是最底层的元数据语言，定义数据类型、约束、组合规则（allOf/anyOf/oneOf）。它是 OpenAPI 和 MCP 的共同子集——OpenAPI 3.1 直接复用了 JSON Schema 2020-12 草案。直接用 JSON Schema 描述工具，优点是无外部依赖、运行时零成本，缺点是缺少「端点路由」「鉴权」「传输协议」这些工程概念。
OpenAPI 3.1（swagger.io/specification、openapis.org）在 JSON Schema 之上加了端点（paths）、HTTP 方法、参数位置（query/path/header）、鉴权方案（securitySchemes）、服务端点等概念。它是面向 HTTP/REST 的——天然适合「Agent 调外部 SaaS API」「企业内已有 OpenAPI 文档」的场景。但对本地工具、子进程、IDE 内的 tool 调用，OpenAPI 描述起来比较笨拙（需要包成 HTTP 端点）。
MCP（modelcontextprotocol.io）则完全脱离了 HTTP 假设。它用 JSON-RPC 2.0 作为传输层之上的语义层，把工具抽象为 tools/list 与 tools/call 两个原语，配套还有 resources（数据资源）、prompts（提示模板）、sampling（让 LLM 主动调用子 LLM）。MCP 的杀手锏是双向长连接——服务端可以在任意时刻 push 资源更新、采样请求给客户端，这是 OpenAPI 的「请求-响应」模型做不到的。
关键点
- JSON Schema 适合单进程内的工具描述（LangChain 的
StructuredTool、Pydantic 模型），是最小公约数，零协议栈成本。 - OpenAPI 3.1 适合复用现有 REST API——把企业已有 API 文档「稍微补点 description」就能给 Agent 用，AWS Lambda 的 URL 函数 + OpenAPI 文档就是典型范式。
- MCP 适合多 Agent、多工具、有状态场景——IDE 内编辑器集成、Claude Code / VS Code 的 Copilot MCP 集成 都是这种范式。
- 选型口诀：单进程→JSON Schema；HTTP API→OpenAPI；IDE/桌面/双向→MCP。
- 三者不是替代关系而是层级关系：MCP 内部用 JSON Schema 描述工具参数；OpenAPI 3.1 底层也是 JSON Schema——schema 这层是统一的，差异在「协议层」与「传输层」。
行业影响
工具描述协议化最大的受益方是企业落地 Agent 的工程团队——以前接入一个新工具要改 3-5 个 SDK 的适配器，现在只要按 MCP / OpenAPI 规范写一次描述文件，主流 Agent 框架都能直接消费。LangChain 在 langchain.com 也提供了统一的 tool adapter 层。但短期内，「协议混用」会持续——OpenAPI 描述存量系统、MCP 描述新建工具、JSON Schema 兜底内嵌函数——一个成熟的 Agent 系统往往是三种范式并用，靠统一网关层做协议转换。
结语
选哪种契约，取决于工具的边界：工具是「进程内函数」还是「HTTP 端点」还是「长连接服务」？从工程角度，JSON Schema 是底座、OpenAPI 是 HTTP 时代的工业标准、MCP 是 Agent 时代的协议候选。三者会在未来 2-3 年内共存并互补——理解它们各自的边界，比选边站更重要。
参考资料
官方文档
- Anthropic: Model Context Protocol 发布公告 [200] - 2024-11
- Model Context Protocol 官方文档（介绍） [200] - 持续更新
- Model Context Protocol 规范 2025-06-18 [200] - 2025-06
- Anthropic: Tool Use 概述 [200]
- AWS Lambda: 使用 OpenAPI 定义 HTTP API [200]
- Model Context Protocol 示例 [200]
开源项目
- LangChain 文档（统一 tool adapter） [200]
- LangSmith 文档（Agent 调试与评估） [200]
- Weaviate 向量数据库文档 [200]
- Chroma 向量数据库文档 [200]
行业报道
- 机器之心 [200]
- 36 氪 [200]
- 量子位 [200]
- Anthropic Engineering Blog: Building Effective Agents [200] - 2024-12
社区讨论
- HN Algolia 搜索：MCP + JSON Schema + tool design [200] - 持续聚合
- 掘金技术社区 [200]
- 开源中国 [200]
对比基准
- OpenAPI Initiative 官网 [200]
- Swagger 规范文档 [200]
- JSON Schema 官方 [200]
- JSON Schema 入门教程 [200]
- Artificial Analysis（模型对比基准索引） [200]
本文由 AI 生成。内容基于公开资料整理，可能存在事实偏差，引用链接请以原始来源为准。