GitHub Repo
MIT
April 18, 2026 at 12:01 PM0 views
Open Multi-Agent: Lightweight Multi-Agent Orchestration for TypeScript
@JackChen-meProject Author
- 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.
Enjoying this project?
Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.
Repository:https://github.com/JackChen-me/open-multi-agent
GitHub - JackChen-me/open-multi-agent: Open Multi-Agent: Lightweight Multi-Agent Orchestration for TypeScript
Open Multi-Agent is a lightweight orchestration engine designed for TypeScript that delivers goal-driven workflows with minimal setup....
github - jackchen-me/open-multi-agent
Project
open-multi-agent-lightweight-multi-agent-orchestration-for-typescript
Created
April 18
Last Updated
April 18, 2026 at 12:01 PM