企业官网建设流程全解析

如果你也在用大模型写代码或做自动化流程，大概率已经发现一个令人头痛的问题：把一整个复杂任务丢给单个 Agent，刚开始还挺顺，任务一多就崩——上下文越来越长、工具调用频繁打架、一个环节失败整条链路重来。我前两个月把手里一个内部工具项目从“单 Agent 硬扛”重构成了基于 DeepAgents、MCP、A2A、Skills 的多智能体集群，效果比我预想的好很多。这篇文章把我这次实战的完整思路、架构决策、踩坑过程和可复现的配置方案整理出来，目标读者是那种“已经在用 Claude/Codex/DeepAgents 做自动化、想再往前一步走向生产级多智能体协作”的工程师。

先说这套组合的通俗比喻：DeepAgents 是项目负责人，负责拆任务、派活、收结果；MCP 是整个团队共享的“标准插线板”，数据库、浏览器、设计稿、文件系统都通过它统一接入；A2A 是同事之间商量工作用的“内部交流协议”，让不同 Agent 能互相传需求、传产物；Skills 则是团队沉淀下来的操作手册和老员工经验，Agent 按需调出来照做。前两个月我把这套体系搭起来，今天把这套体系里每个模块的作用边界、工程落地细节和排查思路完整写出来，希望能帮你少走弯路。

1. 四个部件各管哪一段：先给多智能体集群做角色分工

1.1 DeepAgents：真正的编排者，不是另一个大模型

很多朋友第一次听到 DeepAgents，会误以为它是一个“更聪明的模型”。其实完全不是。DeepAgents 是一个生产级的多智能体编排框架，它的核心工作是调度：把一个大任务拆成若干小任务，分发给多个 Worker Agent，跟踪每个任务的进度，回收结果，再组合成最终产出。

我用下来最核心的两个概念是 orchestrator（编排者）和 worker（执行者）。编排者负责规划，它拿到一个高层目标后，会先生成任务清单，再根据任务的依赖关系逐个派发。DeepAgents 里有一个类似任务管理器的模块，维护任务的排队、运行、完成、失败状态，还会动态把新任务插入队列。这套机制解决的核心问题是：单 Agent 一旦任务链过长，上下文必然爆炸，而编排者可以把上下文切分成多个短小的子任务上下文，每个 Worker 只关心自己那一小段，结束就释放。

注意：DeepAgents 的各版本 API 名字和语言 SDK 有差异，我用的是 Python 版本，但本文讲的 orchestration-worker 模型、任务状态机、任务队列思想是跨版本通用的。

1.2 MCP：统一智能体的“手”

MCP（Model Context Protocol）解决的是智能体怎么操作外部工具和数据的问题。它由 Anthropic 提出，目前已是非常广泛接受的标准协议，本质是一个 client-server 架构：大模型应用侧是 MCP client，外部工具和数据源包成 MCP server，两边通过标准协议通信。你不需要再让每个 Agent 各自发明一套工具调用格式，也不需要为每个数据库单独写一套解析插件，全部统一成一套“USB-C 接口”，插上就能用。

具体来说，MCP server 对外暴露三类能力：resources（资源，给模型读取的数据）、tools（工具，模型可调用的操作）、prompts（提示词，给模型定制的交互模板）。比如一个 PostgreSQL MCP server，可以暴露read_schema、run_query这类工具；一个浏览器 MCP server，可以暴露open_page、click、extract_text这类工具。Agent 只需要说“我要查数据库结构”，MCP 会自动把请求路由到对应工具。

现在 MCP 的生态比想象中广得多，不只是数据库和浏览器。游戏引擎 UE 已经在接入 MCP，国内一些后台管理框架（比如若依的 pro 版本）也在合并 MCP 功能，设计稿标注工具（Figma、蓝湖）同样有对应的 MCP server。这意味着多智能体集群可以操作的工具范围比我最早设想的要宽得多。

1.3 A2A：让 Agent 之间说“人话”

如果说 MCP 解决的是“Agent 连接工具”，那 A2A（Agent2Agent）解决的就是“Agent 连接 Agent”。这是多智能体集群里最容易被忽略、却最关键的一环。A2A 是 Google 联合多家厂商推动的开放协议，建立在 HTTP 和 JSON-RPC 2.0 之上，每个 Agent 通过一个公开的 AgentCard 来声明自己的能力、接受任务的方式、支持的消息格式。

AgentCard 默认放在/.well-known/agent-card.json，我项目里一个典型的卡片长这样：

