Swarm-Lab：多智能体实验平台

我开源了一个多 AI Agent 实验平台------Swarm-Lab 开发全记录

GitHub：https://github.com/allensteveshaw/Swarm-Lab

欢迎 Star、Fork、提 Issue，有任何问题都可以在评论区交流。

一、为什么要做这个项目

最近一年，多智能体（Multi-Agent）这个方向越来越热。从 AutoGen 到 CrewAI，各种框架层出不穷，但我发现一个共同问题：大部分框架太重，抽象太多，你很难直观地看到 Agent 之间到底在发生什么。

我想要的是一个能在浏览器里实时观察 AI Agent 群体行为的平台------它们怎么交流，怎么分工，怎么涌现出超越单个 Agent 的能力。于是就有了 Swarm Lab。

这个项目的核心哲学来自一个极简的观察：一个 Agent 蜂群，其实只需要两种能力就能表达任意复杂的协作结构------

create：派生子 Agent
send：向任意 Agent 发消息

就这两个原语，足够了。

二、什么是 Agent 蜂群

"蜂群"这个比喻来自自然界：单只蜜蜂的智能非常有限，但几万只蜜蜂组成的蜂群却能完成极其复杂的任务------选址、筑巢、分工采蜜、调节巢内温度。没有一只蜜蜂知道"全局计划"，但整体行为高度有序。这种现象叫涌现（Emergence）。

AI Agent 蜂群的思路与此相似：不靠一个超级 Agent 包揽所有事，而是让多个相对简单的 Agent 各司其职，通过相互通信协作完成复杂任务。

这带来几个实际好处：

并行：多个 Agent 同时工作，不用等一个超长 prompt 跑完
专业化：每个 Agent 聚焦一个角色（研究员、写作者、审阅者），比让一个 Agent 什么都做效果更好
可观测：拆分成多个 Agent 之后，你能看到每一步在发生什么，哪个环节出了问题
可替换：某个 Agent 的模型换成更强的，不影响其他 Agent

当然，蜂群也有它的问题：Agent 之间会产生大量消息，Token 消耗快；协调不好容易陷入循环；角色设计不合理会导致互相推诿。Swarm Lab 的一个重要用途，就是让你在实验环境里把这些问题暴露出来、研究清楚。

三、项目是什么

Swarm Lab 是一个全栈多智能体实验平台，基于 Next.js 构建，前后端一体，不需要单独部署 Python 服务。

它有两条核心实验路线：

路线	用途
协作实验	多 Agent 群聊、任务编排、子 Agent 派生、蓝图一键部署
博弈实验	谁是卧底、狼人杀------用真实游戏验证 AI 的策略推理能力

支持的 LLM 接入方式：GLM（智谱）、OpenRouter、任意 OpenAI 兼容接口（通义千问、DeepSeek、本地 Ollama 等）。不同 Agent 可以用不同的模型，在一个任务里混跑。

四、技术选型

选型原则只有一个：能跑起来，能看到效果，不过度工程化。

层级	选型
框架	Next.js 16（App Router，全栈，前后端统一）
前端	React 19 + TypeScript 5
样式	Tailwind CSS 4 + 自定义 CSS 设计令牌系统
动画	Framer Motion 11
图表	Recharts 3
ORM	Drizzle ORM
数据库	PostgreSQL 17
实时通信	Server-Sent Events（SSE）
缓存/发布订阅	Redis 7
工具协议	MCP SDK（Model Context Protocol）

选 Next.js 全栈的原因是：API 路由和页面在同一个项目里，本地开发只需要 npm run dev 一条命令，部署也简单。SSE 代替 WebSocket，因为 Agent 的消息流天然是单向推送，SSE 足够且更轻量。

五、核心功能详解

4.1 实验室大厅（/lab）

启动后进入这个页面，这是整个平台的控制台。

页面上方是四个 KPI 卡片：当前活跃 Agent 数、运行中的任务数、累计消息数量、消耗的 Token 总量。这些数据实时更新，让你对蜂群整体状态一目了然。

下方是三组图表：

消息趋势折线图：横轴是时间，纵轴是消息量，能直观看出任务执行期间的活跃程度
任务终止原因饼图：任务是正常完成、超时、还是被手动停止的，一眼看出
模型使用占比环形图：哪个模型用得最多，跑混合模型实验时特别有用
游戏场次统计柱状图：记录你跑了多少局卧底和狼人杀

