企业官网建设流程全解析

1. 多 Agent 协作到底在解决什么问题

1.1 从单兵作战到团队配合的必然转变

先说一个我自己的真实经历。去年我接手了一个需求，要在一周内完成一个包含数据清洗、特征工程、模型训练、报告生成和可视化看板的完整项目。如果按传统方式，我一个人从头写到尾，光是调试数据管道就能耗掉三天。后来我尝试把这套流程拆成四个独立的 Agent 来跑——一个专门负责数据清洗，一个负责特征工程，一个负责模型训练和评估，最后一个负责生成报告和图表。结果三天就交付了，而且每个环节的质量比我一个人硬扛还要稳定。

这就是多 Agent 协作最朴素的价值：把复杂任务拆解成多个独立但互相配合的执行单元，每个单元专注做好一件事，通过明确的交接协议串联起来。

很多人第一次听到“多 Agent 协作”会觉得这是个很玄的概念，其实你完全可以把它理解成一个小型软件团队。团队里有前端、后端、测试、产品，每个人有自己的职责边界，有明确的输入和输出，有约定的沟通方式。多 Agent 系统也是一样的道理，只不过团队成员从人变成了 AI 实例。

1.2 什么场景下真的需要多 Agent

不是所有任务都值得上多 Agent。我踩过的坑告诉我，下面这几类场景才是多 Agent 真正能发挥价值的地方：

• 任务链路长且环节异构：比如从原始数据到最终报告，中间要经过清洗、分析、建模、写作等多个性质完全不同的阶段。用一个 Agent 从头做到尾，它很容易在某个环节“忘记”前面的约束，或者在风格上前后不一致。
• 需要多视角交叉验证：比如代码审查场景，一个 Agent 写代码，另一个 Agent 专门挑毛病，第三个 Agent 负责跑测试。这种“对抗式”协作能显著降低错误率。
• 单次上下文窗口不够用：当任务涉及大量文档、代码库或数据集时，单个 Agent 的上下文很容易被撑爆。拆成多个 Agent 后，每个 Agent 只加载自己需要的那部分信息，效率反而更高。
• 需要并行加速：有些子任务之间没有依赖关系，比如同时生成多个模块的文档、同时测试多个接口。多 Agent 并行跑，时间能压缩到原来的几分之一。

反过来，如果你的任务就是“帮我写一段正则表达式”或者“解释一下这个报错”，那完全没必要上多 Agent，单个 Agent 甚至直接问搜索引擎更快。工具选型的第一原则永远是：够用就好，别为了炫技而过度设计。

1.3 多 Agent 协作的核心挑战

多 Agent 听起来很美，但真正落地时会遇到几个非常现实的问题：

第一个是上下文传递。Agent A 做完数据清洗后，怎么把结果和必要的元信息传给 Agent B？如果传得太多，B 的上下文被撑爆；如果传得太少，B 缺少关键信息导致输出质量下降。这个平衡点需要反复调试。

第二个是职责边界模糊。我见过很多失败的多 Agent 项目，根本原因就是两个 Agent 的职责有重叠，导致互相“踢皮球”或者重复劳动。比如一个 Agent 负责“分析数据”，另一个负责“生成洞察”，这两个职责在实际操作中很难划清界限。

第三个是错误传播。如果 Agent A 的输出有错误，Agent B 基于错误输入继续工作，错误会被逐级放大，到最后你拿到一份看起来完整但完全不可信的结果。所以多 Agent 系统里必须有校验和回滚机制。

第四个是协调开销。Agent 之间通信本身也要消耗资源和时间。如果拆得太细，协调开销可能超过任务本身的收益。我一般建议初次尝试时控制在 3 到 5 个 Agent 之间，跑通后再根据实际瓶颈决定是否继续拆分。

理解了这些挑战，接下来我们进入具体的方案设计。

2. 多 Agent 协作的整体架构设计

2.1 三种主流协作模式及选型依据

