# Agent Team

## 简介

Agent Team 是JiuwenSwarm 平台的核心协作功能，它让多个智能体（Agent）能够围绕同一目标形成协作团队，共同完成复杂任务。与单个 Agent 的能力增强不同，Agent Team 强调的是团队协作、分工执行和持续交付。


---

## 一、概念科普

### 1.1 Agent Team 的定位

**Agent Team 不是单个 Agent 的能力增强，而是多个 Agent 的团队协作。**

想象一下，当你需要完成一个复杂任务时，比如"深度调研某个行业并生成分析报告"，这个任务涉及多个环节：
- 信息收集和调研
- 数据分析和整理
- 报告撰写和排版
- 内容校对和优化

如果只用一个 Agent 来完成，它需要同时具备调研、分析、写作、校对等多种能力，而且需要按顺序一步步执行，效率较低。

而 Agent Team 的思路是：**让多个专业化的 Agent 组成团队，每个 Agent 负责自己擅长的部分，协同完成整个任务。**

> **类比理解**：就像一个项目团队，有项目经理负责统筹，有调研员负责收集信息，有分析师负责数据处理，有文案负责撰写报告。每个人专注自己的领域，协作完成项目。

### 1.2 为什么需要 Agent Team？

**单个 Agent 的局限性：**

1. **难以兼顾多环节**：一个 Agent 很难同时精通调研、分析、执行、校对等多个环节
2. **串行执行效率低**：任务必须按顺序一步步完成，无法并行推进
3. **复杂任务易出错**：长链路任务容易出现遗漏或偏差
4. **难以持续优化**：每个环节的结果难以被其他环节及时参考和改进

**Agent Team 的优势：**

1. **专业分工**：每个 Agent 专注自己擅长的领域，执行质量更高
2. **并行执行**：多个 Agent 可以同时工作，大幅提升效率
3. **协作接力**：前置任务的结果可以被后续任务直接使用
4. **持续交付**：团队可以持续推进任务，直到完成最终目标

### 1.3 从 Harness Engineering 到 Coordination Engineering

传统的 Agent 开发思路是 **Harness Engineering**（驾驭工程），重点在于：
- 如何让单个 Agent 更强大
- 如何设计更好的提示词（Prompt）
- 如何增强 Agent 的工具能力

而 Agent Team 代表的是 **Coordination Engineering**（协同工程），重点转向：
- 如何让多个 Agent 有效分工
- 如何建立协作机制和流程
- 如何实现任务流转和结果汇总

> **关键认知**：Agent Team 的核心不是"更强的 Agent"，而是"更好的协作"。重点在于如何组织团队、分配任务、推进流程。

---

## 二、使用指导

### 2.1 适用场景

**什么时候该用 Agent Team？**

Agent Team 更适合以下类型的任务：

| 任务特征 | 是否适合 Agent Team | 说明 |
|---------|-------------------|------|
| **链路长、步骤多** | ✅ 适合 | 任务需要多个环节，每个环节可以独立执行 |
| **角色分工明显** | ✅ 适合 | 不同环节需要不同的专业能力 |
| **可并行推进** | ✅ 适合 | 部分任务可以同时执行，不必等待前置任务 |
| **需要持续迭代** | ✅ 适合 | 任务需要多轮优化和改进 |
| **简单问答** | ❌ 不适合 | 单个 Agent 就能快速回答 |
| **单步处理** | ❌ 不适合 | 任务简单，不需要分工协作 |

**典型适用场景：**

1. **深度调研并生成报告**
   - 调研 Agent 收集信息
   - 分析 Agent 处理数据
   - 撰写 Agent 编写报告
   - 校对 Agent 优化内容

2. **资料整理后输出方案**
   - 整理 Agent 分类资料
   - 分析 Agent 提取要点
   - 设计 Agent 制定方案
   - 评审 Agent 优化方案

