14 KiB

Raw Blame History

Open Multi-Agent

TypeScript 多智能体编排框架。一次 runTeam() 调用从目标到结果——框架自动拆解任务、解析依赖、并行执行。

3 个运行时依赖 · 33 个源文件 · Node.js 能跑的地方都能部署 · 被 Latent Space AI News 提及（AI 工程领域头部 Newsletter，17 万+订阅者）

为什么选择 Open Multi-Agent？

目标进，结果出 — runTeam(team, "构建一个 REST API")。协调者智能体自动将目标拆解为带依赖关系的任务图，分配给对应智能体，独立任务并行执行，最终合成输出。无需手动定义任务或编排流程图。
TypeScript 原生 — 为 Node.js 生态而生。npm install 即用，无需 Python 运行时、无子进程桥接、无额外基础设施。可嵌入 Express、Next.js、Serverless 函数或 CI/CD 流水线。
可审计、极轻量 — 3 个运行时依赖（@anthropic-ai/sdk、openai、zod），33 个源文件。一个下午就能读完全部源码。
模型无关 — Claude、GPT、Gemma 4 和本地模型（Ollama、vLLM、LM Studio、llama.cpp server）可以在同一个团队中使用。通过 baseURL 即可接入任何 OpenAI 兼容服务。
多智能体协作 — 定义不同角色、工具和模型的智能体，通过消息总线和共享内存协作。
结构化输出 — 为任意智能体添加 outputSchema（Zod），输出自动解析为 JSON 并校验，校验失败自动重试一次。通过 result.structured 获取类型化结果。
任务重试 — 为任务设置 maxRetries，失败时自动指数退避重试。所有尝试的 token 用量累计，确保计费准确。
人机协同 — runTasks() 支持可选的 onApproval 回调。每批任务完成后，由你的回调决定是否继续执行后续任务。
生命周期钩子 — AgentConfig 上的 beforeRun / afterRun。在执行前拦截 prompt，或在执行后处理结果。从钩子中 throw 可中止运行。
循环检测 — AgentConfig 上的 loopDetection 可检测智能体重复相同工具调用或文本输出的卡死循环。可配置行为：警告（默认）、终止、或自定义回调。
可观测性 — 可选的 onTrace 回调为每次 LLM 调用、工具执行、任务和智能体运行发出结构化 span 事件——包含耗时、token 用量和共享的 runId 用于关联追踪。未订阅时零开销，零额外依赖。

快速开始

需要 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）
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 = {
  name: 'developer',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You implement what the architect designs.',
  tools: ['bash', 'file_read', 'file_write', 'file_edit'],
}

const reviewer: AgentConfig = {
  name: 'reviewer',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You review code for correctness and clarity.',
  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(`成功: ${result.success}`)
console.log(`Token 用量: ${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_start reviewer               // 实现完成后自动解锁
task_complete developer
task_complete reviewer
agent_complete coordinator        // 综合所有结果
Success: true
Tokens: 12847 output tokens

三种运行模式

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

示例

所有示例都是可运行脚本，位于 examples/ 目录。使用 npx tsx 运行：

npx tsx examples/01-single-agent.ts

示例	展示内容
01 — 单智能体	`runAgent()` 单次调用、`stream()` 流式输出、`prompt()` 多轮对话
02 — 团队协作	`runTeam()` 自动编排 + 协调者模式
03 — 任务流水线	`runTasks()` 显式依赖图（设计 → 实现 → 测试 + 评审）
04 — 多模型团队	`defineTool()` 自定义工具、Anthropic + OpenAI 混合、`AgentPool`
05 — Copilot	GitHub Copilot 作为 LLM 提供者
06 — 本地模型	Ollama + Claude 混合流水线，通过 `baseURL` 接入（兼容 vLLM、LM Studio 等）
07 — 扇出聚合	`runParallel()` MapReduce — 3 个分析师并行，然后综合
08 — Gemma 4 本地	`runTasks()` + `runTeam()` 本地 Gemma 4 via Ollama — 零 API 费用
09 — 结构化输出	`outputSchema`（Zod）— 校验 JSON 输出，通过 `result.structured` 获取
10 — 任务重试	`maxRetries` / `retryDelayMs` / `retryBackoff` + `task_retry` 进度事件
11 — 可观测性	`onTrace` 回调 — LLM 调用、工具、任务、智能体的结构化 span 事件
12 — Grok	同示例 02（`runTeam()` 团队协作），使用 Grok（`XAI_API_KEY`）
13 — Gemini	Gemini 适配器测试，使用 `gemini-2.5-flash`（`GEMINI_API_KEY`）

架构

┌─────────────────────────────────────────────────────────────────┐
│  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       │
         │               └──────────────────────┘
┌────────▼──────────┐
│  AgentRunner      │    ┌──────────────────────┐
│  - conversation   │───►│  ToolRegistry        │
│    loop           │    │  - defineTool()      │
│  - tool dispatch  │    │  - 5 built-in tools  │
└───────────────────┘    └──────────────────────┘

内置工具

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

支持的 Provider

Provider	配置	环境变量	状态
Anthropic (Claude)	`provider: 'anthropic'`	`ANTHROPIC_API_KEY`	已验证
OpenAI (GPT)	`provider: 'openai'`	`OPENAI_API_KEY`	已验证
Grok (xAI)	`provider: 'grok'`	`XAI_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`	—	已验证

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

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

本地模型 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。）

参与贡献

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

Provider 集成 — 验证并文档化 OpenAI 兼容 Provider（DeepSeek、Groq、Qwen、MiniMax 等）通过 baseURL 接入。详见 #25。对于非 OpenAI 兼容的 Provider，欢迎贡献新的 LLMAdapter 实现——接口只需两个方法：chat() 和 stream()。
示例 — 真实场景的工作流和用例。
文档 — 指南、教程和 API 文档。

作者

JackChen — 前 WPS 产品经理，现独立创业者。关注小红书「杰克西｜硅基杠杆」，持续获取我的 AI Agent 观点和思考。

贡献者

Star 趋势

许可证

MIT

14 KiB Raw Blame History Unescape Escape