OpenAI 助手群管理器：将您的 OpenAI 助手转化为一支“军队”的库.

| | Mintplex Labs Inc | NPM

什么是 Swarm 管理器？

OpenAI 的助手 API 为开发构建自主 AI 助手（通常称为“代理”）的开发者提供了极大的便利。这个 Node.js 库通过一次 API 调用即可访问您整个自定义代理注册表及其功能。现在，一个代理“管理器”可以智能且快速地并行委派任务给一个或多个其他助手，从而让您轻松处理委派任务的操作。

过去需要手动管理每个助手负责什么工作的繁琐工作，如今都由这个库自动完成，并以一种简洁的方式呈现出来。

它是如何工作的？

Swarm 管理器是 OpenAI Node.js SDK 的扩展——在 beta.assistants 上新增了一个 .swarm 方法。

首先，安装 OpenAI 的 Node.js SDK：

yarn add openai
# 或 
npm install openai

然后，安装 openai-assistant-swarm 包：

yarn add @mintplex-labs/openai-assistant-swarm
# 或 
npm install @mintplex-labs/openai-assistant-swarm

接下来，像平常一样使用 SDK，调用扩展函数并初始化代理群管理器：

// 按照常规方式启用 OpenAI 客户端
const OpenAIClient = (
    new OpenAI({
        apiKey: process.env.OPEN_AI_KEY
    }));

// 然后只需在客户端上调用此函数，即可扩展 OpenAI SDK，使其具备
// OpenAIClient.beta.assistants.swarm 相关功能。
EnableSwarmAbilities(OpenAIClient, {
  // 所有选项均为可选
  debug: false, // 用于查看流程的控制台日志输出以及用于调试的 Playground 链接。
  managerAssistantOptions: {
         name: "[AUTOMATED] ___Swarm Manager", // 由该库创建和维护的代理名称
        model: "gpt-4", // 使用 gpt-4 以获得更好的推理能力和调用能力。
        instructions: '您将赋予代理管理器的任务委派指令'; // 覆盖默认指令。
    };
});

// 初始化群管理器以创建群管理器，并将其注册到您的账户中。群管理器可以通过 EnableSwarmAbilities 中的选项进行配置。
await OpenAIClient.beta.assistants.swarm.init();
// 现在，所有群管理功能都已为您所用！

一个简单的示例

以下是一个完整的示例，演示如何将单个输入委派给 3 个可用的助手……

import OpenAI from 'openai';
import { EnableSwarmAbilities } from '@mintplex-labs/openai-assistant-swarm';
const OpenAIClient = new OpenAI({apiKey: process.env.OPEN_AI_KEY});
EnableSwarmAbilities(OpenAIClient);
await OpenAIClient.beta.assistants.swarm.init();

// 可选——在此处设置监听器，等待特定事件返回给用户，因为目前尚不支持流式传输。

// 对单个文本提示运行主流程，以便在所有可用的助手之间委派任务。
const response = OpenAIClient.beta.assistants.swarm.delegateWithPrompt('纽约市现在的天气如何？今天最热门的股票是什么？');
// 例如，假设您的 OpenAI 助手注册表中有海盗机器人、天气机器人和股票机器人。
// 下面的线程会并行运行，并最终返回结果给您！
// |--> 将委派给现有的天气机器人
// |--> 将委派给现有的股票观察机器人
// -> 海盗机器人不会被调用。
// -----
// 主线程将回复类似如下的内容：“我已经安排了两位助手来处理您的请求。关于股票方面的协助，我已将任务委派给了股票机器人；至于旧金山的天气情况，我们的天气机器人将为您提供当前的天气状况。他们很快就会满足您的需求。”
//
// 当每个子线程完成任务或返回 `required_action` 时，您将收到响应，这些响应可以在您的代码库中轻松处理。

console.log({
  parentRun: response.parentRun, // 主线程的所有信息
  subRuns: response.subRuns, // 为每个分叉出的子线程创建的运行数组及其状态！
})

