18 KiB

Raw Blame History

Open Multi-Agent

面向 TypeScript 的轻量多智能体编排引擎。3 个运行时依赖，零配置，一次 runTeam() 调用从目标到结果。

CrewAI 是 Python。LangGraph 需要你自己画图。open-multi-agent 是你现有 Node.js 后端里 npm install 一下就能用的那一层。当你需要让一支 agent 团队围绕一个目标协作时，只提供这个，不多不少。

3 个运行时依赖 · 41 个源文件 · Node.js 能跑的地方都能部署

English | 中文

你真正得到的三件事

一次调用从目标到结果。 runTeam(team, "构建一个 REST API") 启动一个协调者 agent，把目标拆成任务 DAG，解析依赖，独立任务并行执行，最终合成输出。不需要画图，不需要手动连任务。
TypeScript 原生，3 个运行时依赖。 @anthropic-ai/sdk、openai、zod。这就是全部运行时。可嵌入 Express、Next.js、Serverless 函数或 CI/CD 流水线。没有 Python 运行时，没有子进程桥接，没有云端 sidecar。
多模型团队。 Claude、GPT、Gemini、Grok、MiniMax、Copilot，或任何 OpenAI 兼容的本地模型（Ollama、vLLM、LM Studio、llama.cpp）可以在同一个团队中使用。让架构师用 Opus 4.6，开发者用 GPT-5.4，评审用本地的 Gemma 4，一次 runTeam() 调用全部搞定。Gemini 作为 optional peer dependency 提供：使用前需 npm install @google/genai。

其他能力（MCP 集成、上下文策略、结构化输出、任务重试、人机协同、生命周期钩子、循环检测、可观测性）在下方章节和 examples/ 里。

哲学：我们做什么，不做什么

我们的目标是做 TypeScript 生态里最简单的多智能体框架。简单不等于封闭。框架的长期价值不在于功能清单的长度，而在于它连接的网络有多大。

我们做：

一个协调者，把目标拆成任务 DAG。
一个任务队列，独立任务并行执行，失败级联到下游。
共享内存和消息总线，让 agent 之间能看到彼此的输出。
多模型团队，每个 agent 可以用不同的 LLM provider。

我们不做：

Agent Handoffs。 如果 agent A 需要把对话中途交接给 agent B，去用 OpenAI Agents SDK。在我们的模型里，每个 agent 完整负责自己的任务，不会中途交接。
状态持久化 / 检查点。 短期内不做。加存储后端会打破 3 个依赖的承诺，而且我们的工作流执行时间是秒到分钟级，不是小时级。如果真实使用场景转向长时间工作流，我们会重新评估。

正在跟踪：

A2A 协议。 观望中，等生产级采纳到位再行动。

完整理由见 DECISIONS.md。

和 X 有什么不同？

vs. LangGraph JS。 LangGraph 是声明式图编排：你定义节点、边、条件路由，然后 compile() + invoke()。open-multi-agent 是目标驱动：你声明团队和目标，协调者在运行时把目标拆成任务 DAG。LangGraph 给你完全的拓扑控制（适合固定的生产工作流）。这个框架代码更少、迭代更快（适合探索型多智能体协作）。LangGraph 还有成熟的检查点能力，我们没有。

vs. CrewAI。 CrewAI 是成熟的 Python 选择。如果你的技术栈是 Python，用 CrewAI。open-multi-agent 是 TypeScript 原生：3 个运行时依赖，直接嵌入 Node.js，不需要子进程桥接。编排能力大致相当，按语言契合度选。

vs. Vercel AI SDK。 AI SDK 是 LLM 调用层：统一的 TypeScript 客户端，支持 60+ provider，带流式、tool calls、结构化输出。它不做多智能体编排。open-multi-agent 需要多 agent 时叠在它之上。两者互补：单 agent 用 AI SDK，需要团队用这个。

谁在用

open-multi-agent 是一个新项目（2026-04-01 发布，MIT 许可，5,500+ stars）。生态还在成形，下面这份列表很短，但都真实：

temodar-agent（约 50 stars）。WordPress 安全分析平台，作者 Ali Sünbül。在 Docker runtime 里直接使用我们的内置工具（bash、file_*、grep）。已确认生产环境使用。
rentech-quant-platform。 多智能体量化交易研究平台，5 条管线 + MCP 集成，基于 open-multi-agent 构建。早期信号，项目非常新。
家用服务器 Cybersecurity SOC。 本地完全离线运行 Qwen 2.5 + DeepSeek Coder（通过 Ollama），在 Wazuh + Proxmox 上构建自主 SOC 流水线。早期用户，未公开。

你在生产环境或 side project 里用 open-multi-agent 吗？开一个 Discussion，我们会把你列上来。

快速开始

需要 Node.js >= 18。

npm install @jackchen_me/open-multi-agent

根据使用的 Provider 设置对应的 API key。通过 Ollama 使用本地模型无需 API key — 参见 example 06。

