Quick Start

Requires Node.js >= 18.

npm install @open-multi-agent/core

Migrating from @jackchen_me/open-multi-agent? That package is deprecated; install @open-multi-agent/core instead.

import { OpenMultiAgent, type AgentConfig } from '@open-multi-agent/core'

const agents: AgentConfig[] = [
  { name: 'architect', model: 'claude-sonnet-4-6', systemPrompt: 'Design clean API contracts.', tools: ['file_write'] },
  { name: 'developer', model: 'claude-sonnet-4-6', systemPrompt: 'Implement runnable TypeScript.', tools: ['bash', 'file_read', 'file_write', 'file_edit'] },
  { name: 'reviewer', model: 'claude-sonnet-4-6', systemPrompt: 'Review correctness and security.', 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, sharedMemory: true })

// Built-in filesystem tools default to a `<cwd>/.agent-workspace` sandbox.
// Point the agent at an absolute path inside that root.
const result = await orchestrator.runTeam(
  team,
  `Create a REST API for a todo list in ${process.cwd()}/.agent-workspace/todo-api/`,
)

console.log(result.success, result.totalTokenUsage.output_tokens)

Run an example locally

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

Three agents collaborate on a REST API while onProgress streams the coordinator's task DAG:

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

Local models via Ollama need no API key, see providers/ollama. For hosted providers (OPENAI_API_KEY, GEMINI_API_KEY, etc.), see Supported Providers.

Examples

examples/ is organized by category: basics, cookbook, patterns, providers, and integrations. See examples/README.md for the full index. (production/ is open for contributions — see the acceptance criteria.)

Real-world workflows ([`cookbook/`](./examples/cookbook/))

End-to-end scenarios you can run today. Each one is a complete, opinionated workflow.

• contract-review-dag: four-task DAG for contract review with parallel branches and step-level retry on failure.
• meeting-summarizer: three specialised agents fan out on a transcript, an aggregator merges them into one Markdown report with action items and sentiment.
• competitive-monitoring: three parallel source agents extract claims from feeds; an aggregator cross-checks them and flags contradictions.
• translation-backtranslation: translate EN to target with one provider, back-translate with another, flag semantic drift.
• incident-postmortem-dag: three independent root tasks fan out at t=0, then a root-cause hypothesizer and postmortem writer synthesize them into one document.
• personalized-interview-simulator: a stateful interviewer (Agent.prompt() across turns) plus a transcript-reading observer, with readline human input and a Zod-validated debrief.

Vercel AI SDK (optional)

Install the optional peer ai plus any @ai-sdk provider you need (for example @ai-sdk/openai). Pass adapter: new AISdkAdapter(model) on AgentConfig to route that agent through the AI SDK instead of the built-in provider factory. provider, apiKey, baseURL, and region are ignored when adapter is set. Mixed teams work as usual: only agents with adapter use the AI SDK.

import { openai } from '@ai-sdk/openai'
import { AISdkAdapter } from '@open-multi-agent/core/ai-sdk'
import { OpenMultiAgent } from '@open-multi-agent/core'

const oma = new OpenMultiAgent()
await oma.runAgent(
  {
    name: 'researcher',
    model: 'gpt-4o',
    adapter: new AISdkAdapter(openai('gpt-4o')),
    systemPrompt: 'You are a researcher.',
  },
  'What are the latest AI trends?',
)

The coordinator accepts the same hook via runTeam(team, goal, { coordinator: { adapter: new AISdkAdapter(...) } }).

Integrations

• Engram — "Git for AI memory." Syncs knowledge across agents instantly and flags conflicts. (repo)
• @agentsonar/oma — Sidecar detecting cross-run delegation cycles, repetition, and rate bursts.

Built an integration? See the integration guide for how to submit a reference or vendor example and get your product listed.

Patterns and integrations

• basics/team-collaboration: runTeam() coordinator pattern.
• patterns/structured-output: any agent returns Zod-validated JSON.
• patterns/multi-perspective-code-review: a generator feeds security, performance, and style reviewers running in parallel, then a synthesizer returns Zod-validated findings.
• patterns/cross-provider-reasoning: preserve a reasoning model's thought stream across a provider switch via preserveReasoningAsText.
• patterns/cost-tiered-pipeline: assign a different model per stage and estimate per-model USD cost from onTrace token counts.
• patterns/fan-out-aggregate: MapReduce-style fan-out via AgentPool.runParallel().
• patterns/agent-handoff: synchronous sub-agent delegation via delegate_to_agent.
• patterns/plan-replay: decompose a goal once with planOnly, serialize it with createPlanArtifact, then replay the same DAG via runFromPlan without re-running the coordinator.
• integrations/trace-observability: onTrace spans for LLM calls, tools, and tasks.
• integrations/mcp-github: expose an MCP server's tools to an agent via connectMCPTools().
• integrations/with-vercel-ai-sdk: Next.js app combining OMA runTeam() with AI SDK useChat streaming.
• Provider examples: scripts under examples/providers/ covering hosted providers, OpenAI-compatible endpoints, and local models.

Run any script with npx tsx examples/<path>.ts.