F-《AI接口协议：API调模型、MCP接工具、A2A连Agent》

目录一、API以 标准 OpenAI 接口 为代表1.1 请求1.2 成功响应 ❌ 失败响应二、MCPModel Context Protocol模型上下文协议2.1 请求握手调用2.2 成功响应2.3 失败响应jsonrpc 错误格式三、A2AAgent2Agent智能体间协议3.1 实例1拉取 AgentCard —— 先搞清楚 对方要什么凭证3.1.1 请求3.1.2 响应这就是 A2A 的 身份证 招聘启事3.2 实例2带鉴权的成功请求 —— message/send3.2.1 请求注意 token 在 HTTP 头不在 JSON body 里3.2.2 成功响应任务直接做完状态 completed3.3 实例 3失败场景一没带 token /token 过期4013.3.1 请求故意不带 Authorization 头3.3.2 失败响应3.4 实例 4失败场景二token 有效但你没权限4033.4.1 请求3.4.2 失败响应3.5 实例 5失败场景三JSON-RPC协议层错误方法不存在 / 参数错3.5.1 方法名写错应该是 message/send写成了 message/sendTask3.5.2 参数结构错误params 里没传 message3.6 实例 6任务做到一半要 二次鉴权auth-required3.6.1 第一次请求的响应任务没失败而是停下来等你补凭证3.6.2 客户端补完凭证后再发一条 message/send 把新 token 带回去四、除了 MCP / A2A / API还有别的主流吗4.1 Anthropic Messages API原生模型接口4.2 Function Calling / Tool Use工具调用约定4.3 OpenAPI / Swagger通用接口描述规范一、API以 标准 OpenAI 接口 为代表定义一套 应用 ↔ 单个大模型服务 之间的 HTTP 接口。你发一段对话messages模型回一段回答choices。通俗比喻像吧台点单—— 你应用对服务员模型服务说 来杯咖啡他递给你一杯。这一来一回就是一次 API 调用。作用在什么环节想和说 环节—— 应用 / 智能体向上够到大模型拿推理与生成能力。什么时候用只要对话 / 生成问答、写作、翻译、总结用现成模型。接口规范端点POST /v1/chat/completions鉴权Authorization: Bearer sk-xxx请求体核心字段model、messages、temperature、max_tokens响应体核心字段choices[0].message.content、usage流式用 SSE典型示例请求 响应1.1 请求// 请求 curl https://api.openai.com/v1/chat/completions \ -H Authorization: Bearer sk-xxx \ # ← 输入 key 鉴权 -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: system, content: 你是一个贴心的助手}, {role: user, content: 上海今天天气如何} ], temperature: 0.7, max_tokens: 300 }1.2 成功响应 ❌ 失败响应// 不同的响应的情况成功或失败 // ✅ 成功HTTP 200 { choices: [ { message: { role: assistant, content: 很抱歉我无法实时获取天气… } } ], usage: { total_tokens: 21 } } // ❌ 失败 ① key 错误HTTP 401 { error: { message: Incorrect API key provided, type: invalid_request_error, code: invalid_api_key } } // ❌ 失败 ② 额度/限流HTTP 429 { error: { message: You exceeded your current quota, type: insufficient_quota, code: insufficient_quota } }代码逐句解释model指定用哪个模型决定了能力和价格。messages整个对话历史是一个数组。每条里role表示说话人身份 ——system 系统设定给它立人设user 用户提问assistant 助手之前的回答多轮对话靠它接上下文。temperature随机性旋钮调低更确定、调高更有创意。max_tokens这次最多生成多少个词token。响应里的choices候选回答数组message.content就是要展示的正文。usage本次总共消耗了多少 token用来计费 / 限流。二、MCPModel Context Protocol模型上下文协议定义一套 智能体 / 模型Host 客户端↔ 工具和数据Server 的协议让模型能调用外部工具、读取数据。基于JSON-RPC 2.0。通俗比喻像万能接线板—— 模型是电器MCP 把数据库、文件、外部 API 统一做成标准插座电器一插就能用不用给每个插座单独定制线。接口规范模型Client(模型Host)↔Server(工具)典型方法initialize握手协商能力→resources/list、tools/list、tools/call、prompts/get传输stdio本地进程或Streamable HTTP网络角色扮演MCP 有三个角色① Host是用户直接交互的应用程序如豆包电脑版 / App、DeepSeek App、腾讯元宝以及类似的其他它内嵌大模型、维护对话上下文并管理所有 MCP 连接。注意MCP 规范只定义了 Host 是内嵌大模型、管理 MCP Client 的那个进程但没规定这个进程必须跑在用户本机。实际有两种部署部署形态真正的 Host 跑在哪用户手里的 App 是什么MCP Client 跑在哪桌面端模式Claude Desktop、Cursor、Trae 桌面版用户本机的桌面进程就是 Host 本身用户本机云端 Agent 模式豆包、Coze、Dify、腾讯元器厂商的服务器Agent 运行时只是一个瘦前端发消息、收结果厂商服务器上国内 App 的真实架构类似智能体开发平台你手机上的豆包 App │ ① 你打字帮我查下今天的日程 ▼ 豆包服务端字节的机房 ├─ ② 大模型在这里跑 ├─ ③ MCP Client 在这里跑 │ └─ 带 token 去连 日历 MCP Server / 企业微信 MCP Server ▼ 结果下发回你手机 App 显示②Client是 Host 内部的一个组件每个Client 实例专门与一个 MCP Server 建立连接负责完成 initialize 握手、携带 OAuth token、收发 JSON-RPC 请求与响应。③ Server是工具 / 资源提供方如文件系统、GitHub、数据库、Slack。对外暴露 tools、resources、prompts 三类能力清单接收 Client 的调用并返回结果。一个 Host 可以同时挂载多个 Client每个 Client 对应一个 Server大模型不直接连接任何 Server所有请求都由 Host 调度、通过对应 Client 转发到 Server。典型示例请求 响应2.1 请求握手调用① 初始化握手id: 1鉴权头 initializecurl -X POST https://mcp.example.com/mcp \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:initialize, params:{protocolVersion:2025-11-25,capabilities:{}}}② 确认初始化完成通知无 id不期待响应curl -X POST https://mcp.example.com/mcp \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:notifications/initialized,params:{}}③ 调用工具id: 2tools/call 查上海天气curl -X POST https://mcp.example.com/mcp \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:2,method:tools/call, params:{name:get_weather,arguments:{city:上海}}}说明鉴权头Authorization: Bearer sk-xxx每次请求都带notifications/initialized用notifications/前缀且不带id服务端不返回响应。协议版本按服务端initialize返回的protocolVersion为准。2.2 成功响应① initialize 成功HTTP 200{ jsonrpc: 2.0, id: 1, result: { protocolVersion: 2025-11-25, capabilities: { tools: {} }, serverInfo: { name: weather-server, version: 1.0.0 } } }③ tools/call 成功返回结果{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: 福州今天多云气温 21~27℃。 } ], isError: false } }MCP 里工具调用 “成功” 不代表业务成功业务失败但调用通顺时服务端仍返回result并把isError置true见下面失败②。2.3 失败响应jsonrpc 错误格式所有错误统一走error字段HTTP 状态码也相应变化① 鉴权失败HTTP 401{ jsonrpc: 2.0, id: 1, error: { code: -32001, message: Unauthorized: invalid or missing API key } }② 工具内部业务失败HTTP 200但 isErrortrue{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: 未找到城市「福州」的天气数据 } ], isError: true } }③ 工具不存在HTTP 400JSON-RPC 参数错误{ jsonrpc: 2.0, id: 2, error: { code: -32602, message: Unknown tool: get_weather } }④ 握手顺序错误 / 协议不兼容HTTP 400{ jsonrpc: 2.0, id: 1, error: { code: -32600, message: Initialize must be the first request } }常见 JSON-RPC 错误码code含义-32700解析错误JSON 语法-32600无效请求顺序 / 结构错误-32601方法不存在-32602参数错误工具不存在也常归此类-32603内部错误-32001未授权 / 鉴权失败一句话先把initialize握手成功拿回protocolVersion再发notifications/initialized最后tools/call失败统一看error.code业务层失败则看result.isError。代码逐句解释jsonrpc:2.0声明这是 JSON-RPC 2.0 格式一种通用远程调用规范。id请求编号响应里带上同一个 id好把 回答 和 问的问题 对上号。method要调用的方法名 ——initialize 握手协商版本和能力tools/call 真正执行某个工具。params该方法需要的参数。tools/call里name 工具名arguments 传给它的参数键值对。响应里的result服务器返回的数据content是内容数组type:text表示这是一段文本模型读到后就能接着推理。三、A2AAgent2Agent智能体间协议定义一套 智能体 ↔ 智能体 的对等协作协议。两个 agent 先互相发现通过 AgentCard 名片再派活、交接成果。基于 JSON-RPC 2.0。通俗比喻像公司之间的商务合作—— 每个 agent 是一家公司先亮出 名片 业务介绍AgentCard再通过 项目任务单task派活交付 成果物artifact。不是上下级是对等合作。共同点和 API、MCP 一样开放、基于 JSON/HTTP、为解耦互通而生区别只在 连的是谁。角色A2A 协议里的角色是按 这次请求谁主动发起 来定的A2A Client客户端 请求方。它拿着对端的 AgentCard在 HTTP 头里带上 token发message/send等结果。代表用户或上级 agent 去 叫别人干活。A2A Server服务端 / Remote Agent 响应方。暴露端点、接活干活、回结果的一方。它发布自己的 AgentCard监听/a2a端点校验 token把请求变成一个Task最后回result或error。接口规范发现每个 agent 暴露AgentCard含name、url、skills典型方法message/send发消息 / 派活以及任务相关方法task/get、task/cancel等核心对象task任务、artifact成果物、part消息片段传输HTTP SSE业务流向全景5 步以下实例1~5就是按照这顺序。发现客户端先拉对端的AgentCard一份 JSON名片看它要求怎么鉴权。取凭证按名片上写的方式OAuth2 / APIKey / Basic…走 A2A 协议之外的渠道拿到 token。发任务在 HTTP 头里带上 tokenPOST 一个message/send的 JSON-RPC 请求。收结果服务端返回一个Task对象状态可能是completed直接成功、working异步、或auth-required中途还要补凭证。失败兜底鉴权失败回 HTTP 401/403业务错误回 JSON-RPC error 对象。典型示例请求 响应3.1 实例1拉取 AgentCard —— 先搞清楚 对方要什么凭证这一步通常不需要鉴权名片本身是公开发现用的但里面会声明鉴权要求。3.1.1请求GET /.well-known/agent-card.json HTTP/1.1 Host: weather-agent.example.com3.1.2响应这就是 A2A 的 身份证 招聘启事{ protocolVersion: 0.3.0, // 我支持的 A2A 协议版本 name: Weather Agent, // 对端智能体叫什么 description: 提供全球天气查询服务, url: https://weather-agent.example.com/a2a, // 真正发请求的端点 supportedTransports: [jsonrpc], // 我支持 JSON-RPC 这种传输方式 // ★ 关键这里声明了你要怎么证明你是谁 securitySchemes: { oauth2: { // 方案名叫 oauth2 type: oauth2, description: 请先到 https://idp.example.com 用 OAuth2 换 token, flows: { clientCredentials: { tokenUrl: https://idp.example.com/oauth2/token } } }, apiKey: { // 同时也接受静态 API Key二选一 type: apiKey, in: header, // key 放在哪个位置 name: X-API-Key // 放在名为 X-API-Key 的请求头里 } }, // ★ 关键security 是AND 的 OR——下面两种组合任选其一即可 security: [ { oauth2: [weather.read] }, // 组合A用 OAuth2且要有 weather.read 这个 scope { apiKey: [] } // 组合B或直接带 API Key ], skills: [ { id: get_weather, // 我会干的活的唯一编号 name: 查询天气, description: 根据城市名返回当前天气 } ] }注释要点A2A 规定客户端先读这张名片再决定去https://idp.example.com/oauth2/token换 token。换 token 这件事不在 A2A 协议范围内是 带外out-of-band 完成的。3.2 实例2带鉴权的成功请求 —— message/send有一步带外步骤假设客户端已经用 client_credentials 换到了一个 JWTeyJhbGciOiJSUzI1NiIs...然后。。。3.2.1 请求注意 token 在 HTTP 头不在 JSON body 里//请求头 POST /a2a HTTP/1.1 Host: weather-agent.example.com Content-Type: application/json // JSON-RPC 报文必须用这个 Content-Type Authorization: Bearer eyJhbGciOiJSUzI1NiIs... // ★ 鉴权就在这一行下面的 JSON 里不出现身份信息//请求体 { jsonrpc: 2.0, // 固定声明这是 JSON-RPC 2.0 报文 id: req-20261102-001, // 请求 ID响应会原样带回用来配对 method: message/send, // 调用哪个方法发一条消息 params: { message: { role: user, // 这条消息是谁发的调用方用户 messageId: msg-abc-001, // 这条消息自己的 ID幂等/去重用 parts: [ // 消息体由若干片段(Part)组成可以是文字、文件、结构化数据 { type: text, // 片段类型纯文本 text: 福州今天天气怎么样 } ] }, configuration: { acceptedOutputModes: [text] // 我能接受的返回格式 } } }3.2.2 成功响应任务直接做完状态 completed对端的智能体完成任务的响应。//响应头 HTTP/1.1 200 OK Content-Type: application/json//响应体 { jsonrpc: 2.0, id: req-20261102-001, // ★ 和请求里的 id 对上 result: { // 成功时走 result 字段失败时走 error 字段 taskId: task-7788, // 服务端为这次工作分配的任务 ID status: { state: completed, // 任务终态已完成 message: { role: agent, // 这条回复是智能体发的 messageId: msg-def-009, // 这条消息自己的ID幂等/去重用响应的消息ID parts: [ { type: text, text: 福州今天多云转晴气温 22~28℃东南风 3 级。 } ] } }, artifacts: [ // 产出物文件、报表等这里是直接文字所以可空 { artifactId: art-001, name: weather_report, parts: [ { type: text, text: 数据来源xxx气象接口 } ] } ] } }注释要点A2A 里 消息 (Message) 是一轮对话任务 (Task) 是一次完整工作单元。completed表示一次同步搞定如果是长任务会先回working再用 SSE 流式推送或回调 webhook 通知。3.3 实例 3失败场景一没带 token /token 过期401这是最常见的鉴权失败。注意HTTP 状态码本身就是错误信号body 里再用 JSON-RPC error 说明细节。3.3.1 请求故意不带 Authorization 头POST /a2a HTTP/1.1 Host: weather-agent.example.com Content-Type: application/json // 漏了 Authorization 头3.3.2 失败响应HTTP/1.1 401 Unauthorized //失败原因代码未授权 Content-Type: application/json WWW-Authenticate: Bearer realmweather-agent, errorinvalid_token, error_descriptiontoken 缺失或已过期请重新获取 // ★ WWW-Authenticate 是 HTTP 标准头告诉客户端该用什么方式重新认证{ jsonrpc: 2.0, id: req-20261102-002, error: { code: -32005, // A2A 扩展错误段-32000~-32099未认证 message: Unauthorized, data: { // data 里放调试细节可选 httpStatus: 401, detail: 请求头中缺少有效的 Bearer token } } }注释要点规范要求服务端在 401 时必须带WWW-Authenticate头引导客户端去重新走 OAuth 流程。3.4 实例 4失败场景二token 有效但你没权限403token 是真的、没过期但你的 OAuth scope 不够名片上要求weather.read你只拿到了weather.write。3.4.1 请求POST /a2a HTTP/1.1 Host: weather-agent.example.com Content-Type: application/json Authorization: Bearer eyJhbGciOiJSUzI1NiIs... // token 本身合法{ jsonrpc: 2.0, id: req-20261102-003, method: message/send, params: { /* ...同上... */ } }3.4.2 失败响应HTTP/1.1 403 Forbidden Content-Type: application/json{ jsonrpc: 2.0, id: req-20261102-003, error: { code: -32004, // 已认证但权限不足 message: Permission denied, data: { requiredScope: weather.read, yourScopes: [weather.write], detail: 当前 token 缺少 weather.read 授权范围 } } }注释要点401 vs 403 的区别 ——401 是 你是谁我不认识403 是 我认识你但这事你不能干。3.5 实例 5失败场景三JSON-RPC协议层错误方法不存在 / 参数错这种是报文本身不合法跟鉴权无关用标准 JSON-RPC 错误码。3.5.1 方法名写错应该是message/send写成了message/sendTask请求{ jsonrpc: 2.0, id: req-004, method: message/sendTask, // ← 这个方法不存在 params: {} }响应{ jsonrpc: 2.0, id: req-004, error: { code: -32601, // ★ JSON-RPC 标准码Method not found message: Method not found, data: { hint: 你要找的是不是 message/send 或 message/stream } } }3.5.2 参数结构错误params 里没传 message{ jsonrpc: 2.0, id: req-005, method: message/send, params: { message: null } // ← message 必须是对象不能为 null }响应{ jsonrpc: 2.0, id: req-005, error: { code: -32602, // ★ JSON-RPC 标准码Invalid params message: Invalid params, data: { field: params.message, reason: 必须是非空对象 } } }标准错误码速查-32700报文不是合法 JSON-32600请求结构不对-32601方法不存在-32602参数不对-32603服务端内部炸了。3.6 实例 6任务做到一半要 二次鉴权auth-required这是 A2A 很有特色的一点调用方 token 是对的但智能体执行过程中要去访问另一个系统比如你的邮箱那个系统要单独登录。此时任务不直接失败而是转入auth-required状态。3.6.1 第一次请求的响应任务没失败而是停下来等你补凭证{ jsonrpc: 2.0, id: req-006, result: { taskId: task-9900, status: { state: auth-required, // ★ 中断态需要你再提供一次凭证 message: { role: agent, parts: [ { type: data, // 用结构化数据描述要什么凭证 data: { type: oauth2, authUrl: https://mail.example.com/oauth/authorize?client_idxxx, reason: 我需要读取你邮箱里的航班确认邮件来自动填入行程 } } ] } } } }3.6.2 客户端补完凭证后再发一条 message/send 把新 token 带回去POST /a2a HTTP/1.1 Host: weather-agent.example.com Authorization: Bearer 原来的A2A token // 主凭证照常带{ jsonrpc: 2.0, id: req-007, method: message/send, params: { message: { role: user, messageId: msg-888, parts: [ { type: data, // ★ 把二次凭证作为 data 片段塞回来 data: { mailOAuthToken: eyJhbGciOi...邮箱系统发的token } } ], messageId: msg-888 }, configuration: { acceptedOutputModes: [text] } } }注释要点A2A 把 主通道鉴权HTTP 头里的 Bearer和 任务内二次鉴权业务消息里的数据分开避免把各种系统的 token 都堆在 HTTP 头里。四、除了 MCP / A2A / API还有别的主流吗有。按同一套格式挑三个最有代表性的再简述其余的。4.1 Anthropic Messages API原生模型接口定义Claude 的原生调用接口是和 OpenAI 兼容格式并列的两大原生格式之一端点POST /v1/messages字段和 OpenAI 略有差异。比喻同一家 吧台 的另一种点单方式 —— 菜一样就是菜单格式不同。共同点同属 调用单个模型 这一层JSON HTTP。示例 解释// 请求 { model: claude-sonnet-4-5, max_tokens: 300, system: 你是贴心助手, messages: [ { role: user, content: 福州天气 } ] }// 响应 { id: msg_x, content: [ { type: text, text: 很抱歉我无法实时获取天气… } ], usage: { input_tokens: 10, output_tokens: 18 } }解释与 OpenAI 不同 ①system是独立顶层字段不是塞进 messages②content是数组可含文本 / 图片等多模态③usage区分input读入和output生成token。4.2 Function Calling / Tool Use工具调用约定定义OpenAI 定义的 让模型主动声明要调哪个函数 的约定各家兼容。模型在响应里返回tool_calls应用执行函数后再把结果回填给模型。比喻模型写了一张便签我要打这个电话、号码和说辞是这些—— 你帮它打再把对方回的话告诉它。共同点和 MCP 目的一致让模型用外部能力但它更 轻、由调用方自己实现不依赖统一协议。示例 解释// 响应模型决定调用某个工具 { choices: [ { message: { role: assistant, content: null, tool_calls: [ { id: call_1, function: { name: get_weather, arguments: {\city\:\福州\} } } ] } } ] }解释tool_calls 模型要执行的函数列表function.name 函数名arguments 参数JSON 字符串。应用解析后执行真实函数再把结果以role:tool回填给模型模型据此继续回答。4.3 OpenAPI / Swagger通用接口描述规范定义描述任意 REST 接口的 说明书 规范YAML/JSON定义端点、参数、鉴权。是 web 通用标准AI 工具可读它来知道接口怎么调。比喻给接口写的 使用说明书 / 菜谱。共同点和上面一样都基于 JSON/HTTP、为了 让机器读懂接口。示例 解释精简openapi: 3.0.0 paths: /weather: get: parameters: - name: city in: query type: string解释paths声明端点get声明这是 GET 请求parameters声明它需要一个city查询参数。模型读到这份说明就知道该调/weather?city福州。其余主流简述gRPC高性能 RPC适合服务间内部调用、GraphQL灵活查询适合聚合多个数据源、Ollama / vLLM本地推理框架绝大多数也提供 OpenAI 兼容端点。