企业官网建设流程全解析

1. 从一堆热搜词里，我看到了同一个焦虑

最近后台和群里被问得最多的一类问题，几乎都绕着三个词打转：多 Agent、MCP、A2A。有人拿着mcp是什么这种最基础的问题来问，也有人已经在折腾codex 接入 figma mcp 怎么授权、idea插件通义灵码怎么使用mcp链接oracle这种落地细节了。中间还夹着一堆看着就头大的词：a2a spring、c++ a2a、ruoyi-vue-pro合并mcp功能、x32dbg 的mcp插件、cheat engine 桥接mcp教程。

把这些词摊开看，你会发现它们其实指向同一件事：大家手里的模型已经够聪明了，但"聪明"和"能干活"之间还差一层东西。这层东西，就是协议和编排。多 Agent 解决的是"一个脑子不够用，那就分工"；MCP 解决的是"模型怎么安全、标准化地够到外部工具和数据"；A2A 解决的是"多个 Agent 之间怎么互相说话、互相派活"。

我写这篇不是要给你灌概念。市面上讲"什么是 Agent"的文章已经烂大街了，但真正把这三样东西串起来、讲清楚它们各自管哪一段、边界在哪、什么时候该用哪个的，少。更关键的是，很多人一上来就想搞"多 Agent 协作"，结果连单个 Agent 怎么稳定调用一个工具都没跑通，最后项目烂尾，还以为是模型不行。

这篇适合三类人：一是刚接触mcp协议、想搞明白它到底解决什么问题的开发者；二是已经在用 Dify、Coze、通义灵码这类平台，想接自己的数据库或内部系统的同学；三是准备做多 Agent 编排、在a2a spring或c++ a2a这类技术栈上选型的人。我会把这三层从底到顶拆开讲，配上能直接抄的配置思路和踩坑记录。看完你至少能判断：你手上这个需求，到底该上 MCP，还是该上多 Agent，还是两个都得上。

2. 先把三个概念的地基打牢，别急着上框架

2.1 MCP 到底是什么：给模型装一个标准化的"USB 接口"

mcp是什么这个问题被搜了无数次，我用一句话给你说透：MCP（Model Context Protocol）是一套让模型和外部能力之间用统一格式对话的约定。你可以把它理解成 USB 接口。以前每个外设都有自己的奇葩接口，鼠标一个、键盘一个、U 盘一个，插错就冒烟。USB 出来之后，只要设备支持 USB，电脑就能认。MCP 干的就是这件事——只要你的工具按 MCP 规范暴露能力，任何支持 MCP 的模型客户端都能直接调用，不用为每个模型单独写一套适配。

它解决的核心痛点是碎片化。在没有 MCP 之前，你想让模型查一下公司数据库，得写一个函数调用；想让它读一下本地文件，又得写一套；换个模型平台，全部重写。MCP 把这些能力抽象成三类原语：Resources（资源，只读数据）、Tools（工具，可执行动作）、Prompts（提示模板）。模型通过标准协议去发现、去调用，客户端负责把结果喂回去。

这里有个很多人搞混的点：MCP 不是模型本身的能力，它是客户端和服务器之间的协议。你的工具跑在一个 MCP Server 里，模型所在的宿主（比如某个 IDE 插件、某个桌面客户端）作为 MCP Client 去连它。所以codex无法找到mcp这类问题，八成不是模型的问题，而是 Client 没配对 Server 的启动方式或路径。

2.2 多 Agent 是什么：一个脑子不够，那就组个队

多 Agent 的本质是任务分解与角色分工。单个 Agent 在面对复杂任务时，容易上下文爆炸、注意力涣散、一步错步步错。多 Agent 的思路是：把一个大任务拆成若干子任务，每个子任务交给一个"专精"的 Agent，各自有独立的系统提示、独立的工具集、独立的上下文窗口。

举个最直观的例子。你要做一个"自动调研并生成报告"的系统。单 Agent 的做法是：一个模型又搜资料、又分析、又写报告，上下文里塞满了原始网页，写到后面它自己都忘了前面查了啥。多 Agent 的做法是：一个检索 Agent只负责搜和筛，把干净的结构化结果交出去；一个分析 Agent只负责从结构化结果里提炼观点；一个写作 Agent只负责成文。每个 Agent 的上下文都很干净，输出质量自然稳定。