右侧是近期工作区列表，点击直接进入对应的 Agent 群聊环境。

4.2 消息协作中心（/im）

这是整个平台最核心的页面，三栏布局：左侧会话列表、中间消息流、右侧 Agent 详情面板。

左侧面板列出当前工作区的所有群组，每个群组显示未读消息数和最后一条消息预览。Agent 头像旁边有状态指示点：绿色表示空闲（IDLE），黄色表示正在推理（BUSY），灰色表示休眠（WAKING）。

中间消息区是真正的多 Agent 群聊现场。每条消息气泡都有头像和角色标签，AI 的回复支持 Markdown 渲染，代码块有语法高亮，Mermaid 图表直接渲染。消息是流式传输的，你能看到 AI 一个字一个字地打出来。

右侧面板分四个子面板，每个有不同的颜色标识：

Content（青色）：Agent 当前输出的完整内容
Reasoning（紫色）：Agent 的推理过程（如果模型支持思维链）
Tools（琥珀色）：工具调用记录------Agent 调用了什么工具、参数是什么、返回了什么
History（绿色）：Agent 完整的上下文历史

页面内嵌了一个 Viz 可视化画布：用力导向图展示所有 Agent 之间的通信关系，消息发送时会有动态光束在节点间流动，直观感受信息流向。

任务系统是另一个亮点。你可以从预设模板（辩论、论文写作、代码评审等）一键发起任务，设置 Token 预算上限和最大对话轮数，防止 Agent 陷入死循环。任务结束后系统会自动生成一份 AI 分析报告，总结任务过程中的关键转折点。

4.3 蓝图工坊（/blueprints）

蓝图是预配置好的蜂群架构，一键部署，不需要手动创建 Agent、配置关系。

内置四种蓝图：

蓝图	角色构成	典型用途
辩论	正方 + 反方 + 主持人	让两个 AI 就同一命题对撞，收集不同视角
论文写作	研究员 + 写作者 + 审阅者	三个 Agent 协作完成长文档
代码评审	开发者 + 高级工程师 + QA	代码自动走评审流程
产品设计	PM + 设计师 + 工程师	从需求到方案自动推演

每次启动蓝图都会创建独立的新工作区，互不干扰，可以同时跑多个。

4.4 游戏实验场（/undercover、/werewolf）

这是让 Swarm Lab 区别于其他平台的部分。用真实的社交推理游戏来量化 AI 策略能力。

谁是卧底：1 个人类玩家 + 5 个 AI Agent，每局随机选出一个 AI 作为卧底，拿到不同的词。所有人轮流发言描述自己的词，然后投票淘汰。你能观察到 AI 是怎么根据别人的发言调整自己的描述策略的------哪些 AI 比较激进，哪些比较保守，哪些善于伪装。

狼人杀：6 人局（人类可选择参与或旁观），包含狼人、预言家、女巫三个特殊角色。夜晚阶段 AI 独立执行各自的技能，白天阶段所有人发言讨论再投票。整个流程完全自动跑完，你看日志就能分析 AI 的博弈逻辑。

游戏界面做了圆桌布局，玩家头像围坐一圈，发言时有气泡弹出，淘汰时有动画效果。游戏结束后同样会生成 AI 复盘分析报告。

4.5 组织关系图谱（/graph）

独立页面展示当前工作区所有 Agent 的父子层级关系。节点按角色类型有不同颜色，边表示派生关系。当 Agent 动态创建子 Agent 时，图谱实时更新。

六、几个设计细节

Agent 状态机：每个 Agent 有 IDLE / BUSY / WAKING 三种状态。消息到达时 Agent 从 IDLE 切到 WAKING，开始推理后切到 BUSY，输出完毕回到 IDLE。前端通过 SSE 订阅这个状态流，头像旁的状态点实时变化。

防死循环机制：任务系统内置了重复消息检测，当 Agent 连续输出相似内容超过阈值时，自动中断任务并生成原因说明，避免无效的 Token 消耗。

热重载连接池 ：开发模式下 Next.js 频繁热重载，如果每次都新建数据库连接会把连接池打爆。用 globalThis 挂载单例解决这个问题------进程内复用同一个连接实例，连接数始终可控。