在实际项目中，我总结出三种最常用的多 Agent 协作模式，每种模式适合不同的任务类型。

第一种是流水线模式（Pipeline）。Agent 按顺序排列，前一个的输出是后一个的输入，像工厂流水线一样。这种模式最适合任务链路清晰、阶段划分明确的场景，比如“数据清洗 → 特征工程 → 模型训练 → 报告生成”。优点是逻辑简单、易于调试；缺点是如果中间某个环节出错，整个链路都要重跑。

第二种是主从模式（Orchestrator-Worker）。有一个“主 Agent”负责拆解任务、分配工作、汇总结果，多个“从 Agent”各自执行子任务。这种模式适合任务可以并行拆分的场景，比如同时生成多个模块的代码。主 Agent 相当于项目经理，从 Agent 相当于执行者。优点是并行效率高；缺点是主 Agent 的调度逻辑需要精心设计，否则容易成为瓶颈。

第三种是辩论模式（Debate）。多个 Agent 对同一个问题给出各自的答案，然后通过交叉评审或投票选出最优解。这种模式适合需要高质量决策的场景，比如代码审查、方案评审。优点是能显著降低单点错误；缺点是资源消耗成倍增加。

我个人的选型经验是这样的：

对于大多数初次尝试多 Agent 的团队，我强烈建议从流水线模式开始。它的心智负担最小，调试起来最直观，而且能覆盖大部分实际需求。

2.2 为什么我选择 Handoff 作为核心交接机制

在多 Agent 协作中，Agent 之间的“交接”是最关键的环节。我试过几种不同的交接方式，最后稳定在Handoff机制上。

Handoff 的核心思想很简单：当前 Agent 完成自己的任务后，不是直接把原始输出丢给下一个 Agent，而是生成一份结构化的“交接文档”，包含任务摘要、关键决策、未解决问题和下一步建议。下一个 Agent 拿到这份文档后，能快速理解上下文，而不需要重新阅读所有原始材料。

我举个例子说明为什么 Handoff 比直接传递原始输出更好。假设 Agent A 负责数据清洗，它处理了 10 万条数据，删除了 3000 条异常值，填充了 500 个缺失值。如果直接把清洗后的数据丢给 Agent B，B 完全不知道中间发生了什么，可能会对某些数据分布感到困惑。但如果 A 生成一份 Handoff 文档，写明“删除了 3000 条异常值，原因是超出 3 倍标准差；填充了 500 个缺失值，使用中位数填充”，B 就能在理解数据来源的基础上继续工作。

Handoff 文档我一般要求包含以下几个字段：

• 任务摘要：用两三句话说明这个环节做了什么。
• 关键决策：列出所有影响后续环节的重要选择，以及选择理由。
• 输出物清单：明确列出传递给下一个 Agent 的文件、数据或代码。
• 未解决问题：如果有遗留问题，明确标注出来，提醒下游 Agent 注意。
• 下一步建议：基于当前进展，给下一个 Agent 提供行动建议。

这套机制看起来增加了额外工作，但实际跑下来，它节省的沟通成本远远超过生成文档的成本。尤其是在多轮迭代中，Handoff 文档就是整个系统的“记忆”，能有效防止上下文丢失。

2.3 AGENTS.md：让协作规则可配置、可复用

多 Agent 系统跑起来后，最大的痛点之一是规则散落在各个 Agent 的提示词里，改一处要改好几处，而且容易漏改。后来我引入了AGENTS.md文件来集中管理协作规则。

AGENTS.md本质上是一个配置文件，里面定义了每个 Agent 的角色、职责、输入输出格式、交接规则和约束条件。所有 Agent 在启动时都会读取这个文件，确保大家对规则的理解是一致的。

我通常把AGENTS.md分成几个区块：

