agent-swarm

安装和使用 agent-swarm

main 中的仓库是权威来源。执行操作前，请重新获取引用的文件，因为此已安装技能是快照。 命令或选项发生变化时，请使用当前示例。标记已完成的清单项。记录跳过的可选项及原因。

安装

• 必需：确定目标环境。 确认主机、Compose 或 Kubernetes、执行框架、凭据、Agent 数量，以及采用私有还是公开访问。默认使用 Compose 示例中的所有 Agent，即参考部署配置（1 个负责人和 11 个工作 Agent）；只有在有明确理由时才减少数量。这些选择会决定资源和网络配置。阅读部署指南。
• 必需：检查先决条件。 Compose 需要 Git、带 Compose v2 的 Docker、OpenSSL、curl 和 jq。Kubernetes 需要 kubectl、Helm 和持久化存储。确认有足够的容量运行所选工作 Agent。阅读 Compose 示例和 chart 配置值。
• 必需：为组件配置最低要求。 保持 .env 精简：仅包含启动身份、身份验证、加密、URL 和执行框架凭据。通过 swarm config 设置受支持的非启动配置项，以便系统验证并重新加载这些配置。应用组件最低配置中的全部三个层级。
• 必需：保护机密信息和持久化数据。 生成 API 密钥，并将加密密钥与数据库一同妥善保存。每个 Agent 都需要独立的个人卷，其中存放其首次启动时生成的 UUID。该卷可保留身份并支持任务恢复；加密密钥则用于保护加密后的凭据。阅读机密信息加密和组件最低配置。
• 必需，二选一：Compose。 克隆仓库，复制 .env.docker.example，设置 API_KEY 和执行框架凭据（Agent ID 为可选项），然后启动示例服务。示例定义了实际的环境变量和卷。执行 Compose 操作步骤。
• 必需，二选一：Kubernetes。 创建凭据 Secret，并安装 oci://ghcr.io/desplega-ai/charts/agent-swarm。使用 --version 固定版本；省略此参数将安装最新发布的 chart。镜像标签与 chart 的 appVersion 一致，因此应通过 chart 版本固定镜像版本。使用池副本数设置工作 Agent 的规模。执行 Helm 操作步骤。按照 Kubernetes 和 Helm 配置 Ingress、仪表板连接和 CORS。
• 必需：将 API 卷挂载到 /app/data，绝不要挂载到 /app。 命名卷会覆盖其挂载路径下的镜像内容，因此挂载到 /app 会使镜像中的 migrations/ 和 package.json 在安装时固定不变，而二进制文件仍会升级。随后，API 会查询一个没有任何迁移创建的数据库架构，而 /health 会报告过时版本并持续显示正常。现有安装需要一次性迁移数据。执行版本固定和升级操作步骤。
• 必需：固定镜像版本。 使用 Compose 时，在 .env 中将 AGENT_SWARM_VERSION 设置为一个已发布版本，并确认 API 和每个 Agent 解析到相同的标签。留空表示使用 latest；它会随每次提交到 main 而变动，并非发布版本。若设置了 pull_policy: always，未固定版本的部署栈可能在任何一次重启时更换版本。固定版本与挂载到 /app/data 缺一不可；仅固定版本并不能确保升级安全。执行版本固定和升级操作步骤。
• 必需：验证运行情况。 检查 /health、经过身份验证的 /api/agents，以及一个已完成的任务。API 健康并不能证明工作 Agent 可以执行任务。执行 API 验证操作步骤。
• 可选：一同部署 agent-fs。 当 Agent 需要持久化文件交换时，启用共享文件、附件和搜索。Compose 配置包含 agent-fs 和 MinIO。Helm 可通过 agentFs.enabled 启用它。阅读 agent-fs 部署指南及其最低配置和省略操作步骤。
• 可选：选择其他执行框架。 如果凭据或模型有相应要求，可选择 Codex、搭配 OpenRouter 的 pi，或 Bedrock。阅读执行框架配置指南和凭据最低配置。
• 建议：配置 HTTPS。 托管式仪表板、OAuth 回调和 Webhook 需要公开的 HTTPS API 源站。Compose 附带 Caddy tls 配置文件；chart 提供了 cert-manager 快捷配置。执行 HTTPS 操作步骤。
• 可选：使用其他部署管理器。 使用部署指南配置 VPS 代理、Dokploy 和 Coolify。使用 DEPLOYMENT.md配置 systemd。引导向导是另一种方案，详见入门指南。
• 必需，在任何升级前：备份数据库和加密密钥。 迁移只能向前执行，因此重新固定到较旧标签并不能回滚；备份才可以。使用 Compose 时执行升级操作步骤，使用 Helm 时执行 Kubernetes 运维操作步骤。
• 建议在 Kubernetes 上使用：了解日常运维。 升级、调整池规模、轮换凭据、备份以及故障排除表格，均见 Kubernetes 运维操作步骤。
• 可选：添加备份和遥测。 备份可用于恢复。OpenTelemetry 可展示服务活动。阅读 chart 备份设置和 OpenTelemetry。

按以下顺序使用

• 必需：通过 HTTP 和 MCP 访问 API。 HTTP 在端口 3013 上提供 /docs 和 /openapi.json。MCP 使用 /mcp。使用 bunx @desplega.ai/agent-swarm connect 连接你的编码 Agent。这样即可让你的项目访问该 swarm。请按照 API 和编码 Agent 操作流程操作。
• 可选：连接管理 UI。 将 https://app.agent-swarm.dev 指向你的 API，或在本地运行 apps/ui。使用它检查任务、管理 Agent 并配置部署。请阅读 UI 指南和本地 UI 命令。
• 可选：先启用 Slack。 Slack 提供原生任务接收、回复和引导功能。导入 slack-manifest.json，创建两个令牌，配置 API，然后给机器人发送私信。请执行 Slack 操作流程。
• 可选：启用 GitHub 或 GitLab。 连接仓库事件，以便 Agent 响应开发工作。请阅读 GitHub、GitLab和集成最低要求。
• 可选：启用其他集成。 添加为工作提供支持的系统。请阅读 Linear、Jira、AgentMail、Kapso和 Sentry。请落实这些集成的最低要求。
• 可选：添加连接。 注册 OpenAPI、GraphQL 或 MCP 服务，让脚本能够通过类型化接口访问外部系统。通过负责人或 Settings → Connections 配置连接。请阅读脚本连接。如需更多集成，请通过 x 路由器使用 Composio。
• 可选：深入探索。 当周期性工作需要上下文或自动化时，请使用持久能力。请阅读记忆、工作流、计划任务、脚本、应用和工作 Agent 技能。