Network-AI

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

If Network-AI is useful to you, consider giving it a star ⭐ — it helps others find the project.

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 / Ed25519 audit trails, and permission gating
• Context signal-over-noise (v5.15) — ContextComposer assembles token-budgeted, relevance-ranked context packs (semantic/lexical × recency decay × scope affinity, position-aware layout); context_pack + blackboard_search MCP tools let agents pull curated state instead of dumping the whole board into their window
• 32 adapters — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, OpenAI Responses (Assistants successor), LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, Claude Agent SDK (agentic loops), OpenAI Agents SDK, Vertex AI, Gemini (Developer API), Pydantic AI, Browser Agent, Hermes (NousResearch Hermes / any OpenAI-compatible endpoint), Orchestrator (hierarchical multi-orchestrator), and RLM (Recursive Language Model / any RLM-compatible HTTP endpoint) — 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
• v5.0 modules — Agent VCR (record/replay), comparison runner, coverage reporter, goal DSL, approval inbox, job queue, gRPC/HTTP transport, playground REPL, adapter test harness, and more
• Model-interaction lifecycle governance (v5.13) — GovernedModelGateway absorbs the model refusal → fallback → billing chain (cross-model fallback, fallback-credit repricing, effort governance, thinking-block handoff) behind one governed, budgeted, audited call

The silent failure mode in multi-agent systems: parallel agents writing to the same key use 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 the coordination 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
• A Claude Code plugin — /plugin install network-ai@network-ai
• A Gemini CLI extension — gemini extensions install https://github.com/Jovancoding/Network-AI
• An OpenClaw skill — clawhub install network-ai

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

🛡️ Model-Interaction Lifecycle Governance

Most governance tools stop at the agent boundary — they police which tools an agent may call before it acts. Network-AI also governs the layer underneath: how an agent talks to the model. When a frontier model declines a request with a classifier refusal, Network-AI absorbs the refusal → fallback → billing chain and presents one governed, budgeted, audited call.

• GovernedModelGateway — detect stop_reason:"refusal", audit which classifier fired, route to a fallback model, and redeem the fallback-credit token so the retry is repriced as a cache read.
• ModelBudget — per-model USD accounting with fallback-credit repricing; never sums tokens across models.
• RefusalTelemetry — a refusal is an HTTP 200, invisible to error-rate monitoring; emitted as a discrete non-error signal with an unservedRefusalCount gap to alert on.
• EffortPolicy — turn the effort cost dial into a policy object: cap sub-agents at low, require justification for xhigh/max.
• ThinkingBlockManager — keep thinking blocks unchanged on the same model; strip them on a cross-model fallback; guard prompts against reasoning_extraction refusals.
• Per-sub-agent fallback — FanOutFanIn steps and TeamRunner tasks each carry their own fallback agent and per-request retry budget (RetryBudget), because a turn can refuse independently across an agent and its sub-agents.

import { AnthropicMessagesAdapter, ModelBudget, RefusalTelemetry } from 'network-ai';

const adapter = new AnthropicMessagesAdapter();
await adapter.initialize({});
adapter.registerModelAgent('analyst', {
  client,                              // bring your own Anthropic client
  model: 'claude-fable-5',
  fallbackModels: ['claude-opus-4-8'], // classifier refusals fall through here
  budget: new ModelBudget({
    ceilingUsd: 5,
    pricing: {
      'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },
      'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },
    },
  }),
  telemetry: new RefusalTelemetry(),
});
const result = await adapter.executeAgent('analyst', { action: 'Summarize Q3 results', params: {} }, { agentId: 'cli' });
// result.data: { servedModel, servedByFallback, refused, refusalCategories, attempts, totalCostUsd }

OWASP Agentic AI Top 10 (2026) — engine coverage

Verify programmatically with verifyOwaspCoverage() (exported from network-ai):

⚡ Try in 60 Seconds

npm install network-ai

import { LockedBlackboard } from 'network-ai';

const board = new LockedBlackboard('.');
const id    = board.propose('status', { ready: true }, 'agent-1');
board.validate(id, 'agent-1');
board.commit(id);

console.log(board.read('status'));  // { ready: true }

Two agents, atomic writes, no race conditions. That's it.

Want the full 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 compliance monitoring — all without a single LLM call.

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

What's Included

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

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

    subgraph SO["SwarmOrchestrator"]
        AG["AuthGuardian\n(HMAC / Ed25519 permission tokens)"]:::security
        AR["AdapterRegistry\n(route tasks to frameworks)"]:::routing
        QG["QualityGateAgent\n(validate blackboard writes)"]:::quality
        QA["QAOrchestratorAgent\n(scenario replay, regression tracking)"]:::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
        QA -->|"orchestrates"| QG
    end

    SO --> AUDIT["data/audit_log.jsonl\n(HMAC / Ed25519-signed)"]:::audit

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