可用工具

通过提示进行委派

首先，你可能最感兴趣的主要功能——将任务委派给子助手。它的设置非常简单，同时也可以监听事件并将其融入到你当前的工作流中。

// 设置一个事件监听器，用于监听父级响应完成的事件，这样你就不用等待父级和所有子级的响应全部完成。
// 这在你需要提前返回父级响应，同时处理可能需要或不需要执行的子任务工具调用时非常有用。
OpenAIClient.beta.assistants.swarm.emitter.on('parent_assistant_complete', (args) => {
    console.group('父级助手响应已完成');
    console.log(args.parentRun.playground) // => https://platform.openai.com/playground.... 用于在浏览器中调试线程和运行。
    console.log(args.parentRun.textResponse) // => 哎呀！你想跟船长说话吗？我这就去把他找来，你这个陆地笨蛋。
    // args.parentRun => OpenAI 返回的完整 Run 对象，你可以从中获取 thread_id 和其他属性，比如状态。
    console.log('\n\n')
    console.groupEnd();
});

// 设置一个事件监听器，用于监听委派的子助手响应完成的事件，这样你就不用等待父级和所有子级的响应全部完成。
// 在这里，你可以处理所有子级 Run 的工具调用（如果需要的话）。
OpenAIClient.beta.assistants.swarm.emitter.on('child_assistants_complete', (args) => {
    console.group('子级助手响应已完成');
    console.log(args.subRuns.map((run) => run.textResponse)) // => 哎呀！我是这艘船的船长。你是来抢我的宝藏的吧？
    console.log(args.subRuns.map((run) => run.playground)) // => https://platform.openai.com/playground.... 用于在浏览器中调试线程和运行。
    // args.subRuns[x].run => OpenAI 返回的完整 Run 对象，你可以从中获取 thread_id 和其他属性，比如状态。
    console.log('\n\n')
    console.groupEnd();
});

// 设置一个事件监听器，以便在每个步骤事件完成后查看相关信息：
OpenAIClient.beta.assistants.swarm.emitter.on('poll_event', ({ data }) => {
    console.group('轮询事件！');
    console.log({
        状态: data.status,
        文本: data.prompt 或 data.textResponse,
        Run ID: data?.run?.id,
        链接: data.playground,
        Run 状态: data?.run?.status,
    })
    console.log('\n\n')
    console.groupEnd();
});

// 使用单个文本提示运行主流程，让工作在所有可用的助手之间自动委派。
const response = OpenAIClient.beta.assistants.swarm.delegateWithPrompt('让我跟这艘船的头号海盗说句话！你们怎么看？？');
// 你也可以直接等待整个流程结束，而不必设置监听器，从而使代码更加同步。
console.log({
  父级Run: response.parentRun,
  子级Runs: response.subRuns,
})

// 你还可以将给定的任务或提示聚焦到你已知想要处理委派工作的特定助手子集中。
// OpenAIClient.beta.assistants.swarm.delegateWithPrompt('让我跟这艘船的头号海盗说句话！你们怎么看？？', ['asst_lead_pirate']);

获取所有可用助手

目前，你需要分页查询助手列表才能知道哪些助手可以回答问题或处理任务。现在，你只需一次调用，我们就会为你处理好分页问题。

const allAssistants = await OpenAIClient.beta.assistants.swarm.allAssistants();
console.log(`在此 OpenAI 账户下找到了 ${allAssistants.length} 个助手`);
// 返回的是一个助手对象数组，你可以对其进行筛选或管理。Swarm 管理员不会出现在此列表中。

一次性获取多个已知助手

通过 API，你每次只能获取一个助手。现在，你可以一次性获取多个助手。

