Agent Swarm

这是什么？适合谁？

Agent Swarm（agent-swarm.dev，desplega.sh 出品）是一个开源的企业级 Agentic Operating System——把「AI 干活」组织成一套完整的操作系统：一个 lead agent 负责接收与分派任务，Worker（可以是 Claude Code、Codex、pi、opencode、Devin 或任意 ACP Agent）在相互隔离的 Docker 容器中执行，配合跨会话持久的共享记忆（persistent brain）、工具、定时任务、脚本与应用，以及 review gate 审查门禁，最终把工作成果以 Pull Request、Slack 回复或邮件回复的形式交付。

它解决的核心痛点：编码 Agent 直接跑在本机会互相干扰、上下文丢失、无法审计。Agent Swarm 把每个任务放进隔离容器，Worker 之间通过 lead agent 协调，记忆与身份跨会话持久化，「昨天的经验」不会因为今天重启而消失。

适合谁：

• 团队想把 AI 编码 Agent（Claude Code/Codex 等）接入真实工作流（Slack 里 @ 一下就开工，PR 自动提交）的技术团队
• 需要多 Agent 并行干活且有审查合规要求（review gate、RBAC、任务审计）的工程组织
• 想自托管（数据不出域）而非用 SaaS Agent 平台的企业

不适合谁：只想本地跑一个编码 Agent 的个人开发者（直接用 Claude Code 更简单）；没有 Docker/K8s 运维能力的团队；要求开箱即用零配置的小白用户。

准备工作

1. 环境：Docker + Docker Compose（或 Kubernetes + Helm，官方提供 OCI Helm chart）；API Key + 至少一个 harness 凭据（如 Claude Code / Codex 的凭据）
2. 成本：MIT 免费开源；运行成本 = 服务器资源 + 所用 Agent/模型的 API 计费；官方另有 Agent Swarm Cloud 服务（网站条款单独说明）
3. 时间：Docker Compose 部署约 30-60 分钟（含配置 8 个 agent UUID 与加密密钥）；接通 Slack 并跑通第一个任务约 1 小时
4. 前置知识：Docker/Compose 基本操作、.env 配置、OAuth/凭据管理概念；会用至少一种编码 Agent
5. 替代方案：OpenHands（开源 Agent 平台）、Devin（SaaS）、LangGraph（代码编排库）——Agent Swarm 的差异点是「多 Worker 容器隔离 + lead-worker 架构 + 企业集成开箱即用」

快速上手（3 步）

第一步：安装 operator skill 或克隆部署

给自己的编码 Agent 装 operator skill（推荐，Agent 会自己照着部署）：

npx skills add desplega-ai/agent-swarm

或手动部署 Docker Compose：

git clone https://github.com/desplega-ai/agent-swarm.git && cd agent-swarm
cp .env.docker.example .env   # 填 API_KEY、harness 凭据、8 个 agent UUID
openssl rand -base64 32 > encryption_key
chmod 600 .env encryption_key
docker compose -f docker-compose.example.yml --env-file .env up -d

预期产出：API 服务跑在 http://localhost:3013（/docs 与 /openapi.json 可查），基础设施容器全部健康。README 强调先读 Compose checklist。

第二步：接一个任务入口（Slack 或 GitHub）

在集成配置里接通 Slack（或 GitHub/GitLab/Linear/Jira/邮件）——lead agent 从这些渠道接收目标。发一条 Slack 消息描述任务，lead agent 会拆解并分派给容器里的 Worker。

预期产出：Slack 线程里看到 lead agent 的任务确认与 Worker 分派，可在官方 Dashboard（app.agent-swarm.dev 连接你的自托管 API）实时观察执行。

第三步：跑通一个「Slack → PR」任务

在 Slack 里 @ 你的 swarm：「在 xxx 仓库给 Y 功能加个测试并提 PR」。Lead agent 分派 Worker 在隔离容器里 checkout、编码、跑测试，经 review gate 审查后提交 PR 并回到 Slack 线程报告。

预期产出：GitHub 上出现一个 PR，Slack 线程收到完成回复；Dashboard 中任务记录、Worker 执行历史与共享记忆全部可查。

常见踩坑（症状 → 原因 → 解决）