# AGENTS.md ## 全局规则 - 所有 Agent 输出必须使用 Markdown 格式 - 所有 Agent 必须在输出末尾附上 Handoff 文档 - 任何 Agent 发现上游输入有问题，必须立即中止并报告 ## Agent 定义 ### Agent A: 数据清洗 - 职责：读取原始数据，处理缺失值、异常值和重复值 - 输入：raw_data.csv - 输出：cleaned_data.csv + handoff_a.md - 约束：不得修改原始数据文件 ### Agent B: 特征工程 - 职责：基于清洗后的数据生成特征 - 输入：cleaned_data.csv + handoff_a.md - 输出：features.csv + handoff_b.md - 约束：必须记录每个特征的生成逻辑 ## 交接规则 - 上游 Agent 必须在 Handoff 文档中明确标注输出物的路径和格式 - 下游 Agent 在开始工作前必须验证输入物的完整性和格式 - 如果验证失败，下游 Agent 必须回退给上游 Agent 并说明原因

有了这个文件，整个系统的规则就变得透明且可维护。新增一个 Agent 时，只需要在AGENTS.md里加一段定义，其他 Agent 不需要做任何修改。这比把规则硬编码在每个 Agent 的提示词里要优雅得多。

2.4 上下文变量的设计与传递

多 Agent 协作中，上下文变量的设计直接决定了系统的稳定性和效率。我一般把上下文变量分成三类：

第一类是全局变量，比如项目名称、目标描述、输出目录、时间戳。这些变量在所有 Agent 之间共享，每个 Agent 都能读取，但只有主 Agent 有权限修改。

第二类是阶段变量，比如当前处理的数据文件路径、上一步的统计摘要、中间产物的版本号。这些变量随着任务推进而更新，每个 Agent 完成工作后负责更新自己相关的部分。

第三类是局部变量，只在单个 Agent 内部使用，比如临时文件路径、调试信息、中间计算结果。这些变量不参与交接，任务完成后自动清理。

我踩过的一个坑是：早期我把所有变量都放在一个全局字典里，结果 Agent 之间互相覆盖，导致数据错乱。后来改成分类管理后，问题就消失了。上下文变量管理的核心原则是：谁产生，谁负责；谁修改，谁记录。

3. 核心 Skill 的设计与实现细节

3.1 什么是 Skill，为什么它比普通提示词更强

在多 Agent 系统里，Skill 是我用来封装“可复用能力”的基本单元。你可以把它理解成一个函数：有明确的输入、有确定的处理逻辑、有规范的输出。和普通提示词相比，Skill 有几个显著优势：

• 可复用：同一个 Skill 可以被多个 Agent 调用，不需要重复编写提示词。
• 可测试：Skill 的输入输出是明确的，可以单独写测试用例验证。
• 可组合：多个 Skill 可以串联或并联，形成更复杂的能力。
• 可版本管理：Skill 可以像代码一样进行版本控制，方便追踪变更。

我目前维护的 Skill 库里有几十个常用 Skill，覆盖了数据读取、格式转换、代码生成、质量检查、报告撰写等常见需求。每次启动新项目时，我只需要从库里挑选合适的 Skill 组合起来，就能快速搭建出一个可用的多 Agent 系统。

3.2 一个强大协作 Skill 的完整结构

下面我以一个实际在用的“协作调度 Skill”为例，拆解它的完整结构。这个 Skill 的作用是：接收一个任务描述，自动拆解成子任务，分配给对应的 Agent，并管理整个执行流程。

name: collaboration-orchestrator version: 2.3.0 description: 多 Agent 协作调度 Skill，负责任务拆解、分配、监控和结果汇总 inputs: - name: task_description type: string required: true description: 待完成的任务描述 - name: available_agents type: list required: true description: 可用 Agent 列表及其能力描述 - name: max_rounds type: integer default: 5 description: 最大迭代轮数 outputs: - name: final_result type: string description: 最终汇总结果 - name: execution_log type: object description: 完整执行日志，包含每轮的任务分配和结果 steps: - name: analyze_task action: 分析任务描述，识别关键环节和依赖关系 - name: decompose action: 将任务拆解成子任务，标注每个子任务的输入输出 - name: assign action: 根据 Agent 能力匹配子任务 - name: execute action: 按依赖顺序执行子任务，收集结果 - name: validate action: 校验每个子任务的输出质量 - name: aggregate action: 汇总所有子任务结果，生成最终输出 constraints: - 每个子任务必须有明确的验收标准 - 如果某个子任务失败，最多重试 2 次 - 如果重试后仍失败，记录问题并继续执行不依赖该子任务的部分

