> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Swarm 多智能体协作

> 了解 Shannon 的 Swarm 工作流：Lead Agent 驱动的自主多智能体协作

## 什么是 Swarm 模式？

Swarm 模式部署多个持久化的自主智能体，它们并行工作以解决复杂任务。一个由 LLM 驱动的 **Lead Agent** 动态协调团队——规划任务、生成智能体、重新分配工作，并基于实时事件做出决策。

与静态编排（任务预先分解且不会改变）不同，Lead Agent 持续监控进度并动态适应：创建新任务、取消冗余工作、在情况变化时重新分配空闲智能体。

## 工作原理

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

### Lead Agent 事件循环

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

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

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

### 生命周期概览

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

### 任务依赖 (DAG)

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

```text theme={null}
任务:
├── 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`） |

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

## 智能体间通信

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

### P2P 消息

智能体通过 Redis 支持的邮箱向特定队友发送直接消息。消息类型包括 `request`、`offer`、`accept`、`delegation` 和 `info`。

每次 LLM 调用前，智能体的邮箱会被检查是否有新消息。传入的消息会出现在智能体的提示上下文中。

### 共享工作区

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

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

## 知识去重

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

<AccordionGroup>
  <Accordion title="L1: 单智能体 URL 缓存">
    每个智能体缓存其已获取的 URL。如果在同一智能体循环中再次请求相同 URL，将返回缓存内容而无需网络调用。
  </Accordion>

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

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

## 收敛检测

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

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

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

  <Accordion title="最大迭代强制完成">
    在最后一次迭代时，如果智能体尚未调用 `done` 或 `idle`，工作流强制完成并从最近的迭代中构建摘要。
  </Accordion>
</AccordionGroup>

瞬时错误（速率限制、超时、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**         |

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

## 配置

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`                | 最终综合完成                 |

## 下一步

<CardGroup cols={2}>
  <Card title="Swarm 教程" icon="users" href="/cn/tutorials/swarm-workflow">
    分步指南：运行 Swarm 工作流
  </Card>

  <Card title="工作流和模式" icon="diagram-project" href="/cn/quickstart/concepts/workflows">
    其他工作流类型和认知模式
  </Card>

  <Card title="流式传输" icon="stream" href="/cn/quickstart/concepts/streaming">
    实时事件流
  </Card>

  <Card title="成本控制" icon="dollar-sign" href="/cn/quickstart/concepts/cost-control">
    多智能体任务的预算管理
  </Card>
</CardGroup>