ANTHROPIC_API_KEY
OPENAI_API_KEY
GEMINI_API_KEY
XAI_API_KEY（Grok）
MINIMAX_API_KEY（MiniMax）
MINIMAX_BASE_URL（MiniMax — 可选，用于选择接入端点）
GITHUB_TOKEN（Copilot）

三个智能体，一个目标——框架处理剩下的一切：

import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
import type { AgentConfig } from '@jackchen_me/open-multi-agent'

const architect: AgentConfig = {
  name: 'architect',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You design clean API contracts and file structures.',
  tools: ['file_write'],
}

const developer: AgentConfig = { /* 同样结构，tools: ['bash', 'file_read', 'file_write', 'file_edit'] */ }
const reviewer: AgentConfig = { /* 同样结构，tools: ['file_read', 'grep'] */ }

const orchestrator = new OpenMultiAgent({
  defaultModel: 'claude-sonnet-4-6',
  onProgress: (event) => console.log(event.type, event.agent ?? event.task ?? ''),
})

const team = orchestrator.createTeam('api-team', {
  name: 'api-team',
  agents: [architect, developer, reviewer],
  sharedMemory: true,
})

// 描述一个目标——框架将其拆解为任务并编排执行
const result = await orchestrator.runTeam(team, 'Create a REST API for a todo list in /tmp/todo-api/')

console.log(`Success: ${result.success}`)
console.log(`Tokens: ${result.totalTokenUsage.output_tokens} output tokens`)

执行过程：

agent_start coordinator
task_start architect
task_complete architect
task_start developer
task_start developer              // 无依赖的任务并行执行
task_complete developer
task_complete developer
task_start reviewer               // 实现完成后自动解锁
task_complete reviewer
agent_complete coordinator        // 综合所有结果
Success: true
Tokens: 12847 output tokens

三种运行模式

模式	方法	适用场景
单智能体	`runAgent()`	一个智能体，一个提示词——最简入口
自动编排团队	`runTeam()`	给一个目标，框架自动规划和执行
显式任务管线	`runTasks()`	你自己定义任务图和分配

如果需要 MapReduce 风格的扇出而不涉及任务依赖，直接使用 AgentPool.runParallel()。参见示例 07。

示例

examples/ 里有 17 个可运行脚本和 1 个完整项目。推荐从这几个开始：

02 — 团队协作：runTeam() 协调者模式。
06 — 本地模型：通过 baseURL 把 Ollama 和 Claude 放在同一条管线。
09 — 结构化输出：任意 agent 产出 Zod 校验过的 JSON。
11 — 可观测性：onTrace 回调，为 LLM 调用、工具、任务发出结构化 span。
17 — MiniMax：使用 MiniMax M2.7 的三智能体团队。
with-vercel-ai-sdk：Next.js 应用 — OMA runTeam() + AI SDK useChat 流式输出。

用 npx tsx examples/02-team-collaboration.ts 运行脚本示例。

架构

┌─────────────────────────────────────────────────────────────────┐
│  OpenMultiAgent (Orchestrator)                                  │
│                                                                 │
│  createTeam()  runTeam()  runTasks()  runAgent()  getStatus()   │
└──────────────────────┬──────────────────────────────────────────┘
                       │
            ┌──────────▼──────────┐
            │  Team               │
            │  - AgentConfig[]    │
            │  - MessageBus       │
            │  - TaskQueue        │
            │  - SharedMemory     │
            └──────────┬──────────┘
                       │
         ┌─────────────┴─────────────┐
         │                           │
┌────────▼──────────┐    ┌───────────▼───────────┐
│  AgentPool        │    │  TaskQueue             │
│  - Semaphore      │    │  - dependency graph    │
│  - runParallel()  │    │  - auto unblock        │
└────────┬──────────┘    │  - cascade failure     │
         │               └───────────────────────┘
┌────────▼──────────┐
│  Agent            │
│  - run()          │    ┌──────────────────────┐
│  - prompt()       │───►│  LLMAdapter          │
│  - stream()       │    │  - AnthropicAdapter  │
└────────┬──────────┘    │  - OpenAIAdapter     │
         │               │  - CopilotAdapter    │
         │               │  - GeminiAdapter     │
         │               │  - GrokAdapter       │
         │               │  - MiniMaxAdapter    │
         │               └──────────────────────┘
┌────────▼──────────┐
│  AgentRunner      │    ┌──────────────────────┐
│  - conversation   │───►│  ToolRegistry        │
│    loop           │    │  - defineTool()      │
│  - tool dispatch  │    │  - 6 built-in tools  │
└───────────────────┘    └──────────────────────┘

内置工具

工具	说明
`bash`	执行 Shell 命令。返回 stdout + stderr。支持超时和工作目录设置。
`file_read`	读取指定绝对路径的文件内容。支持偏移量和行数限制以处理大文件。
`file_write`	写入或创建文件。自动创建父目录。
`file_edit`	通过精确字符串匹配编辑文件。
`grep`	使用正则表达式搜索文件内容。优先使用 ripgrep，回退到 Node.js 实现。
`glob`	按 glob 模式查找文件。返回按修改时间排序的匹配路径。

工具配置