这个 Skill 的设计有几个关键点值得说明：

第一，输入输出明确。每个字段都有类型和描述，调用方不需要猜测怎么传参。

第二，步骤可追踪。每个步骤都有名字和动作描述，执行过程中可以精确知道当前进行到哪一步。

第三，约束条件清晰。什么情况下重试、什么情况下跳过、什么情况下中止，都有明确规定。

第四，版本化管理。version字段让我能追踪 Skill 的演进历史，出问题时可以快速回滚到上一个稳定版本。

3.3 Skill 的注册、发现与调用机制

Skill 写好后，需要一套机制让 Agent 能够发现并调用它。我采用的是“注册中心 + 按需加载”的方案。

注册中心本质上是一个索引文件，记录了所有可用 Skill 的名称、版本、描述和入口路径。Agent 启动时，先读取注册中心，了解当前有哪些 Skill 可用。当 Agent 需要某个能力时，根据描述匹配到对应的 Skill，然后加载并调用。

{ "skills": [ { "name": "collaboration-orchestrator", "version": "2.3.0", "path": "./skills/orchestrator", "tags": ["协作", "调度", "任务拆解"] }, { "name": "data-cleaner", "version": "1.5.2", "path": "./skills/data-cleaner", "tags": ["数据", "清洗", "预处理"] }, { "name": "report-generator", "version": "3.1.0", "path": "./skills/report-generator", "tags": ["报告", "写作", "汇总"] } ] }

这种设计的好处是解耦。Agent 不需要硬编码任何 Skill 的路径，只需要根据标签或描述来匹配。新增 Skill 时，只需要在注册中心加一条记录，所有 Agent 都能立即发现并使用它。

我踩过的一个坑是：早期我把 Skill 的调用逻辑直接写在 Agent 的提示词里，结果每次新增 Skill 都要修改所有 Agent 的提示词，维护成本极高。改成注册中心机制后，这个问题彻底解决了。

3.4 协作 Skill 中的错误处理与重试策略

多 Agent 系统跑起来后，错误是常态而不是例外。我的协作 Skill 里内置了一套分层的错误处理策略：

第一层是输入校验。每个 Skill 在执行前，先校验输入是否符合预期格式。如果不符合，立即返回错误，不进入实际处理逻辑。这能拦截掉大部分低级错误。

第二层是执行监控。Skill 执行过程中，记录关键节点的状态。如果某个步骤超时或返回异常，立即中止并记录现场信息。

第三层是重试机制。对于可恢复的错误（比如网络超时、临时资源不足），自动重试最多 2 次。重试时适当调整参数，比如增加超时时间或降低并发数。

第四层是降级处理。如果重试后仍然失败，根据预设的降级策略处理。比如某个数据源不可用，就使用缓存数据；某个 Agent 不可用，就把它的任务分配给备用 Agent。

第五层是人工介入。如果所有自动处理都失败，系统会生成一份详细的错误报告，包含失败环节、错误信息、已尝试的解决方案和建议的人工处理步骤。

这套分层策略的核心思想是：能自动恢复的自动恢复，不能自动恢复的优雅降级，实在不行才找人。实际跑下来，90% 以上的错误都能在前三层解决，需要人工介入的情况很少。

4. 完整实操流程：从零搭建一个多 Agent 协作系统

4.1 环境准备与目录结构规划

在开始搭建之前，先把目录结构规划好。我一般用这样的结构：