3. **多人角色式内容生产**
   - 创意 Agent 提供构思
   - 撰写 Agent 编写内容
   - 编辑 Agent 优化排版
   - 审核 Agent 检查质量

4. **复杂任务拆分执行**
   - 规划 Agent 拆解任务
   - 执行 Agent 并行处理
   - 汇总 Agent 整合结果
   - 验证 Agent 检查完整性

### 2.2 协作流程

**Agent Team 的核心协作链路：**

```
用户提出目标 → Leader 分析需求 → Leader 组建团队 → Leader 拆解任务
→ Teammate 认领任务 → Teammate 执行任务 → Teammate 汇报结果
→ Leader 汇总结果 → 输出最终交付物
```

**详细流程说明：**

#### 第一步：用户提出目标

用户以自然语言描述任务目标，例如：
- "帮我调研新能源汽车行业，并生成一份分析报告"
- "整理这些技术文档，输出一份使用指南"

#### 第二步：Leader 分析需求

Leader Agent 接收用户目标后，会：
- 理解任务的核心需求
- 分析任务的执行环节
- 评估需要的专业角色
- 制定整体执行计划

#### 第三步：Leader 组建团队

Leader Agent 根据任务需求，组建合适的团队：
- 确定需要的 Agent 角色（如调研、分析、撰写）
- 为每个角色分配任务
- 建立任务之间的依赖关系

#### 第四步：Teammate 认领任务

各个 Teammate Agent 根据自己的专长，认领相应任务：
- 确认任务内容和要求
- 准备执行所需的资源
- 开始独立执行任务

#### 第五步：Teammate 执行任务

Teammate Agent 独立执行自己的任务：
- 按照任务要求完成工作
- 在需要时向 Leader 求助
- 生成中间结果或交付物

#### 第六步：Teammate 汇报结果

任务完成后，Teammate Agent 会：
- 向 Leader 汇报执行结果
- 提交中间产物或交付物
- 等待后续任务安排

#### 第七步：Leader 汇总结果

Leader Agent 收集所有 Teammate 的结果：
- 整合各个环节的产出
- 检查任务完成情况
- 生成最终交付物

> **关键理解**：这是一个"团队协作过程"，不是用户手动逐个调用多个 Agent。用户只需要提出目标，整个团队会自动协作完成。

**任务依赖关系：**

任务之间可以存在依赖关系：
- **前置任务**：必须先完成的任务，后续任务依赖其结果
- **后续任务**：需要等待前置任务完成后才能开始
- **并行任务**：可以同时执行，互不依赖

例如，在"调研并生成报告"的任务中：
- 调研任务（前置）→ 分析任务（后续）→ 撰写任务（后续）
- 排版任务可以与撰写任务并行
- 校对任务需要等待撰写任务完成

### 2.3 启动 Agent Team 模式

Agent Team 模式是 JiuwenSwarm 平台的一种特殊协作模式，用户可以通过以下方式启动：

**方式一：前端对话页面切换**

在 JiuwenSwarm 的前端对话页面，可以直接切换到集群模式（Agent Team 模式）。这是最简单的启动方式，只需在对话界面选择对应的模式即可。

![模式切换按钮](../assets/images/切换到集群模式.png)

点击"集群模式"按钮后，界面切换为 Agent Team 模式：

![集群模式激活](../assets/images/集群模式激活.png)

**方式二：频道内 /mode 命令切换**

在频道对话中，可以使用 `/mode` 命令切换到 Agent Team 模式：

```
/mode team
```

执行后，当前对话将进入 Agent Team 模式，Leader Agent 会自动接管任务协调。

**在 Agent Team 模式下如何输入 Prompt**

进入 Agent Team 模式后，用户输入 Prompt 的方式与普通对话类似，但建议注意以下几点以更好地帮助任务完成：

