Agent Swarm 完全指南：用开源的多 Agent 编排引擎构建企业级 AI 团队

当你的团队从单条 Prompt 进化到几十个 AI Agent 协同工作时，”谁来协调 Agent 之间的任务”就成了一个绕不开的问题。每个 Agent 有自己的工具集、记忆和角色定位，但缺乏一个中央调度层——这就像一支没有指挥的乐队，每个乐手都在独自演奏。

Agent Swarm 正是为解决这个问题而生的开源编排引擎。它提供 Lead Agent 统一调度 + Worker Agent Docker 隔离执行的架构，让多个 AI Agent 像一支真正的团队那样工作。

什么是 Agent Swarm

Agent Swarm 是一套开源的多 Agent 编排框架（MIT 协议，556⭐），由 Desplega Labs 团队开发。它的核心理念是：每个公司都应该拥有一个持续进化的智能层——Agent Swarm 就是那层”智慧大脑”。

与传统的单 Agent 模式不同，Agent Swarm 引入了三个关键设计：

• Lead Agent（领导 Agent）：接收任务，分解为子任务，分配给 Worker，汇总结果
• Worker Agent（工人 Agent）：在 Docker 隔离环境中执行具体工作（编码、研究、审查、测试等）
• 共享记忆系统：Worker 执行完成后将经验写回向量数据库，整个集群越来越聪明

你可以把它理解为 AI 版的 Kubernetes——只是编排的不是容器，而是 AI Agent。

架构速览：Hub-and-Spoke 模式

Agent Swarm 采用 Hub-and-Spoke（中心辐射）架构：

用户 (Slack / GitHub / Email / CLI)
         |
    Lead Agent  ←→  MCP API Server  ←→  SQLite DB
         |
    ┌────┼────┐
Worker  Worker  Worker
(Docker 容器，完整开发环境)

核心组件包括：

• MCP API 服务器：中心协调点，对外暴露 MCP 协议接口（支持 STDIO 和 HTTP 两种传输模式），所有 Agent 的注册、任务分配、状态管理都在这里完成。默认运行在 3013 端口。
• SQLite 数据库：存储所有状态——Agent 配置、任务队列、记忆向量、集成配置。
• 调度器：轮询式定时任务触发器，支持 cron 表达式。
• 工作流引擎：DAG（有向无环图）执行器，8 种执行器类型，支持 checkpoint 持久化和版本历史。
• 心跳模块：每 90 秒扫描集群健康状态，自动修复常见问题（死锁检测、Worker 状态修正）。

快速上手：5 分钟启动你的第一个 Swarm

Agent Swarm 提供了两种启动方式：

方式一：Onboard 向导（推荐）

bunx @desplega.ai/agent-swarm onboard
npx @desplega.ai/agent-swarm onboard

交互式向导会收集凭据、生成 docker-compose.yml 和 .env 文件、启动堆栈并验证健康状态。你也可以使用非交互模式：

ANTHROPIC_API_KEY=sk-ant-*** npx @desplega.ai/agent-swarm onboard --yes --preset=dev

可用预设：dev、content、research、solo。使用 --dry-run 可预览文件内容而不写入。

方式二：手动 Docker Compose

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm
cp .env.docker.example .env
docker compose -f docker-compose.example.yml --env-file .env up -d

启动后，API 运行在 http://localhost:3013，交互式文档在 http://localhost:3013/docs。

使用模板赋予 Agent 角色

Agent Swarm 内置了官方模板系统，可以为不同类型的 Worker 预配置身份、技能和初始化脚本。只需设置 TEMPLATE_ID 环境变量：

TEMPLATE_ID=official/coder docker compose up worker-1 -d

TEMPLATE_ID=official/lead docker compose up lead -d

官方模板包括：

模板每 24 小时从模板注册中心缓存刷新一次。你还可以创建自定义模板并贡献给社区。

核心特性详解

1. 共享记忆与持久身份