ProjectContextManager is a Layer-3 Python helper (scripts/context_manager.py) that injects persistent project goals, decisions, and milestones into agent system prompts — see ARCHITECTURE.md § Layer 3.

→ 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
• context_pack — token-budgeted, relevance-ranked context brief for a task (use instead of dumping the whole board into your window)
• blackboard_search — ranked top-K search over blackboard entries (semantic when an embedder is wired, lexical otherwise)
• budget_status / budget_spend / budget_reset — federated token tracking
• token_create / token_validate / token_revoke — HMAC / Ed25519-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>.

Use as a Claude Code Plugin

Network-AI ships as a Claude Code plugin — the MCP server wires in automatically, so every tool listed above becomes available inside Claude Code with no manual config.

Install from the self-hosted marketplace (zero approval needed):

/plugin marketplace add Jovancoding/Network-AI
/plugin install network-ai@network-ai

That's it — blackboard_read, budget_status, audit_query, token_create, and the rest load as native Claude Code tools. Under the hood the plugin runs npx -y -p network-ai network-ai-server --stdio (stdio MCP transport), so it always uses the published npm package.

The repo root carries the standard plugin layout:

Validate the manifests locally with claude plugin validate ..

Gate Claude Code itself with AuthGuardian (hooks). Every tool call Claude Code makes — shell commands, file edits, web fetches — can be audited and permission-gated through the same weighted scoring (justification 40%, trust 30%, risk 30%) Network-AI applies to swarm agents:

// .claude/settings.json — see examples/claude-code-hooks.json for the full config
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash|Write|Edit|WebFetch",
      "hooks": [{ "type": "command",
                  "command": "npx -y -p network-ai network-ai hook pre-tool-use --mode enforce" }]
    }]
  }
}

--mode observe (default) audits every call to data/hooks_audit.jsonl without blocking; --mode enforce maps tools to resource types (Bash → SHELL_EXEC, Write/Edit → FILE_SYSTEM, WebFetch → EXTERNAL_SERVICE) and requires an AuthGuardian grant — denied calls escalate to you as an interactive prompt. --deny "rm -rf" patterns hard-block regardless of mode.

Use with OpenAI Codex

Network-AI also runs as an OpenAI Codex MCP server — in both the Codex CLI and the IDE extension. The same tools that load in Claude Code become available in Codex.

Add it with one command (uses the published npm package):

codex mcp add network-ai -- npx -y -p network-ai network-ai-server --stdio

In the Codex TUI, run /mcp to confirm network-ai is connected.

Or scope it to a project — the repo root ships a .codex/config.toml so any trusted checkout picks the server up automatically. To register it globally instead, drop the same block into ~/.codex/config.toml:

[mcp_servers.network-ai]
command = "npx"
args = ["-y", "-p", "network-ai", "network-ai-server", "--stdio"]

Either route exposes the full tool set (blackboard_read, budget_status, audit_query, token_create, …) over stdio MCP — no API keys, no running server to manage.

Use with Gemini CLI

Network-AI ships as a Gemini CLI extension — the repo root carries gemini-extension.json, which wires in the stdio MCP server and a GEMINI.md context file automatically:

gemini extensions install https://github.com/Jovancoding/Network-AI

Or register just the MCP server directly:

gemini mcp add network-ai npx -- -y -p network-ai network-ai-server --stdio

Run /mcp inside Gemini CLI to confirm the network-ai tools are loaded. For building Gemini-powered swarm agents, use the GeminiAdapter (Gemini Developer API / AI Studio) or VertexAIAdapter (Vertex AI on GCP) — and for Google's Agent2Agent ecosystem, A2AServer exposes this orchestrator as a discoverable A2A agent:

import { A2AServer } from 'network-ai';

const a2a = new A2AServer({
  name: 'Network-AI Orchestrator',
  secret: process.env.A2A_SECRET,
  executor: async (text) => ({ text: await runSwarmTask(text) }),
});
a2a.startServer(4310); // serves /.well-known/agent.json + tasks/send

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) · --env <name> (environment) · --json (machine-readable output) · --minimal (skip WAL replay + sweep — CI/test fast startup)

→ 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

NemoClaw sandbox swarm (no API key) — 3 agents in isolated NVIDIA NemoClaw sandboxes with deny-by-default network policies:

npx ts-node examples/10-nemoclaw-sandbox-swarm.ts

Adapter System

32 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 32 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
npm run test:phase9       # Agent runtime, console, strategy agent
npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate, Route Classifier

3,638 passing assertions across 41 test suites (npm run test:all):

Documentation

Use with Claude, ChatGPT & Codex

Using Claude Code (the CLI)? See Use as a Claude Code Plugin — one command installs every tool.

Using OpenAI Codex (CLI or IDE)? See Use with OpenAI Codex — add the MCP server with a single codex mcp add.

Using Gemini CLI? See Use with Gemini CLI — install the extension with a single gemini extensions install.

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  ·  Code of Conduct  ·  Security Policy  · 

Download History