{ "@context": "https://a2a-protocol.org/ns/1.0", "name": "backend-worker", "description": "负责后端接口开发和数据库操作的Worker Agent", "url": "http://agent-cluster.internal/backend-worker", "capabilities": { "skills": ["python", "postgresql", "rest-api"], "actions": ["implement-endpoint", "migrate-schema", "run-tests"] }, "security": { "auth": "none" } }

当编排者要向某个 Worker 派活时，它向该 Worker 的 AgentCard URL 发送一个任务请求（task request），Worker 收到后返回任务 ID。之后编排者可以查询任务状态、接收任务产生的 artifact（比如代码文件、接口测试报告）。如果任务太重，Worker 支持下推服务，主动把状态推回来。

A2A 让多智能体系统第一次有了“横向协同”的可能。以前做多智能体往往是把多个 Agent 塞进同一个框架里、用框架私有的消息机制互通，A2A 把这些消息机制统一成了公开协议，任何支持 A2A 的 Agent（不管底层用的是哪种框架）都能互相协作，这也是我这次选择它的核心原因。

1.4 Skills：把“怎么做”固化成可复用的肌肉记忆

如果说 MCP 是硬件接口，A2A 是通信协议，那 Skills 就是团队的经验沉淀。最近 Claude 和 Codex 生态里 Skills 非常火，GitHub 上有大量开源的 skills 包，比如 Superpowers、find skills 这类技能库，核心形态都一致：一个带结构化元数据的SKILL.md文件，加上若干辅助脚本和资源文件。

技能的作用是把“如何完成某类任务”的完整方法论固化下来。比如一个“数据库建模 Skills”，会告诉 Agent：先收集字段约束、再画 ER 图、再生成迁移脚本，每一步要检查哪些边界条件。Agent 拿到SKILL.md后能按图索骥，不需要每一次都从零推理。这比单纯往提示词里塞指令可靠得多，因为技能是从实际项目中反复验证过的流程，而且可以版本化管理。

我团队现在的做法是：每次项目踩完坑、得出正确流程后，就沉淀一个 Skill，放进独立的 skills 仓库，所有 Worker 通过配置加载。这样多智能体集群的能力会随着时间越来越强，而不是一直重复踩坑。

四个部件做个对照总结：

2. 工程脚手架：目录结构、安装顺序与最容易忽略的版本细节

2.1 一个单仓多模块的工作区布局

我一开始犯过错误：把每个 Agent 建一个独立仓库，结果依赖版本管理、配置同步都成了灾难。后来改成了单仓多模块，结构如下：

agent-cluster/ ├── orchestrator/ # 编排者服务 │ ├── main.py │ └── tasks/ ├── workers/ # 各类 Worker │ ├── backend_worker/ │ ├── frontend_worker/ │ └── data_worker/ ├── mcp_servers/ # 自建的 MCP server │ ├── postgres_mcp/ │ └── file_system_mcp/ ├── skills/ # 技能库（来自官方/社区/自建） │ ├── database-design/ │ ├── api-codegen/ │ └── code-review/ ├── configs/ │ ├── mcp_config.json # 统一 MCP server 配置 │ ├── agent_cards/ # 各Worker的AgentCard配置 │ └── cluster.yaml # 集群拓扑配置 └── logs/

这个布局最大的好处是：技能和配置都能被所有 Worker 共享，而且mcp_config.json只有一份，任何工具接入的变化都在一个地方体现，不会出现“前端 Worker 知道有数据库 MCP、后端 Worker 却不知道”的割裂状态。

2.2 安装顺序与依赖版本

多智能体集群涉及三个独立的技术栈：MCP SDK、A2A SDK、DeepAgents。安装顺序我建议固定为：先 MCP，再 A2A，最后 DeepAgents。原因很简单：DeepAgents 编排层的配置里会引用 MCP server 和 A2A 的 AgentCard，如果反向安装，你会发现配置写完了、SDK 还没就位，导致大量假阳性报错。

版本细节上非常容易踩雷：MCP SDK 的 Python 包和 TypeScript 包更新节奏差异大，A2A 的 SDK 也在快速迭代，不同小版本之间的消息 schema 可能不兼容。我建议把三个 SDK 的版本全部锁死写进requirements.txt或package.json，并且记录实际验证过的版本组合。这个问题后面在踩坑部分我会展开讲。

2.3 预置一组生产常用的 MCP server

实测中我用得最多的一组 MCP server 如下：

配置统一写到mcp_config.json，每个 Worker 按需加载审批过的 server。打个比方，MCP server 就像团队公用的工具箱，但不是每个成员都能拿所有工具，谁有权用哪个工具需要在配置里声明清楚。

