easy-agent Agent Teams多智能体协作:多个AI队友如何分工完成复杂需求
easy-agent Agent Teams多智能体协作:多个AI队友如何分工完成复杂需求
Easy Agent 的 Agent Teams 功能让多个 AI 队友在同一进程中协作:一个 lead 主 Agent 负责调度,若干命名的后台队友并行干活,通过消息收件箱与共享任务列表分工完成复杂需求。本文讲清 Agent Teams 如何开启、四步协作工作流、崩溃恢复机制,以及多智能体协作的最佳实践,帮你快速上手 easy-agent 的多智能体能力。
为什么需要多智能体协作:单 Agent 的瓶颈
平时我们用 easy-agent 干活时,是一个 Agent 顺序执行:读代码、改文件、跑测试,一步步做完。遇到这类需求时效率会明显下降:
- 天然可并行的任务:比如「同时做后端接口、前端页面,再派一个人做代码审查」,一个 Agent 只能做完一件再做下一件;
- 长时运行的角色分工:搜索调研、实现、审查这几类工作互相独立,串行执行浪费时间;
- 上下文被长对话占用:主 Agent 一边陪聊一边跑任务,上下文越积越重。
Agent Teams 的思路是:把当前会话从「一个 Agent 对用户」升级为「lead 主 Agent 协调多名队友」。每个队友是进程内的后台子 Agent,拥有独立的上下文窗口和工具集,主 Agent 不需要干等,可以继续对话或调度其他队友。
💡 它不是开多个终端窗口,也不是跨机器集群——所有队友都在同一个
eagent进程里运行,管理成本很低。
快速开启:两种方式解锁 Agent Teams
Agent Teams 默认关闭,需要显式开启。开启后,TeamCreate、SendMessage 等团队工具才会出现在模型可见的工具列表中(见 src/utils/agentTeamsEnabled.ts)。
| 开启方式 | 用法 | 适用场景 |
|---|---|---|
| 命令行参数 | eagent --agent-teams |
单次会话临时使用 |
| 环境变量 | export EASY_AGENT_TEAMS=1 |
长期启用,配合脚本 |
先装好 easy-agent 再开启:
npm install -g --ignore-scripts eagent
export EASY_AGENT_TEAMS=1
eagent
多智能体协作完整工作流:四步走
团队的全部生命周期由四个工具驱动,源码分别在 src/tools/teamCreateTool.ts、src/tools/agentTool.ts、src/tools/sendMessageTool.ts 和 src/tools/teamDeleteTool.ts。
第一步:TeamCreate 创建团队
lead 调用 TeamCreate({ team_name: "refactor-auth", description: "..." }) 后,当前进程就成为团队 leader。系统会在 ~/.easy-agent/teams/<team-name>/team.json 落盘团队文件,记录成员、心跳和版本;此后 SendMessage、共享任务列表才生效。
几个约束值得记住:
- 一个会话同时只有一个活跃团队,不能嵌套子团队,队友也不能再创建团队;
- 团队名会自动清洗为小写字母、数字和连字符;
- 同名团队已存在于磁盘时,直接创建会报错,避免误接上一轮崩溃留下的状态。
第二步:用 Agent 工具生成命名队友
lead 通过带名字和团队名的 Agent 调用生成队友,例如:
Agent({ name: "backend", team_name: "refactor-auth",
run_in_background: true, subagent_type: "general-purpose",
prompt: "实现 /v2/login 鉴权接口…" })
要点:
name是队友的通讯呼号,之后SendMessage就用它寻址;- 命名队友强制后台运行——同步调用会阻塞主循环,反而收不到消息;
subagent_type可选内置的general-purpose、explore(见 src/agents/builtIn/index.ts),也可以把自定义 Agent 定义写在<项目>/.easy-agent/agents/<name>.md里,用 Markdown 正文作为队友的系统提示词;- 可传
isolation: "worktree",让队友在独立的 git worktree 里改代码,互不踩踏。
第三步:SendMessage 消息协作 + 共享任务列表
队友之间靠两套机制协作:
1. 消息收件箱(Mailbox)
SendMessage({ to: "backend", message: "…" }) 把消息写进目标队友的收件箱,运行中的队友会在下一次模型调用前读到它。还有两个实用能力:
to: "*"广播给所有活跃队友;- 控制消息:
type: "shutdown_request"让队友在当前工具批次结束后停止,type: "abort_request"立即取消(机制见 src/utils/teammateMailbox.ts)。
2. 共享任务列表
团队激活期间,TaskCreate、TaskList、TaskGet、TaskUpdate 都指向同一份团队任务列表,lead 和所有队友看到的是相同任务。认领规则很严谨:
- 用
TaskUpdate({ taskId: "1", status: "in_progress" })认领,认领和依赖检查是串行的,不会出现两个队友抢到同一任务; - 只有任务 owner 能把它释放回
pending或标记为completed; - 队友运行结束时,未完成的认领自动回到
pending,不会丢任务。
每轮系统提示词中还会注入一份团队状态快照——谁在跑、谁空闲、谁 stale,以及完整的工作流规则,源码见 src/agents/teamPromptInjection.ts。
第四步:TeamDelete 解散团队收尾
工作完成后调用 TeamDelete():删除团队文件、各队友收件箱和共享任务列表,会话回到单 Agent 模式。
- 仍有活跃队友时拒绝删除——先用
SendMessage发出 shutdown 请求等他们完成; - 队友留下的 dirty worktree 不会被自动删除,会提示你手动审查,避免误删未提交的工作;
- 崩溃后残留的团队,可以用
TeamDelete({ team_name: "…", forceStale: true })强制清理,但活的成员永远不会被强删。
崩溃恢复:resume 找回未完成的团队
这是 Agent Teams 最贴心的设计之一:CLI 进程意外退出后,团队文件还留在磁盘上,直接 TeamDelete 之前也可以恢复现场。
重启后调用 TeamCreate({ team_name: "<name>", resume: true }),系统会:
- 拒绝接管 lead 进程还活着的团队(防止两个大脑抢一个身体);
- 把上一轮的活跃成员标记为
stale,并把它们认领的任务全部退回 pending; - 不会自动重启这些队友的模型调用——你需要审查那些任务,再手动启动新的队友运行。
详细的恢复语义见官方文档 docs/agent-teams.md。
终端里如何观察队友动态
队友是后台运行的,主界面不会被打断,但你可以随时围观:
Shift+↑/Shift+↓:打开队友选择器,上下移动光标;Enter:进入某个队友的实时视图,看它读了什么文件、跑了什么命令;k:在选人界面按 k 可以停掉高亮的队友;Esc:返回主会话。
交互细节实现在 src/ui/hooks/useTeammateNavigation.ts。此外,当队友消息到达时,空闲的交互会话会被唤醒,你不需要轮询。
多智能体协作最佳实践:什么时候该组队
| 场景 | 推荐做法 |
|---|---|
| 后端 + 前端 + 审查等长时并行角色 | 开团队,TeamCreate 后派命名队友 |
| 单个短小的子任务(查一个函数、读一个文件) | 普通 Agent(...) 前台调用即可,不用组队 |
| 队友间有依赖关系 | 用共享任务列表的 pending/in_progress/completed 状态表达依赖 |
| 队友改同一批文件 | 加 isolation: "worktree" 隔离工作区 |
| 需要立刻叫停 | abort_request;优雅停则用 shutdown_request |
一句话总结:任务能自然拆成多个长跑角色才组队;拆不开就别折腾,单 Agent 或普通子 Agent 更简单可靠。
想深入验证团队行为,可以跑一下并发成员加入、版本校验、任务争抢和进程退出恢复的完整测试:
npm run test:team-lifecycle
(测试入口:src/scripts/test-team-lifecycle.ts)
写在最后
easy-agent 的 Agent Teams 把「多智能体协作」做成了有边界、可恢复的机制:一个 lead 调度、命名队友并行、收件箱通信、共享任务列表、崩溃可恢复——而且全部状态透明地落在本地磁盘,不上报任何遥测。如果你的需求天然可以分工,不妨按本文的四步工作流开一个团队,让多个 AI 队友帮你把复杂需求拆着做完。更多整体能力介绍见 README.zh-CN.md 与配置文档 docs/configuration.md。


