# jackchen-me/open-multi-agent architecture

> Architecture diagram of the GitHub repository jackchen-me/open-multi-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jackchen-me/open-multi-agent
- Repository: https://github.com/jackchen-me/open-multi-agent

## Overview

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: [`src/tool/built-in/index.ts`](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/index.ts) (Built-ins), [`src/index.ts`](https://github.com/jackchen-me/open-multi-agent/blob/main/src/index.ts) (Package API), [`src/orchestrator/orchestrator.ts`](https://github.com/jackchen-me/open-multi-agent/blob/main/src/orchestrator/orchestrator.ts) (Orchestrator), [`src/agent/runner.ts`](https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/runner.ts) (Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Public API"]
  node_src_index["Package API<br/>facade<br/>[index.ts]"]
  node_src_types["Types<br/>[types.ts]"]
end

subgraph group_orchestration["Orchestration"]
  node_orch["Orchestrator<br/>execution coordinator<br/>[orchestrator.ts]"]
  node_sched["Scheduler<br/>[scheduler.ts]"]
end

subgraph group_agents["Agents"]
  node_agent["Agent<br/>[agent.ts]"]
  node_runner["Runner<br/>agent loop<br/>[runner.ts]"]
  node_pool["Agent Pool<br/>concurrency control<br/>[pool.ts]"]
end

subgraph group_team["Team"]
  node_team["Team<br/>collaboration model<br/>[team.ts]"]
  node_msg["Message Bus<br/>team messaging<br/>[messaging.ts]"]
end

subgraph group_tasks["Tasks"]
  node_task["Task<br/>[task.ts]"]
  node_queue["Task Queue<br/>dag queue<br/>[queue.ts]"]
end

subgraph group_tools["Tools"]
  node_toolfw["Tool Framework<br/>tool registry<br/>[framework.ts]"]
  node_toolexec["Tool Executor<br/>tool dispatch<br/>[executor.ts]"]
  node_builtins["Built-ins<br/>tool set<br/>[index.ts]"]
  node_bash["Bash<br/>shell tool<br/>[bash.ts]"]
  node_fread["File Read<br/>filesystem tool<br/>[file-read.ts]"]
  node_fwrite["File Write<br/>filesystem tool<br/>[file-write.ts]"]
  node_fedit["File Edit<br/>filesystem tool<br/>[file-edit.ts]"]
  node_grep["Grep<br/>search tool<br/>[grep.ts]"]
end

subgraph group_llm["LLM"]
  node_adapter["LLM Adapter<br/>provider interface<br/>[adapter.ts]"]
  node_anthropic["Anthropic<br/>llm provider<br/>[anthropic.ts]"]
  node_openai["OpenAI<br/>llm provider<br/>[openai.ts]"]
end

subgraph group_state["State"]
  node_memory["Shared Memory<br/>shared state<br/>[shared.ts]"]
  node_store["Memory Store<br/>[store.ts]"]
  node_sem["Semaphore<br/>concurrency primitive<br/>[semaphore.ts]"]
end

subgraph group_examples["Examples"]
  node_ex1["Single Agent<br/>example<br/>[01-single-agent.ts]"]
  node_ex2["Team Collaboration<br/>example"]
  node_ex3["Task Pipeline<br/>example"]
  node_ex4["Multi-Model Team<br/>example"]
end

node_src_index -->|"exports"| node_orch
node_src_index -->|"exports"| node_agent
node_src_index -->|"exports"| node_toolfw
node_src_index -->|"exports"| node_builtins
node_src_index -->|"exports"| node_src_types
node_orch -->|"delegates"| node_sched
node_orch -->|"creates"| node_team
node_orch -->|"uses"| node_pool
node_orch -->|"runs"| node_agent
node_sched -->|"orders"| node_task
node_sched -->|"drives"| node_queue
node_team -->|"contains"| node_msg
node_team -->|"shares"| node_memory
node_team -->|"uses"| node_queue
node_queue -->|"tracks"| node_task
node_pool -->|"limits"| node_sem
node_agent -->|"executes"| node_runner
node_runner -->|"calls"| node_adapter
node_runner -->|"dispatches"| node_toolexec
node_runner -->|"coordinates"| node_msg
node_runner -->|"reads-writes"| node_memory
node_adapter -->|"implements"| node_anthropic
node_adapter -->|"implements"| node_openai
node_toolfw -->|"registers"| node_builtins
node_toolfw -->|"feeds"| node_toolexec
node_builtins -->|"includes"| node_bash
node_builtins -->|"includes"| node_fread
node_builtins -->|"includes"| node_fwrite
node_builtins -->|"includes"| node_fedit
node_builtins -->|"includes"| node_grep
node_memory -->|"backs"| node_store
node_ex1 -->|"uses"| node_agent
node_ex2 -->|"uses"| node_team
node_ex3 -->|"uses"| node_queue
node_ex4 -->|"uses"| node_anthropic
node_ex4 -->|"uses"| node_openai

click node_src_index "https://github.com/jackchen-me/open-multi-agent/blob/main/src/index.ts"
click node_src_types "https://github.com/jackchen-me/open-multi-agent/blob/main/src/types.ts"
click node_orch "https://github.com/jackchen-me/open-multi-agent/blob/main/src/orchestrator/orchestrator.ts"
click node_sched "https://github.com/jackchen-me/open-multi-agent/blob/main/src/orchestrator/scheduler.ts"
click node_team "https://github.com/jackchen-me/open-multi-agent/blob/main/src/team/team.ts"
click node_msg "https://github.com/jackchen-me/open-multi-agent/blob/main/src/team/messaging.ts"
click node_task "https://github.com/jackchen-me/open-multi-agent/blob/main/src/task/task.ts"
click node_queue "https://github.com/jackchen-me/open-multi-agent/blob/main/src/task/queue.ts"
click node_agent "https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/agent.ts"
click node_runner "https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/runner.ts"
click node_pool "https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/pool.ts"
click node_adapter "https://github.com/jackchen-me/open-multi-agent/blob/main/src/llm/adapter.ts"
click node_anthropic "https://github.com/jackchen-me/open-multi-agent/blob/main/src/llm/anthropic.ts"
click node_openai "https://github.com/jackchen-me/open-multi-agent/blob/main/src/llm/openai.ts"
click node_toolfw "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/framework.ts"
click node_toolexec "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/executor.ts"
click node_builtins "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/index.ts"
click node_bash "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/bash.ts"
click node_fread "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/file-read.ts"
click node_fwrite "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/file-write.ts"
click node_fedit "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/file-edit.ts"
click node_grep "https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/grep.ts"
click node_memory "https://github.com/jackchen-me/open-multi-agent/blob/main/src/memory/shared.ts"
click node_store "https://github.com/jackchen-me/open-multi-agent/blob/main/src/memory/store.ts"
click node_sem "https://github.com/jackchen-me/open-multi-agent/blob/main/src/utils/semaphore.ts"
click node_ex1 "https://github.com/jackchen-me/open-multi-agent/blob/main/examples/01-single-agent.ts"
click node_ex2 "https://github.com/jackchen-me/open-multi-agent/blob/main/examples/02-team-collaboration.ts"
click node_ex3 "https://github.com/jackchen-me/open-multi-agent/blob/main/examples/03-task-pipeline.ts"
click node_ex4 "https://github.com/jackchen-me/open-multi-agent/blob/main/examples/04-multi-model-team.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_src_types,node_adapter,node_anthropic,node_openai toneBlue
class node_orch,node_sched,node_memory,node_store,node_sem toneAmber
class node_agent,node_runner,node_pool,node_ex1,node_ex2,node_ex3,node_ex4 toneMint
class node_team,node_msg toneRose
class node_task,node_queue toneIndigo
class node_toolfw,node_toolexec,node_builtins,node_bash,node_fread,node_fwrite,node_fedit,node_grep toneTeal
```

## Components

### Public API

Package façade and shared types.

- [Package API](https://github.com/jackchen-me/open-multi-agent/blob/main/src/index.ts): facade · Main package surface re-exporting the primary APIs and types. · `src/index.ts`
- [Types](https://github.com/jackchen-me/open-multi-agent/blob/main/src/types.ts): shared types · Shared type definitions used across the framework. · `src/types.ts`

### Orchestration

Top-level coordination, scheduling, and team execution.

- [Orchestrator](https://github.com/jackchen-me/open-multi-agent/blob/main/src/orchestrator/orchestrator.ts): execution coordinator · Top-level runtime that runs agents, teams, and task workflows. · `src/orchestrator/orchestrator.ts`
- [Scheduler](https://github.com/jackchen-me/open-multi-agent/blob/main/src/orchestrator/scheduler.ts): workflow scheduler · Coordinates task and team execution flow beneath the orchestrator. · `src/orchestrator/scheduler.ts`

### Agents

Agent runtime, pooling, and model-driven execution.

- [Agent](https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/agent.ts): public agent · Public agent API exposing run and stream behavior. · `src/agent/agent.ts`
- [Runner](https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/runner.ts): agent loop · Executes the conversation loop, tool calls, and model turns. · `src/agent/runner.ts`
- [Agent Pool](https://github.com/jackchen-me/open-multi-agent/blob/main/src/agent/pool.ts): concurrency control · Schedules multiple agents or tasks in parallel within one process. · `src/agent/pool.ts`

### Team

Coordination primitives for multi-agent collaboration.

- [Team](https://github.com/jackchen-me/open-multi-agent/blob/main/src/team/team.ts): collaboration model · Defines a team of agents plus coordination state and policies. · `src/team/team.ts`
- [Message Bus](https://github.com/jackchen-me/open-multi-agent/blob/main/src/team/messaging.ts): team messaging · Routes messages between agents inside a team. · `src/team/messaging.ts`

### Tasks

Task graph and dependency-aware queueing.

- [Task](https://github.com/jackchen-me/open-multi-agent/blob/main/src/task/task.ts): task model · Represents units of work and their dependencies. · `src/task/task.ts`
- [Task Queue](https://github.com/jackchen-me/open-multi-agent/blob/main/src/task/queue.ts): dag queue · Resolves dependency order and propagates task completion or failure. · `src/task/queue.ts`

### Tools

Tool registration, validation, execution, and built-ins.

- [Tool Framework](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/framework.ts): tool registry · Registers and validates tools before execution. · `src/tool/framework.ts`
- [Tool Executor](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/executor.ts): tool dispatch · Runs tools requested by the agent loop. · `src/tool/executor.ts`
- [Built-ins](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/index.ts): tool set · Exports the built-in local tools as a bundle. · `src/tool/built-in/index.ts`
- [Bash](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/bash.ts): shell tool · Executes shell commands. · `src/tool/built-in/bash.ts`
- [File Read](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/file-read.ts): filesystem tool · Reads file contents. · `src/tool/built-in/file-read.ts`
- [File Write](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/file-write.ts): filesystem tool · Writes file contents. · `src/tool/built-in/file-write.ts`
- [File Edit](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/file-edit.ts): filesystem tool · Edits file contents in place. · `src/tool/built-in/file-edit.ts`
- [Grep](https://github.com/jackchen-me/open-multi-agent/blob/main/src/tool/built-in/grep.ts): search tool · Searches files for matching text. · `src/tool/built-in/grep.ts`

### LLM

Provider abstraction and concrete model adapters.

- [LLM Adapter](https://github.com/jackchen-me/open-multi-agent/blob/main/src/llm/adapter.ts): provider interface · Common chat and stream contract for model providers. · `src/llm/adapter.ts`
- [Anthropic](https://github.com/jackchen-me/open-multi-agent/blob/main/src/llm/anthropic.ts): llm provider · Anthropic-backed implementation of the LLM adapter. · `src/llm/anthropic.ts`
- [OpenAI](https://github.com/jackchen-me/open-multi-agent/blob/main/src/llm/openai.ts): llm provider · OpenAI-backed implementation of the LLM adapter. · `src/llm/openai.ts`

### State

Shared in-process memory and concurrency utilities.

- [Shared Memory](https://github.com/jackchen-me/open-multi-agent/blob/main/src/memory/shared.ts): shared state · Persistent in-process memory shared across agents in a team. · `src/memory/shared.ts`
- [Memory Store](https://github.com/jackchen-me/open-multi-agent/blob/main/src/memory/store.ts): memory store · Backing store for shared team context. · `src/memory/store.ts`
- [Semaphore](https://github.com/jackchen-me/open-multi-agent/blob/main/src/utils/semaphore.ts): concurrency primitive · Limits parallel work in the single-process runtime. · `src/utils/semaphore.ts`

### Examples

Usage examples for the main execution modes.

- [Single Agent](https://github.com/jackchen-me/open-multi-agent/blob/main/examples/01-single-agent.ts): example · Demonstrates one-agent execution. · `examples/01-single-agent.ts`
- [Team Collaboration](https://github.com/jackchen-me/open-multi-agent/blob/main/examples/02-team-collaboration.ts): example · Demonstrates multi-agent collaboration. · `examples/02-team-collaboration.ts`
- [Task Pipeline](https://github.com/jackchen-me/open-multi-agent/blob/main/examples/03-task-pipeline.ts): example · Demonstrates dependency-driven task execution. · `examples/03-task-pipeline.ts`
- [Multi-Model Team](https://github.com/jackchen-me/open-multi-agent/blob/main/examples/04-multi-model-team.ts): example · Demonstrates a team using multiple model providers. · `examples/04-multi-model-team.ts`

## Connections

- 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.
