How jackchen-me/open-multi-agent works
1. Overall shape
This is a TypeScript, in-process multi-agent framework for Node.js. The core idea is: an orchestrator creates a team of agents, schedules tasks with dependencies, routes messages between agents, and lets agents call tools and LLM providers through a common abstraction layer.
2. Public entry point
src/index.ts is the package façade. It likely re-exports the main orchestrator, agent APIs, tool registry/executor, built-in tools, and type definitions so consumers interact with one stable surface instead of internal modules directly.
3. Orchestration layer
src/orchestrator/orchestrator.ts is the top-level coordinator exposed by the README as OpenMultiAgent. It owns the main workflows: runAgent, runTeam, runTasks, team creation, and status/progress reporting. This layer is the boundary between user code and the execution engine.
4. Team boundary
src/team/team.ts and src/team/messaging.ts define a team as a set of agent configs plus coordination mechanisms. The team encapsulates:
- a message bus for agent-to-agent communication,
- optional shared memory,
- and a task queue for work distribution.
This is the main unit for collaboration.
5. Task scheduling
src/task/task.ts and src/task/queue.ts model a task graph with dependencies. The queue resolves dependency order, unblocks downstream tasks when prerequisites complete, and can cascade failures when a dependency fails. This is the DAG scheduler described in the README.
6. Parallel execution control
src/agent/pool.ts and src/utils/semaphore.ts provide concurrency control for multiple agents or tasks running in one process. The pool is the execution boundary that lets independent work run in parallel without overwhelming the runtime or the LLM providers.
7. Agent runtime
src/agent/agent.ts and src/agent/runner.ts implement the agent loop. The agent is the public-facing entity with run() and stream() behavior, while the runner owns the conversation loop, tool dispatch, and turn-by-turn interaction with the model. This is where an agent translates a task into LLM calls and tool actions.
8. LLM abstraction
src/llm/adapter.ts defines the provider interface, and src/llm/anthropic.ts plus src/llm/openai.ts are concrete adapters. The architecture is model-agnostic: agents can target different providers in the same team, as long as they implement the common chat() and stream() contract. External dependencies here are the Anthropic and OpenAI APIs.
9. Tool subsystem
src/tool/framework.ts, src/tool/executor.ts, and src/tool/built-in/* form the tool layer. Tools are registered in a registry, validated with schemas, then executed by the tool executor when the agent requests them. The built-ins are:
- bash for shell commands,
- file_read,
- file_write,
- file_edit,
- grep.
This layer is the bridge from LLM decisions to local side effects on the filesystem or shell.
10. Shared memory
src/memory/store.ts and src/memory/shared.ts provide persistent-in-process context shared across agents in a team. This is separate from message passing: the bus is for coordination, while shared memory is for retained knowledge and cross-agent state.
11. Execution data flow
The typical path is: user call → orchestrator → team/task selection → agent pool schedules work → agent runner invokes LLM adapter → model may request tools → tool executor runs local actions or file/shell operations → results return to the agent loop → outputs and events flow back to orchestrator. For multi-agent runs, messages and shared memory are available between steps.
12. User-facing examples
The examples/ directory demonstrates the main architectural modes:
single-agent execution, team collaboration, explicit task pipelines, and mixed-model teams. These examples map directly to the core subsystems above and show that the package is designed for both ad hoc agent runs and structured DAG-based workflows.
13. Runtime and deployment implications
The framework is intentionally “in-process”: it runs inside one Node.js process and avoids subprocess orchestration overhead except where the bash tool is explicitly used. That makes the architecture suitable for serverless, CI/CD, Docker, and local automation where the main integration points are LLM APIs plus local filesystem/shell access.
Main entry points: built-in/index.ts Built-ins · src/index.ts Package API · orchestrator.ts Orchestrator · runner.ts Runner
Components 29
Public API
Package façade and shared types.
- Package API · Main package surface re-exporting the primary APIs and types.
src/index.ts - Types · Shared type definitions used across the framework.
src/types.ts
Orchestration
Top-level coordination, scheduling, and team execution.
- Orchestrator · Top-level runtime that runs agents, teams, and task workflows.
src/orchestrator/orchestrator.ts - Scheduler · Coordinates task and team execution flow beneath the orchestrator.
src/orchestrator/scheduler.ts
Agents
Agent runtime, pooling, and model-driven execution.
- Agent · Public agent API exposing run and stream behavior.
src/agent/agent.ts - Runner · Executes the conversation loop, tool calls, and model turns.
src/agent/runner.ts - Agent Pool · Schedules multiple agents or tasks in parallel within one process.
src/agent/pool.ts
Team
Coordination primitives for multi-agent collaboration.
- Team · Defines a team of agents plus coordination state and policies.
src/team/team.ts - Message Bus · Routes messages between agents inside a team.
src/team/messaging.ts
Tasks
Task graph and dependency-aware queueing.
- Task · Represents units of work and their dependencies.
src/task/task.ts - Task Queue · Resolves dependency order and propagates task completion or failure.
src/task/queue.ts
Tools
Tool registration, validation, execution, and built-ins.
- Tool Framework · Registers and validates tools before execution.
src/tool/framework.ts - Tool Executor · Runs tools requested by the agent loop.
src/tool/executor.ts - Built-ins · Exports the built-in local tools as a bundle.
src/tool/built-in/index.ts - Bash · Executes shell commands.
src/tool/built-in/bash.ts - File Read · Reads file contents.
src/tool/built-in/file-read.ts - File Write · Writes file contents.
src/tool/built-in/file-write.ts - File Edit · Edits file contents in place.
src/tool/built-in/file-edit.ts - Grep · Searches files for matching text.
src/tool/built-in/grep.ts
LLM
Provider abstraction and concrete model adapters.
- LLM Adapter · Common chat and stream contract for model providers.
src/llm/adapter.ts - Anthropic · Anthropic-backed implementation of the LLM adapter.
src/llm/anthropic.ts - OpenAI · OpenAI-backed implementation of the LLM adapter.
src/llm/openai.ts
State
Shared in-process memory and concurrency utilities.
- Shared Memory · Persistent in-process memory shared across agents in a team.
src/memory/shared.ts - Memory Store · Backing store for shared team context.
src/memory/store.ts - Semaphore · Limits parallel work in the single-process runtime.
src/utils/semaphore.ts
Examples
Usage examples for the main execution modes.
- Single Agent · Demonstrates one-agent execution.
examples/01-single-agent.ts - Team Collaboration · Demonstrates multi-agent collaboration.
examples/02-team-collaboration.ts - Task Pipeline · Demonstrates dependency-driven task execution.
examples/03-task-pipeline.ts - Multi-Model Team · Demonstrates a team using multiple model providers.
examples/04-multi-model-team.ts
Connections 36
- Package API → Orchestrator: exports · Public package surface exposes the orchestrator.
- Package API → Agent: exports · Public package surface exposes agent APIs.
- Package API → Tool Framework: exports · Public package surface exposes tool primitives.
- Package API → Built-ins: exports · Public package surface exposes bundled tools.
- Package API → Types: exports · Public package surface exposes shared types.
- Orchestrator → Scheduler: delegates · Orchestrator uses the scheduler to coordinate workflows.
- Orchestrator → Team: creates · Orchestrator assembles teams for multi-agent runs.
- Orchestrator → Agent Pool: uses · Orchestrator dispatches work through the agent pool.
- Orchestrator → Agent: runs · Orchestrator can run a single agent directly.
- Scheduler → Task: orders · Scheduler works over task dependencies.
- Scheduler → Task Queue: drives · Scheduler relies on the task queue to resolve execution order.
- Team → Message Bus: contains · Team owns the message bus for intra-team communication.
- Team → Shared Memory: shares · Team can expose shared memory to agents.
- Team → Task Queue: uses · Team can distribute work through a task queue.
- Task Queue → Task: tracks · Queue manages task state and dependency relationships.
- Agent Pool → Semaphore: limits · Pool uses a semaphore to bound concurrency.
- Agent → Runner: executes · Agent behavior is implemented by the runner loop.
- Runner → LLM Adapter: calls · Runner sends conversation turns through the LLM adapter.
- Runner → Tool Executor: dispatches · Runner forwards tool requests to the tool executor.
- Runner → Message Bus: coordinates · Runner can exchange messages through team messaging.
- Runner → Shared Memory: reads-writes · Runner can persist and retrieve shared context.
- LLM Adapter → Anthropic: implements · Anthropic is one concrete adapter implementation.
- LLM Adapter → OpenAI: implements · OpenAI is one concrete adapter implementation.
- Tool Framework → Built-ins: registers · Framework includes the built-in tool set.
- Tool Framework → Tool Executor: feeds · Validated tool definitions are executed by the tool executor.
- Built-ins → Bash: includes · Built-in tool bundle includes bash.
- Built-ins → File Read: includes · Built-in tool bundle includes file read.
- Built-ins → File Write: includes · Built-in tool bundle includes file write.
- Built-ins → File Edit: includes · Built-in tool bundle includes file edit.
- Built-ins → Grep: includes · Built-in tool bundle includes grep.
- Shared Memory → Memory Store: backs · Shared memory is backed by the memory store.
- Single Agent → Agent: uses · Example demonstrates single-agent execution.
- Team Collaboration → Team: uses · Example demonstrates team collaboration.
- Task Pipeline → Task Queue: uses · Example demonstrates dependency-driven task pipelines.
- Multi-Model Team → Anthropic: uses · Example demonstrates mixed-model teams.
- Multi-Model Team → OpenAI: uses · Example demonstrates mixed-model teams.