Open Multi-Agent

TypeScript framework for multi-agent orchestration. One runTeam() call from goal to result — the framework decomposes it into tasks, resolves dependencies, and runs agents in parallel.

3 runtime dependencies · 33 source files · Deploys anywhere Node.js runs · Mentioned in Latent Space AI News

English | 中文

Why Open Multi-Agent?

• Goal In, Result Out — runTeam(team, "Build a REST API"). A coordinator agent auto-decomposes the goal into a task DAG with dependencies and assignees, runs independent tasks in parallel, and synthesizes the final output. No manual task definitions or graph wiring required.
• TypeScript-Native — Built for the Node.js ecosystem. npm install, import, run. No Python runtime, no subprocess bridge, no sidecar services. Embed in Express, Next.js, serverless functions, or CI/CD pipelines.
• Auditable and Lightweight — 3 runtime dependencies (@anthropic-ai/sdk, openai, zod). 33 source files. The entire codebase is readable in an afternoon.
• Model Agnostic — Claude, GPT, Gemma 4, and local models (Ollama, vLLM, LM Studio, llama.cpp server) in the same team. Swap models per agent via baseURL.
• Multi-Agent Collaboration — Agents with different roles, tools, and models collaborate through a message bus and shared memory.
• Structured Output — Add outputSchema (Zod) to any agent. Output is parsed as JSON, validated, and auto-retried once on failure. Access typed results via result.structured.
• Task Retry — Set maxRetries on tasks for automatic retry with exponential backoff. Failed attempts accumulate token usage for accurate billing.
• Human-in-the-Loop — Optional onApproval callback on runTasks(). After each batch of tasks completes, your callback decides whether to proceed or abort remaining work.
• Lifecycle Hooks — beforeRun / afterRun on AgentConfig. Intercept the prompt before execution or post-process results after. Throw from either hook to abort.
• Loop Detection — loopDetection on AgentConfig catches stuck agents repeating the same tool calls or text output. Configurable action: warn (default), terminate, or custom callback.
• Observability — Optional onTrace callback emits structured spans for every LLM call, tool execution, task, and agent run — with timing, token usage, and a shared runId for correlation. Zero overhead when not subscribed, zero extra dependencies.

Quick Start

Requires Node.js >= 18.

npm install @jackchen_me/open-multi-agent

Set the API key for your provider. Local models via Ollama require no API key — see example 06.

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• GEMINI_API_KEY
• GITHUB_TOKEN (for Copilot)

Three agents, one goal — the framework handles the rest:

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,
})

// 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`)

What happens under the hood:

agent_start coordinator
task_start architect
task_complete architect
task_start developer
task_start developer              // independent tasks run in parallel
task_complete developer
task_start reviewer               // unblocked after implementation
task_complete developer
task_complete reviewer
agent_complete coordinator        // synthesizes final result
Success: true
Tokens: 12847 output tokens

Three Ways to Run

Mode	Method	When to use
Single agent	runAgent()	One agent, one prompt — simplest entry point
Auto-orchestrated team	runTeam()	Give a goal, framework plans and executes
Explicit pipeline	runTasks()	You define the task graph and assignments

Examples

All examples are runnable scripts in examples/. Run any of them with npx tsx:

npx tsx examples/01-single-agent.ts

Example	What it shows
01 — Single Agent	runAgent() one-shot, stream() streaming, prompt() multi-turn
02 — Team Collaboration	runTeam() auto-orchestration with coordinator pattern
03 — Task Pipeline	runTasks() explicit dependency graph (design → implement → test + review)
04 — Multi-Model Team	defineTool() custom tools, mixed Anthropic + OpenAI providers, AgentPool
05 — Copilot	GitHub Copilot as an LLM provider
06 — Local Model	Ollama + Claude in one pipeline via baseURL (works with vLLM, LM Studio, etc.)
07 — Fan-Out / Aggregate	runParallel() MapReduce — 3 analysts in parallel, then synthesize
08 — Gemma 4 Local	runTasks() + runTeam() with local Gemma 4 via Ollama — zero API cost
09 — Structured Output	outputSchema (Zod) on AgentConfig — validated JSON via result.structured
10 — Task Retry	maxRetries / retryDelayMs / retryBackoff with task_retry progress events
11 — Trace Observability	onTrace callback — structured spans for LLM calls, tools, tasks, and agents
12 — Grok	Same as example 02 (runTeam() collaboration) with Grok (XAI_API_KEY)
13 — Gemini	Gemini adapter smoke test with gemini-2.5-flash (GEMINI_API_KEY)

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

Built-in Tools

Tool	Description
bash	Execute shell commands. Returns stdout + stderr. Supports timeout and cwd.
file_read	Read file contents at an absolute path. Supports offset/limit for large files.
file_write	Write or create a file. Auto-creates parent directories.
file_edit	Edit a file by replacing an exact string match.
grep	Search file contents with regex. Uses ripgrep when available, falls back to Node.js.

Supported Providers

Provider	Config	Env var	Status
Anthropic (Claude)	provider: 'anthropic'	ANTHROPIC_API_KEY	Verified
OpenAI (GPT)	provider: 'openai'	OPENAI_API_KEY	Verified
Grok (xAI)	provider: 'grok'	XAI_API_KEY	Verified
GitHub Copilot	provider: 'copilot'	GITHUB_TOKEN	Verified
Gemini	provider: 'gemini'	GEMINI_API_KEY	Verified
Ollama / vLLM / LM Studio	provider: 'openai' + baseURL	—	Verified
llama.cpp server	provider: 'openai' + baseURL	—	Verified

Verified local models with tool-calling: Gemma 4 (see example 08).

Any OpenAI-compatible API should work via provider: 'openai' + baseURL (DeepSeek, Groq, Mistral, Qwen, MiniMax, etc.). Grok now has first-class support via provider: 'grok'.

Local Model Tool-Calling

The framework supports tool-calling with local models served by Ollama, vLLM, LM Studio, or llama.cpp. Tool-calling is handled natively by these servers via the OpenAI-compatible API.

Verified models: Gemma 4, Llama 3.1, Qwen 3, Mistral, Phi-4. See the full list at ollama.com/search?c=tools.

Fallback extraction: If a local model returns tool calls as text instead of using the tool_calls wire format (common with thinking models or misconfigured servers), the framework automatically extracts them from the text output.

Timeout: Local inference can be slow. Use timeoutMs on AgentConfig to prevent indefinite hangs:

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
}

Troubleshooting:

• Model not calling tools? Ensure it appears in Ollama's Tools category. Not all models support tool-calling.
• Using Ollama? Update to the latest version (ollama update) — older versions have known tool-calling bugs.
• Proxy interfering? Use no_proxy=localhost when running against local servers.

LLM Configuration Examples

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

(Set your XAI_API_KEY environment variable — no baseURL needed anymore.)

Contributing

Issues, feature requests, and PRs are welcome. Some areas where contributions would be especially valuable:

• Provider integrations — Verify and document OpenAI-compatible providers (DeepSeek, Groq, Qwen, MiniMax, etc.) via baseURL. See #25. For providers that are NOT OpenAI-compatible (e.g. Gemini), a new LLMAdapter implementation is welcome — the interface requires just two methods: chat() and stream().
• Examples — Real-world workflows and use cases.
• Documentation — Guides, tutorials, and API docs.

Author

JackChen — Ex PM (¥100M+ revenue), now indie builder. Follow on X for AI Agent insights.

Contributors

Star History

Translations

Help translate this README — open a PR.

License

MIT