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

[一、API（以 "标准 OpenAI 接口" 为代表）](#一、API（以 "标准 OpenAI 接口" 为代表）)

[1.1 请求](#1.1 请求)

[1.2 成功响应 &❌ 失败响应](#1.2 成功响应 &❌ 失败响应)

[二、MCP（Model Context Protocol，模型上下文协议）](#二、MCP（Model Context Protocol，模型上下文协议）)

[2.1 请求（握手&调用）](#2.1 请求（握手&调用）)

[2.2 成功响应](#2.2 成功响应)

[2.3 失败响应（jsonrpc 错误格式）](#2.3 失败响应（jsonrpc 错误格式）)

三、A2A（Agent2Agent，智能体间协议）

[3.1 实例1：拉取 AgentCard ------ 先搞清楚 "对方要什么凭证"](#3.1 实例1：拉取 AgentCard —— 先搞清楚 "对方要什么凭证")

[3.1.1 请求](#3.1.1 请求)

[3.1.2 响应（这就是 A2A 的 "身份证 + 招聘启事"）](#3.1.2 响应（这就是 A2A 的 "身份证 + 招聘启事"）)

[3.2 实例2：带鉴权的成功请求 ------ message/send](#3.2 实例2：带鉴权的成功请求 —— message/send)

[3.2.1 请求（注意 token 在 HTTP 头，不在 JSON body 里）](#3.2.1 请求（注意 token 在 HTTP 头，不在 JSON body 里）)

[3.2.2 成功响应（任务直接做完，状态 = completed）](#3.2.2 成功响应（任务直接做完，状态 = completed）)

[3.3 实例 3：失败场景一：没带 token /token 过期（401）](#3.3 实例 3：失败场景一：没带 token /token 过期（401）)

[3.3.1 请求（故意不带 Authorization 头）](#3.3.1 请求（故意不带 Authorization 头）)

[3.3.2 失败响应](#3.3.2 失败响应)

[3.4 实例 4：失败场景二：token 有效，但你没权限（403）](#3.4 实例 4：失败场景二：token 有效，但你没权限（403）)

[3.4.1 请求](#3.4.1 请求)

[3.4.2 失败响应](#3.4.2 失败响应)

[3.5 实例 5：失败场景三：JSON-RPC协议层错误（方法不存在 / 参数错）](#3.5 实例 5：失败场景三：JSON-RPC协议层错误（方法不存在 / 参数错）)

[3.5.1 方法名写错（应该是 message/send，写成了 message/sendTask）](#3.5.1 方法名写错（应该是 message/send，写成了 message/sendTask）)

[3.5.2 参数结构错误（params 里没传 message）](#3.5.2 参数结构错误（params 里没传 message）)

[3.6 实例 6：任务做到一半要 "二次鉴权"（auth-required）](#3.6 实例 6：任务做到一半要 "二次鉴权"（auth-required）)

[3.6.1 第一次请求的响应（任务没失败，而是停下来等你补凭证）](#3.6.1 第一次请求的响应（任务没失败，而是停下来等你补凭证）)

[3.6.2 客户端补完凭证后，再发一条 message/send 把新 token 带回去](#3.6.2 客户端补完凭证后，再发一条 message/send 把新 token 带回去)

[四、除了 MCP / A2A / API，还有别的主流吗？](#四、除了 MCP / A2A / API，还有别的主流吗？)

[4.1 Anthropic Messages API（原生模型接口）](#4.1 Anthropic Messages API（原生模型接口）)

[4.2 Function Calling / Tool Use（工具调用约定）](#4.2 Function Calling / Tool Use（工具调用约定）)

[4.3 OpenAPI / Swagger（通用接口描述规范](#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 请求

python 复制代码

// 请求
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 成功响应 &❌ 失败响应

python 复制代码

// 不同的响应的情况（成功或失败）
// ✅ 成功（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，用来计费 / 限流。

二、MCP（Model 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 显示

部署形态	真正的 Host 跑在哪	用户手里的 App 是什么	MCP Client 跑在哪
桌面端模式（Claude Desktop、Cursor、Trae 桌面版）	用户本机的桌面进程	就是 Host 本身	用户本机
云端 Agent 模式（豆包、Coze、Dify、腾讯元器）	厂商的服务器（Agent 运行时）	只是一个瘦前端（发消息、收结果）	厂商服务器上

② 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，鉴权头 + initialize）

python 复制代码

curl -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，不期待响应）

python 复制代码

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: 2，tools/call 查上海天气）

python 复制代码

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）

python 复制代码

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "weather-server", "version": "1.0.0" }
  }
}

③ tools/call 成功（返回结果）

python 复制代码

{
  "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）

python 复制代码

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Unauthorized: invalid or missing API key"
  }
}

② 工具内部业务失败（HTTP 200，但 isError=true）

python 复制代码

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "未找到城市「福州」的天气数据" }
    ],
    "isError": true
  }
}

③ 工具不存在（HTTP 400，JSON-RPC 参数错误）

python 复制代码

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32602,
    "message": "Unknown tool: get_weather"
  }
}

④ 握手顺序错误 / 协议不兼容（HTTP 400）

python 复制代码

{
  "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" 表示这是一段文本，模型读到后就能接着推理。

三、A2A（Agent2Agent，智能体间协议）

定义：一套 "智能体 ↔ 智能体 " 的对等协作协议。两个 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 头里带上 token，POST 一个 message/send 的 JSON-RPC 请求。
收结果 ：服务端返回一个 Task 对象，状态可能是 completed（直接成功）、working（异步）、或 auth-required（中途还要补凭证）。
失败兜底：鉴权失败回 HTTP 401/403，业务错误回 JSON-RPC error 对象。

典型示例（请求 + 响应）：

3.1 实例1：拉取 AgentCard ------ 先搞清楚 "对方要什么凭证"

这一步通常不需要鉴权（名片本身是公开发现用的），但里面会声明鉴权要求。

3.1.1 请求

python 复制代码

GET /.well-known/agent-card.json HTTP/1.1
Host: weather-agent.example.com

3.1.2 响应（这就是 A2A 的 "身份证 + 招聘启事"）

python 复制代码

{
  "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 换到了一个 JWT：eyJhbGciOiJSUzI1NiIs...，然后。。。

3.2.1 请求（注意 token 在 HTTP 头，不在 JSON body 里）

python 复制代码

//请求头：
POST /a2a HTTP/1.1
Host: weather-agent.example.com
Content-Type: application/json          // JSON-RPC 报文必须用这个 Content-Type
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...   // ★ 鉴权就在这一行，下面的 JSON 里不出现身份信息

python 复制代码

//请求体：
{
  "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）

对端的智能体完成任务的响应。

python 复制代码

//响应头：
HTTP/1.1 200 OK
Content-Type: application/json

python 复制代码

//响应体：
{
  "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 头）

python 复制代码

POST /a2a HTTP/1.1
Host: weather-agent.example.com
Content-Type: application/json
// 漏了 Authorization 头

3.3.2 失败响应

python 复制代码

HTTP/1.1 401 Unauthorized       //失败原因代码：未授权
Content-Type: application/json
WWW-Authenticate: Bearer realm="weather-agent", error="invalid_token",
                  error_description="token 缺失或已过期，请重新获取"
// ★ WWW-Authenticate 是 HTTP 标准头，告诉客户端"该用什么方式重新认证"

python 复制代码

{
  "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 有效，但你没权限（403）

token 是真的、没过期，但你的 OAuth scope 不够（名片上要求 weather.read，你只拿到了 weather.write）。

3.4.1 请求

python 复制代码

POST /a2a HTTP/1.1
Host: weather-agent.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...   // token 本身合法

python 复制代码

{
  "jsonrpc": "2.0",
  "id": "req-20261102-003",
  "method": "message/send",
  "params": { /* ...同上... */ }
}

3.4.2 失败响应

python 复制代码

HTTP/1.1 403 Forbidden
Content-Type: application/json

python 复制代码

{
  "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`）

请求：

python 复制代码

{
  "jsonrpc": "2.0",
  "id": "req-004",
  "method": "message/sendTask",     // ← 这个方法不存在
  "params": {}
}

响应：

python 复制代码

{
  "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）

python 复制代码

{
  "jsonrpc": "2.0",
  "id": "req-005",
  "method": "message/send",
  "params": { "message": null }     // ← message 必须是对象，不能为 null
}

响应：

python 复制代码

{
  "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 第一次请求的响应（任务没失败，而是停下来等你补凭证）

python 复制代码

{
  "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_id=xxx",
              "reason": "我需要读取你邮箱里的航班确认邮件来自动填入行程"
            }
          }
        ]
      }
    }
  }
}

3.6.2 客户端补完凭证后，再发一条 message/send 把新 token 带回去

python 复制代码

POST /a2a HTTP/1.1
Host: weather-agent.example.com
Authorization: Bearer <原来的A2A token>   // 主凭证照常带

python 复制代码

{
  "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。 示例 + 解释：

python 复制代码

// 请求
{ "model": "claude-sonnet-4-5", "max_tokens": 300,
  "system": "你是贴心助手",
  "messages": [ { "role": "user", "content": "福州天气？" } ] }

python 复制代码

// 响应
{ "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 目的一致（让模型用外部能力），但它更 "轻"、由调用方自己实现，不依赖统一协议。 示例 + 解释：

python 复制代码

// 响应：模型决定调用某个工具
{ "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 兼容端点）。