Open Multi-Agent: Lightweight Orchestration for TypeScript

Overview

Open Multi-Agent is a lightweight orchestration engine designed for TypeScript. Its core promise is to minimize setup friction by delivering a goal-driven workflow that resolves to a single runTeam() invocation. This means you provide a team and a goal, and the framework handles decomposition, dependency resolution, parallel execution, and synthesis of the final result without you worrying about plotting a graph or wiring tasks.
The project emphasizes minimal runtime surface area: three runtime dependencies, zero config, and seamless embedding in existing Node.js backends. It is designed to deploy anywhere Node.js runs, with no Python subprocess bridges or cloud-sidecar requirements. The three runtime dependencies are @anthropic-ai/sdk, openai, and zod, which collectively power the multi-model, multi-provider orchestration.
Quick visuals to grasp the project at a glance:
GitHub stars badge:
License badge:
TypeScript badge:
Coverage badge:
A compact yet powerful feature: you can kick off a team-based workflow with a single call like runTeam(team, "Build a REST API"). The coordinator agent decomposes the goal into a task DAG, resolves dependencies, runs independent tasks in parallel, and synthesizes the final output. There is no need for you to draw graphs or wire task connections; the framework handles the orchestration behind the scenes.
The ecosystem presents a TypeScript-native runtime with three dependencies, enabling you to embed Open Multi-Agent into Express, Next.js, serverless functions, or CI/CD pipelines. There is no Python runtime involved, and no need for a subprocess bridge to connect to a cloud provider. This design facilitates fast iteration and a compact deployment footprint.

What You Actually Get

Goal-to-call abstraction: the central promise is to produce a complete outcome from a single runTeam() invocation. The orchestrator creates a coordinator agent that translates a broad objective into a structured task DAG, orchestrates parallel task execution, and then synthesizes the end product.
TypeScript-native architecture: the runtime is purpose-built for the Node.js ecosystem. The three runtime dependencies (@anthropic-ai/sdk, openai, zod) cover the core LLM calls, model management, and strict schema validation. This approach avoids Python runtimes, bridges, or cloud-sidecar components, ensuring a lightweight footprint.
Multi-model teams: a team can host a mix of agents, each potentially backed by different providers. You can mix Claude, GPT, Gemini, Grok, MiniMax, DeepSeek, Copilot, or any OpenAI-compatible local model within the same runTeam() call. An optional peer dependency (Gemini via npm install @google/genai) enables Gemini as a peer model provider when desired.
Composition and collaboration: teams are composed of individual agents that operate on distinct tasks end-to-end. The framework supports a shared memory and a message bus so agents can observe outputs from others, enabling collaboration without mid-conversation handoffs. If you need a higher level of tooling, you can integrate MCP tools for model-context interactions, or use local tools via the built-in ToolRegistry.
Practical workflow: in a typical scenario, a team includes architects, developers, and reviewers. The orchestrator creates a sequence where tasks start in parallel when possible, and subsequent tasks unlock as dependencies complete. The result is a synthesized document, code skeleton, or any structured output required by the goal.
CLI and JSON-focused operation: for shell-based workflows or CI pipelines, the package exposes a JSON-first binary (oma) with commands such as oma run, oma task, and oma provider. This enables automation and scripting without diving into the runtime API in every scenario.
Quick-start constants: you can model a three-agent setup with a single orchestrator. The code snippet demonstrates how to define agents, assemble a team, and invoke runTeam() to produce a REST API for a todo list, with progress and token usage metrics returned as part of the result.
Visualizing the flow: the under-the-hood sequence shows the state transitions from agent_start through coordinator task completion, culminating in a final synthesized result. The example clearly marks the progression of architect and developer tasks running in parallel, followed by reviewer validation, and finally the coordinator synthesizing the output.
Visual assets included for context:
Star history:
Contributors overview:

Philosophy: What We Build, What We Don’t

