企业官网建设流程全解析

目录

一、API（以 "标准 OpenAI 接口" 为代表）

1.1 请求

1.2 成功响应 &❌ 失败响应

二、MCP（Model Context Protocol，模型上下文协议）

2.1 请求（握手&调用）

2.2 成功响应

2.3 失败响应（jsonrpc 错误格式）

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

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

3.1.1 请求

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

3.2 实例2：带鉴权的成功请求 —— message/send

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

3.2.2 成功响应（任务直接做完，状态 = completed）

3.3 实例 3：失败场景一：没带 token /token 过期（401）

3.3.1 请求（故意不带 Authorization 头）

3.3.2 失败响应

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

3.4.1 请求

3.4.2 失败响应

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

3.5.1 方法名写错（应该是 message/send，写成了 message/sendTask）

3.5.2 参数结构错误（params 里没传 message）

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

3.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，用来计费 / 限流。

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

②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）

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

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 查上海天气）

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，但 isError=true）

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

③ 工具不存在（HTTP 400，JSON-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 错误码：

一句话：先把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就是按照这顺序。

1. 发现：客户端先拉对端的AgentCard（一份 JSON"名片"），看它要求怎么鉴权。
2. 取凭证：按名片上写的方式（OAuth2 / APIKey / Basic…），走 A2A 协议之外的渠道拿到 token。
3. 发任务：在 HTTP 头里带上 token，POST 一个message/send的 JSON-RPC 请求。
4. 收结果：服务端返回一个Task对象，状态可能是completed（直接成功）、working（异步）、或auth-required（中途还要补凭证）。
5. 失败兜底：鉴权失败回 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.com

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

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 realm="weather-agent", error="invalid_token", error_description="token 缺失或已过期，请重新获取" // ★ 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 有效，但你没权限（403）

token 是真的、没过期，但你的 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_id=xxx", "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 兼容端点）。