多Agent协作编排通用方法论
编制：万有AI产品团队
基于：Ahub智慧运营中心系统实战 + HubCoordinator/EventBus/InternalAPI实际代码
一、为什么需要多Agent协作？
单个Agent能力有限，复杂任务需要多个Agent协同完成。但协作不是简单的"把任务扔给多个Agent"——需要编排、通信、容错、成本控制。
多Agent协作是把"一群人"变成"一个团队"的关键。
| 维度 | 无协作 | 有协作 |
|---|---|---|
| 任务处理 | 单Agent处理所有任务 | 按能力分工，专业的人做专业的事 |
| 通信方式 | 无 | 事件驱动+内部API双通道 |
| 容错能力 | 单点故障 | 熔断+降级+备选Agent |
| 成本控制 | 无 | CostGuard预算保护 |
| 编排方式 | 无 | Coordinator统一编排 |
思想源流：从组织分工到Agent协作
多Agent协作方法论站在两个肩膀上：
- 组织学传统：从个体户到公司再到集团，人类组织的答案始终是分工+协作+治理。Agent团队复用同一组织学：能力注册=岗位设置，编排器=管理层，熔断降级=风险预案。
- 分布式系统工程：消息队列、事件驱动、Saga模式、熔断器——微服务时代沉淀的通信与容错模式，本方法论把它们平移到Agent间协作：双通道通信（API总线+EventBus）对应同步调用与异步事件的老搭档。
- AHUB编排实战：HubCoordinator的任务分解→Agent匹配→执行→聚合链路，以及"编排器只协调不执行"的纪律，都从实战返工中萃取。
一句话：多Agent协作的本质，是给AI团队装上组织学与通信协议——Agent会分工还不够，还要会开会。
二、协作架构总览
┌──────────────────────────────────────────────────────────────┐
│ 多Agent协作架构 │
│ │
│ ┌──────────────────────────────────────────────────────────┐│
│ │ HubCoordinator（编排器） ││
│ │ ││
│ │ 任务提交 → 分析分解 → 调度分发 → 执行监控 → 结果聚合 ││
│ │ │ │ │ │ │ ││
│ │ ▼ ▼ ▼ ▼ ▼ ││
│ │ CostGuard SemanticEngine SubTask TraceTracker Result ││
│ │ 预算检查 语义分析 分配 行为追踪 聚合 ││
│ └──────────────────────────────────────────────────────────┘│
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 明察 │ │ 凤鸣 │ │ 璇玑 │ │
│ │ :8001 │ │ :8002 │ │ :8003 │ │
│ │ 独立进程 │ │ 独立进程 │ │ 独立进程 │ │
│ │ mingcha │ │ fengming │ │ xuanji │ │
│ │ Schema │ │ Schema │ │ Schema │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └────────┬────────┴────────┬────────┘ │
│ │ │ │
│ ┌────────▼────────┐ ┌──────▼──────────┐ │
│ │ 内部API总线 │ │ EventBus │ │
│ │ localhost~5ms │ │ Redis Stream │ │
│ │ 编排类通信 │ │ 通知类通信 │ │
│ └─────────────────┘ └─────────────────┘ │
└──────────────────────────────────────────────────────────────┘
三、编排器（HubCoordinator）
3.1 设计原理
编排器是团队的"项目经理"——接收任务、分析分解、调度分发、监控执行、聚合结果。它自己不执行具体操作，只负责协调。
3.2 任务生命周期
PENDING → ANALYZING → DISPATCHING → EXECUTING → AGGREGATING → COMPLETED
│ │
└──→ PAUSED（系统暂停） └──→ FAILED
│ │
└──→ ESCALATED（升级到人类）
| 状态 | 含义 | 触发条件 |
|---|---|---|
| PENDING | 等待处理 | 任务刚提交 |
| ANALYZING | 分析分解 | 语义分析+Agent匹配 |
| DISPATCHING | 调度分发 | 分配SubTask给Agent |
| EXECUTING | 执行中 | Agent执行SubTask |
| AGGREGATING | 结果聚合 | 收集所有SubTask结果 |
| COMPLETED | 完成 | 所有SubTask成功 |
| FAILED | 失败 | 任一关键SubTask失败 |
| ESCALATED | 已升级 | 需要人类介入 |
| PAUSED | 已暂停 | 系统全局暂停 |
3.3 任务分解流程
1. 语义分析：SemanticEngine解析任务描述，提取关键术语
2. Agent匹配：根据术语的domain匹配具备相关能力的Agent
3. 技能匹配：从SkillRegistry查找Agent已注册的技能
4. 原子操作分配：为每个技能分配原子操作（AtomService）
5. 生成SubTask列表
Agent能力注册表（来自SkillRegistry）：
AGENT_CAPABILITIES = {
"mingcha-product": {
"domains": ["product", "user", "feedback"],
"skills": ["competitor-scan", "health-dashboard", "prd-generate"],
"atoms": ["query.get_product_stats", "query.get_user_feedback", "analysis.analyze_health_trend"],
},
"fengming-marketing": {
"domains": ["marketing", "content", "geo"],
"skills": ["geo-ranking", "content-publish", "roi-calculate"],
"atoms": ["query.get_geo_ranking", "analysis.calculate_roi", "action.publish_content"],
},
"xuanji-ip": {
"domains": ["ip", "policy", "filing"],
"skills": ["ip-inventory", "filing-submit", "policy-scan"],
"atoms": ["query.get_ip_inventory", "action.submit_filing"],
},
}
> 💡 技能注册与原子服务的完整设计详见 ⑳Agent技能与原子服务方法论。协作编排是技能的"调度层"，技能是协作编排的"执行层"。
3.4 任务提交前置检查
async def submit_task(self, title, description, priority, initiator, params):
# 1. 全局暂停检查
if GlobalPauseManager.is_paused():
return CoordinatedTask(status=TaskStatus.PAUSED)
# 2. 预算检查
if not await cost_guard.check_before_call(initiator):
return CoordinatedTask(status=TaskStatus.FAILED)
# 3. 创建追踪
trace = trace_tracker.start_trace(task_id, title, initiator)
# 4. 执行任务流程
try:
await self._analyze_and_decompose(task, params)
await self._dispatch_subtasks(task)
await self._execute_subtasks(task)
await self._aggregate_results(task)
except Exception:
task.status = TaskStatus.FAILED
四、双通道通信
4.1 为什么需要双通道？
不同类型的通信有不同的要求：编排类通信需要可靠、同步；通知类通信需要快速、异步。用一种通道无法同时满足两种需求。
| 通道 | 内部API总线 | EventBus |
|---|---|---|
| 协议 | HTTP REST | Redis Stream |
| 延迟 | ~5ms | ~10ms |
| 可靠性 | 请求-响应，确认送达 | 发布-订阅，尽力送达 |
| 适用场景 | 编排类：任务分配、结果获取 | 通知类：状态变更、发现广播 |
| 通信模式 | 同步 | 异步 |
| 示例 | Coordinator→明察：执行分析任务 | 凤鸣→明察：营销数据已更新 |
4.2 内部API总线
每个Agent作为独立进程运行，暴露localhost REST API：
| Agent | 端口 | Schema |
|---|---|---|
| 明察 | :8001 | mingcha |
| 凤鸣 | :8002 | fengming |
| 璇玑 | :8003 | xuanji |
| 天枢 | :8099 | ahub |
| VPA-COO | :8010 | - |
| VPA-CFO | :8011 | - |
| VPA-CLO | :8012 | - |
| VPA-GR | :8013 | - |
4.3 EventBus事件路由
事件类型与Agent的路由映射：
| 事件类型 | 路由目标Agent |
|---|---|
| PRODUCT_HEALTH_CHANGE | 明察 |
| USER_FEEDBACK | 明察 |
| MARKETING_DATA_UPDATE | 凤鸣 |
| GEO_RANKING_CHANGE | 凤鸣 |
| IP_ASSET_UPDATE | 璇玑 |
| FILING_STATUS_CHANGE | 璇玑 |
| COST_ALERT | 明察 |
| QUALITY_ALERT | 明察 |
| AGENT_ERROR | 明察 |
五、熔断器（CircuitBreaker）
5.1 设计原理
当某个Agent频繁失败时，不应该继续向它发送请求，而应该"熔断"——暂时停止调用，给Agent恢复时间。
5.2 三状态模型
成功率正常 失败次数≥阈值
CLOSED ──────────→ 正常运行 ──────────→ OPEN
↑ │
│ │ 超时后
│ 半开探测成功 ▼
└──────── HALF_OPEN ←───────────────────┘
│
│ 半开探测失败
└────────→ OPEN
| 状态 | 含义 | 行为 |
|---|---|---|
| CLOSED | 正常 | 所有请求正常通过 |
| OPEN | 熔断 | 所有请求被拒绝，等待恢复超时 |
| HALF_OPEN | 半开 | 允许少量请求通过，探测Agent是否恢复 |
5.3 参数配置
@dataclass
class CircuitBreaker:
failure_threshold: int = 5 # 连续失败5次触发熔断
recovery_timeout: float = 30.0 # 熔断30秒后进入半开
half_open_max_calls: int = 3 # 半开状态最多允许3次探测
5.4 熔断后的故障接管
熔断器决定"断不断"，但断开后谁来接替工作？信任链（TrustChain）定义了Agent故障时的自动接管顺序。
Agent故障 → 熔断器OPEN → 查找TrustChain → 顺位Agent接管
├── 第1顺位可用 → 接管
└── 第1顺位不可用 → 第2顺位
> 💡 信任链的完整设计（含接管约束、归还规则）详见 ㉓Agent信任等级与交互状态方法论。
六、事件驱动架构
6.1 事件模型
@dataclass
class AhubEvent:
event_type: EventType # 37种事件类型
source: str # 事件来源Agent
payload: Dict[str, Any] # 事件负载
timestamp: str # 事件时间
6.2 事件审计
所有事件都记录到审计日志（PostgreSQL EventModel），支持：
- 按事件类型查询
- 按来源Agent查询
- 批量写入（buffer_size=50，flush_interval=30s）
七、通用方法论总结
7.1 多Agent协作设计五步法
- 定义Agent能力：每个Agent注册自己的domain和atoms
- 设计编排流程：任务提交→分析→调度→执行→聚合
- 选择通信通道：编排类用内部API，通知类用EventBus
- 实现容错机制：熔断器+降级+备选Agent
- 建立成本控制：CostGuard预算保护+Token追踪
7.2 关键设计原则
| 原则 | 说明 | 反模式 |
|---|---|---|
| 编排与执行分离 | Coordinator只协调不执行 | Coordinator自己执行任务 |
| 双通道通信 | 编排类同步，通知类异步 | 所有通信走一种通道 |
| 进程级隔离 | 每个Agent独立进程+独立Schema | 所有Agent共享进程和数据库 |
| 熔断保护 | Agent故障不拖垮整个系统 | Agent故障导致级联失败 |
| 能力注册 | Agent主动注册能力，Coordinator按需调度 | 硬编码调度规则 |
| 事件审计 | 所有事件可追溯 | 事件发出去就不管了 |
7.3 课程化要点
- 多Agent协作概论：从单Agent到多Agent的架构演进
- 编排器实战：任务分解+Agent匹配+结果聚合
- 双通道通信实战：内部API+EventBus的设计与实现
- 熔断器实战：三状态模型+参数调优
- 事件驱动实战：事件定义+路由+审计
- 成本控制实战：CostGuard预算保护机制
八、常见误区
- 编排器既当指挥又当演员：Coordinator自己下场执行任务——编排与执行必须分离，否则调度瓶颈与业务故障耦合。
- 单通道通信：把异步通知塞进请求-响应模型——该用EventBus的走EventBus，同步通道阻塞会传染。
- 没有熔断的乐观架构：假设Agent永远健康——一个Agent故障级联拖垮全局，熔断器三状态+备选Agent接管是标配。
- Agent越多越好：没有治理的扩展是混乱放大器——先有编排、通信、熔断、审计四件套，再扩Agent数量。
- 事件发了就不管：无审计无追踪，故障时无法回溯——所有事件入库可查，这是事件驱动架构的底线。
九、方法论关系（知识乐高）
- Agent能力体系Skill建设方法论（16）：Skill是被编排的最小能力单元——编排器调度的是挂载了Skill的Agent
- Agent状态管理与容错方法论（25）：熔断器三状态模型的技术底座，本方法论5.3参数配置直接引用
- Agent后台意识机制方法论（19）：闲时利用——熔断降级省下的资源交给后台意识做健康检查与记忆巩固
- 创建第一个AI联合创始人方法论（10）：从单Agent到多Agent的扩展路径——第一个联合创始人站稳了，才谈"生子"与"家族"
- 万有因缘与创业八步实操法（44）："和"字诀的工程版——不同Agent相互辅助、有机整合，协作编排就是让"和"落地为"合"