但多 Agent 不是银弹。它带来三个新问题：通信成本、状态一致性、错误传播。Agent 之间怎么传消息？传丢了怎么办？A 给 B 的中间结果错了，B 和 C 全跟着错。这就是为什么 A2A 会出现。

2.3 A2A 是什么：Agent 之间的"外交协议"

A2A（Agent-to-Agent）解决的是Agent 之间如何互相发现、互相委派任务、互相交换结果。如果说 MCP 是"模型对外部工具的接口"，那 A2A 就是"Agent 对 Agent 的接口"。它关心的是：一个 Agent 怎么知道另一个 Agent 能干什么（能力发现）、怎么把任务派过去（任务委派）、怎么拿到进度和结果（状态同步）。

热搜里出现的a2a spring、c++ a2a，说明大家已经在具体技术栈上找实现了。Spring 生态里做 A2A，通常是基于 HTTP/SSE 或者消息队列来做 Agent 间的通信；C++ 做 A2A 更多出现在对性能敏感、或者需要和已有 C++ 系统集成的场景。如何把 agent 暴露出 a2a agentcoard这个搜索词里的 "agentcoard" 大概率是 "agent card" 的拼写变体——A2A 里确实有个核心概念叫Agent Card，就是一张描述"我是谁、我能干什么、怎么调用我"的名片，别的 Agent 靠读这张卡来决定要不要把活派给你。

三者关系我画个表你就清楚了：

注意：这三者不是替代关系，是叠加关系。一个成熟系统往往是：多个 Agent 各自通过 MCP 调用自己的工具，Agent 之间通过 A2A 通信。别指望用一个就能解决全部问题。

3. 为什么现在必须补这堂课：三个真实的翻车现场

3.1 翻车一：把 MCP 当成"万能插件"，结果权限失控

我见过一个团队，为了让模型能操作内部系统，把数据库的读写权限、文件系统的删除权限、甚至一些管理接口，全部通过一个 MCP Server 暴露出去。他们的想法很简单："反正模型很聪明，它会自己判断该不该删。" 结果一次测试中，模型为了"清理临时数据"，把一个不该动的表给清了。

问题出在哪？MCP 的 Tools 是能力，不是策略。协议只负责"能不能调"，不负责"该不该调"。权限控制、操作审计、危险动作二次确认，这些必须在 MCP Server 这一层或者更上层做掉。正确做法是：每个 Tool 都要有明确的输入校验和权限边界，危险操作要么不暴露，要么强制走人工确认。x32dbg 的mcp插件、cheat engine 桥接mcp教程这类搜索背后，其实也是同一个问题——把调试器这种高权限工具通过 MCP 暴露出去，风险极高，必须严格限定作用域。

3.2 翻车二：多 Agent 编排做成了"消息接力赛"，一错全错

另一个典型场景是做多agent编排示例时，很多人第一反应是搞一条链：Agent A 输出给 Agent B，B 输出给 C，C 输出给 D。看起来很美，实际跑起来就是灾难。因为链式结构没有任何校验和回退机制，A 的一个小偏差会被 B 放大，被 C 再放大，到 D 的时候已经面目全非。

我自己的经验是：多 Agent 编排里，最值钱的不是"怎么连"，而是"怎么验"。每个 Agent 的输出都要有结构化的 schema 约束，下游 Agent 拿到输入先做一次校验，不合格就打回或者走兜底分支。链式结构只适合步骤之间强依赖、且每步都可验证的场景。更稳的做法是"编排器 + 工作者"模式：一个 Orchestrator Agent 负责拆任务和汇总，多个 Worker Agent 并行干活，Orchestrator 对每个 Worker 的结果做质量把关。

3.3 翻车三：A2A 没做能力发现，硬编码调用满天飞

如何把 agent 暴露出 a2a agentcoard这个搜索词，说明已经有人意识到 Agent Card 的重要性了。但我见过太多项目，A2A 通信是硬编码的：Agent A 的代码里直接写死了 Agent B 的地址和接口格式。B 一升级、一改接口，A 就挂。这就是没做能力发现（Capability Discovery）的后果。

A2A 的正确姿势是：每个 Agent 启动时注册自己的 Agent Card，声明能力、输入输出格式、调用方式；调用方先查 Card，再决定怎么调。这样 B 换了实现、加了能力，A 不用改代码。a2a spring生态里，这件事通常靠注册中心或者服务发现来做；c++ a2a场景下，可能就是一个共享的配置文件或者轻量注册服务。