1. **明确目标**：清晰描述最终期望的交付物，例如"帮我调研新能源汽车行业，并生成一份分析报告"
2. **指定范围**：说明任务的范围和边界，例如"重点关注国内市场，时间范围是近三年"
3. **提供约束**：如果有格式、篇幅、风格等要求，一并说明，例如"报告需要包含数据图表，篇幅不少于5000字"
4. **一次输入完整需求**：尽量在一次 Prompt 中给出完整需求，避免分多次输入导致团队反复调整

### 2.4 Team Skills

Agent Team 模式下同样支持技能（Skills）的使用和开发。团队中的每个 Agent 都可以配置和使用技能，团队也可以共享技能资源。

**Team Skills 的概念：**

- **个人技能**：每个 Agent 自己配置和使用的技能，存放在各自的 `workspaces/<agent_name>_workspace/skills/` 目录下
- **团队共享技能**：团队级别的共享技能，存放在 `team-workspace/skills/` 目录下，所有团队成员都可以使用

**技能在团队中的作用：**

1. **增强专业能力**：每个 Agent 可以通过技能增强自己在特定领域的执行能力
2. **共享工具资源**：团队共享技能可以让所有成员使用同一套工具，避免重复开发
3. **协作效率提升**：技能可以让 Agent 更高效地完成分配的任务

> 有关 Team Skills 的详细使用和开发教程，请参阅 [SwarmSkills 指南](SwarmSkills.md)。

### 2.5 Team Memory

**Round 定义**：Agent Team 中一轮完整的团队协作周期，通常包含任务分配、执行、汇报和汇总等阶段。

Agent Team 模式下，每个团队都有自己的双层记忆：成员各自的**个人记忆**（独立读写）和团队共享的 **`TEAM_MEMORY.md`**（所有成员只读，Leader 在 round 结束后由提取 agent 自动写入）。

**团队生命周期与记忆行为：**

| 生命周期 | 个人记忆 | 团队记忆 | 适用场景 |
|----------|----------|----------|----------|
| **临时团队（temporary）** | 只读访问父 agent 的 workspace 记忆 | 无 | 单次任务、即用即弃 |
| **持久团队（persistent）** | 每个成员独立读写 | 自动提取 + 跨 round 累积 | 长期协作、需经验沉淀 |

**详细说明：**

- **临时团队**：
  - 成员只读访问父 agent 的 workspace 记忆，无法污染源记忆
  - 无团队记忆，团队销毁后不留痕
  - 适合单次任务、即用即弃的场景

- **持久团队**：
  - 每个成员拥有独立的个人记忆，支持读写操作
  - 团队记忆由 Leader 在每个 round 结束后自动提取，并跨 round 累积
  - 预定义成员的原有 workspace 通过 symlink 自动延续
  - 适合长期协作、需要经验沉淀的场景

**记忆层级与访问权限：**

| 层级 | 访问权限 | 写入方 |
|------|----------|--------|
| 个人记忆 | 该成员独占 | 成员自身（在会话中调用记忆工具） |
| 团队记忆 | 所有成员只读 | Leader 在 round 结束后由提取 agent 自动写入 |