We build a focused, principled toolkit for team-based, goal-driven workflows:
A coordinator that decomposes a goal into a task DAG, enabling structured planning.
A task queue that executes independent tasks in parallel and cascades failures to dependents when necessary.
A shared memory and message bus so agents can observe and react to each other’s outputs.
Multi-model teams where each agent may use a different LLM provider, accommodating heterogeneous toolchains and capabilities.
We don’t build certain extensible features that would conflict with the three-dependency promise:
Agent handoffs: the framework avoids mid-conversation transfers between agents. If your workflow requires cross-agent handoffs, use the OpenAI Agents SDK in Python instead. In this model, each agent owns a single task end-to-end.
State persistence / checkpointing: no persistent storage backend is provided by default. Workflows are designed to run in seconds to minutes, where a full persistence layer would violate the three-dependency constraint. If long-running workflows become common, we will reassess this stance.
In-flight A2A protocol: while there’s consideration for actor-to-actor protocol enhancements as production adoption grows, the current focus remains on first-class orchestration and task-level autonomy within a single runTeam() invocation.

How This Differs From Alternatives

vs LangGraph JS: LangGraph provides declarative graph orchestration by letting you define nodes, edges, and conditional routing, then compile and invoke the graph. Open Multi-Agent, in contrast, is goal-driven: you declare a team and a goal, and the system decomposes the task graph dynamically at runtime. LangGraph excels for fixed, production-grade graphs with mature checkpointing; Open Multi-Agent emphasizes rapid iteration and exploratory multi-agent work with less upfront topology definition.
vs CrewAI: CrewAI is a mature Python-based solution. If your stack is Python-centric, CrewAI is a natural fit. Open Multi-Agent remains TypeScript-native with three runtime dependencies and a direct Node.js embedding without subprocess bridges, placing itself as a robust option for TS-first ecosystems.
vs Vercel AI SDK: The AI SDK focuses on LLM calls, streaming, tool calls, and structured outputs but does not orchestrate multi-agent teams. Open Multi-Agent sits on top when you need a coordinated team of agents with shared state and cross-agent collaboration. The two can be complementary: use the AI SDK for single-agent work and turn to Open Multi-Agent when you need team-based orchestration.

Quick Start Guide

Prerequisites: Node.js version 18 or newer.
Installation: npm install @jackchen_me/open-multi-agent
API keys and local models:
Required for cloud providers: ANTHROPICAPIKEY, OPENAIAPIKEY, GEMINIAPIKEY, XAIAPIKEY (Grok), MINIMAXAPIKEY, MINIMAXBASEURL (optional for China endpoint), DEEPSEEKAPIKEY, GITHUB_TOKEN (Copilot)
Local models via Ollama require no API key. Local inference can be used with Ollama, vLLM, LM Studio, or llama.cpp via an OpenAI-compatible API wrapper. For local use, you can point the baseURL to a local server like http://localhost:11434/v1 and use apiKey: 'ollama'.
CLI usage: oma run, oma task, oma provider, etc., with JSON-first input/output formats. This enables shell scripting and CI integration without custom runtime logic.
Simple three-agent example: the following conceptual snippet shows three agents (architect, developer, reviewer) and an orchestrator to run a team. It demonstrates how a team is created and how runTeam() is invoked to generate a REST API for a todo-list backend:
The example defines agent configurations, creates an orchestrator with a default model, builds a team with sharedMemory, and executes:
- 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)
Under-the-hood flow can be summarized as:
- agentstart, coordinator taskstart, architect taskstart, architect taskcomplete, developer taskstart, developer taskstart (parallel), developer taskcomplete, reviewer taskstart when unblocked, reviewer taskcomplete, agentcomplete, coordinator (synthesis), resulting in a final Success: true with token usage logged.

Architecture at a Glance