可以通过预设、白名单和黑名单对 agent 的工具访问进行精细控制。

工具预设

为常见场景预定义的工具组合：

const readonlyAgent: AgentConfig = {
  name: 'reader',
  model: 'claude-sonnet-4-6',
  toolPreset: 'readonly',  // file_read, grep, glob
}

const readwriteAgent: AgentConfig = {
  name: 'editor',
  model: 'claude-sonnet-4-6',
  toolPreset: 'readwrite',  // file_read, file_write, file_edit, grep, glob
}

const fullAgent: AgentConfig = {
  name: 'executor',
  model: 'claude-sonnet-4-6',
  toolPreset: 'full',  // file_read, file_write, file_edit, grep, glob, bash
}

高级过滤

将预设与白名单、黑名单组合，实现精确控制：

const customAgent: AgentConfig = {
  name: 'custom',
  model: 'claude-sonnet-4-6',
  toolPreset: 'readwrite',        // 起点：file_read, file_write, file_edit, grep, glob
  tools: ['file_read', 'grep'],   // 白名单：与预设取交集 = file_read, grep
  disallowedTools: ['grep'],      // 黑名单：再减去 = 只剩 file_read
}

解析顺序： preset → allowlist → denylist → 框架安全护栏。

自定义工具

通过 agent.addTool() 添加的工具始终可用，不受过滤规则影响。

支持的 Provider

Provider	配置	环境变量	状态
Anthropic (Claude)	`provider: 'anthropic'`	`ANTHROPIC_API_KEY`	已验证
OpenAI (GPT)	`provider: 'openai'`	`OPENAI_API_KEY`	已验证
Grok (xAI)	`provider: 'grok'`	`XAI_API_KEY`	已验证
MiniMax（全球）	`provider: 'minimax'`	`MINIMAX_API_KEY`	已验证
MiniMax（国内）	`provider: 'minimax'` + `MINIMAX_BASE_URL`	`MINIMAX_API_KEY`	已验证
GitHub Copilot	`provider: 'copilot'`	`GITHUB_TOKEN`	已验证
Gemini	`provider: 'gemini'`	`GEMINI_API_KEY`	已验证
Ollama / vLLM / LM Studio	`provider: 'openai'` + `baseURL`	—	已验证
llama.cpp server	`provider: 'openai'` + `baseURL`	—	已验证

Gemini 需要 npm install @google/genai（optional peer dependency）。

已验证支持 tool-calling 的本地模型：Gemma 4（见示例 08）。

任何 OpenAI 兼容 API 均可通过 provider: 'openai' + baseURL 接入（DeepSeek、Groq、Mistral、Qwen 等）。Grok 和 MiniMax 现已原生支持，分别使用 provider: 'grok' 和 provider: 'minimax'。

本地模型 Tool-Calling

框架支持通过 Ollama、vLLM、LM Studio 或 llama.cpp 运行的本地模型进行 tool-calling。Tool-calling 由这些服务通过 OpenAI 兼容 API 原生处理。

已验证模型： Gemma 4、Llama 3.1、Qwen 3、Mistral、Phi-4。完整列表见 ollama.com/search?c=tools。

兜底提取： 如果本地模型以文本形式返回工具调用，而非使用 tool_calls 协议格式（常见于 thinking 模型或配置不当的服务），框架会自动从文本输出中提取。

超时设置： 本地推理可能较慢。使用 AgentConfig 上的 timeoutMs 防止无限等待：

const localAgent: AgentConfig = {
  name: 'local',
  model: 'llama3.1',
  provider: 'openai',
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama',
  tools: ['bash', 'file_read'],
  timeoutMs: 120_000, // 2 分钟后中止
}

常见问题：

模型不调用工具？确保该模型出现在 Ollama 的 Tools 分类中。并非所有模型都支持 tool-calling。
使用 Ollama？更新到最新版（ollama update）——旧版本有已知的 tool-calling bug。
代理干扰？本地服务使用 no_proxy=localhost。

LLM 配置示例

const grokAgent: AgentConfig = {
  name: 'grok-agent',
  provider: 'grok',
  model: 'grok-4',
  systemPrompt: 'You are a helpful assistant.',
}

（设置 XAI_API_KEY 环境变量即可，无需 baseURL。）

const minimaxAgent: AgentConfig = {
  name: 'minimax-agent',
  provider: 'minimax',
  model: 'MiniMax-M2.7',
  systemPrompt: 'You are a helpful assistant.',
}

设置 MINIMAX_API_KEY。适配器通过 MINIMAX_BASE_URL 选择接入端点：

https://api.minimax.io/v1 全球端点，默认
https://api.minimaxi.com/v1 中国大陆端点

也可在 AgentConfig 中直接传入 baseURL 覆盖环境变量。

参与贡献

欢迎提 Issue、功能需求和 PR。以下方向的贡献尤其有价值：

示例 — 真实场景的工作流和用例。
文档 — 指南、教程和 API 文档。

贡献者

Star 趋势

许可证

MIT

18 KiB Raw Blame History Unescape Escape