2.4 把 Skills 来源纳入版本管理

Skills 的来源有三种：官方市场、GitHub 开源技能库、团队内部自建。我强烈建议：不要直接往生产集群里引一个不断变动的技能市场源，而是把选中的技能目录固定一个版本，复制进仓库的skills/目录。

比如你想用社区流行的迁移工具技能包，就固定其版本纳入仓库；团队自己沉淀的技能还要配套写验收用例，防止技能更新改坏了之前的行为。近来 Pro-level 技能包如 Superpowers 这类项目的流行，也证明了把技能集中管理、按需装配的模式已经被广泛验证。在一个多智能体集群里，Skills 是模型推理能力的补充，管理不好它就是不稳定因素，管好了它就是整个集群的竞争力。

3. 第一个闭环：让两个 Worker 协作做一个“带数据库的 CRUD 后台”

3.1 任务拆解：从一句需求到子任务树

纸上谈兵没意思，我拿实例走一遍。假设编排者收到这样一句需求：“为库存表做一个简单的 CRUD 管理后台，包含前端页面和后端接口。”这句话看起来简单，对于单个 Agent 来说却要同时处理建表、写接口、开发页面、联调四件事，上下文很快不够用。

在 DeepAgents 里，编排者会先把需求展开成子任务树：

需求：库存表 CRUD 后台 ├── T1: 后端 Worker 读取库存表结构（PostgreSQL MCP） ├── T2: 后端 Worker 生成迁移脚本与数据访问层 ├── T3: 前端 Worker 读取设计稿标注（Figma MCP） ├── T4: 前端 Worker 生成列表/新增/编辑页面 ├── T5: 两个 Worker 通过 A2A 交换 API 契约 └── T6: 编排者汇总前后端产物，输出验收报告

T1 和 T3 没有依赖关系，可以并行跑；T2 依赖 T1，T4 依赖 T3；T5 是跨 Agent 协同的关键节点。这就是编排者存在的意义：把一个复杂任务切成有依赖关系的小任务，并决定谁先谁后。

3.2 注册两个 Worker 的 MCP 与 Skills

后端 Worker 的配置长这样（简化版）：

# workers/backend_worker/agent.py from deepagents import WorkerAgent backend_worker = WorkerAgent( name="backend-worker", system_prompt="你是后端开发专家，负责接口和数据库相关工作。", mcp_servers=["postgresql_mcp"], # 只加载它需要的工具 skills=["database-design", "api-codegen"], # 让它按技能模板干活 agent_card_url="http://agent-cluster.internal/backend-worker", )

前端 Worker 类似，但加载的是设计稿 MCP 和前端开发 skills。

这里需要注意一个容易被忽略的设计：Worker 加载的 MCP server 和 Skill 越少，它的行为越可控。我给每个 Worker 维护了一份“能力白名单”，不在白名单内的 MCP server 一律不加载。这样能避免 Worker 在任务的某个中间步骤里突然调用一个不该用的工具，把整个系统的可预测性拉高一个档次。

3.3 用 A2A 完成跨 Agent 交付

CRUD 项目里最有意思的环节是 T5：前后端接口契约的交换。后端 Worker 需要告诉前端 Worker“我的接口路径是/api/inventory，请求参数是page、pageSize，返回结构是{list, total}”。这套消息是通过 A2A 协议传递的。

编排者在任务分配时，会把“后端接口定义”作为 artifact，通过 A2A 的 task 消息推给前端 Worker。前端 Worker 拿到消息后，可以直接解码出接口契约，然后调用前端开发 skills 生成匹配的页面。整个过程里，两个 Worker 并没有通过同一个框架内部消息系统对话，而是标准的 A2A 协议，这意味着以后哪怕把前端 Worker 换成别家框架的 Agent，只要它实现了 A2A，依然能无缝协作。

3.4 这个案例里我最想强调的设计决策：工具归 MCP，对话归 A2A

很多人第一次搭多智能体时会把工具调用和 Agent 间通信混在一起，让 Agent 之间用发工具请求的方式互相调用。这看起来方便，实际上非常危险。工具请求是短连接、强类型、高频率的；Agent 对话是长周期、弱类型、允许双向交付的。混在一起会导致：消息超时定义混乱、认证权限难以划分、日志无法追溯“到底是谁在调用工具”。

正确做法是：任何 Agent 想操作外部资源，一律走 MCP；任何 Agent 想向另一个 Agent 提需求或交付产物，一律走 A2A。两者边界分明，出现问题的时候只需要查对应协议层的日志就够了。

4. 集群编排：三种协作拓扑与任务状态机设计

