Swarm 多智能体协作

什么是 Swarm 模式？

Swarm 模式部署多个持久化的自主智能体，它们并行工作以解决复杂任务。一个由 LLM 驱动的 Lead Agent 动态协调团队——规划任务、生成智能体、重新分配工作，并基于实时事件做出决策。与静态编排（任务预先分解且不会改变）不同，Lead Agent 持续监控进度并动态适应：创建新任务、取消冗余工作、在情况变化时重新分配空闲智能体。

工作原理

Shannon 的 Swarm 工作流由事件驱动的 Lead Agent 循环驱动：

Lead Agent 事件循环

Lead Agent 在特定事件触发时唤醒，并决定下一步操作：

唤醒 Lead 的事件:
├── agent_idle       — 智能体完成当前任务或变为可用状态
├── agent_completed  — 智能体产出最终输出
├── help_request     — 智能体请求 Lead 生成辅助智能体
├── checkpoint       — 定期计时器（每 120 秒）审查整体进度
└── human_input      — 用户在执行过程中发送新指令

每次唤醒时，Lead 接收完整的团队状态（智能体、任务、预算），并选择一个或多个行动。

生命周期概览

初始规划 — Lead 接收用户查询并创建一组初始任务，可选择性地设置依赖链
智能体生成 — Lead 生成智能体并分配任务，遵循依赖顺序
事件驱动协调 — 当智能体完成工作、报告空闲或到达检查点时，Lead 动态重新分配任务、修订计划或生成新智能体
综合 — 当所有任务完成时，Lead 可以生成专用的综合智能体或声明 done 以产出最终响应

任务依赖 (DAG)

任务可以声明对其他任务的依赖，形成有向无环图（DAG）：

任务:
├── task-1: "研究美国 AI 芯片市场"              (depends_on: [])
├── task-2: "研究日本 AI 芯片市场"              (depends_on: [])
├── task-3: "研究韩国 AI 芯片市场"              (depends_on: [])
└── task-4: "撰写对比分析报告"                   (depends_on: [task-1, task-2, task-3])

系统强制执行依赖顺序——task-4 在三个研究任务全部完成之前无法被分配。Lead 可以通过 revise_plan 动态创建新的依赖链。

Lead Agent 行动

每次 Lead 唤醒时，它选择一个或多个行动：

行动	描述
`spawn_agent`	为特定任务创建新智能体
`assign_task`	将待处理任务分配给空闲智能体
`revise_plan`	动态创建新任务或取消现有任务
`send_message`	向特定智能体发送消息
`broadcast`	向所有智能体广播消息
`file_read`	读取工作区文件（零 LLM 成本，最多 3 轮）
`shutdown_agent`	终止特定智能体
`interim_reply`	向用户推送进度更新
`noop`	不执行操作（当前无需行动）
`done`	声明所有工作完成，进入关闭阶段
`reply`	直接向用户返回最终回复（仅在关闭阶段使用）
`synthesize`	触发合成流水线而非直接回复

智能体行动

每次迭代，智能体选择一个行动：

行动	描述
`tool_call`	执行工具（网页搜索、文件读取等）
`publish_data`	通过工作区与团队分享发现
`send_message`	向特定队友发送直接消息
`request_help`	请求 Lead 生成新的辅助智能体
`idle`	通知当前任务完成，等待重新分配
`done`	返回最终响应（自动转换为 `idle`）

智能体无法自行退出。当智能体返回 done 时，它会自动转换为 idle 状态。只有 Lead Agent 可以通过 shutdown_agent 终止智能体。这确保了 Lead 对团队组成保持完全控制。

智能体间通信

Swarm 智能体通过两种机制协作：

P2P 消息

智能体通过 Redis 支持的邮箱向特定队友发送直接消息。消息类型包括 request、offer、accept、delegation 和 info。每次 LLM 调用前，智能体的邮箱会被检查是否有新消息。传入的消息会出现在智能体的提示上下文中。

共享工作区

智能体将发现发布到基于主题的工作区列表中。每次迭代前，每个智能体都会从所有主题获取最近的工作区条目，使整个团队了解集体进展。

共享工作区:
├── 主题: "findings"
│   ├── Agent-Takao: "NVIDIA 以 80% 的市场份额主导美国市场..."
│   └── Agent-Mitaka: "日本专注于边缘 AI 芯片..."
└── 主题: "sources"
    └── Agent-Kichijoji: "三星晶圆代工计划已公布..."

知识去重

Shannon 通过三层去重机制防止智能体间的重复工作：

L1: 单智能体 URL 缓存

每个智能体缓存其已获取的 URL。如果在同一智能体循环中再次请求相同 URL，将返回缓存内容而无需网络调用。

L2: 跨智能体共享 URL 元数据

URL 元数据（标题、摘要、关键事实）在团队所有智能体之间共享。当智能体 B 尝试获取智能体 A 已处理的 URL 时，它会收到缓存的元数据而非重新获取——节省时间和 Token。

L3: 搜索重叠检测

追踪所有智能体发现的搜索结果 URL。当新搜索返回的 URL 中 70% 以上已被其他智能体发现时，系统注入警告提示寻找新角度。此外，搜索饱和检测器使用 Jaccard 词级相似度（阈值 0.7，窗口 3 个查询）比较近期查询，标记重复搜索。