project/ ├── AGENTS.md # 协作规则配置 ├── skills/ # Skill 库 │ ├── registry.json # Skill 注册中心 │ ├── orchestrator/ # 协作调度 Skill │ ├──># Agent A: 数据准备者 ## 角色 你是一个数据准备专家，负责将原始数据转化为可供分析使用的干净数据集。 ## 职责 - 读取原始数据文件 - 处理缺失值、异常值和重复值 - 统一数据格式和编码 - 生成数据质量报告 ## 输入 - 原始数据文件路径 - 数据字典（如果有） ## 输出 - 清洗后的数据文件 - 数据质量报告 - Handoff 文档 ## 约束 - 不得修改原始数据文件 - 所有清洗操作必须记录在 Handoff 文档中 - 如果数据质量问题超过阈值，必须中止并报告 ## 交接规则 完成工作后，生成 handoff_a.md，包含： - 任务摘要 - 关键决策及理由 - 输出物清单 - 未解决问题 - 对 Agent B 的建议

这种定义方式的好处是边界清晰。每个 Agent 知道自己该做什么、不该做什么、做到什么程度算完成。实际跑下来，职责边界清晰的系统，出错率比模糊定义的系统低很多。

4.3 编写协作 Skill 的完整代码

下面是一个简化版的协作调度 Skill 的核心代码，用 Python 实现：

import json import yaml from pathlib import Path from datetime import datetime class CollaborationOrchestrator: def __init__(self, config_path, registry_path): self.config = yaml.safe_load(Path(config_path).read_text()) self.registry = json.loads(Path(registry_path).read_text()) self.execution_log = [] self.handoffs = {} def analyze_task(self, task_description): """分析任务，识别关键环节""" # 实际实现中，这里会调用 LLM 做任务分析 # 简化版：根据关键词匹配 stages = [] if "数据" in task_description or "清洗" in task_description: stages.append("data_preparation") if "分析" in task_description or "统计" in task_description: stages.append("analysis") if "报告" in task_description or "汇总" in task_description: stages.append("reporting") return stages def decompose(self, task_description, stages): """将任务拆解成子任务""" subtasks = [] for i, stage in enumerate(stages): subtask = { "id": f"task_{i+1}", "stage": stage, "description": f"执行 {stage} 阶段的工作", "depends_on": [f"task_{i}"] if i > 0 else [], "status": "pending" } subtasks.append(subtask) return subtasks def assign(self, subtasks): """根据 Agent 能力匹配子任务""" agent_mapping = { "data_preparation": "agent_a", "analysis": "agent_b", "reporting": "agent_c" } for subtask in subtasks: subtask["assigned_to"] = agent_mapping.get(subtask["stage"], "unknown") return subtasks def execute(self, subtasks): """按依赖顺序执行子任务""" completed = set() max_rounds = self.config.get("max_rounds", 5) for round_num in range(max_rounds): progress = False for subtask in subtasks: if subtask["status"] != "pending": continue if not all(dep in completed for dep in subtask["depends_on"]): continue # 执行子任务 result = self._run_subtask(subtask) subtask["status"] = "completed" if result["success"] else "failed" subtask["result"] = result if result["success"]: completed.add(subtask["id"]) self.handoffs[subtask["id"]] = result.get("handoff", {}) else: # 重试逻辑 if subtask.get("retry_count", 0) < 2: subtask["retry_count"] = subtask.get("retry_count", 0) + 1 subtask["status"] = "pending" progress = True self._log(subtask) if not progress: break return subtasks def _run_subtask(self, subtask): """实际执行子任务，这里需要接入具体的 Agent 调用""" # 简化版：返回模拟结果 return { "success": True, "output": f"{subtask['stage']} 完成", "handoff": { "task_id": subtask["id"], "summary": f"完成 {subtask['stage']} 阶段", "timestamp": datetime.now().isoformat() } } def validate(self, subtasks): """校验子任务输出质量""" issues = [] for subtask in subtasks: if subtask["status"] != "completed": issues.append(f"{subtask['id']} 未完成") elif not subtask.get("result", {}).get("output"): issues.append(f"{subtask['id']} 输出为空") return issues def aggregate(self, subtasks): """汇总所有子任务结果""" final_result = { "task_summary": "多 Agent 协作任务完成", "subtask_results": [ { "id": s["id"], "stage": s["stage"], "status": s["status"], "output": s.get("result", {}).get("output", "") } for s in subtasks ], "handoffs": self.handoffs, "execution_log": self.execution_log } return final_result def _log(self, subtask): """记录执行日志""" self.execution_log.append({ "timestamp": datetime.now().isoformat(), "task_id": subtask["id"], "stage": subtask["stage"], "status": subtask["status"], "assigned_to": subtask.get("assigned_to") }) def run(self, task_description): """完整执行流程""" stages = self.analyze_task(task_description) subtasks = self.decompose(task_description, stages) subtasks = self.assign(subtasks) subtasks = self.execute(subtasks) issues = self.validate(subtasks) result = self.aggregate(subtasks) result["issues"] = issues return result