4. MCP 落地实操：从零把一个工具接进模型

4.1 选型：自己写 Server 还是用现成的

在动手之前先想清楚：你要暴露的能力，是通用能力还是私有能力？通用能力（读文件、查网页、跑命令）大概率已经有现成的 MCP Server，直接用，别重复造轮子。私有能力（公司内部系统、特定数据库）才需要自己写 Server。

自己写 Server 时，语言选择看你的现有技术栈。Python 和 TypeScript 的 SDK 最成熟，文档最全，新手优先选这两个。如果你要接的是 Oracle 这种企业数据库，像idea插件通义灵码怎么使用mcp链接oracle这种场景，通常是用现成的数据库 MCP Server，配置好连接串和只读账号即可，不需要自己写协议层。

4.2 一个最小可用的 MCP Server 长什么样

下面是一个 Python 版的最小示例，暴露一个"查询订单状态"的工具。注意看它的结构：工具声明、参数 schema、执行逻辑，三部分清清楚楚。

from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import json app = Server("order-service") # 声明工具：名字、描述、参数 schema @app.list_tools() async def list_tools(): return [ Tool( name="query_order_status", description="根据订单号查询订单当前状态，只读操作", inputSchema={ "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，格式为 ORD 开头加 12 位数字" } }, "required": ["order_id"] } ) ] # 执行逻辑：注意这里做了输入校验 @app.call_tool() async def call_tool(name: str, arguments: dict): if name != "query_order_status": raise ValueError(f"未知工具: {name}") order_id = arguments.get("order_id", "") if not order_id.startswith("ORD") or len(order_id) != 15: return [TextContent(type="text", text="订单号格式不正确")] # 这里换成你真实的查询逻辑 result = {"order_id": order_id, "status": "已发货", "updated_at": "2025-01-01"} return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False))] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ == "__main__": import asyncio asyncio.run(main())

这段代码有几个关键点值得说。第一，description 写得越清楚，模型调用越准。别写"查询订单"，要写清楚参数格式和操作性质。第二，输入校验必须在 Server 端做，不能指望模型每次都传对。第三，只读操作和写操作要分开暴露，写操作要么单独一个工具，要么加确认参数。

4.3 客户端配置：为什么你的模型"找不到 MCP"

codex无法找到mcp这类问题，排查顺序我总结成一张表：

codex 接入 figma mcp 怎么授权、codex 接入蓝湖mcp这类问题，本质是远程 MCP Server 的鉴权。远程 Server 通常需要 OAuth 或者 API Key，配置的时候要确保 token 有正确的 scope。授权失败最常见的原因是回调地址配错，或者 token 权限范围不够。

实操心得：调试 MCP 时，先用最简单的 stdio 模式跑通本地工具，确认协议层没问题，再去搞远程和鉴权。一上来就搞远程 OAuth，出问题你根本分不清是协议问题还是鉴权问题。

5. 多 Agent 编排：别一上来就搞全自动

5.1 编排模式选型：链式、并行还是编排器

多agent编排示例搜出来的方案五花八门，但归根结底就三种模式：

链式（Sequential）：A 做完给 B，B 做完给 C。适合步骤强依赖、每步可验证的流程，比如"提取需求 → 生成代码 → 跑测试"。缺点是错误会累积，所以每步之间必须有校验。

并行（Parallel）：多个 Agent 同时干活，最后汇总。适合子任务相互独立的场景，比如"同时调研三个竞品"。优点是快，缺点是汇总逻辑要写好，不然结果打架。

编排器（Orchestrator）：一个主 Agent 负责拆解、派活、验收，Worker Agent 负责执行。这是最灵活也最稳的模式，适合复杂任务。代价是编排器本身的设计要花心思，它得知道每个 Worker 的能力边界。

我的建议是：新手从链式开始，跑通了再上编排器。链式结构简单，出问题好定位。直接上编排器，你会被"编排器自己判断失误"和"Worker 执行失误"两类问题同时折磨。

5.2 一个可落地的编排器骨架

下面这个伪代码展示编排器的核心逻辑：拆任务、派活、验收、兜底。

