TypeScript/Node.js 기반 다중 에이전트 오케스트레이터: 공유 상태, 가드레일, 예산 및 크로스 프레임워크 조정 기능

TypeScript/Node.js 기반 다중 에이전트 오케스트레이터 — 공유 상태, 가드레일, 예산, 그리고 크로스 프레임워크 조정

Network-AI가 유용하다면 별점 ⭐을 부여하는 것을 고려해 주세요 — 이는 다른 사람들이 프로젝트를 찾도록 돕습니다.

Network-AI는 모든 AI 에이전트 스택에 조정(coordination), 가드레일(guardrails), 거버넌스(governance) 기능을 추가하는 TypeScript/Node.js 기반 다중 에이전트 오케스트레이터입니다.

잠금 기능이 있는 공유 블랙보드 (Shared blackboard with locking) — 원자적(propose → validate → commit) 방식으로 작동하여 병렬 에이전트 간의 레이스 컨디션(race conditions) 및 스플릿-브레인 실패를 방지합니다.

가드레일과 예산 (Guardrails and budgets) — FSM 거버넌스, 에이전트별 토큰 상한선, HMAC / Ed25519 감사 추적(audit trails), 그리고 권한 게이팅(permission gating) 기능을 제공합니다.

문맥 신호-잡음 (Context signal-over-noise) (v5.15) — ContextComposer가 토큰 예산이 책정되고 관련성 순위가 매겨진 문맥 팩(context packs)을 조립합니다 (의미론적/어휘적 × 최근성 감쇠 × 범위 친화도, 위치 인식 레이아웃); context_pack

+blackboard_search

MCP 도구를 사용하면 에이전트들이 전체 블랙보드를 창에 쏟아내는 대신 선별된 상태를 가져올 수 있습니다.

32개 어댑터 (adapters) — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, OpenAI Responses (Assistants 후속 모델), LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, Claude Agent SDK (에이전트 루프), OpenAI Agents SDK, Vertex AI, Gemini (Developer API), Pydantic AI, Browser Agent, Hermes (NousResearch Hermes / 모든 OpenAI 호환 엔드포인트), Orchestrator (계층적 다중 오케스트레이터), 그리고 RLM (재귀 언어 모델 / 모든 RLM 호환 HTTP 엔드포인트) — 접착 코드(glue code)나 종속성(lock-in)이 없습니다.

영구 프로젝트 메모리 (Persistent project memory) (Layer 3) — context_manager.py

결정(decisions), 목표(goals), 스택(stack), 마일스톤(milestones), 그리고 금지된 패턴(banned patterns)을 모든 시스템 프롬프트에 주입하여 에이전트가 항상 전체 프로젝트 컨텍스트를 갖도록 합니다.v5.0 모듈 — Agent VCR (기록/재생), 비교 러너(comparison runner), 커버리지 리포터(coverage reporter), 목표 DSL, 승인 인박스(approval inbox), 작업 큐(job queue), gRPC/HTTP 전송(transport), 플레이그라운드 REPL, 어댑터 테스트 하네스(adapter test harness) 등모델 상호작용 수명 주기 거버넌스 (v5.13) — GovernedModelGateway

모델의 거부(refusal)를 흡수하여 → 폴백(fallback) → 청구 체인(billing chain)을 구성합니다 (크로스 모델 폴백, 폴백-크레딧 재가격 책정, 노력 거버넌스, 사고 블록 핸드오프). 이 모든 과정을 하나의 통제되고, 예산이 책정되며, 감사된 호출로 처리합니다.

다중 에이전트 시스템의 침묵하는 실패 모드(silent failure mode): 병렬 에이전트가 동일한 키에 쓰기 작업을 할 때 기본적으로 마지막 쓰기가 승리하는 방식(last-write-wins)을 사용합니다. 즉, 한 에이전트의 결과가 다른 에이전트의 작업 도중에 조용히 덮어쓰여집니다. 그 결과는 스플릿 브레인 상태(split-brain state)를 초래하며, 이중 지출(double-spends), 모순되는 결정, 손상된 컨텍스트 등이 발생하지만 오류가 던져지지 않습니다. Network-AI의 propose → validate → commit

뮤텍스(mutex)는 공유 상태에 쓰기 작업이 도달하기 전에 조정 계층(coordination layer)에서 이를 방지합니다.

Network-AI를 다음과 같이 사용하세요:

• A TypeScript/Node.js 라이브러리 — import { createSwarmOrchestrator } from 'network-ai'

• An MCP 서버 — npx network-ai-server --port 3001

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

• A Claude Code 플러그인 — /plugin install network-ai@network-ai

• A Gemini CLI 확장 프로그램 — gemini extensions install https://github.com/Jovancoding/Network-AI

• An OpenClaw 스킬 — clawhub install network-ai

5분 퀵스타트 → | 아키텍처 → | 모든 어댑터 → | 벤치마크 →

대부분의 거버넌스 도구는 에이전트 경계(agent boundary)에서 멈춥니다. 즉, 에이전트가 행동하기 전에 어떤 도구를 호출할 수 있는지 감시합니다. Network-AI는 그 아래 계층까지 거버넌스를 적용합니다: 에이전트가 모델과 대화하는 방식입니다. 프론티어 모델(frontier model)이 분류기 거부(classifier refusal)로 요청을 거부할 경우, Network-AI는 이 거부를 흡수하여 → 폴백 → 청구 체인을 구성하고 하나의 통제되고, 예산이 책정되며, 감사된 호출로 제시합니다.

— detectGovernedModelGateway

`stop_reason:

클래시파이어가 어떤 것을 발동했는지 감사하고, 폴백(fallback) 모델로 라우팅하며, 폴백-크레딧 토큰을 상환하여 재시도 비용이 캐시 읽기처럼 책정되도록 합니다. — 모델별 USD 회계 처리와 폴백-크레딧 재가격 책정; 절대 모델 간에 토큰을 합산하지 않습니다. ModelBudget

— 거절(refusal)은 HTTP 200이며, 에러율 모니터링에는 보이지 않습니다. RefusalTelemetry로 이산적인 비-에러 신호로 방출됩니다.

unservedRefusalCount

경고를 위한 간격을 조정합니다. — EffortPolicy

effort

비용 다이얼을 정책 객체에 연결합니다: 서브 에이전트를 low로 제한하고, xhigh 또는 max의 정당성 입증을 요구합니다.

— 사고(thinking) 블록은 동일한 모델에서 변경 없이 유지됩니다. 크로스-모델 폴백에서는 제거되며, 프롬프트는 ThinkingBlockManager가 reasoning_extraction하는 것을 방지합니다.

거절 사항.서브 에이전트별 폴백—FanOutFanIn 단계와 TeamRunner 작업 각각은 자체적인 폴백 에이전트와 요청당 재시도 예산(RetryBudget)을 가집니다. 왜냐하면 턴(turn)은 에이전트 및 그 서브 에이전트 전반에 걸쳐 독립적으로 거절할 수 있기 때문입니다.

import { AnthropicMessagesAdapter, ModelBudget, RefusalTelemetry } from 'network-ai';
const adapter = new AnthropicMessagesAdapter();
await adapter.initialize({});
...

verifyOwaspCoverage()로 프로그래밍 방식으로 검증합니다.
(
network-ai에서 내보냄:)

이 설정은 한 번 읽히고 고정되며, 런타임에는 강화(tightenAsiConfig) ext{만 가능하고} 약화될 수는 없습니다.

enforce 모드 AgentRuntime

또한 sourceProtection을 강제하고

비밀과 같은 환경 변수를 자식 프로세스에서 차단합니다.

import { createAsiConfig, ProofGate, CapabilityIssuer, SignedAttestationVerifier, AgentRuntime } from 'network-ai';
const config = createAsiConfig({ mode: 'enforce', auditors: ['auditor-1'] });
const key = { name: 'ops', alg: 'hmac-sha256' as const, key: process.env.CAPABILITY_KEY! };
...

Limits.Strict 모드는 오작동의 비용을 높이지만, 격리 증명(containment proof)은 아닙니다. 동일한 호스트에서 임의 코드 실행이 가능한 에이전트는 다른 설정으로 프로세스를 재시작할 수 있으므로, strict 모드를 OS 수준의 격리와 아웃-오브-프로세스(ExternalAuthority)와 함께 사용하세요.

Consensus는 최대 $f$개의 결함 있는 독립적인 평가자(evaluators)를 가정합니다.

npm install network-ai

import { LockedBlackboard } from 'network-ai';
const board = new LockedBlackboard('.');
const id = board.propose('status', { ready: true }, 'agent-1');
...

두 에이전트, 원자적 쓰기(atomic writes), 레이스 컨디션 없음. 그게 전부입니다.

완벽한 스트레스 테스트를 원하시나요? API 키 필요 없음, 약 3초:

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

우선순위 선점(priority preemption), AuthGuardian 권한 게이팅(permission gating), FSM 거버넌스(FSM governance), 그리고 규정 준수 모니터링을 단 하나의 LLM 호출 없이 실행합니다.

만약 이것이 레이스 컨디션으로부터 당신을 구했다면, ⭐를 눌러 다른 사람들도 알게 해주세요.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

| ✅ 원자적 공유 상태 (Atomic shared state) | 파일 시스템 뮤텍스(filesystem mutex)를 사용한 제안 → 검증 → 커밋 방식 — 분할뇌(split-brain) 없음 |
| ✅ 토큰 예산 (Token budgets) | 에이전트별 하드 상한선 및 실시간 지출 추적 기능 |
| ✅ 권한 게이팅 (Permission gating) | HMAC / Ed25519 서명된 토큰, 에이전트 및 리소스별 범위 지정
| ... |

%%{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
...

FederatedBudget

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

(FederatedBudget는 독립적인 내보내기(standalone export)입니다. 별도로 인스턴스화하고, 선택적으로 블랙보드 백엔드에 연결하여 노드 간 토큰 예산 강제 적용을 할 수 있습니다.)

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.

(ProjectContextManager는 계층 3(Layer-3) 파이썬 도우미 파일(scripts/context_manager.py)로, 지속적인 프로젝트 목표, 결정 및 마일스톤을 에이전트 시스템 프롬프트에 주입합니다 — ARCHITECTURE.md § Layer 3 참조.)

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

(npm install network-ai)
네이티브 의존성 없음, 빌드 단계 없음. 어댑터는 종속성이 없어(BYOC — bring your own client) 사용 가능합니다.

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.
(그 다음 모든 MCP 호환 클라이언트를 여기에 연결합니다.)

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

{
"mcpServers": {
"network-ai": {
...

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

(Cursor / Cline / 모든 SSE 기반 MCP 클라이언트 — 동일한 URL을 가리키도록 설정합니다:)

{
"mcpServers": {
"network-ai": {
...

Verify it's running:
(실행 여부를 확인하세요:)

curl http://localhost:3001/health # { "status": "ok", "tools": <n>, "uptime": <ms> }
curl http://localhost:3001/tools # 전체 도구 목록

MCP를 통해 노출되는 도구:

blackboard_read

/blackboard_write`