4.1 路由式、广播式、队列式三种协作拓扑

多智能体集群不是只有“编排者派活”这一种模式，实际生产里我用过三种拓扑：

• 路由式：编排者根据任务类型把请求派给固定 Worker。比如“前端相关任务只发给前端 Worker”，特点是指责明确、效率高、好追踪，缺点是单点 Worker 容易成为瓶颈、可用性依赖路由判断的准确性。
• 广播式：编排者把任务同时广播给多个 Worker，让它们并行产出各自方案，再对结果做交叉评审/择优。这在方案设计、代码评审这类场景特别好用，本质是拿资源换质量；缺点是 Token 成本和延迟都会上升，不适合高频简单任务。
• 队列式：所有任务进一个共享队列，多个同类 Worker 排队消费。适合“一秒内并发几十个相似请求”的批量场景，比如批量生成报表、批量生成测试用例，消息队列在这里负责削峰填谷。

我在 CRUD 项目里用路由式，日常批量任务用队列式，方案类任务用广播式。三种拓扑之间可以通过 DeepAgents 的编排逻辑动态切换，而不是一套拓扑走到底。

4.2 任务状态机：从 New 到 Failed

多智能体集群最容易变成“黑盒”——任务发出去之后你不知道它在哪一步、卡在谁手里、为什么失败。我的解法是给每个任务建模完整状态机，并在每一步打结构化日志：

New → Dispatched → InProgress → NeedsInput → Completed ↘ Failed

• New：任务已创建，进入队列；
• Dispatched：编排者已决定发给哪个 Worker；
• InProgress：Worker 开始执行；
• NeedsInput：任务执行中需要外部输入（比如人工确认、或者其他 Agent 的产物）；
• Completed：Worker 标记完成并交付 artifact；
• Failed：失败并携带错误原因。

每个状态切换都记录时间戳和负责的 Agent。划分清楚后，出问题不用猜，直接查“任务卡在哪个状态、停留了多久、关联了哪个 Agent”就能定位。我的代码里会为每个状态切换预留回调函数，比如进入 Failed 时自动触发重试逻辑或人工通知。

4.3 可恢复性：让集群挂了还能继续跑

第一版集群我做得太“乐观”，所有任务状态都存在内存里，编排者一重启，所有进行中的任务全部丢失，好几个 Worker 白跑一场。后来我把任务状态持久化到 PostgreSQL，每个任务有全局唯一 ID，Worker 的执行步骤记录幂等 key，重跑时通过幂等 key 跳过已完成的部分。

可恢复性是集群和单 Agent 的核心区别之一。单 Agent 挂了就重来一次；集群是多个 Agent 并行执行，如果编排者挂了而 Worker 还在跑、任务状态丢失，那整个集群的一致性就崩了。所以在落地时建议从一开始就让任务状态落盘、关键操作幂等化。很多严肃行业（电网调度、科研计算）的多智能体协同之所以强调“可靠运行”，深层的工程基础就是这一套状态持久化和异常恢复机制。

5. 上线两周，我们踩过的坑：完整排查链路三例

5.1 症状一：Agent 报“找不到工具”，但配置明明写对了

某次后端 Worker 在执行数据库任务时报错，提示找不到 PostgreSQL MCP 暴露的工具。我第一反应是mcp_config.json写错了，反复检查 URL、端口、鉴权头，全都正确。后来我按以下链路排查：

1. 先确认 MCP server 进程是否正常启动，日志里有没有报错；
2. 直接用命令行工具向 MCP server 发请求，检查tools/list返回的工具列表，确认 server 本身可用；
3. 检查 Worker 启动时加载的 MCP client 是否成功连接，观察握手日志；
4. 发现 MCP server 的版本更新后，把新工具放在了新的命名空间，而 Worker 里加载的是旧索引；
5. 清除 Worker 的 MCP 工具索引缓存，重启后恢复。

这个 Case 的教训是：MCP server 和 Worker 之间的工具列表是“发布时拉取”的，不是每次调用实时获取的。工具更新后，必须主动刷新 Worker 侧的索引，否则就会出现配置正确、运行报错的诡异现象。

5.2 症状二：A2A 握手成功，但任务卡在 InProgress

另一个高频故障：编排者向 Worker 派发 A2A 任务后，任务状态一直停在 InProgress，既不失败也不完成。排查链路如下：