这段代码的核心逻辑是：分析 → 拆解 → 分配 → 执行 → 校验 → 汇总。每一步都有明确的输入输出，方便调试和扩展。

实际使用时，_run_subtask方法需要接入真实的 Agent 调用逻辑。我一般会在这里调用 LLM API，把 Agent 的提示词和当前上下文传进去，拿到输出后再解析成结构化结果。

4.4 运行、监控与结果验证

系统跑起来后，监控是必不可少的。我一般关注几个关键指标：

• 每个子任务的执行时间：如果某个子任务耗时异常，说明可能遇到了问题。
• 重试次数：重试次数过多说明输入质量或 Skill 逻辑有问题。
• Handoff 文档的完整性：如果 Handoff 文档缺少关键字段，下游 Agent 会受影响。
• 最终输出的质量：这是最直观的指标，可以通过人工抽检或自动校验来评估。

我通常会在logs/目录下生成一份详细的执行日志，格式如下：

{ "run_id": "20250115_143022", "task": "生成一份销售数据分析报告", "start_time": "2025-01-15T14:30:22", "end_time": "2025-01-15T14:35:47", "total_duration_seconds": 325, "subtasks": [ { "id": "task_1", "stage": "data_preparation", "status": "completed", "duration_seconds": 120, "retry_count": 0 }, { "id": "task_2", "stage": "analysis", "status": "completed", "duration_seconds": 150, "retry_count": 1 }, { "id": "task_3", "stage": "reporting", "status": "completed", "duration_seconds": 55, "retry_count": 0 } ], "issues": [] }

有了这份日志，出问题时可以快速定位到具体环节。比如上面这个例子，task_2重试了一次，说明分析阶段可能遇到了数据格式问题，下次可以针对性优化。

5. 常见问题与排查技巧实录

5.1 Agent 之间上下文丢失怎么办

这是多 Agent 系统里最常见的问题。表现是：下游 Agent 的输出明显偏离了上游的意图，或者重复问了上游已经解决的问题。

根本原因通常是 Handoff 文档写得太简略，或者关键信息没有结构化地传递。我踩过的一个典型坑是：Agent A 在清洗数据时删除了某列，但没有在 Handoff 文档里说明，结果 Agent B 在分析时找不到这列，直接报错。

解决方案是强制要求 Handoff 文档包含“变更清单”字段，明确列出所有对数据的修改操作。同时，下游 Agent 在开始工作前，必须先校验输入物是否符合预期，如果不符合，立即回退并说明原因。

我现在的做法是在AGENTS.md里加一条硬性规则：

任何 Agent 在修改输入数据后，必须在 Handoff 文档的“变更清单”中逐条记录修改内容、修改原因和影响范围。下游 Agent 在开始工作前必须核对变更清单，确认无误后才能继续。

这条规则加上后，上下文丢失的问题减少了 80% 以上。

5.2 任务拆解粒度怎么把握

