JackChen-me/open-multi-agent

open-multi-agent 是面向 TypeScript 后端的 multi-agent 编排框架。给它一个目标；coordinator agent 会将其分解为 task DAG，并行执行相互独立的任务，并合成结果。三个 runtime dependencies，可直接嵌入任何 Node.js 后端。

你的工程师描述目标，而不是绘制图。

一次典型运行，通过 onProgress 实时流式输出：

agent_start coordinator
task_start design-api
task_complete design-api
task_start implement-handlers
task_start scaffold-tests         // independent tasks run in parallel
task_complete scaffold-tests
task_complete implement-handlers
task_start review-code            // unblocked after implementation
task_complete review-code
agent_complete coordinator        // synthesizes final result
Success: true
Tokens: 12847 output tokens

Features

Capability	What you get
Goal-driven coordinator	一次 runTeam(team, goal) 调用。coordinator 将目标分解为 task DAG，并行执行相互独立的任务，并合成结果。
Mix providers in one team	10 个原生 provider：Anthropic、OpenAI、Azure、Bedrock、Gemini、Grok、DeepSeek、MiniMax、Qiniu、Copilot。Ollama / vLLM / LM Studio / OpenRouter / Groq 通过 OpenAI-compatible 接入。(完整列表)
Tools + MCP	6 个内置 tool（bash、file_*、grep、glob），可选择启用 delegate_to_agent，通过 defineTool() + Zod 自定义 tool，通过 connectMCPTools() 接入任意 MCP server。
Streaming + structured output	每个 adapter 都支持 token-by-token streaming；最终答案通过 Zod 验证，解析失败时自动重试。(structured-output)
Observability	onProgress events、onTrace spans、运行后 HTML dashboard，可渲染已执行的 task DAG。(trace-observability)
Pluggable shared memory	默认进程内 KV；通过实现 MemoryStore 可替换为 Redis / Postgres / 你自己的 backend。

Production controls（context strategies、带 backoff 的任务 retry、loop detection、tool output truncation/compression）见 Production Checklist。

Quick Start

需要 Node.js >= 18。

Try it locally

Clone、安装、运行。

git clone https://github.com/JackChen-me/open-multi-agent && cd open-multi-agent
npm install
export ANTHROPIC_API_KEY=sk-...
npx tsx examples/basics/team-collaboration.ts

三个 agent（architect、developer、reviewer）在 /tmp/express-api/ 中协作开发一个 REST API。随着 progress events 流式输出，你可以看到 coordinator 分解目标，并并行运行独立任务。

通过 Ollama 使用本地模型不需要 API key，见 providers/ollama。其他 provider（OPENAI_API_KEY、GEMINI_API_KEY 等）请查看 Supported Providers。

Use it in your project

npm install @jackchen_me/open-multi-agent

三个 agent，一个目标。框架处理其余部分：

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 specifies. Write clean, runnable TypeScript.',
  tools: ['bash', 'file_read', 'file_write', 'file_edit'],
}

const reviewer: AgentConfig = {
  name: 'reviewer',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You review code for correctness, security, and clarity.',
  tools: ['file_read', 'grep'],
}

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

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

