Skip to main content
并行协作

Agent Teams

Agent Teams 让一个 Qoder CLI 交互式会话变成一个小型 Agent 团队。交互入口保持不变：在当前会话里描述目标，main Agent 会根据任务需要创建 teammate，让不同成员并行研究、实现、验证或互相交接结果。 它适合处理“一个人做会很长、拆开做更清楚”的任务，比如同时检查多个模块、让一个成员实现另一个成员验证、把大型重构拆成探索和执行两个方向。
Beta Agent Teams 当前是 beta 特性，默认不启用。启动 Qoder CLI 前需要先打开环境变量开关：QODER_AGENT_TEAMS=1 qodercli。 也可以把 QODER_AGENT_TEAMS=1 写入用户级配置目录中的 .env 文件，让后续启动自动启用。默认用户级配置路径：macOS/Linux 为 $HOME/.qoder/.env，Windows 为 %USERPROFILE%\.qoder\.env。修改 .env 后，需要重新启动 Qoder CLI 才会生效。

Agent Teams 是什么

Agent Teams 中有两个角色：
角色说明
main Agent用户直接对话的 Agent，负责理解目标、拆分任务、汇总结果，并报告重要进展。
teammatemain Agent 创建的 teammate，例如 researcher、coder、reviewer。teammate 有自己的上下文，可以继续接收 Task 和 SendMessage。
一个典型会话如下： 
Qoder CLI session
+-- main conversation
|   `-- main Agent 和用户对话、分配 Task、汇总结果
|
+-- Agent Team
|   +-- @researcher  研究代码路径
|   +-- @coder       实现改动
|   `-- @reviewer    复核风险
|
`-- shared Task list
    +-- Task A  owner=@researcher
    +-- Task B  owner=@coder
    `-- Task C  owner=@reviewer
无需手动创建团队。一个交互式会话只有一个当前团队；当 main Agent 需要 teammate 时，会通过带名字的 Agent 调用把成员加入团队。

如何使用

最稳定的方式是在请求里明确说“使用 Agent Teams”，并给出期望的成员分工： 
使用 Agent Teams 处理这个重构。
创建 researcher、coder、reviewer 三个 teammate：
1. researcher 先梳理认证模块的调用链。
2. coder 根据 researcher 的结论修改代码。
3. reviewer 复核改动风险和缺失测试。
最终请给出改动摘要、涉及文件和验证结果。
如果请求只写“并行处理”或“找几个 Agent 看一下”，Qoder CLI 可能会选择普通 Subagent、background task 或 Workflow。需要团队成员持续协作时，建议直接点名 Agent Teams。

工作原理

Agent Teams 的核心是“teammate + SendMessage + shared Task list”。

协同流程

可以把 Agent Teams 理解成一个由 main Agent 组织的协作闭环：main Agent 负责理解目标、创建 teammate、分配 Task、使用 SendMessage 协调问题和发现，并汇总结果；teammate 负责各自的具体工作；shared Task list 负责记录谁在做什么、当前进展如何。 
用户目标
  |
  v
+------------+
| main Agent |
+------------+
  |  创建 teammate
  |  分配 / 更新 shared Task
  |  收集结果并汇总
  |
  +-----------------------+
  |                       |
  v                       v
+------------------+   +------------------------+
| shared Task list |   | SendMessage            |
| owner / status   |   | 问题 / 发现 / 结果     |
+------------------+   +------------------------+
  |                       |
  +-----------+-----------+
              |
              v
+-------------+ SendMessage +----------+
| @researcher | <---------> | @reviewer |
+-------------+             +----------+
       |                         |
       +-----------+-------------+
                   |
                   v
              进展和结果
                   |
                   v
              main Agent
                   |
                   v
                最终答复

生命周期和 resume

Agent Teams 只在当前打开的 TUI 会话中存在。每次启动启用 Agent Teams 的交互式会话时，Qoder CLI 会为这次会话准备一个临时 team；main Agent 会在这个 team 中创建 teammate。 在同一次 TUI 中，teammate 可以多次经历 running -> idle -> running。idle 表示当前没有正在执行的工作，不表示 teammate 已退出。 
当前 TUI 会话
+-- main conversation
+-- Agent Team
|   +-- @researcher  running / idle
|   `-- @reviewer    running / idle
`-- shared Task list
退出 TUI 时，Qoder CLI 会结束这次会话里的 teammate，并清理本次 team 状态。之后使用 resume 恢复会话时，主会话的历史记录会恢复；但上一次打开 TUI 时创建的 teammate，以及这些 teammate 当时的运行状态不会一起回来。已经出现在主会话里的汇总或 SendMessage 内容仍会作为历史内容保留，但原来的 teammate 不会继续运行。 如果 resume 后仍需要团队协作，需要让 main Agent 重新创建 teammate。teammate 只在当前 TUI 会话内存活，退出 TUI 后不会保留到下一次 resume。

TUI 展示方式

Agent Teams 当前在一个 TUI 窗口内展示。会话底部可以看到 agents 列表；按向下键进入列表后，可以通过上下键选择 main conversation 或不同 teammate，按回车切换到对应视图，按 Esc 返回 main conversation。 当前不支持多个 TUI 面板分屏展示。不同 teammate 不是并排显示，而是在同一个会话窗口中切换查看。