多模型混跑：每个 Agent 独立绑定一个模型配置（Model Profile），同一个任务里可以有用 GPT-4o 的、用 Claude 的、用 GLM 的不同 Agent 协作，观察异构模型的协作效果。

CSS 设计令牌系统：整套 UI 用 CSS 变量定义颜色、间距、圆角等设计令牌，深色主题下各组件的层级关系清晰。状态点、气泡、游戏座位等都有对应的 CSS class，方便后续主题扩展。

七、本地跑起来

环境要求：Node.js 20+，Docker Desktop。

bash 复制代码

# 克隆
git clone https://github.com/allensteveshaw/Swarm-Lab.git
cd Swarm-Lab/backend

# 安装依赖
npm install

# 复制并填写配置
cp .env.example .env.local
# 编辑 .env.local，填入你的 LLM API Key

# 启动数据库
docker compose up -d

# 启动服务
npm run dev          # macOS / Linux
npm run dev:win      # Windows

# 初始化数据库（首次必须执行）
curl -X POST http://localhost:3017/api/admin/init-db

Windows 用户也可以直接双击根目录的 start_swarm_lab.bat，一键完成上面所有步骤。

配置文件里支持三种 LLM 接入方式，配一种就够用：

env 复制代码

# 方案 A：智谱 GLM
LLM_PROVIDER=glm
GLM_API_KEY=你的key

# 方案 B：OpenRouter（可接 Claude、GPT-4o 等）
LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=你的key

# 方案 C：OpenAI 兼容（通义千问、DeepSeek、本地 Ollama）
LLM_PROVIDER=openai_compatible
OPENAI_COMPAT_API_KEY=你的key
OPENAI_COMPAT_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_COMPAT_MODEL=qwen-max-latest

八、接下来想做的

Agent 记忆系统：目前每个 Agent 的上下文是滚动窗口，想加入长期记忆，让 Agent 能记住跨任务的信息
更多蓝图模板：头脑风暴、市场调研、测试生成等场景
更多游戏：考虑加入阿瓦隆（Avalon），对抗性更强
可视化增强：Viz 画布目前是力导向图，想加入时间轴回放功能，能重播整个任务过程

九、致谢

Swarm-Lab 不是从零开始写的。它的地基来自一个开源项目------@chmod777john 的 Swarm-IDE。

第一次看到 Swarm-IDE 的时候，我被它的架构设计打动了。它用极简的方式验证了一个核心命题：Agent 蜂群只需要 create 和 send 两个原语，就能表达任意复杂的协作结构。代码干净，思路清晰，没有多余的抽象。

但 Swarm-IDE 定位是概念验证（Proof of Concept），很多地方只有骨架，离"能直接用"还有距离：没有 Dashboard、没有数据统计、没有游戏模式、没有蓝图系统、Windows 环境跑起来也需要折腾。

Swarm-Lab 的工作就是在这个骨架上，把"能用"这件事做完：

补全了实验室大厅（数据大盘、图表、工作区管理）
加入了蓝图工坊（四套预配置蜂群，一键部署）
加入了游戏实验场（谁是卧底 + 狼人杀，用博弈量化 AI 策略）
完善了任务编排系统（Token 预算、防死循环、任务复盘报告）
加入了多模型配置管理（每个 Agent 独立绑定模型）
重写了整套 UI（CSS 设计令牌系统、深色主题、动画细节）
做了完整的 Windows 支持（一键启动脚本、PowerShell 兼容）
修复了开发模式下的数据库连接泄漏问题
修复了 group_members 悬空行导致的成员计数错误

感谢原作者开源了那个干净的起点。没有它，Swarm-Lab 不会以现在这个形态存在。

十、总结

Swarm-Lab 本质上是一个可观测的 AI Agent 沙盒。它不追求生产级的稳定性，追求的是让你能快速搭起一个多 Agent 场景，直观看到发生了什么，然后调整参数再试一次。

多 Agent 系统最有趣的地方不在于单个 Agent 有多强，而在于多个普通 Agent 组合在一起，能否涌现出超越个体的行为模式。这个问题目前还没有标准答案，Swarm Lab 就是为了帮你去探索这个答案而存在的。

如果你也在研究 Multi-Agent，欢迎来 Star 和贡献：

https://github.com/allensteveshaw/Swarm-Lab

有问题、有想法，评论区见。