Quick Start

What you will finish

You will scaffold a project, exercise the real OMA scheduler with scripted model responses, and open the generated Markdown, JSON, and HTML reports. The first run needs no API key and makes no model request.

Before you start

• Node.js 20 or newer (Node.js 22 or 24 recommended)
• npm access to download the generated project’s dependencies
• About five minutes

You do not need a provider account or API key for the first run.

Your first run

1. Create a starter

   npm create oma-app@latest my-oma

   The interactive scaffolder asks for a starter and runtime. For the clearest introduction to scheduling, choose Multi-agent DAG Demo. The PR Review and Security Analysis starters show the same runtime in more opinionated workflows.

2. What runs automatically

   The interactive command installs dependencies and runs npm run demo for you. Scripted model responses drive the real task scheduler, parallel execution, aggregation, report writers, and offline Run Viewer.

   The demo does not read a provider credential or make a model request. Installing the project still downloads packages from npm, and every generated report identifies the model responses as simulated.

   To run the same demo again:

   cd my-oma
   npm run demo

3. Check the result

   A successful run gives you three views of the same execution:

   • Terminal progress shows tasks starting, completing, and unblocking after their dependencies.
   • Markdown and JSON reports under reports/ make the result easy to read or process.
   • The HTML report opens the offline Run Viewer, where you can inspect the executed task DAG and task-level evidence.

   At this point you have exercised real OMA orchestration. Only the model responses were scripted.

4. Switch to a real model

   For a cloud or OpenAI-compatible starter, copy the environment template:

   cp .env.example .env

   Add your credential and model configuration to .env, then start the run:

   npm run dev

   An Ollama starter uses your local Ollama service instead and needs no cloud API key. The scaffolder never downloads a model for you. See Providers for environment variables, compatible endpoints, and local tool-calling guidance.

Control what the scaffolder runs

# Write files only; do not install dependencies or run the demo.
npm create oma-app@latest my-oma -- --no-install

# Install dependencies, but do not run the demo.
npm create oma-app@latest my-oma -- --no-run

Add OMA to an existing project

If you already have a TypeScript backend, install the library directly:

npm install @open-multi-agent/core

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

Then define a small team and give it a goal:

team.ts

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

const model = process.env.OMA_MODEL ?? 'gpt-5.4'
const agents: AgentConfig[] = [
  { name: 'researcher', model, systemPrompt: 'Find the important facts.' },
  { name: 'writer', model, systemPrompt: 'Turn the facts into a concise brief.' },
]

const oma = new OpenMultiAgent({ defaultProvider: 'openai', defaultModel: model })
const team = oma.createTeam('brief-team', { name: 'brief-team', agents })
const result = await oma.runTeam(team, 'Produce a launch brief for our new API.')

console.log(result.success)

Built-in tools are default-deny. Grant only the tools each agent needs; see Tool configuration before adding filesystem or shell access.

Where next

Choose a Run ModeDecide between runAgent(), runTeam(), and runTasks().

ExamplesComplete workflows you can run or adapt.

ProvidersConfigure hosted, OpenAI-compatible, or local models.