1. .env 里 8 个 agent UUID 不知道怎么填。原因：系统为多 Worker 预置身份槽位，每个 UUID 对应一个 agent 身份。解决：用 uuidgen 生成 8 个即可，凭据与身份随后在 Dashboard 里绑定；README 的 Compose checklist 有逐项说明。
2. encryption_key 权限报错或服务起不来。原因：密钥文件权限过宽被安全检查拒绝。解决：严格按 chmod 600 .env encryption_key 设置权限再 up -d。
3. 升级老 worker 后行为异常。原因：官方明确「升级旧 worker 时保持 MULTI_RUNTIME_ENABLED=false，直到它们支持 runtime identities」——多运行时特性默认开启，但旧 worker 不兼容。解决：在环境变量里显式关闭，逐个升级 worker 后再放开（见官方 environment reference）。
4. 把 Cloud 服务和自托管搞混。原因：网站与 Cloud 服务有自己的隐私/条款页，self-hosted 软件是 MIT——两者法律边界不同。解决：只用自托管即纯 MIT；要用 Dashboard 云端界面时单独读 agent-swarm.dev 的 terms/privacy。
5. Worker 容器里模型凭据失效。原因：harness 凭据（Claude Code/Codex 的 OAuth token 等）有过期机制，容器重启后可能未自动刷新。解决：在 Dashboard 的凭据管理里更新；把凭据刷新纳入运维例行。

初级用法

• 单渠道起步：先只接 Slack 一个入口，跑通 lead→worker→PR 全链路后再加 GitHub/Jira
• Dashboard 观察员模式：把 app.agent-swarm.dev 连到自托管 API，先只观察不干预，熟悉任务生命周期（deferred task、review gate、realtime rooms）
• 定时任务：用内置 schedules 跑每日例行（如依赖检查报告），体会「OS」属性

高级玩法

• Schema 校验任务结果：调用方需要结构化 JSON 时用 MCP 的 send-task（schema-validated task results），把 swarm 当成可编程的任务执行引擎
• Deferred tasks 编排：用 defer-task 让任务在「所有/任一被监听任务到达终态」或截止时间时自动唤醒，实现跨任务依赖 DAG
• Extensions 自定义钩子：写 TypeScript 扩展 hook（作为 draft 安装、由 operator 激活），把公司内部审批/发布流程嵌进 swarm
• Realtime rooms 协作：共享页面状态、presence 与 live channels，做多 Agent 并行处理同一工单的场景

小技巧

1. 部署前必读 skills/agent-swarm/references/compose.md（官方 Compose checklist），比直接看 docker-compose.example.yml 少踩一半坑
2. 新部署默认开启 Slack thread renderer v2、queued steering、RBAC、task-tool preloading、hybrid memory search 等特性——升级老部署时逐项核对 feature defaults 再合并配置
3. 数据库保留策略默认 dry-run，生产启用前先确认 retention 配置
4. API 的 /docs（OpenAPI）是完整接口文档，自动化调用（CI 触发 swarm 任务）从这里入手
5. 多种 harness 可混用：Claude Code、Codex、pi、opencode、Devin、ACP Agent 都能当 Worker，按任务类型分配

常见问题 FAQ

Q1: 和 OpenHands、Devin 这类产品怎么选？

A: Devin 是 SaaS 闭源；OpenHands 是开源 Agent 平台但以单 Agent 会话为中心。Agent Swarm 的定位是「公司的 Agentic OS」——lead-worker 架构 + 容器隔离 Worker + 企业渠道集成（Slack/Jira/邮件）+ review gate/RBAC，适合组织级多任务并行；个人单任务场景 OpenHands 更轻。

Q2: 免费吗？Cloud 服务和自托管的关系？

A: 自托管软件 MIT 免费；Agent Swarm Cloud（网站与 Dashboard 云端部分）是独立服务，有单独的条款与隐私政策。Dashboard 也可以连接你自己的 API 使用。

Q3: 什么样的硬件规格够用？

A: 官方未给出硬性最低配置，但每个 Worker 一个 Docker 容器 + 基础设施（API、记忆存储）意味着中小团队建议 8 核 16GB 起步；K8s 路线用官方 Helm chart（charts/agent-swarm）做资源弹性。

Q4: 支持哪些编码 Agent 当 Worker？

A: README 明确：Claude Code、Codex、pi、opencode、Devin 或 ACP Agent，且可混用；「Your choice of harness and models」是产品主张之一。

Q5: 集成渠道有哪些？

A: Slack、GitHub、GitLab、Linear、Jira、AgentMail、WhatsApp（Kapso）、Composio、Sentry、Devin、Serply search，官方有集成指南专页（docs.agent-swarm.dev/docs/integrations）。

Q6: 项目活跃度如何？

A: 高度活跃——2025-12-19 建仓，★804 / 🔱104，最近一次 push 2026-09-17（昨天），releases 每日一版（v1.149.1 → v1.150.0 → v1.151.0 连续三天发版），README 自述「This repo evolves every single day」。

免责声明

本文基于公开资料整理（GitHub 仓库 README 全文、GitHub API 实时数据、官方文档站可达性核验，采集日期 2026-09-18），AI 辅助生成。本站未实际部署该系统；多 Worker 容器编排的稳定性、Slack 集成体验与 review gate 的实际行为以实测为准。

参考链接

• GitHub 仓库 desplega-ai/agent-swarm
• 官网 agent-swarm.dev
• 官方文档 docs.agent-swarm.dev
• Agent 模板库 templates.agent-swarm.dev