OpenMultiAgent (Orchestrator)
Primary entry points: createTeam(), runTeam(), runTasks(), runAgent(), getStatus()
Team
Contains: AgentConfig[] definitions, MessageBus, TaskQueue, SharedMemory
Core Components
AgentPool: manages multiple agents, supports parallelism and task-level isolation
TaskQueue: schedules and runs tasks, handles semaphores, detects dependencies, cascades failures
SharedMemory: a memory space shared by agents to observe outputs
MessageBus: facilitates cross-agent communication and event propagation
Execution Flow
Agent instances run tasks, with a central coordination point that defines task order, handles dependencies, and triggers the synthesis phase
Adapters and Tools
LLMAdapter: abstracts provider connections (Anthropic, OpenAI, Grok, MiniMax, DeepSeek, Copilot, Gemini, Ollama-based local models)
ToolRegistry: central registry of built-in tools and custom tools
AgentRunner: manages agent conversations and tool dispatch
Built-in Tools
bash: executes shell commands with support for timeout and working directory
fileread, filewrite, file_edit: file I/O with safe handling and path considerations
grep: regex-based content search
glob: file pattern matching across the filesystem
Tool Configuration and Filtering
Tool presets (readonly, readwrite, full) provide baseline access for common use cases
Advanced filtering allows combining presets with allowlists and denylists
Resolution order: preset → allowlist → denylist → framework safety rails
MCP Tools: optional integration with Model Context Protocol to expose MCP server tools
Local tools added via agent.addTool() remain available regardless of filtering
Local Model Tool-Calling
Tool-calling is supported by native servers (Ollama, vLLM, LM Studio, llama.cpp)
Verified models include Gemma 4, Llama 3.1, Qwen 3, Mistral, Phi-4
Fallback extraction: if a model returns tool calls in free text, the framework extracts them automatically
Timeout: you can configure timeoutMs in AgentConfig to avoid indefinite hangs
Troubleshooting guidance covers model tool support, Ollama versions, and proxy considerations
LLM Configuration Examples
grokAgent, minimaxAgent, deepseekAgent sample AgentConfig snippets illustrate how to set provider and model
Environment variables (XAIAPIKEY, MINIMAXAPIKEY, DEEPSEEKAPIKEY) control credentials
BaseURL and apiKey usage demonstrate how to connect to local or remote providers
Runtime Providers and Status
Anthropic (Claude), OpenAI (GPT), Grok (xAI), MiniMax (Global and China), DeepSeek, GitHub Copilot, Gemini, Ollama/vLLM/LM Studio
Local deployment scenarios show baseURL and provider combinations for flexible integration
Gemini requires an optional peer dependency (npm install @google/genai)
Local Model Tool-Calling and Verification
Verified models and local tool-calling support enable robust experimentation with offline or on-premises stacks
Ollama-based tool-calling is highlighted with guidance on supported models and troubleshooting steps
Local Configuration and Troubleshooting
Timeout handling helps guard against hanging workflows
Proxy considerations (no_proxy) for local server communication
Tools you can call locally are surfaced in the ToolRegistry and can be extended through addTool()
Example Scenarios and Use Cases
18 runnable scripts plus a full-stack demo exist under examples/
Notable examples include:
- 02 — Team Collaboration: runTeam() orchestrator pattern
- 06 — Local Model: Ollama and Claude integration via baseURL
- 09 — Structured Output: Zod-validated JSON from any agent
- 11 — Trace Observability: onTrace spans across LLMs, tools, and tasks
- 17 — MiniMax: three-agent team using MiniMax M2.7
- 18 — DeepSeek: three-agent team with DeepSeek Chat
- with-vercel-ai-sdk: Next.js app integrating runTeam() with streaming AI SDK useChat
Contributing and Community
Issues and feature requests are welcome, with a focus on expanding Examples and Documentation
Contributors image:
Star History and Recognition
Star history visualization:
License
MIT

Built-in Tools in Detail