const assistantIds = ['asst_customer_success', 'asst_lead_pirate_manager', 'asst_that_was_deleted' ]
const specificAssistants = await OpenAIClient.beta.assistants.swarm.getAssistants(assistantIds);
console.log(`从提供的 ${assistantIds.length} 个 ID 中找到了 ${specificAssistants.length} 个助手。`);
// 返回的是一个助手对象数组，你可以对其进行筛选或管理。Swarm 管理员不会出现在此列表中。
// 无效的助手不会出现在最终结果中。

OpenAI Assistant Swarm Manager 快速上手指南

OpenAI Assistant Swarm Manager 是一个 Node.js 库，旨在将您的 OpenAI Assistant（智能体）组建为一支协同工作的“军队”。它通过一个统一的 API 调用，让一个主管理智能体能够智能、并行地将任务分发给其他多个子智能体，从而轻松处理复杂的自主代理工作流。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 运行时环境: Node.js (推荐 v18 或更高版本)
• 包管理器: npm 或 yarn
• 前置依赖:
  • OpenAI Node.js SDK (openai)
  • OpenAI API Key (需在环境变量中配置 OPEN_AI_KEY)
  • 已在 OpenAI 平台创建至少一个自定义 Assistant (用于被分发任务)

提示：国内开发者若遇到 npm/yarn 安装缓慢问题，可临时切换至国内镜像源：

# npm 用户
npm config set registry https://registry.npmmirror.com
# yarn 用户
yarn config set registry https://registry.npmmirror.com

安装步骤

首先安装官方的 OpenAI SDK，然后安装 openai-assistant-swarm 扩展库。

使用 npm:

npm install openai
npm install @mintplex-labs/openai-assistant-swarm

使用 yarn:

yarn add openai
yarn add @mintplex-labs/openai-assistant-swarm

基本使用

以下是最简单的使用示例，展示如何初始化 Swarm 管理器并将一个用户提示词分发给现有的多个智能体并行处理。

1. 初始化与配置

import OpenAI from 'openai';
import { EnableSwarmAbilities } from '@mintplex-labs/openai-assistant-swarm';

// 1. 像往常一样初始化 OpenAI 客户端
const OpenAIClient = new OpenAI({
  apiKey: process.env.OPEN_AI_KEY
});

// 2. 启用 Swarm 能力，扩展 beta.assistants 对象
EnableSwarmAbilities(OpenAIClient, {
  debug: false, // 设为 true 可查看调试日志和 Playground 链接
  managerAssistantOptions: {
    name: "[AUTOMATED] ___Swarm Manager", // 管理器智能体名称
    model: "gpt-4",                       // 推荐使用 gpt-4 以获得更好的推理能力
    instructions: 'You are a manager that delegates tasks to other assistants.' // 自定义指令
  }
});

// 3. 初始化 Swarm 管理器（会自动创建并注册管理器智能体）
await OpenAIClient.beta.assistants.swarm.init();

2. 执行任务分发

调用 delegateWithPrompt 方法，传入自然语言指令。库会自动分析意图，并从您账户下的现有智能体中选择合适的一个或多个来并行执行任务。

// 执行分发：例如询问天气和股票，系统会自动分配给对应的 Weather Bot 和 Stock Bot
const response = await OpenAIClient.beta.assistants.swarm.delegateWithPrompt(
  'What is the weather in New York city right now? Also what is the top stock for today?'
);

// 查看结果
console.log({
  parentRun: response.parentRun, // 父线程（管理器）的运行信息
  subRuns: response.subRuns,     // 子线程（被分发的智能体）的运行状态和结果数组
});

3. (可选) 监听事件

如果您需要实时获取进度或在子任务完成时立即处理，可以使用事件监听器：

// 监听父智能体（管理器）回复完成
OpenAIClient.beta.assistants.swarm.emitter.on('parent_assistant_complete', (args) => {
  console.log('管理器回复:', args.parentRun.textResponse);
});

// 监听所有子智能体任务完成
OpenAIClient.beta.assistants.swarm.emitter.on('child_assistants_complete', (args) => {
  const results = args.subRuns.map((run) => run.textResponse);
  console.log('子任务结果:', results);
});