完整的存储布局、提取分类（`[decision]` / `[lesson]` / `[member]` / `[context]`）、跨团队/跨成员隔离机制详见 [记忆系统 → Agent Team 团队记忆](记忆.md#进阶agent-swarm-团队记忆)。

---

## 四、案例实践

### 4.1 任务目标

深度调研新能源汽车行业，生成一份分析报告。

### 4.2 用户输入

```
帮我调研新能源汽车行业的发展现状、主要厂商、技术趋势，并生成一份分析报告。
```

### 4.3 协作过程

**Leader 分析需求**

Leader Agent 接收目标后，分析任务：
- 任务环节：行业现状分析、主要厂商竞争格局、技术发展趋势分析、市场前景预测、报告整合与撰写
- 需要角色：行业分析师、竞争分析师、技术分析师、市场分析师、报告撰写专家
- 执行计划：先调研，再分析，最后撰写

![leader analysis](../assets/images/leader分析需求.png)

**Leader 组建团队**

Leader Agent 组建团队：
- 行业分析师：负责行业现状分析
- 竞争分析师：负责厂商竞争格局分析
- 技术分析师：负责技术发展趋势分析
- 市场分析师：负责市场前景预测
- 报告撰写专家：负责报告整合与撰写

![leader build teams](../assets/images/leader组建团队.png)

**Team Agent 执行**
Team Agent 接收指派任务后，开始执行

![Team execute tasks](../assets/images/团队成员接收任务.png)

**Leader 汇总结果**

Leader Agent 整合所有结果：
- 检查任务完成情况
- 整合最终报告
- 向用户交付成果

![Team execute tasks](../assets/images/leader总结结果.png)

### 4.4 产出结果

最终交付物：一份完整的新能源汽车行业分析报告，包含：
- 行业发展现状
- 主要厂商分析
- 技术趋势总结
- 数据图表展示

![Team execute tasks](../assets/images/team结果.png)


---

## 五、协作方式

### 5.1 角色分工

**Leader Agent 的职责**

Leader Agent 是团队的领导者，主要负责：

| 职责 | 说明 |
|------|------|
| **目标理解** | 理解用户提出的任务目标，分析核心需求 |
| **团队组建** | 根据任务需求，组建合适的 Agent 团队 |
| **任务规划** | 拆解任务，分配给合适的 Teammate Agent |
| **关键决策** | 审批重要决策，协调团队执行 |
| **整体推进** | 监控任务进度，确保团队持续推进 |
| **结果汇总** | 整合所有 Teammate 的结果，生成最终交付物 |

**Teammate Agent 的职责**

Teammate Agent 是团队的执行者，主要负责：

| 职责 | 说明 |
|------|------|
| **认领任务** | 根据自己的专长，认领合适的任务 |
| **独立执行** | 按照任务要求，独立完成工作 |
| **求助协调** | 在遇到困难时，向 Leader 求助 |
| **汇报结果** | 完成任务后，向 Leader 汇报执行结果 |
| **提交产物** | 提交中间结果或交付物，供后续环节使用 |

**分级自主协同**

Agent Team 采用的是"分级自主协同"模式：
- **不是完全人工编排**：用户不需要手动指定每个 Agent 的任务
- **不是无人治理**：Leader Agent 会统筹协调，确保团队有序执行
- **自主认领**：Teammate Agent 可以自主认领任务，发挥专长
- **协同推进**：Leader 和 Teammate 协作推进，持续交付

> **关键理解**：Leader 负责统筹协调，Teammate 负责专业执行，两者协同完成任务。

### 5.2 共享协作

**团队共享工作区**

Agent Team 提供团队共享工作区，成员之间可以围绕同一批中间产物协作：

**共享内容包括：**
- 调研结果
- 分析数据
- 报告草稿
- 中间文档
- 任务状态

**协作优势：**

1. **持续流转**：调研结果、分析结果、报告草稿等可以在团队内持续流转
2. **避免重复**：每个 Agent 不需要各做各的，可以直接使用前置环节的结果
3. **实时参考**：后续环节可以实时参考前置环节的产出
4. **协同优化**：多个 Agent 可以共同优化同一份文档

**共享工作区文件结构：**

Agent Team 的文件结构分为两个层级：**团队共享工作区**和**成员独立工作空间**。

- **团队共享工作区（team-workspace）**：所有团队成员共享的目录，存放团队产出物和共享技能。每个 Agent Team Session 会独立创建一个文件夹，文件夹下包含 team-workspace。
- **成员独立工作空间（workspaces）**：每个 Agent 的专属空间，存放各自的配置、记忆、技能和待办事项。

完整路径层级如下：

```
.agent_teams/                          ← Agent Team 根目录
└── <team_name>/                       ← 每个团队独立一个文件夹
    ├── team-workspace/                 ← 团队共享工作区（所有成员共享）
    │   ├── artifacts/                  ← 团队产出物
    │   │   ├── code/                   ← 代码产出
    │   │   ├── docs/                   ← 文档产出
    │   │   └── reports/                ← 报告产出
    │   └── skills/                     ← 团队共享技能
    └── workspaces/                     ← 各成员独立工作空间
        └── <agent_name>_workspace/     ← 各 Agent 的独立空间
            ├── AGENT.md                ← 智能体配置
            ├── memory/                 ← 个人长期记忆（general 场景）
            ├── coding_memory/          ← 个人编码记忆（coding 场景）
            ├── skills/                 ← 技能库
            ├── todo/                   ← 待办事项
            └── ...                     ← 其他 Agent 专属文件
```

**协作机制：**

- **共享目录**：团队共享一个工作目录，存放所有中间产物
- **冲突控制**：避免多个 Agent 同时修改同一文件导致冲突
- **版本管理**：记录中间产物的版本变化，便于追溯

> **协作体验**：用户可以看到团队共享的中间产物，了解任务推进情况，而不需要手动传递文件。

### 5.3 任务推进

**事件驱动机制**

Agent Team 不是一次性分完工就结束，而是依靠事件驱动持续推进：

**推进机制：**

1. **任务状态变化**：任务完成后，自动触发后续任务
2. **消息协同**：Agent 之间通过消息传递协调执行
3. **异常恢复**：遇到异常时，团队可以自动恢复和调整

**用户可观察的点：**

1. **任务完成后自动推进**：前置任务完成后，后续任务会自动开始
2. **关键决策由 Leader 审批**：重要决策需要 Leader Agent 审批确认
3. **团队状态可追踪**：用户可以观察任务推进、成员状态和结果汇总

**持续推进示例：**

在"调研并生成报告"的任务中：
- 调研任务完成 → 自动触发分析任务
- 分析任务完成 → 自动触发撰写任务
- 撰写任务完成 → 自动触发校对任务
- 校对任务完成 → Leader 汇总结果

> **关键理解**：Agent Team 是一个持续推进的团队，不是一次性分完工就结束。任务之间会自动流转，团队会持续协作直到完成最终目标。

---

## 六、常见问题

### Q1：Agent Team 和普通对话有什么区别？

**普通对话**：单个 Agent 与用户交互，适合简单问答和单步处理。

**Agent Team**：多个 Agent 组成团队协作，适合复杂任务和多环节执行。

### Q2：如何判断是否需要使用 Agent Team？

判断标准：
- 任务是否需要多个环节？
- 不同环节是否需要不同的专业能力？
- 任务是否可以并行推进？
- 任务是否需要持续迭代？

如果答案是"是"，就适合使用 Agent Team。

### Q3：Leader Agent 和 Teammate Agent 有什么区别？

**Leader Agent**：负责统筹协调，包括目标理解、团队组建、任务规划、关键决策、整体推进、结果汇总。

**Teammate Agent**：负责专业执行，包括认领任务、独立执行、求助协调、汇报结果、提交产物。

### Q4：Agent Team 如何持续推进任务？

Agent Team 采用事件驱动机制：
- 任务状态变化自动触发后续任务
- Agent 之间通过消息协同
- 遇到异常时可以自动恢复和调整

### Q5：用户可以看到团队的协作过程吗？

是的，用户可以观察：
- 任务推进情况
- Agent 成员状态
- 中间产物和结果汇总

### Q6：同一频道可以同时运行多个 Team 会话吗？

本地运行模式支持同一频道下的多个 Team 会话同时运行。切换当前查看的会话只影响界面展示，不会停止其他会话的后台任务；暂停、取消或删除操作只作用于指定会话。

分布式运行模式保持单频道单活动会话语义。创建或切换到另一个 Team 会话时，系统会先停止该频道中原有的活动或待启动会话，以确保远程成员 bootstrap、传输连接和运行时资源不会跨会话复用。

---

## 七、附录

### 7.1 相关资源

- [官网技术博客：Agent Team](https://openjiuwen.com/blogs/blog-artical?id=225)

---