拆得太粗，单个 Agent 负担过重，容易出错；拆得太细，协调开销超过任务本身。我的一般原则是：

• 每个子任务的执行时间控制在 1 到 5 分钟之间。太短说明拆得过细，太长说明还可以继续拆。
• 每个子任务有明确的验收标准。如果说不清楚“做到什么程度算完成”，说明拆解还不够清晰。
• 子任务之间的依赖关系尽量简单。如果依赖关系复杂到需要画图才能理清，说明拆解方式有问题，应该重新设计。

我通常先用粗粒度拆解跑一遍，观察哪个环节耗时最长或出错最多，然后针对性地细化那个环节。这种“先跑通再优化”的方式比一开始就追求完美拆解要高效得多。

5.3 Skill 调用失败的排查思路

Skill 调用失败时，我一般按这个顺序排查：

第一步，检查输入格式。90% 的失败都是输入格式不对导致的。用jsonschema之类的工具做严格校验，能拦截掉大部分问题。

第二步，检查依赖资源。Skill 依赖的文件、API、数据库是否可用？我遇到过好几次因为临时文件被清理导致 Skill 失败的情况，后来加了资源检查步骤就解决了。

第三步，检查权限。Skill 是否有权限读写目标文件？是否有权限调用外部服务？权限问题在多 Agent 系统里很常见，因为不同 Agent 可能运行在不同的权限上下文中。

第四步，查看详细日志。如果前三步都没问题，就需要看 Skill 内部的执行日志了。我一般会在 Skill 的关键节点打日志，方便定位问题。

下面是我整理的一份常见问题速查表：

5.4 多 Agent 系统的性能优化经验

系统跑通后，下一步就是优化性能。我总结了几条实用的优化经验：

第一，并行化无依赖的子任务。如果两个子任务之间没有依赖关系，就让它们并行跑。我用asyncio实现并行调度，实测下来能把总耗时压缩 40% 左右。

第二，缓存重复计算的结果。有些 Skill 的输出是确定性的，同样的输入总是得到同样的输出。这类 Skill 的结果可以缓存起来，下次遇到相同输入时直接返回缓存结果。

第三，精简 Handoff 文档。Handoff 文档不是越详细越好，关键是传递“下游需要知道的信息”。我一般控制在 500 字以内，超过这个长度就说明可能包含了冗余信息。

第四，合理设置超时时间。超时时间太短会导致正常任务被误杀，太长会导致问题任务拖慢整个系统。我一般根据历史执行时间的 P95 值来设置，留出 20% 的余量。

第五，定期清理中间产物。多 Agent 系统跑久了，workspace/intermediate/目录会积累大量临时文件。我一般设置一个定时任务，每天清理超过 7 天的中间产物，避免磁盘空间被占满。

5.5 从单 Agent 迁移到多 Agent 的注意事项

如果你现在用的是单 Agent，想迁移到多 Agent，我建议按这个顺序来：

第一步，先梳理现有流程。把单 Agent 做的事情拆解成清晰的步骤，标注每步的输入输出。这一步不需要写代码，用纸笔或者流程图工具就行。

第二步，识别可独立拆分的环节。哪些环节是相对独立的？哪些环节之间有强依赖？优先拆分独立环节。

第三步，先拆一个环节试试。不要一次性全拆，先拆一个环节，跑通后再拆下一个。这样风险可控，出问题也容易回滚。

第四步，建立 Handoff 机制。在拆分之前，先把 Handoff 文档的格式和规则定好。这是多 Agent 协作的基础设施，必须先建好。

第五步，逐步替换。每次替换一个环节，观察一段时间，确认稳定后再替换下一个。全部替换完成后，再考虑优化整体性能。

我自己的经验是：从单 Agent 迁移到多 Agent，最大的挑战不是技术，而是思维方式的转变。你需要从“一个 Agent 做所有事”转变为“多个 Agent 各司其职、互相配合”。这个转变需要时间，但只要跑通第一个多 Agent 项目，后面的路就顺了。

