多 Agent 系统最容易出现的假繁荣是：角色很多、对话很长、Demo 很热闹，但结果不可复现、任务不收敛、失败后只能重来。工程目标不是“让多个模型聊天”，而是稳定地产出经过验证的工件。
一、三个常见误区
- 把角色提示词当架构：“产品经理 Agent、架构师 Agent、开发 Agent”只是名称，没有输入输出契约。
- 让所有 Agent 共享完整对话：上下文越来越长，冲突信息和无关历史持续污染决策。
- 只让模型判断完成：模型说“代码已完成”不能替代编译、测试、静态检查和验收用例。
二、用任务图而不是群聊组织协作
把目标拆成有依赖关系的任务图：需求澄清 → 方案设计 → 代码变更 → 测试 → Review → 发布说明。每个节点定义负责人、输入工件、输出 schema、工具权限、完成条件和失败策略。
TaskNode {
id
objective
dependencies[]
input_artifacts[]
output_schema
allowed_tools[]
acceptance_checks[]
retry_policy
}协调器只负责状态推进和路由，不应该亲自完成所有推理。专业 Agent 读取最小必要上下文，产出结构化结果；验证器根据客观证据决定是否进入下一节点。
三、共享的是状态与证据，不是无限对话
推荐把上下文分成四层：
- 目标层：用户目标、范围和不可违反的约束。
- 计划层：任务图、依赖、当前状态和风险。
- 工件层：需求文档、设计、代码 diff、测试报告。
- 记忆层：长期稳定的项目约定和历史决策。
每个结论都应尽量附带证据引用，例如文件路径、代码行、测试输出或文档段落。这样 Reviewer 可以验证，而不是相信另一个模型的自然语言总结。
四、质量门禁：把“完成”改成“通过检查”
| 阶段 | 机器门禁 | 模型门禁 |
|---|---|---|
| 需求 | 字段完整、约束无冲突 | 场景与边界是否覆盖 |
| 设计 | 接口 schema、依赖检查 | 取舍是否合理 |
| 编码 | 编译、Lint、类型检查 | 可维护性与风险 Review |
| 测试 | 单测、集成测试、覆盖率 | 是否遗漏关键场景 |
| 发布 | 变更清单、回滚脚本 | 说明是否清晰 |
模型擅长发现语义风险，工具擅长给出确定结果。两者需要组合：先运行工具，再把结构化输出交给 Reviewer，而不是让 Reviewer 猜代码能否运行。
五、失败恢复：让系统从检查点继续
每个任务节点完成后保存输入、输出、工具调用摘要和检查结果。失败时根据类型处理：工具暂时失败可重试；输出不满足 schema 让原 Agent 修复；方案冲突回退到上游节点；预算耗尽或连续失败进入人工接管。
if tool_error.retryable:
retry_with_backoff()
elif validation_failed:
send_feedback_to_owner_agent()
elif upstream_assumption_invalid:
reopen_dependency_node()
else:
escalate_with_evidence_bundle()为了防止循环，需要设置节点最大尝试次数、全局 token/时间预算、重复结论检测和终止条件。真正的“收敛”来自有限状态和明确验收，而不是提示词里写一句“请务必完成”。
最小可行实现：先从单协调器 + 3 个角色开始：Planner 生成任务图，Worker 执行工具，Reviewer 基于测试证据验收。等状态、工件和门禁稳定后，再扩展专业 Agent。
多 Agent 的价值不是模拟一个组织，而是把复杂工作拆成可追踪、可验证、可恢复的流水线。