收敛检测

三种机制防止智能体无限运行：

无进展检测

如果智能体连续 3 次迭代没有执行任何有意义的操作（空或无法识别的 action），则认为已收敛，转换为 idle 状态。注意 tool_call、send_message 和 publish_data 都会重置此计数器。

连续错误中止

如果连续发生 3 次永久性工具错误（非速率限制等瞬时错误），智能体中止并报告失败。

最大迭代强制完成

在最后一次迭代时，如果智能体尚未调用 done 或 idle，工作流强制完成并从最近的迭代中构建摘要。

瞬时错误（速率限制、超时、503）触发自动重试，退避时间递增（5 秒增量，最大 30 秒），不计入中止阈值。

全局预算控制

Swarm 执行受三层预算约束，防止成本失控：

预算层	默认值	描述
`max_total_llm_calls`	`200`	所有智能体的最大 LLM 调用总次数
`max_total_tokens`	`1,000,000`	所有智能体的最大 Token 消耗总量
`max_wall_clock_minutes`	`30`	整个 Swarm 的最大挂钟时间

Lead Agent 在其上下文中接收预算信息（剩余调用次数、Token、时间），使其能够做出成本感知的决策——例如在预算紧张时关闭低优先级智能体或跳过可选任务。

何时使用 Swarm

场景	推荐工作流
简单问答、单步任务	Simple / DAG
带引用的多步骤研究	Research Workflow
多智能体代码审查、测试和修复	Swarm
多视角金融分析（基本面、技术面、情绪面）	Swarm
使用 Python/Bash 执行的数据处理流水线	Swarm
智能体需要分享中间发现的任务	Swarm
需要动态发现子任务的长时间探索	Swarm
子任务之间有复杂依赖链的任务	Swarm

Swarm 模式比标准工作流使用更多 Token，因为每个智能体运行多次 LLM 迭代，且 Lead Agent 的协调决策也消耗 Token。请在真正受益于持久化协作多智能体执行的任务中使用它。

配置

Swarm 行为通过 config/features.yaml 控制：

参数	默认值	描述
`swarm.enabled`	`true`	启用/禁用 Swarm 工作流
`swarm.max_agents`	`10`	最大智能体总数（初始 + 动态）
`swarm.max_iterations_per_agent`	`25`	每个智能体的最大推理-行动循环次数
`swarm.agent_timeout_seconds`	`1800`	每个智能体超时（30 分钟）
`swarm.max_messages_per_agent`	`20`	每个智能体的 P2P 消息上限
`swarm.workspace_snippet_chars`	`800`	提示中每个工作区条目的最大字符数
`swarm.workspace_max_entries`	`5`	向每个智能体显示的最近条目数
`swarm.max_total_llm_calls`	`200`	整个 Swarm 的全局 LLM 调用预算
`swarm.max_total_tokens`	`1000000`	整个 Swarm 的全局 Token 预算
`swarm.max_wall_clock_minutes`	`30`	Swarm 的最大挂钟时间

流式事件

Swarm 工作流发出 SSE 事件用于实时监控：

事件类型	Agent ID	触发时机
`WORKFLOW_STARTED`	`swarm-supervisor`	工作流开始
`PROGRESS`	`swarm-lead` / `swarm-supervisor`	规划、生成、重新分配
`LEAD_DECISION`	`swarm-lead`	Lead 做出规划决策（生成、分配、修订等）
`TASKLIST_UPDATED`	`swarm-lead`	任务依赖图变更（任务创建或取消）
`TEAM_STATUS`	`swarm-lead`	团队组成变更（智能体生成或关闭）
`AGENT_STARTED`	智能体名称	智能体开始第一次迭代
`AGENT_COMPLETED`	智能体名称	智能体完成
`WORKFLOW_COMPLETED`	`swarm-supervisor`	最终综合完成

下一步

Swarm 教程

分步指南：运行 Swarm 工作流

工作流和模式

其他工作流类型和认知模式

流式传输

实时事件流

成本控制

多智能体任务的预算管理

入门指南

核心概念

指南

Swarm 多智能体协作

什么是 Swarm 模式？

工作原理

Lead Agent 事件循环

生命周期概览

任务依赖 (DAG)

Lead Agent 行动

智能体行动

智能体间通信

P2P 消息

共享工作区

知识去重

收敛检测

全局预算控制

何时使用 Swarm

配置

流式事件

下一步

Swarm 教程

工作流和模式

流式传输

成本控制

​什么是 Swarm 模式？

​工作原理

​Lead Agent 事件循环

​生命周期概览

​任务依赖 (DAG)

​Lead Agent 行动

​智能体行动

​智能体间通信

​P2P 消息

​共享工作区

​知识去重

​收敛检测

​全局预算控制

​何时使用 Swarm

​配置

​流式事件

​下一步

Swarm 教程

工作流和模式

流式传输

成本控制

什么是 Swarm 模式？

工作原理

Lead Agent 事件循环

生命周期概览

任务依赖 (DAG)

Lead Agent 行动

智能体行动

智能体间通信

P2P 消息

共享工作区

知识去重

收敛检测

全局预算控制

何时使用 Swarm

配置

流式事件

下一步