teammate

main Agent 创建 teammate 时会给它一个稳定名字，例如 researcher。这个名字后续可以继续用于 SendMessage、分配 Task 和查看状态。 teammate 完成当前一轮工作后通常会进入 idle 状态。idle 不表示退出，而是表示它暂时没有正在执行的工作，之后仍然可以被新 SendMessage 或新 Task 唤醒。 
@researcher running -> idle -> running -> idle
                      ^        |
                      |        `-- 收到新任务后继续工作
                      `-- 当前一轮完成

SendMessage

main Agent 和 teammate、teammate 和 teammate 之间可以通过 SendMessage 互相沟通。teammate 的普通文本输出不会自动通过 SendMessage 发给其他成员；需要发送给特定成员的信息会通过 SendMessage 传递。 UI 里通常会把 SendMessage 内容显示为类似“Message from @researcher”的提示，方便跟进团队协作中的问题、发现和结果。

shared Task

Agent Teams 可以配合 shared Task list 使用。main Agent 可以先创建一组 Task，再让 teammate 分别处理对应事项。 
shared Task list
+-- [in progress] 梳理旧接口调用点  owner=@researcher
+-- [pending]     实现新接口适配    owner=@coder
`-- [pending]     补充迁移测试      owner=@tester
shared Task 的价值是让团队协作更清楚：谁在做什么、哪些 Task 已经完成、哪些 Task 依赖其他 Task，都可以被明确记录。Task 完成不等于 teammate 退出；成员完成 Task 后仍可以留在团队中等待下一步。

和 Subagent 的区别

Agent Teams 建立在 Agent 能力之上，但使用方式和普通 Subagent 不一样。
对比项SubagentAgent Teams
适合任务单个聚焦子任务多个成员持续协作的复杂任务
生命周期通常完成一次任务后返回结果teammate 可以 idle，并在同一会话里继续接收 SendMessage
通信方式结果主要返回给 main Agentmain Agent 和 teammate、teammate 之间可以通过 SendMessage 沟通
任务协调主要靠 main Agent 编排可配合 shared Task list 分配和跟踪
成员身份以 Subagent 类型为主以运行时名字为主，例如 @coder、@reviewer
简单理解：
  • 用 Subagent：把一个清晰子任务交给专门 Agent，等它返回结果。
  • 用 Agent Teams：让多个 teammate 在同一会话里持续协作，必要时通过 SendMessage 沟通、领取 Task、分阶段推进。

什么时候使用 Agent Teams

适合使用 Agent Teams 的情况：
场景为什么适合
大型代码探索不同 teammate 可以分别查看不同模块，再把发现汇总给 main Agent。
实现和复核分离一个成员写代码，另一个成员独立审查风险、测试和边界条件。
多条线并行推进多个互不阻塞的子任务可以同时进行，减少等待时间。
任务会反复交接teammate 可以保持名字和上下文，后续继续接收补充任务。
需要明确协作状态shared Task list 可以记录 owner、状态和依赖关系。
不建议使用 Agent Teams 的情况：
场景更合适的方式
只需要读取一个文件或查一个符号直接让 main Agent 读取或搜索。
只有一个独立子任务使用普通 Subagent 更轻量。
有固定、可复用的多阶段流程使用 Workflow 更容易沉淀成长期流程。
任务很小但需要低成本完成少开 teammate，避免额外上下文和 token 消耗。

使用建议

  • 明确成员职责：给每个 teammate 一个短名字和清楚任务，例如 researcher 负责探索、coder 负责实现、reviewer 负责复核。
  • 明确期望输出：例如需要根因分析、改动摘要、验证结果、风险说明或后续建议。
  • 对复杂任务使用 Task：当任务超过两三步时，让 Qoder CLI 创建 shared Task，方便跟踪 owner、状态和依赖关系。
  • 控制并发规模：同时创建过多 teammate 会增加 token 使用和信息合并成本。大多数场景从 2 到 4 个成员开始更稳。
  • 区分 idle 和退出：看到 teammate idle 是正常状态，表示它可以继续被使用；不需要继续协作时，可以让 main Agent 关闭成员。

示例

并行探索并汇总

使用 Agent Teams 分析这次登录问题。
创建两个 teammate：
1. researcher 检查认证和 session 相关代码。
2. tester 检查现有测试和可复现路径。
请给出根因判断、影响范围、风险点和建议改法。

实现后独立复核

使用 Agent Teams 完成这个修复。
先让 coder 修改代码，再让 reviewer 基于最终 diff 做独立复核。
reviewer 需要检查边界条件、测试覆盖和潜在回归。
请给出改动内容、验证结果和剩余风险。

结合 shared Task

使用 Agent Teams 和 shared Task list 推进这个迁移。
先创建以下 Task：
1. 梳理旧接口调用点。
2. 实现新接口适配。
3. 补充迁移测试。
然后创建 researcher、coder、tester 三个 teammate 分别领取 Task。
请在最终结果里说明每个 Task 的完成情况、关键改动和验证结果。
开始使用
核心概念
使用 Qoder CLI
扩展 Qoder CLI
远程与集成
配置与安全
参考
故障排查