Network-AI

Orquestador multi-agente para TypeScript/Node.js: estado compartido, barreras de seguridad, presupuestos y coordinación entre marcos

Network-AI es un orquestador multi-agente para TypeScript/Node.js que añade coordinación, barreras de seguridad y gobernanza a cualquier pila de agentes de IA.

• Pizarra compartida con bloqueo — el proceso atómico proponer → validar → confirmar evita condiciones de carrera y fallos de cerebro dividido entre agentes paralelos.

• Barreras de seguridad y presupuestos — gobernanza FSM, límites de tokens por agente, pistas de auditoría HMAC / Ed25519 y control de permisos.

• 17 adaptadores — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Personalizado (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw y APS — sin código de pegamento, sin dependencia de un solo proveedor.

• Memoria de proyecto persistente (Capa 3) — context_manager.py inyecta decisiones, objetivos, pila, hitos y patrones prohibidos en cada prompt del sistema para que los agentes siempre tengan el contexto completo del proyecto.

El modo de fallo silencioso en sistemas multi-agente: los agentes paralelos que escriben en la misma clave utilizan por defecto la última escritura ganadora — el resultado de un agente sobrescribe silenciosamente al de otro en pleno vuelo. El resultado es un estado de cerebro dividido: gastos dobles, decisiones contradictorias, contexto corrupto, sin que se lance ningún error. El mutex proponer → validar → confirmar de Network-AI evita esto en la capa de coordinación, antes de que cualquier escritura llegue al estado compartido.

Utiliza Network-AI como:

• Una biblioteca de TypeScript/Node.js — import { createSwarmOrchestrator } from 'network-ai'

• Un servidor MCP — npx network-ai-server --port 3001

• Una CLI — network-ai bb get status / network-ai audit tail

• Una habilidad OpenClaw — clawhub install network-ai

Inicio rápido en 5 minutos →  |  Arquitectura →  |  Todos los adaptadores →  |  Benchmarks →

⚡ Pruébalo en 60 segundos

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 }

Dos agentes, escrituras atómicas, sin condiciones de carrera. Eso es todo.

¿Quieres la prueba de estrés completa? Sin clave API, ~3 segundos:

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

Ejecuta desalojo por prioridad, control de permisos AuthGuardian, gobernanza FSM y monitoreo de cumplimiento — todo sin una sola llamada a LLM.

Si te ahorra una condición de carrera, una ⭐ ayuda a otros a encontrarlo.

Qué incluye

Por qué los equipos usan Network-AI

Arquitectura

%%{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 es una exportación independiente — instáncialo por separado y opcionalmente conéctalo a un backend de pizarra para la aplicación de presupuestos de tokens entre nodos.

ProjectContextManager es un ayudante de Python de Capa 3 (scripts/context_manager.py) que inyecta objetivos, decisiones e hitos persistentes del proyecto en los prompts del sistema de los agentes — ver ARCHITECTURE.md § Layer 3.

→ Arquitectura completa, viaje FSM y protocolo de entrega

Instalación

npm install network-ai

Sin dependencias nativas, sin paso de compilación. Los adaptadores no tienen dependencias (BYOC — trae tu propio cliente).

Uso como servidor MCP

Inicia el servidor (no requiere configuración, cero dependencias):

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

Luego conecta cualquier cliente compatible con MCP.

Claude Desktop — añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor / Cline / cualquier cliente MCP basado en SSE — apunta a la misma URL:

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

Verifica que se esté ejecutando:

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

Herramientas expuestas a través de MCP:

• blackboard_read / blackboard_write / blackboard_list / blackboard_delete / blackboard_exists

• budget_status / budget_spend / budget_reset — seguimiento federado de tokens

• token_create / token_validate / token_revoke — tokens de permiso firmados con HMAC / Ed25519

• audit_query — consulta el registro de auditoría de solo adición

• config_get / config_set — configuración del orquestador en vivo

• agent_list / agent_spawn / agent_stop — ciclo de vida del agente

• fsm_transition — escribe transiciones de estado FSM en la pizarra

Cada herramienta toma un parámetro agent_id — todas las escrituras están verificadas por identidad y con alcance de espacio de nombres, exactamente como en la API de TypeScript.

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

CLI

Controla Network-AI directamente desde la terminal — no se requiere servidor. La CLI importa el mismo motor central utilizado por el servidor MCP.

# 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

Flags globales en cada comando: --data <path> (directorio de datos, por defecto ./data) · --json (salida legible por máquina)

→ Referencia completa en QUICKSTART.md § CLI

Dos agentes, un estado compartido — sin condiciones de carrera

El verdadero diferenciador es la coordinación. Esto es lo que ninguna solución de un solo marco maneja: dos agentes escribiendo en el mismo recurso simultáneamente, de forma atómica, sin corromperse entre sí.

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 }

Añade presupuestos, permisos y agentes entre marcos con el mismo patrón. → QUICKSTART.md

Demostración — Prueba de estrés del plano de control (sin clave API)

Se ejecuta en ~3 segundos. Demuestra las primitivas de coordinación sin ninguna llamada a LLM.

npm run demo -- --08

Lo que muestra: bloqueo atómico de pizarra, desalojo por prioridad (la prioridad 3 gana sobre la prioridad 0 en la misma clave), puerta de permisos AuthGuardian (bloqueado → justificado → concedido con token), parada forzada FSM a 700 ms, captura de violación de cumplimiento en vivo (TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT) y seguimiento de FederatedBudget — todo sin una sola llamada a API.

Tubería de IA de 8 agentes (requiere OPENAI_API_KEY — construye un servicio de procesamiento de pagos de extremo a extremo):

npm run demo -- --07

Enjambre de sandbox NemoClaw (sin clave API) — 3 agentes en sandboxes aislados de NVIDIA NemoClaw con políticas de red de denegación por defecto:

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

[](https://www.youtube