network-ai

# Network-AI

TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination

Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordination, guardrails, and governance to any AI agent stack.

• Shared blackboard with locking — atomic propose → validate → commit prevents race conditions and split-brain failures across parallel agents
• Guardrails and budgets — FSM governance, per-agent token ceilings, HMAC audit trails, and permission gating
• 15 adapters — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, and MiniMax — no glue code, no lock-in
• Persistent project memory (Layer 3) — context_manager.py injects decisions, goals, stack, milestones, and banned patterns into every system prompt so agents always have full project context

The silent failure mode in multi-agent systems: parallel agents writing to the same keyuse last-write-wins by default — one agent's result silently overwrites another's mid-flight.The outcome is split-brain state: double-spends, contradictory decisions, corrupted context,no error thrown. Network-AI's propose → validate → commit mutex prevents this at thecoordination layer, before any write reaches shared state.

Use Network-AI as:

• A TypeScript/Node.js library — import { createSwarmOrchestrator } from 'network-ai'
• An MCP server — npx network-ai-server --port 3001
• A CLI — network-ai bb get status / network-ai audit tail
• An OpenClaw skill — clawhub install network-ai

5-minute quickstart →  |  Architecture →  |  All adapters →  |  Benchmarks →

Try the control-plane stress test — no API key, ~3 seconds:

npx ts-node examples/08-control-plane-stress-demo.ts

Runs priority preemption, AuthGuardian permission gating, FSM governance, and compliancemonitoring against a live swarm. No external services required.

If it saves you from a race condition, a ⭐ helps others find it.

Why teams use Network-AI

Architecture

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1e293b', 'primaryTextColor': '#e2e8f0', 'primaryBorderColor': '#475569', 'lineColor': '#94a3b8', 'clusterBkg': '#0f172a', 'clusterBorder': '#334155', 'edgeLabelBackground': '#1e293b', 'edgeLabelColor': '#cbd5e1', 'titleColor': '#e2e8f0'}}}%%
flowchart TD
    classDef app        fill:#1e3a5f,stroke:#3b82f6,color:#bfdbfe,font-weight:bold
    classDef security   fill:#451a03,stroke:#d97706,color:#fde68a
    classDef routing    fill:#14532d,stroke:#16a34a,color:#bbf7d0
    classDef quality    fill:#3b0764,stroke:#9333ea,color:#e9d5ff
    classDef blackboard fill:#0c4a6e,stroke:#0284c7,color:#bae6fd
    classDef adapters   fill:#064e3b,stroke:#059669,color:#a7f3d0
    classDef audit      fill:#1e293b,stroke:#475569,color:#94a3b8
    classDef context    fill:#3b1f00,stroke:#b45309,color:#fef3c7

    App["Your Application"]:::app
    App -->|"createSwarmOrchestrator()"| SO

    PC["ProjectContextManager\n(Layer 3 — persistent memory)\ngoals · stack · decisions\nmilestones · banned"]:::context
    PC -->|"injected into system prompt"| SO

    subgraph SO["SwarmOrchestrator"]
        AG["AuthGuardian\n(permission gating)"]:::security
        AR["AdapterRegistry\n(route tasks to frameworks)"]:::routing
        QG["QualityGateAgent\n(validate blackboard writes)"]:::quality
        BB["SharedBlackboard\n(shared agent state)\npropose → validate → commit\nfilesystem mutex"]:::blackboard
        AD["Adapters — plug any framework in, swap freely\nLangChain · AutoGen · CrewAI · MCP · LlamaIndex · …"]:::adapters

        AG -->|"grant / deny"| AR
        AR -->|"tasks dispatched"| AD
        AD -->|"writes results"| BB
        QG -->|"validates"| BB
    end

    SO --> AUDIT["data/audit_log.jsonl"]:::audit

FederatedBudget is a standalone export — instantiate it separately and optionally wire it to a blackboard backend for cross-node token budget enforcement.

→ Full architecture, FSM journey, and handoff protocol

Install

npm install network-ai

No native dependencies, no build step. Adapters are dependency-free (BYOC — bring your own client).

Use as MCP Server

Start the server (no config required, zero dependencies):

npx network-ai-server --port 3001
# or from source:
npx ts-node bin/mcp-server.ts --port 3001

Then wire any MCP-compatible client to it.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "network-ai": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Cursor / Cline / any SSE-based MCP client — point to the same URL:

{
  "mcpServers": {
    "network-ai": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Verify it's running:

curl http://localhost:3001/health   # { "status": "ok", "tools": <n>, "uptime": <ms> }
curl http://localhost:3001/tools    # full tool list

Tools exposed over MCP:

• blackboard_read / blackboard_write / blackboard_list / blackboard_delete / blackboard_exists
• budget_status / budget_spend / budget_reset — federated token tracking
• token_create / token_validate / token_revoke — HMAC-signed permission tokens
• audit_query — query the append-only audit log
• config_get / config_set — live orchestrator configuration
• agent_list / agent_spawn / agent_stop — agent lifecycle
• fsm_transition — write FSM state transitions to the blackboard

Each tool takes an agent_id parameter — all writes are identity-verified and namespace-scoped, exactly as they are in the TypeScript API.

Options: --no-budget, --no-token, --no-control, --ceiling <n>, --board <name>, --audit-log <path>.

CLI

Control Network-AI directly from the terminal — no server required. The CLI imports the same core engine used by the MCP server.

# One-off commands (no server needed)
npx ts-node bin/cli.ts bb set status running --agent cli
npx ts-node bin/cli.ts bb get status
npx ts-node bin/cli.ts bb snapshot

# After npm install -g network-ai:
network-ai bb list
network-ai audit tail          # live-stream the audit log
network-ai auth token my-bot --resource blackboard

Global flags on every command: --data <path> (data directory, default ./data) · --json (machine-readable output)

→ Full reference in QUICKSTART.md § CLI

Two agents, one shared state — without race conditions

The real differentiator is coordination. Here is what no single-framework solution handles: two agents writing to the same resource concurrently, atomically, without corrupting each other.

import { LockedBlackboard, CustomAdapter, createSwarmOrchestrator } from 'network-ai';

const board   = new LockedBlackboard('.');
const adapter = new CustomAdapter();

// Agent 1: writes its analysis result atomically
adapter.registerHandler('analyst', async () => {
  const id = board.propose('report:status', { phase: 'analysis', complete: true }, 'analyst');
  board.validate(id, 'analyst');
  board.commit(id);                           // file-system mutex — no race condition possible
  return { result: 'analysis written' };
});

// Agent 2: runs concurrently, writes to its own key safely
adapter.registerHandler('reviewer', async () => {
  const id = board.propose('report:review', { approved: true }, 'reviewer');
  board.validate(id, 'reviewer');
  board.commit(id);
  const analysis = board.read('report:status');
  return { result: `reviewed phase=${analysis?.phase}` };
});

createSwarmOrchestrator({ adapters: [{ adapter }] });

// Both fire concurrently — mutex guarantees no write is ever lost
const [, ] = await Promise.all([
  adapter.executeAgent('analyst',  { action: 'run', params: {} }, { agentId: 'analyst' }),
  adapter.executeAgent('reviewer', { action: 'run', params: {} }, { agentId: 'reviewer' }),
]);

console.log(board.read('report:status'));   // { phase: 'analysis', complete: true }
console.log(board.read('report:review'));   // { approved: true }

Add budgets, permissions, and cross-framework agents with the same pattern. → QUICKSTART.md

Demo — Control-Plane Stress Test (no API key)

Runs in ~3 seconds. Proves the coordination primitives without any LLM calls.

npm run demo -- --08

What it shows: atomic blackboard locking, priority preemption (priority-3 wins over priority-0 on same key), AuthGuardian permission gate (blocked → justified → granted with token), FSM hard-stop at 700 ms, live compliance violation capture (TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT), and FederatedBudget tracking — all without a single API call.

8-agent AI pipeline (requires OPENAI_API_KEY — builds a Payment Processing Service end-to-end):

npm run demo -- --07

Adapter System

15 adapters, zero adapter dependencies. You bring your own SDK objects.

Streaming variants (drop-in replacements with .stream() support):

Extend BaseAdapter (or StreamingBaseAdapter for streaming) to add your own in minutes. See references/adapter-system.md.

Works with LangGraph, CrewAI, and AutoGen

Network-AI is the coordination layer you add on top of your existing stack. Keep your LangChain chains, CrewAI crews, and AutoGen agents — and add shared state, governance, and budgets around them.

Testing

npm run test:all          # All suites in sequence
npm test                  # Core orchestrator
npm run test:security     # Security module
npm run test:adapters     # All 15 adapters
npm run test:streaming    # Streaming adapters
npm run test:a2a          # A2A protocol adapter
npm run test:codex        # Codex adapter
npm run test:priority     # Priority & preemption
npm run test:cli          # CLI layer

1,449 passing assertions across 18 test suites (npm run test:all):

Documentation

Use with Claude, ChatGPT & Codex

Three integration files are included in the repo root:

Claude API / Codex:

import tools from './claude-tools.json' assert { type: 'json' };
// Pass tools array to anthropic.messages.create({ tools }) or OpenAI chat completions

Custom GPT Actions:In the GPT editor → Actions → Import from URL, or paste the contents of openapi.yaml.Set the server URL to your running npx network-ai-server --port 3001 instance.

Claude Projects:Copy the contents of claude-project-prompt.md (below the horizontal rule) into a Claude Project's Custom Instructions field. No server required for instruction-only mode.

Community

Join our Discord server to discuss multi-agent AI coordination, get help, and share what you're building:

Contributing

1. Fork → feature branch → npm run test:all → pull request
2. Bugs and feature requests via Issues

MIT License — LICENSE  ·  CHANGELOG  ·  CONTRIBUTING  · 

multi-agent · agent orchestration · AI agents · agentic AI · agentic workflow · TypeScript · Node.js · LangGraph · CrewAI · AutoGen · MCP · model-context-protocol · LlamaIndex · Semantic Kernel · OpenAI Assistants · Haystack · DSPy · Agno · OpenClaw · ClawHub · shared state · blackboard pattern · atomic commits · guardrails · token budgets · permission gating · audit trail · agent coordination · agent handoffs · governance · cost-awareness