Agent Swarm 的独特之处在于它的记忆系统并非简单的向量检索。Worker 执行任务后会将学到的经验写回共享记忆库，后续任务可以直接引用。记忆系统支持：

• 混合召回：向量检索 + 全文搜索结合
• 原地编辑：Agent 可修正已有记忆而不丢失 ID 或历史
• 角色身份：每个 Agent 拥有独立的 SOUL 文件和 CLAUDE.md，定义其个性、专业领域和行为规则

2. Human-in-the-Loop 审批门

对于不可逆操作（如生产环境部署、资金操作），Agent Swarm 支持 HITL（Human-in-the-Loop）门控机制。Workflow 中可以插入审批节点，只有人工确认后才继续执行。

3. 多通道任务输入

Agent Swarm 支持丰富的任务来源：

• Slack：DM 或 @提及机器人创建任务
• GitHub/GitLab：Issue/PR 事件自动触发
• Email：每个 Agent 拥有独立收件箱
• WhatsApp：通过 Kapso 集成
• Linear/Jira：双向票据同步
• HTTP API：直接通过 REST 接口创建任务

4. Harness 与 LLM 无关

Agent Swarm 设计了”Harness”抽象层，可以接入不同的 AI 后端：

• Claude Code（默认推荐）
• OpenAI Codex
• pi-mono（支持 Anthropic、OpenRouter、Amazon Bedrock）
• Devin
• 原始 LLM API

任务定义中使用抽象的 modelTier 意图（smol、regular、smart、ultra），运行时动态解析到具体提供商。

5. 工作流引擎与 Drain Loop 模式

Agent Swarm 的工作流引擎基于 DAG（有向无环图）实现，支持：

• 条件分支、重试策略、并行执行
• 每个步骤的 checkpoint 持久化
• 定时触发、Webhook 触发、手动触发

内置的 Drain Loop 模式是一种高频使用的设计模式：一个 Issue 进入后，自动触发分析 → 方案设计 → 编码 → 审查 → 测试 → PR 提交的链路，每一步都生成可追溯的产物。

CLI 命令参考

Agent Swarm 提供了完整的 CLI 工具集：

bunx @desplega.ai/agent-swarm 
npx @desplega.ai/agent-swarm 

如何接入 Claude Code 作为 Lead Agent

如果你已经在使用 Claude Code，只需运行：

npx @desplega.ai/agent-swarm connect

然后告诉 Claude Code 注册为 Lead Agent。connect 命令会自动创建 .mcp.json 和 .claude/settings.local.json，包含服务器 URL 和 API Key。从此你的本地 Claude Code 就可以通过 MCP 协议与 Swarm 集群交互，将任务委托给远程 Worker。

生产部署建议

Agent Swarm 的生产部署推荐使用 Docker Compose 多 Worker 模式 + systemd 管理 API 进程。完整的部署指南在项目的 DEPLOYMENT.md 和文档站的部署章节中。

一些关键配置项：

• 监控面板：http://localhost:5274（本地启动 UI）
• 环境变量：通过 .env 配置 API Key、Harness 凭据、数据库路径
• 日志：Worker 输出流向 Docker 日志，可通过 docker logs 查看

总结

Agent Swarm 代表了一种更高维度的 AI 工程范式——不再是”给我写段代码”的单次对话，而是构建一个持续学习、持续进化的 Agent 团队。它的 Lead-Worker 架构、Docker 隔离执行和共享记忆系统，让企业级多 Agent 编排变得可操作、可观测、可扩展。

对于已经在使用 Claude Code 或 Codex 的团队，Agent Swarm 是一个自然的能力延伸：从单 Agent 编码助手升级到多 Agent 团队协作平台。开源、MIT 许可、丰富的模板系统，都让它成为值得投入时间了解的工具。

相关链接

• GitHub 仓库
• 官方文档
• 模板注册中心
• 在线 Dashboard
• 社区 Discord