Agent Collective

Interactive multi-agent simulator: a deterministic TypeScript engine driving a live React Flow dashboard. Six roles claim work, talk along a graph, fail, recover, and get better over time.

Live demo · Usage · Architecture · Deploy

Why this exists

Most “multi-agent” demos hide the loop behind a chat API. This one does the opposite: the world is a testable state machine. The UI is a cockpit. You can step a single tick, inject a resource shock, and watch the collective reroute — without a backend.

What you see

A default collective of Coder, Researcher, Trader, Monitor, Creative, and Critic, already wired as a workflow graph.

Live graph	Chaos and recovery

• Graph — drag nodes, draw edges, status by color (idle / working / failed).
• Clock — play, pause, step, 1×–8×.
• Events — resource shortage, market shift, targeted agent failure.
• Scenarios — save the graph to localStorage, load it later.

Operator walkthrough, including metrics, resources, and the task board: docs/usage.md.

Architecture

The engine owns truth. Each tick mutates SimState; Zustand publishes a clone; React Flow and the side panels render that snapshot.

flowchart LR
  UI[React dashboard] --> Store[Zustand]
  Store -->|"tick / events / CRUD"| Sim["src/sim (pure TS)"]
  Sim -->|snapshot| Store
  Store --> UI

Loading

src/sim/          domain — tick, agents, tasks, events, metrics
src/store/        adapter — play/pause, selection, scenario I/O
src/components/   view — graph + dashboard
docs/             usage, architecture, deploy, screenshots
.github/          CI + PR template

Details and the tick sequence: docs/architecture.md.

Quick start

git clone https://github.com/d0npedro/multi-agent.git
cd multi-agent
npm install
npm run dev

Open the URL Vite prints (usually http://localhost:5173). Press Play, then 4×.

npm test              # engine tests (no browser)
npm run lint
npm run build         # production, base /
npm run preview

Stack

React 19 · Vite 8 · TypeScript · React Flow · Zustand · Vitest · Vercel.

The simulation layer has zero UI imports. Seeded RNG keeps runs reproducible.

Docs

Doc	Contents
Usage	Clock, graph, agents, events, scenarios
Architecture	Layers, tick loop, domain model
Deployment	Vercel root + /multi-agent/ subpath
Contributing	Where to change what
Changelog	What shipped

Regenerate README screenshots against a running dev server:

npm run screenshots

License

MIT © d0npedro