bash
Purpose: execute shell commands; returns stdout and stderr; supports timeout and cwd
file_read
Purpose: read file contents at an absolute path; supports offset and limit for large files
file_write
Purpose: write or create a file; auto-creates parent directories
file_edit
Purpose: edit a file by replacing an exact string match
grep
Purpose: search file contents with regex; uses ripgrep when available
glob
Purpose: locate files by glob pattern; returns paths sorted by modification time

Tool Configuration: Fine-Grained Access and MCP

Tool Presets
readonly: file_read, grep, glob
readwrite: fileread, filewrite, file_edit, grep, glob
full: fileread, filewrite, file_edit, grep, glob, bash
Advanced Filtering
Combine presets with allowlists and denylists for precise control
Example: start with readwrite, then intersect with allowed file_read and grep, but deny grep in the final set
Resolution Order
Preset → allowlist → denylist → framework safety rails
Custom Tools and MCP
Tools added via agent.addTool() are always available
MCP Tools enable Model Context Protocol integration; you can connect to an MCP server and expose its tools directly
Example code demonstrates connecting to an MCP server, registering tools, and cleaning up when done

Local Model Tool-Calling: Practicalities

Supported models and servers
Ollama, vLLM, LM Studio, llama.cpp provide OpenAI-compatible API shells for local tool-calling
Verified local models include Gemma 4, Llama 3.1, Qwen 3, Mistral, Phi-4
Fallback and extraction
If a local model returns tool calls as plain text, the framework automatically extracts tool calls from the text
Timeout and reliability
timeoutMs on AgentConfig helps avoid indefinite hangs in slow local inference scenarios
Troubleshooting tips
Ensure the target model supports tool-calling and appears in Ollama’s Tools category
Keep Ollama updated (ollama update) to address known tool-calling issues
If running behind a proxy, adjust no_proxy to include localhost

LLM Configuration Examples

Grok agent
Example: provider: 'grok', model: 'grok-4', systemPrompt: 'You are a helpful assistant.'
MiniMax agent
Example: provider: 'minimax', model: 'MiniMax-M2.7', systemPrompt: 'You are a helpful assistant.'
Set MINIMAXAPIKEY; the adapter selects the endpoint via MINIMAXBASEURL
DeepSeek agent
Example: provider: 'deepseek', model: 'deepseek-chat', systemPrompt: 'You are a helpful assistant.'
BaseURL override
You can override the environment-driven baseURL by passing baseURL in AgentConfig

Providers and Environment

Supported providers and their configuration
Anthropic (Claude): provider: 'anthropic', ANTHROPICAPIKEY
OpenAI (GPT): provider: 'openai', OPENAIAPIKEY
Grok (xAI): provider: 'grok', XAIAPIKEY
MiniMax (Global): provider: 'minimax', MINIMAXAPIKEY
MiniMax (China): provider: 'minimax', MINIMAXAPIKEY with MINIMAXBASEURL set
DeepSeek: provider: 'deepseek', DEEPSEEKAPIKEY
GitHub Copilot: provider: 'copilot', GITHUB_TOKEN
Gemini: provider: 'gemini', GEMINIAPIKEY
Local models (Ollama/vLLM/LM Studio/llama.cpp): provider: 'openai' with a local baseURL
Gemini integration
Gemini requires an optional peer dependency: npm install @google/genai
When enabled, Gemini can participate as a peer agent provider
Local model tool-calling verification
Gemma 4, Llama 3.1, Qwen 3, Mistral, Phi-4 verified via Ollama tooling
Extensibility
The framework is designed to work with a growing set of providers, including evolving local models and MCP-based tool contexts
You can mix providers across a single runTeam() invocation

Local Model Tool-Calling Deep Dive (Inline Notes)