class Orchestrator: def __init__(self, workers: dict): # workers: {"检索": agent_a, "分析": agent_b, "写作": agent_c} self.workers = workers def run(self, task: str): # 第一步：拆解任务，产出结构化子任务列表 subtasks = self.plan(task) results = {} for st in subtasks: worker = self.workers.get(st["role"]) if not worker: results[st["id"]] = {"error": f"没有能处理 {st['role']} 的 Agent"} continue # 第二步：执行，带重试 output = self.execute_with_retry(worker, st, max_retry=2) # 第三步：验收，不合格走兜底 if not self.validate(output, st["expected_schema"]): output = self.fallback(st) results[st["id"]] = output # 第四步：汇总 return self.aggregate(results) def execute_with_retry(self, worker, subtask, max_retry): for i in range(max_retry + 1): try: return worker.run(subtask["input"]) except Exception as e: if i == max_retry: return {"error": str(e)}

这里最关键的是validate和fallback。没有验收的多 Agent 系统，等于没有质检的流水线。验收标准要提前定义好，通常是 JSON schema 或者明确的字段检查。兜底策略可以是"返回错误让上游处理"，也可以是"降级到简单模式"，看业务容忍度。

5.3 上下文管理：多 Agent 最容易忽略的坑

多 Agent 系统里，上下文怎么传是个大学问。全量传，上下文爆炸；只传结论，信息丢失。我的做法是分层传递：Agent 之间传的是"结构化摘要 + 原始数据引用"，而不是原始数据本身。比如检索 Agent 给分析 Agent 的，是"我找到了 5 篇相关文章，摘要如下，原文存在 XXX 位置"，分析 Agent 需要细节时再按引用去取。

这样做的好处是每个 Agent 的上下文都很干净，坏处是需要一个共享的存储层。但这个存储层的成本，远低于上下文爆炸带来的质量和成本问题。

6. A2A 通信：让 Agent 之间"说人话"

6.1 Agent Card：先想清楚"我是谁"

A2A 的第一步不是写通信代码，是设计 Agent Card。一张合格的 Card 至少包含：Agent 标识、能力描述、输入输出格式、调用端点、鉴权方式、限流信息。这就像给每个 Agent 发一张名片，别人拿到名片才知道怎么找你办事。

{ "agent_id": "research-agent-v1", "name": "调研 Agent", "description": "接收调研主题，返回结构化的调研结果", "capabilities": ["web_search", "summarize", "cite_sources"], "input_schema": { "type": "object", "properties": { "topic": {"type": "string"}, "depth": {"type": "string", "enum": ["quick", "deep"]} }, "required": ["topic"] }, "output_schema": { "type": "object", "properties": { "summary": {"type": "string"}, "sources": {"type": "array"} } }, "endpoint": "http://research-agent.internal/a2a", "auth": "bearer", "rate_limit": "10/min" }

如何把 agent 暴露出 a2a agentcoard这个问题的答案就在这：把你的 Agent 能力写成这样一张结构化的卡，注册到一个所有 Agent 都能查到的地方。查得到，才谈得上协作。

6.2 通信协议选型：HTTP、SSE 还是消息队列

a2a spring场景下，通信方式的选择直接影响系统复杂度：

我的经验是：任务耗时在 30 秒以内的，用 HTTP 同步；超过 30 秒的，用消息队列。SSE 适合需要给用户展示进度的场景，但 Agent 之间的通信，SSE 的复杂度往往不划算。c++ a2a场景下，如果双方都在同一进程内，直接函数调用加个异步框架就够了，没必要上网络协议。

6.3 错误处理与幂等：A2A 的生死线

Agent 之间通信，最怕的是"任务派过去了，但不知道对方做没做"。网络抖动、对方重启、超时重试，都可能导致任务重复执行。所以A2A 的每个任务都要有唯一 ID，接收方要做幂等处理：同一个任务 ID 重复到达，只执行一次，后续直接返回缓存结果。

# 接收方幂等处理示意 processed_tasks = {} def handle_task(task): task_id = task["task_id"] if task_id in processed_tasks: return processed_tasks[task_id] # 直接返回上次结果 result = do_work(task) processed_tasks[task_id] = result return result

这个processed_tasks在生产环境要换成带过期时间的持久化存储，不然内存会爆，重启会丢。别小看这一步，我见过太多 A2A 系统因为没做幂等，重试一次就产生一条重复订单。