6. 多 Agent 协作的扩展方向与个人体会

6.1 从固定流程到动态编排

目前我用的多 Agent 系统还是以固定流程为主，任务拆解和 Agent 分配都是预先定义好的。下一步我想尝试的是动态编排：根据任务的实际特点，自动决定拆解方式和 Agent 组合。

比如同样是数据分析任务，如果数据量小，可能只需要两个 Agent；如果数据量大且复杂，可能需要五个 Agent。动态编排的核心是让系统具备“元认知”能力，能够评估任务难度并做出相应的资源分配决策。

我目前的想法是引入一个“评估 Agent”，专门负责任务难度评估和资源规划。它不直接执行任务，而是为其他 Agent 提供调度建议。这个思路还在验证中，等跑通了再单独写一篇分享。

6.2 多 Agent 系统的可观测性建设

系统越复杂，可观测性越重要。我现在正在完善的是多 Agent 系统的监控面板，希望能实时看到每个 Agent 的状态、每个子任务的进度、每个 Skill 的调用情况。

可观测性建设我分三个层次：

• 日志层：记录所有关键事件，包括 Agent 启动、任务分配、Skill 调用、错误发生等。
• 指标层：统计关键指标，比如任务完成率、平均执行时间、重试率、错误率等。
• 追踪层：追踪单个任务的完整执行链路，从任务创建到最终输出，中间经过了哪些 Agent、哪些 Skill、哪些决策。

这三个层次建好后，排查问题会变得非常高效。以前需要翻半天日志才能定位的问题，现在在面板上扫一眼就能发现异常。

6.3 我踩过的三个大坑

第一个坑是过度设计。刚开始做多 Agent 时，我设计了七个 Agent，每个 Agent 负责一个非常细的环节。结果协调开销巨大，系统跑起来比单 Agent 还慢。后来砍到三个 Agent，效率反而提升了。教训是：Agent 数量不是越多越好，够用就行。

第二个坑是忽视 Handoff 文档的质量。早期我觉得 Handoff 文档就是走个形式，随便写写就行。结果下游 Agent 经常因为缺少关键信息而输出错误结果。后来我把 Handoff 文档的质量纳入验收标准，问题才解决。教训是：Handoff 文档是多 Agent 系统的生命线，必须认真对待。

第三个坑是没有回滚机制。有一次 Agent B 的输出有问题，但系统没有检测到，继续往下跑，最后生成了一份完全错误的报告。后来我加了校验和回滚机制，任何环节发现问题都能立即中止并回退到上一个稳定状态。教训是：多 Agent 系统必须有容错和回滚能力，否则错误会逐级放大。

6.4 给初次尝试者的实用建议

如果你正准备尝试多 Agent 协作，我最后分享几条实用建议：

从简单任务开始。不要一上来就挑战复杂项目，先找一个两三个环节的小任务跑通流程。跑通后再逐步增加复杂度。

先把 Handoff 机制建好。这是多 Agent 协作的基础设施，不要等到出问题了才想起来补。我一般建议在写第一个 Agent 之前，就把 Handoff 文档的模板和规则定好。

控制 Agent 数量。初次尝试建议控制在 3 个以内，跑通后再根据实际需要增加。Agent 越多，协调开销越大，出问题的概率也越高。

重视日志和监控。多 Agent 系统的调试比单 Agent 复杂得多，没有完善的日志和监控，排查问题会非常痛苦。

保持耐心。多 Agent 协作不是一蹴而就的，需要反复调试和优化。我自己的第一个多 Agent 项目跑了整整两周才稳定下来，但稳定之后，效率提升是实实在在的。

这套多 Agent 协作方案我目前已经在三个实际项目中落地使用，最长的跑了半年多，整体稳定性不错。当然，它肯定不是唯一正确的方案，不同团队、不同场景可能需要不同的设计。关键是理解背后的核心原理，然后根据自己的实际情况灵活调整。