Swarm.js: 用 Node.js 编排多智能体系统的轻量级框架

图1: youseai/openai-swarm-node 仓库封面图

想象一下: 你正在开发一个客服系统，需要同时处理售前咨询、技术支持、投诉处理三类完全不同的用户请求。传统的做法是把所有逻辑塞进一个大模型 prompt 里，结果 prompt 越来越长、效果越来越差，还动不动就答非所问。

Swarm.js 提供了另一种思路: 让每个专业 Agent 各司其职、按需交接。

背景: 从 Python 到 Node.js 的桥接

2024年10月，OpenAI 发布了一个实验性框架 OpenAI Swarm，用于探索多智能体系统的轻量级编排方案。Swarm 的核心理念是让多个 Agent 通过简单的指令和函数调用进行协作，而非依赖复杂的编排层。

然而 Swarm 最初只支持 Python，限制了 Node.js 生态中的大量开发者。Pulkit Garg 在 2024 年 10 月中旬推出了 Swarm.js (即 openai-swarm-node)，将 Swarm 的核心抽象完整移植到 Node.js 平台，让 JavaScript/TypeScript 开发者也能用上这套多智能体编排范式。

项目发布后短短数日内便获得 147 颗 Stars，目前已有 22 个 Fork，npm 周下载量持续上升。

类比: 智能体协作就像客服中心

把 Swarm.js 的架构想象成一家客服中心:

• Agent (智能体): 就是接待员，每个接待员有自己擅长的领域 (通过 instructions 定义角色定位)
• Swarm (蜂群): 就是呼叫中心调度系统，负责把来电分配给合适的接待员
• Handoff (交接): 当一个接待员发现自己处理不了时，把客户转给另一个更专业的同事
• Function/Tool (函数/工具): 接待员手上的各种业务系统入口，比如查询订单、办理退款

这套模式的优势在于，每个 Agent 保持职责单一、prompt 简短，容易维护和测试。

核心功能: 简洁而不简单

Agent 的定义与工具注册

Swarm.js 的 Agent 接受三个核心参数: name(名称)、instructions(角色指令) 和 tools(可用工具):

const salesAgent = new Agent({
  name: "Sales Agent",
  instructions: "You are a helpful sales agent specializing in product recommendations.",
  tools: [lookUpItem, executeRefund]
});

Tools 支持两种格式: 普通 JavaScript 函数 (必须有 JSDoc 注释) 或 OpenAI Function Calling 标准格式的对象。框架会自动将函数转换为 JSON Schema，供 GPT 调用。

Handoff (智能体交接)

这是 Swarm 最有特色的设计。当一个 Agent 发现任务超出自己范围时，可以交棒给另一个 Agent:

const transferToAgentB = () => agentB;
const agentA = new Agent({
  name: "Agent A",
  tools: [{ name: 'transferToAgentB', fn: transferToAgentB }]
});

GPT 会根据对话内容决定是否触发交接，整个过程对用户透明。

Context Variables (上下文变量)

在多 Agent 协作时，需要一个共享的上下文来传递信息，比如记录用户当前所在的部门:

const response = await swarm.run({
  agent: agentA,
  messages: [{ role: "user", content: "I need help with my order." }],
  contextVariables: { userId: "12345" }
});

Streaming (流式响应)

支持 stream: true 选项，实时输出 GPT 的 token 片段:

const stream = client.run({ agent, messages, stream: true });
for await (const chunk of stream) {
  console.log(chunk);
}

代码架构: 清晰的四文件结构

Swarm.js 源码仅 4 个文件，总计约 8KB，实现了完整的 Swarm 核心逻辑:

文件	职责	核心逻辑
src/index.js	入口 + 演示代码	定义 lookUpItem/executeRefund 工具，运行示例
src/swarm.js	Swarm 主类	循环调用 Chat Completions API，处理 tool_calls
src/agent.js	Agent 类	管理 instructions/tools，默认使用 gpt-4o
src/tool.js	工具转换器	JSDoc to JSON Schema，将函数注册为 GPT Function

技术栈非常精简: 只依赖 openai(^4.67.3)、dotenv(^16.4.5) 和 joi(^17.13.3)，无任何重型框架。

上手门槛: 极低

安装只需一行命令:

npm install openai-swarm-node

然后配置 OPENAI_API_KEY 环境变量即可运行。

官方提供了 4 个开箱即用的示例项目: basic(基础用法)、triage_agent(分流智能体)、airline(航空公司客服) 和 support_bot(多 Agent 协作客服)。

无 Web UI，完全通过 JavaScript 代码调用，适合嵌入到现有 Node.js 应用中。

局限与注意事项

1. 实验性质: 作者在 README 开头醒目声明这是实验性、教育性框架，不适合生产环境。没有官方支持，API 可能随时变更。
2. 无持久状态: Agent 在调用之间是无状态的 (stateless)，每次 swarm.run() 调用都是独立上下文。如果需要维护会话状态，需要自己实现历史消息管理。
3. 非 OpenAI 官方产品: 虽然致敬 OpenAI Swarm，但这是社区独立实现，与 OpenAI 无直接关联。
4. ISC License: License 为 ISC (类似 BSD 2-Clause)，permissive 但非 Copyleft，企业使用需注意合规审查。
5. 测试覆盖缺失: package.json 中 test 脚本为空，大规模使用前需自行补充测试。

行业意义: 轻量化 Agent 范式的 Node.js 落地

随着 GPT-4o 等大模型 API 成本持续下降，多 Agent 协作正在从概念走向工程化。Swarm.js 的价值在于它不追求大而全，而是专注于最核心的两个问题: 如何定义 Agent 和如何让 Agent 之间交接。

这种极简主义设计让整个框架的学习曲线几乎为零，同时也为更复杂的 Agent 框架 (如 LangChain Agents、CrewAI) 提供了互补思路。

图2: AI 神经网络 - 多 Agent 协作的隐喻

Node.js 生态拥有全球最大的 npm 注册表、海量的 Web 服务和中间件积累。Swarm.js 让 AI Agent 的编排能力可以直接插入到 REST API 服务器、微服务网关、Express/Koa 应用中，打通了 LLM 能力与 Node.js 生态的最后一公里。