Network-AI

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

If Network-AI is useful to you, consider — 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": , "uptime":  }
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 `, `--board `, `--audit-log `.

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 ` (data directory, default `./data`) · `--env ` (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

Keywords

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 · refusal handling · fallback routing · model lifecycle · OWASP agentic AI · effort policy · thinking blocks

Download History