/blackboard_list`

/blackboard_delete`

/blackboard_exists`

context_pack

— 작업에 대한 토큰 예산 책정 및 관련성 순위가 매겨진 간결한 컨텍스트 (전체 보드를 창에 쏟아붓는 대신 사용)
blackboard_search

— 블랙보드 항목에 대한 상위 K개 검색 결과 순위 지정 (임베더(embedder)가 연결된 경우 의미론적, 그렇지 않은 경우 어휘적)
budget_status

/budget_spend`

/budget_reset`

— 페더레이티드 토큰 추적
token_create

/token_validate`

/token_revoke`

— HMAC / Ed25519 서명된 권한 토큰
audit_query

— 추가 전용 감사 로그(append-only audit log) 조회
config_get

/config_set`

— 실시간 오케스트레이터 설정
agent_list

/agent_spawn`

/agent_stop`

— 에이전트 생명 주기(lifecycle)
fsm_transition

— 블랙보드에 FSM 상태 전이 쓰기

각 도구는 모든 쓰기의 출처 에이전트로 기록되는 agent_id 매개변수를 받습니다. MCP 서버의 신뢰 경계(trust boundary)는 전송 인증(SSE/HTTP를 통한 베어러 시크릿, 또는 로컬 stdio)입니다. 클라이언트가 승인되면, 서버는 서버가 보유한 무작위 식별자를 사용하여 그를 대신하여 쓰기 때문에 모든 agent_id가 작동하며 공유 토큰을 알 필요가 없습니다. 호출자가 제공하는 agent_token 값은 MCP를 통해 무시됩니다. 인프로세스 TypeScript 코드는 registerAgent()를 통해 에이전트별 토큰과 네임스페이스를 유지합니다.

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

Network-AI는 Claude Code 플러그인으로 배포됩니다. MCP 서버가 자동으로 연결되므로, 위에 나열된 모든 도구가 수동 구성 없이 Claude Code 내부에서 사용 가능합니다.