1. 先确认 AgentCard URL 能从编排者侧正常访问，排除网络隔离问题；
2. 在 Worker 侧日志里查有没有收到任务请求，发现消息已收到，但 Worker 一直没标记进度；
3. 怀疑是消息超时设置问题：A2A 的默认轮询间隔是 5 秒，而我的长任务经常运行 10 分钟以上，Worker 侧没有在任务执行期间主动推送心跳，导致编排者认为任务已经失联；
4. 将 Worker 的执行过程改为分段状态上报（每完成一个步骤就推送一次 progress 事件）；
5. 顺手排查了另一个隐患：回调 URL 没暴露给 Worker。在某些网络环境里，编排者能访问 Worker，但 Worker 的回调地址却指向一个不可达的内网地址，导致事件推送失败。

提示：A2A 里“任务不失败但也不推进”绝大多数不是协议不通，而是状态更新机制没对齐。排查优先级：网络可达性 → 心跳/进度事件 → 回调 URL → 超时配置。

5.3 症状三：两个 Worker 同时抢着写一张表，数据库锁冲突循环

队列式拓扑上线后，我开了三个同类 Worker 并行跑批处理任务，结果它们同时撞向同一张表，数据库锁冲突日志刷屏，任务互相阻塞。这不是 Agent 本身的问题，是并发治理问题。

解决方案分三层：一是给任务加亲和性，同一张表的写入任务固定分配给同一个 Worker；二是加写队列，同一类写入操作在应用层排队；三是数据库侧给关键任务增加重试逻辑和退避策略。三层叠加之后，锁冲突基本消失。

5.4 一条完整的排查时间线重演

挑一个有代表性的下午：15:00 前端 Worker 汇报“拿不到设计稿标注”；我先看 Figma MCP 的 server 日志，发现 token 过期；刷新 token 后问题还在，再看 Worker 日志发现 MCP client 连接的是旧地址；检查mcp_config.json发现 config 被某个技能脚本覆盖了；查到覆盖源后，我把配置文件改为只读权限，并增加了启动时的配置校验。整个链路花了 40 分钟，但每一步都在缩小范围。事后我把这次排查整理成了一个技能文档（Skills 里的“MCP 故障排查手册”），下次同类问题只需要 Agent 自己按流程跑一遍。

6. 权限边界与安全护栏：让多智能体集群跑在生产环境的前提

6.1 MCP 服务的最小权限模型

Agent 是非常“听话”的执行者，你给它什么工具，它就会尝试用这个工具完成目标。如果不限制权限，数据库 MCP 就会变成万能数据库客户端，文件 MCP 就会变成整个文件系统的开关。我在生产环境强制实施最小权限模型：

• 数据库 MCP：只启动只读模式，任何写操作必须经过专门授权的写工具，而写工具本身还要二次鉴权；
• 文件系统 MCP：白名单目录，Agent 只能读写指定根目录下的文件；
• 浏览器 MCP：禁止调输入敏感信息的接口，禁止下载可执行文件；
• MCP server 本身用独立的服务账号运行，和宿主系统权限隔离。

每个 MCP server 的权限都要在配置文件里显式声明，默认拒绝、按需开放。

6.2 敏感操作插入人工审批

即便做了最小权限，我仍然不敢把“删表”“发公告”“批量改数据”这类高风险操作完全交给 Agent 自主执行。我在编排层加了一个审批位：当任务被判定为高风险时，任务状态从 Dispatched 跳到 NeedsInput，等待人工确认后才继续。

实现方式不复杂：编排者在派发任务前根据动作清单做一次风险评分，超过阈值就挂起并推送审批请求到内部沟通渠道。这一设计在集群上线初期尤其重要——在没跑出充分信任之前，保留人工兜底是值得的。

6.3 从试点到规模化：建议的演进路线

不要一上来就搭一个二十个 Agent 的庞大集群，我建议先按三条路线演进：第一步选一个最痛、最重复的流程（比如“新接口从表结构到代码生成”），把它做成双 Worker 的最小闭环；第二步把踩过的坑沉淀为技能，逐步丰富技能库；第三步再扩展到广播式、队列式等复杂拓扑。稳定的多智能体集群从来不是一次规划出来的，是“最小闭环跑通 + 经验积累 + 渐进扩张”迭代出来的。

就我个人经验而言，多智能体集群最有价值的地方不在于“把一个任务拆得多碎”，而在于每一步都能被观测、被记录、被复现。DeepAgents、MCP、A2A、Skills 这四个部件合在一起，正好把编排、工具、通信、经验四个维度都补齐了。如果你也在构建自己的多智能体系统，我建议把 70% 的精力放在配置管理、状态可观测和权限治理上，模型调用反而是最简单的一部分。先让一个最小闭环稳定运行一个月，再逐步往外扩，这套架构会越用越顺手。