// Describe a goal. The framework breaks it into tasks and orchestrates execution
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`)

Three Ways to Run

Mode	Method	When to use	Example
Single agent	runAgent()	一个 agent，一个 prompt。最简单的入口	basics/single-agent
Auto-orchestrated team	runTeam()	给出目标，由框架规划并执行	basics/team-collaboration
Explicit pipeline	runTasks()	你定义 task graph 和分配关系	basics/task-pipeline

对于没有任务依赖的 MapReduce-style fan-out，可直接使用 AgentPool.runParallel()。见 patterns/fan-out-aggregate。

Preview the plan without running it

向 runTeam() 传入 planOnly: true，coordinator 会分解目标，但不会执行任何 task agent。结果包含 planOnly: true、已填充的 tasks（无 metrics），以及仅 coordinator 的 token usage。适用于在 integration tests 中断言 task DAG，或在真实运行前预估成本。

const plan = await orchestrator.runTeam(team, goal, { planOnly: true })

for (const task of plan.tasks ?? []) {
  console.log(`${task.title} → ${task.assignee} (deps: ${task.dependsOn.length})`)
}

Run from the shell

面向 shell 和 CI，该 package 提供 JSON-first binary。关于 oma run、oma task、oma provider、exit codes 和 file formats，见 docs/cli.md。

Examples

examples/ 按类别组织：basics、cookbook、patterns、providers、integrations 和 production。完整索引见 examples/README.md。

Real-world workflows (cookbook/)

你今天就能运行的端到端场景。每个都是完整且有明确取舍的 workflow。

• contract-review-dag：用于合同审查的四任务 DAG，包含并行分支和失败时的 step-level retry。
• meeting-summarizer：三个 specialized agent 对会议 transcript 进行 fan out，aggregator 将它们合并为一份包含 action items 和 sentiment 的 Markdown 报告。
• competitive-monitoring：三个并行 source agent 从 feeds 中提取 claims；aggregator 交叉检查并标记矛盾。
• translation-backtranslation：用一个 provider 将 EN 翻译到目标语言，再用另一个 provider 回译，并标记 semantic drift。

Patterns and integrations

• basics/team-collaboration：runTeam() coordinator pattern。
• patterns/structured-output：任意 agent 返回经过 Zod 验证的 JSON。
• patterns/agent-handoff：通过 delegate_to_agent 同步委派给 sub-agent。
• integrations/trace-observability：用于 LLM calls、tools 和 tasks 的 onTrace spans。
• integrations/mcp-github：通过 connectMCPTools() 将 MCP server 的 tools 暴露给 agent。
• integrations/with-vercel-ai-sdk：Next.js app，将 OMA runTeam() 与 AI SDK useChat streaming 结合。
• Provider examples：位于 examples/providers/ 下的三 agent teams，覆盖托管 providers、OpenAI-compatible endpoints 和本地模型。

使用 npx tsx examples/<path>.ts 运行任意脚本。

How is this different from X?

快速选择指南。后面是机制拆解。

If you need	Pick
具有成熟 checkpointing 的固定生产拓扑	LangGraph JS
显式 Supervisor + 手工编排的 workflows	Mastra
具有成熟 multi-agent 生态的 Python stack	CrewAI
面向 60+ providers 的 single-agent LLM call layer	Vercel AI SDK
TypeScript，从目标到结果，自动任务分解	open-multi-agent

vs. LangGraph JS. LangGraph 将声明式 graph（nodes、edges、conditional routing）编译为可调用对象。open-multi-agent 运行一个 Coordinator，在 runtime 将目标分解为 task DAG，然后自动并行化独立任务。终点相同（编排式执行），方向相反：LangGraph 是 graph-first，OMA 是 goal-first。

vs. Mastra. 两者都是 TypeScript-native。Mastra 的 Supervisor pattern 要求你手工连接 agents 和 workflows；OMA 的 Coordinator 会在 runtime 根据目标字符串完成连接。如果 workflow 事先已知，Mastra 的显式性会带来收益。如果你不想枚举每个步骤，OMA 的 runTeam(team, goal) 只需一次调用。

vs. CrewAI. CrewAI 是 Python 中成熟的 multi-agent 选项。OMA 面向 TypeScript 后端，只有三个 runtime dependencies，并可直接嵌入 Node.js。两者的编排能力大致可比；选择取决于语言栈。

vs. Vercel AI SDK. AI SDK 是 LLM call layer（60+ providers 的统一 client、streaming、tool calls、structured outputs）。它不编排 multi-agent teams。二者可以组合：single-agent 工作使用 AI SDK，需要团队协作时使用 OMA。

Ecosystem

open-multi-agent 于 2026-04-01 以 MIT 协议发布。迄今为止的公开用户和 integrations：

In production

• temodar-agent（约 60 stars）。由 Ali Sünbül 开发的 WordPress 安全分析平台。在其 Docker runtime 中直接使用我们的内置 tools（bash、file_*、grep）。已确认用于生产。
• Cybersecurity SOC (home lab)。 一个私有部署，通过 Ollama 完全离线运行 Qwen 2.5 + DeepSeek Coder，在 Wazuh + Proxmox 上构建 autonomous SOC pipeline。早期用户，尚未公开。

正在生产或 side project 中使用 open-multi-agent？发起 discussion，我们会将其列在这里。

Integrations

• Engram — “Git for AI memory。”在 agents 之间即时同步知识并标记冲突。(repo)
• @agentsonar/oma — 用于检测跨运行 delegation cycles、repetition 和 rate bursts 的 Sidecar。

构建了 integration？发起 discussion 以加入列表。

Featured partner

面向与 open-multi-agent 深度集成的产品和平台。条款和申请方式见 Featured partner program。

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  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       │
         │               │  - AzureOpenAIAdapter  │
         │               │  - BedrockAdapter      │
         │               │  - CopilotAdapter      │
         │               │  - GeminiAdapter       │
         │               │  - GrokAdapter         │
         │               │  - MiniMaxAdapter      │
         │               │  - DeepSeekAdapter     │
         │               │  - QiniuAdapter        │
         │               └────────────────────────┘
┌────────▼──────────┐
│  AgentRunner      │    ┌──────────────────────┐
│  - conversation   │───►│  ToolRegistry        │
│    loop           │    │  - defineTool()      │
│  - tool dispatch  │    │  - 6 built-in tools  │
└───────────────────┘    │  + delegate (opt-in) │
                         └──────────────────────┘

Observability

三层 telemetry，每一层都可独立消费。

Layer	What it gives you	Where to wire it
onProgress	每个 task 的 lifecycle events：task_start、task_complete、task_retry、task_skipped、agent_start、agent_complete、budget_exceeded、error。轻量、同步。	OrchestratorConfig.onProgress；接入你的 logger 或实时 dashboard。
onTrace	LLM calls、tool executions 和 tasks 的 structured spans。每个 span 携带 parent IDs、durations、token counts 和 tool I/O。	OrchestratorConfig.onTrace；转发到 OpenTelemetry、Datadog、Honeycomb、Langfuse 等。(integrations/trace-observability)
Post-run HTML dashboard	静态 HTML 页面，渲染已执行的 task DAG，包含 timing、token usage 和每个 task 的状态。不需要 server，不需要 D3，只是 string。	import { renderTeamRunDashboard } from '@jackchen_me/open-multi-agent'，然后 fs.writeFileSync('run.html', renderTeamRunDashboard(result))。

三者结合：为运维提供实时进度，为调试和成本归因提供 traces，为每次运行提供可分享的事后分析 artifact。

Built-in Tools

Tool	Description
bash	执行 shell commands。返回 stdout + stderr。支持 timeout 和 cwd。
file_read	读取绝对路径下的文件内容。对大文件支持 offset/limit。
file_write	写入或创建文件。自动创建父目录。
file_edit	通过替换精确匹配的字符串来编辑文件。
grep	用 regex 搜索文件内容。可用时使用 ripgrep，否则回退到 Node.js。
glob	按 glob pattern 查找文件。返回按修改时间排序的匹配路径。

Tool Configuration

• Pick a preset. toolPreset: 'readonly' | 'readwrite' | 'full' 覆盖大多数 agents。
• Narrow further. 在 preset 之上组合 tools（allowlist）和 disallowedTools（denylist）。
• Bring your own. defineTool() + customTools，或在 runtime 使用 agent.addTool()。
• Cap output cost. outputSchema、maxToolOutputChars 和 compressToolResults。
• MCP. 通过 open-multi-agent/mcp 中的 connectMCPTools() 连接外部 servers。

完整细节见 docs/tool-configuration.md。

Shared Memory

Teams 可以共享一个带 namespace 的 key-value store，使后续 agents 能看到前面 agents 的发现。使用 sharedMemory: true 可启用默认进程内 store；或实现 MemoryStore 并通过 sharedMemoryStore 传入，以使用 Redis、Postgres、Engram 等。Keys 在到达 store 前会被命名空间化为 <agentName>/<key>。仅 SDK：CLI 不能传入 runtime objects。

见 docs/shared-memory.md。

Context Management

长时间运行的 agents 很快会触及 input token 上限。AgentConfig.contextStrategy 控制 conversation 如何缩小：

• sliding-window：保留最近 N 轮，丢弃其余内容。成本最低。
• summarize：将旧轮次发送给 summary model，并在原位置保留 summary。
• compact：基于规则的 truncation，不产生额外 LLM call。
• custom：提供你自己的 compress(messages, estimatedTokens)。

见 docs/context-management.md。

Supported Providers

修改 provider、model，并设置 env var。agent config 的形状保持不变：

const agent: AgentConfig = {
  name: 'my-agent',
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  systemPrompt: 'You are a helpful assistant.',
}

First-class providers (named shortcuts)

框架为以下每个 provider 都内置了已连接好的 provider name。你只需设置 provider 和 env var。

在底层，Anthropic 和 Gemini 使用各自的 SDK；其余是在 OpenAI Chat Completions protocol 之上的预配置快捷方式。wire format 与第二张表相同，只是框架替你写好了 baseURL。

Provider	Config	Env var	Example model	Notes
Anthropic (Claude)	provider: 'anthropic'	ANTHROPIC_API_KEY	claude-sonnet-4-6	原生 Anthropic SDK。
Gemini	provider: 'gemini'	GEMINI_API_KEY	gemini-2.5-pro	原生 Google GenAI SDK。需要 npm install @google/genai。
OpenAI (GPT)	provider: 'openai'	OPENAI_API_KEY	gpt-4o
Azure OpenAI	provider: 'azure-openai'	AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT	gpt-4	可选 AZURE_OPENAI_API_VERSION、AZURE_OPENAI_DEPLOYMENT。
GitHub Copilot	provider: 'copilot'	GITHUB_COPILOT_TOKEN（回退到 GITHUB_TOKEN）	gpt-4o	在 OpenAI protocol 之上的自定义 token-exchange flow。
Grok (xAI)	provider: 'grok'	XAI_API_KEY	grok-4	OpenAI-compatible；endpoint 是 api.x.ai/v1。
DeepSeek	provider: 'deepseek'	DEEPSEEK_API_KEY	deepseek-chat	OpenAI-compatible。deepseek-chat（V3，coding）或 deepseek-reasoner（thinking mode）。
MiniMax (global)	provider: 'minimax'	MINIMAX_API_KEY	MiniMax-M2.7	OpenAI-compatible。
MiniMax (China)	provider: 'minimax' + MINIMAX_BASE_URL	MINIMAX_API_KEY	MiniMax-M2.7	设置 MINIMAX_BASE_URL=https://api.minimaxi.com/v1。
Qiniu	provider: 'qiniu'	QINIU_API_KEY	deepseek-v3	OpenAI-compatible。Endpoint https://api.qnaigc.com/v1；支持多个 model families，见 Qiniu AI docs。
AWS Bedrock	provider: 'bedrock'	none（AWS SDK credential chain）	anthropic.claude-3-5-haiku-20241022-v1:0	无 API key。设置 AWS_REGION，或将 region 作为第 4 个参数传给 createAdapter。Credentials 来自 env vars、shared config 或 IAM role。较新的 Claude models（Sonnet 4.x、Haiku 4.x）需要类似 us. 的跨区域 inference profile prefix——请在 Bedrock console 中查看你所在 region 可用的 IDs。也支持 Llama、Mistral、Cohere——见 providers/bedrock 示例。需要 npm install @aws-sdk/client-bedrock-runtime。

Anything else OpenAI-compatible (manual baseURL)

没有内置 shortcut，但工作方式相同。使用 provider: 'openai'，并将 baseURL 指向任何支持 OpenAI Chat Completions 的 server。

Service	Config	Env var	Example model	Notes
Ollama (local)	provider: 'openai' + baseURL: 'http://localhost:11434/v1'	none	llama3.1
vLLM (local)	provider: 'openai' + baseURL	none	(server-loaded)
LM Studio (local)	provider: 'openai' + baseURL	none	(server-loaded)
llama.cpp server (local)	provider: 'openai' + baseURL	none	(server-loaded)
OpenRouter	provider: 'openai' + baseURL: 'https://openrouter.ai/api/v1' + apiKey	OPENROUTER_API_KEY	openai/gpt-4o-mini
Groq	provider: 'openai' + baseURL: 'https://api.groq.com/openai/v1'	GROQ_API_KEY	llama-3.3-70b-versatile
Mistral	provider: 'openai' + baseURL: 'https://api.mistral.ai/v1'	MISTRAL_API_KEY	mistral-large-latest	OpenAI-compatible。见 providers/mistral 示例。

Qwen、Moonshot、Doubao、Together AI、Fireworks 等都可以用同样方式接入。对于 key 不是 OPENAI_API_KEY 的服务（OpenRouter 就是一个例子），通过 apiKey config field 显式传入；否则 openai adapter 会回退到环境中的 OPENAI_API_KEY。

Local Model Tool-Calling

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

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

Fallback extraction： 如果本地模型以文本形式返回 tool calls，而不是使用 tool_calls wire format（thinking models 或配置错误的 servers 中很常见），框架会自动从文本输出中提取它们。

Timeout： 本地 inference 可能很慢。在 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, // abort after 2 minutes
}

Quantized model tuning. 在消费级硬件上运行的高量化 MoE models（Qwen2.5-MoE @ Q4、DeepSeek-MoE @ Q4 等）在默认采样下容易陷入 repetition loops，或 hallucinate tool-call schemas。AgentConfig 暴露 topK、minP、frequencyPenalty、presencePenalty、parallelToolCalls（对于不稳定的 tool-callers，设置为 false 以强制每轮只调用一个 tool），以及用于 server-specific knobs 的 extraBody escape hatch（例如 vLLM 的 repetition_penalty）。Cloud OpenAI 用户不需要这些——默认值已针对 full-precision models 调优。完整配置见 providers/local-quantized。

Troubleshooting:

• 模型不调用 tools？确认它出现在 Ollama 的 Tools category 中。不是所有模型都支持 tool-calling。
• 使用 Ollama？更新到最新版本（ollama update）。旧版本存在已知的 tool-calling bugs。
• 代理干扰？连接本地 servers 时使用 no_proxy=localhost。

Production Checklist

上线前，请接入这些 controls，以保护 token 开销、从故障中恢复，并让你能够调试。

Concern	Knob	Where it lives
限制 conversation	每个 agent 的 maxTurns + contextStrategy（sliding-window / summarize / compact / custom）	AgentConfig
限制 tool output	maxToolOutputChars（或每个 tool 的 maxOutputChars）+ compressToolResults: true	AgentConfig 和 defineTool()
从失败中恢复	每个 task 的 maxRetries、retryDelayMs、retryBackoff（指数乘数）	通过 runTasks() 使用的 Task config
硬性限制开销	orchestrator 上的 maxTokenBudget	OrchestratorConfig
捕获卡住的 agents	loopDetection 配合 onLoopDetected: 'terminate'（或自定义 handler）	AgentConfig
Trace 和 audit	将 onTrace 接入你的 tracing backend；持久化 renderTeamRunDashboard(result)	OrchestratorConfig

Contributing

欢迎提交 issues、feature requests 和 PRs。以下领域的贡献尤其有价值：

• Production examples. 真实世界的端到端 workflows。验收标准和提交格式见 examples/production/README.md。
• Documentation. Guides、tutorials 和 API docs。
• Translations. 帮助将此 README 翻译成其他语言。Open a PR。

Contributors

Project lead: Jack Chen

Framework features

• @ibrahimkzmv（token budget、context strategy、dependency-scoped context、tool presets、glob、MCP integration、configurable coordinator、CLI、dashboard rendering）
• @apollo-mg（context compaction fix、sampling parameters）
• @tizerluo（onPlanReady、onAgentStream）
• @Xin-Mai（output schema validation）
• @JasonOA888（AbortSignal support）
• @EchoOfZion（coordinator skip for simple goals）
• @voidborne-d（OpenAI mixed content fix）
• @hamzarstar（agent delegation co-author）
• @MyPrototypeWhat（trace input/output）
• @SiMinus（streaming reasoning events）

Provider integrations

• @ibrahimkzmv（Gemini）
• @hkalex（DeepSeek、MiniMax）
• @marceloceccon（Grok）
• @Klarline（Azure OpenAI）
• @Deathwing（GitHub Copilot）
• @JackChiang233 和 @jiangzhuo（Qiniu）
• @CodingBangboo（AWS Bedrock）

Examples & cookbook

• @mvanhorn（research aggregation、code review、meeting summarizer、Groq example、Mistral example）
• @Kinoo0（code review upgrade）
• @Optimisttt（research aggregation upgrade）
• @Agentscreator（Engram memory integration）
• @fault-segment 和 yanzizheng（contract-review DAG）
• @HuXiangyu123（cost-tiered example）
• @zouhh22333-beep（translation/backtranslation）
• @pei-pei45（competitive monitoring）
• @mmjwxbc（interview simulator）
• @binghuaren96（incident postmortem DAG）
• @CodingBangboo（Express customer support pipeline）

Docs & tests

• @tmchow（llama.cpp docs）
• @kenrogers（OpenRouter docs）
• @jadegold55（LLM adapter test coverage）

Star History

License

MIT