Local inference paths
Ollama-based tooling integrates with standard OpenAI-compatible API shapes
Local models may require alignment with tool-calling interfaces; the system extracts tool calls if only text output is available
Timeout strategies
timeoutMs setting prevents stalls; recommended for slower local models
Troubleshooting reminders
Confirm the model supports tool-calling in Ollama’s Tools catalog
Keep local servers updated to address known tooling quirks
If using proxies, ensure proper network routing and environment configurations

Contributing and Community Growth

Contributions welcome
Areas where help is especially valuable include: expanding Examples, improving Documentation, and refining tooling presets
Documentation and examples
The project ships with numerous runnable examples and a growing set of tutorials
Community prompts
If you are using Open Multi-Agent in production or a side project, consider starting a discussion to share your workflow or headlining use case

Recurring Visuals and Status

Contributors badge
Contributors image:
Star history visualization
Star History Chart:

Quick Reference: Modes of Operation

Mode, Method, When to Use
Single agent: runAgent() — the simplest entry point for one-agent workflows
Auto-orchestrated team: runTeam() — declare a goal, and the framework plans and executes the task DAG
Explicit pipeline: runTasks() — you define the task graph and assignments for precise control
MapReduce-style fan-out
If you require fan-out with no dependencies, you can call AgentPool.runParallel() directly
See example 07 in the repository for a concrete fan-out pattern

Examples and Demos

The project ships with 18 runnable scripts and a full-stack demo under examples/
Highlights:
02 — Team Collaboration: demonstrates the runTeam() coordinator pattern
06 — Local Model: shows Ollama integration with Claude using baseURL
09 — Structured Output: enforcing Zod-validated JSON from agent outputs
11 — Trace Observability: onTrace spans across LLM calls, tools, and tasks
17 — MiniMax: three-agent team using MiniMax M2.7
18 — DeepSeek: three-agent team using DeepSeek Chat
with-vercel-ai-sdk: Next.js app demonstrating runTeam() in combination with the AI SDK’s streaming useChat
Running examples
Execute with npx tsx examples/02-team-collaboration.ts to verify behavior and study orchestration patterns

Architecture Recap

The design centers on three pillars:
Orchestrator-centric control flow: a single entry point for end-to-end team workflows
Decoupled agent responsibilities: every agent owns one task end-to-end, reducing cross-talk and failure domains
Multi-model, multi-provider flexibility: teams can blend providers to suit use cases and data sensitivities
Practical safeguards:
Tools and presets allow precise shaping of agent capabilities and permissions
Local model tool-calling expands offline, on-premises orchestration
Observability hooks (e.g., tracing) help diagnose and optimize performance and reliability
The architecture fosters rapid iteration:
Developers can experiment with different provider mixes, tool configurations, and team compositions without changing the core runtime
The JSON-first CLI supports automation and continuous integration scenarios

License and Community Etiquette

License
MIT
Encouragement to translate and localize
The project invites translations and cross-language adoption, inviting contributions through PRs and discussions
Community channels
Discussions are welcome on the GitHub Discussions page, and the project maintains a presence for discussions around real-world usage

Final Notes

Open Multi-Agent presents a coherent framework for TypeScript-native multi-agent orchestration with a clear philosophy: keep the surface simple, enable team-based capabilities, and provide a pathway for rapid experimentation with minimal configuration.
The combination of three runtime dependencies, a robust agent-team model, built-in tooling, local model support, and flexible provider options makes it suitable for a wide range of workflows—from software API scaffolding to research experiments and automated QA pipelines.
The project remains active, with ongoing contributions and a growing ecosystem of examples and use cases. Whether you are exploring new multi-agent patterns or building production-grade, team-based automation, Open Multi-Agent offers a focused set of capabilities designed to accelerate development while maintaining a clean, understandable orchestration model.

Open Multi-Agent: Lightweight Multi-Agent Orchestration for TypeScript

Enjoying this project?

GitHub - JackChen-me/open-multi-agent: Open Multi-Agent: Lightweight Multi-Agent Orchestration for TypeScript

Stay Updated

Product

Learn

Company

Legal

Stay Updated