7. 三者协同：一个完整的落地架构长什么样

7.1 分层架构：MCP 在底，A2A 在中，多 Agent 在上

把三者拼起来，一个成熟的系统是这样的：

底层（MCP 层）：每个 Agent 通过 MCP 连接自己需要的工具和数据源。检索 Agent 连搜索 MCP，数据库 Agent 连数据库 MCP，代码 Agent 连文件系统 MCP。这一层解决"能力接入"。

中层（A2A 层）：Agent 之间通过 A2A 协议通信，靠 Agent Card 做能力发现，靠任务 ID 做幂等，靠消息队列或 HTTP 做传输。这一层解决"协作通信"。

上层（编排层）：编排器负责拆解用户任务、派发给合适的 Agent、验收结果、汇总输出。这一层解决"任务调度"。

ruoyi-vue-pro合并mcp功能这类需求，本质就是在一个已有的业务系统里，把 MCP 层接进去，让系统里的能力能被模型调用。做法通常是：把系统里适合暴露的接口，包装成 MCP Server，然后在上层接一个编排器。

7.2 一个真实场景的完整走查

假设你要做一个"自动处理客户工单"的系统。用户提交工单，系统自动分类、查资料、生成回复草稿、人工审核。

第一步，工单分类 Agent 通过 MCP 调用分类模型工具，产出工单类别和紧急度。第二步，编排器根据类别，通过 A2A 把任务派给"知识检索 Agent"，检索 Agent 通过 MCP 查内部知识库，返回相关文档。第三步，回复生成 Agent 拿到工单和文档，生成草稿。第四步，编排器把草稿交给人工审核队列。

整个流程里，MCP 负责每次"够到工具"，A2A 负责 Agent 之间的任务流转，编排器负责全局调度。三者各司其职，缺一不可。

7.3 成本与性能：别忽略这两个隐形杀手

多 Agent + MCP + A2A 的架构，成本主要来自三块：模型调用次数、上下文长度、通信开销。每多一个 Agent，就多一次模型调用；每次 A2A 通信，都可能带着上下文；MCP 每次调用工具，也可能触发模型推理。

控制成本的核心手段是缓存和裁剪。工具调用结果能缓存的缓存，Agent 之间的上下文只传必要的，编排器的拆解逻辑尽量用规则而不是模型。我实测下来，一个设计良好的多 Agent 系统，成本可以做到"单 Agent 全量处理"的 1.5 到 2 倍，而不是很多人以为的 5 倍 10 倍。差距就在这些细节里。

8. 常见问题速查与避坑清单

8.1 MCP 相关问题速查

8.2 多 Agent 避坑清单

• 别一上来就搞全自动：先做"AI 建议 + 人工确认"，跑稳了再逐步放开。
• 每个 Agent 的输出都要有 schema：没有结构约束的输出，下游没法可靠处理。
• 编排器要有兜底：任何一步失败，都要有明确的降级或报错路径。
• 上下文分层传：传摘要和引用，别传原始数据。
• 监控每个 Agent 的成功率和耗时：哪个环节拖后腿，数据会告诉你。

8.3 A2A 避坑清单

• Agent Card 先行：先设计名片，再写通信。
• 任务 ID 必须全局唯一：用 UUID，别用时间戳。
• 接收方必须幂等：重复任务只执行一次。
• 超时和重试要配对：重试次数和超时时间要匹配任务特性。
• 能力发现别硬编码：用注册中心或配置中心，别写死在代码里。

最后分享一个我踩过的坑：多 Agent 系统上线初期，我为了"稳"，给每个 Agent 都配了很长的系统提示和大量示例。结果上下文成本飙升，而且 Agent 反而因为提示太长而"抓不住重点"。后来我把提示精简到核心规则 + 一两个示例，效果反而更好。提示不是越长越好，Agent 也不是越多越好，够用就行。

这套东西我前后折腾了大半年，从单 Agent 到多 Agent，从手写工具调用到 MCP，从硬编码通信到 A2A。最大的体会是：协议和编排的价值，不在于让系统更"智能"，而在于让系统更"可控"。模型的能力会一直涨，但可控性得靠架构设计。把 MCP 的权限边界划清楚，把多 Agent 的验收环节做扎实，把 A2A 的幂等和发现机制建起来，这套系统才能从 demo 走到生产。