AgentBus

SQLite 기반 MCP 이벤트 버스 및 이기종 에이전트 스웜을 위한 컨트롤 서피스.

Cursor, Claude, Antigravity, 그리고 Terminal Agents(Hermes 등)가 같은 워크스페이스를 공유할 때, 그들은 보통 취약한 append-only 파일(log.md)로 협력합니다. SLA 타임아웃, HITL(Human-in-the-Loop) 인터셉트, 엄격한 스키마 검증, 암호화 RBAC가 필요해지기 전까지는 그 방식이 통하죠.

AgentBus는 "전화기 게임"을 로컬호스트 사이드카로 대체합니다: SQLite로 구동되는 Python MCP 서버입니다. 오케스트레이터 런타임에 얽매이지 않습니다. 무거운 클라우드 대시보드도 없습니다. 최상위 AI 오케스트레이션을 위해 만들어진 초고속 로컬 pub/sub일 뿐입니다.

v0.18.0(2026년 8월): v0.12-v0.16에서 도입된 headless runner, async suspend/resume, wake-plane, resilient-delivery 작업에 이어 MCP Python SDK v2로 마이그레이션했습니다. 자세한 내용은 변경 로그를 참조하세요.

참고: okf-agentbus 로 설치하세요(CLI 명령어는 여전히 agentbus). 추가 옵션: [obs,devex,jupyter,sdk].

⚡ "아하" 순간: 재시작 없는 통합

이미 Aider, OpenHands 또는 커스텀 에이전트를 tmux panes에서 실행 중이신가요? 세션을 종료하지 마세요. AgentBus는 이중 인터페이스 아키텍처(MCP + CLI)를 갖추고 있습니다. 오늘 바로 테스트하기 위해 JSON 설정을 연결할 필요가 없습니다. 실행 중인 에이전트에게 이렇게 요청하기만 하면 됩니다:

"터미널에서 agentbus publish --topic okf/handoff --payload '{\"from\":\"grok\",\"to\":\"hermes\",\"summary\":\"Write tests\"}' 를 실행하세요."

SQLite 버스가 MCP 서버 없이도 즉시 캡처합니다. Mission Control TUI에 확신이 생기면 다음 부팅 시 강력한 타입을 지닌 MCP 서버를 연결할 수 있습니다.

Related MCP server: Hivemind

Why AgentBus?

Feature Arsenal (v0.3 - v0.18)

• MCP Python SDK v2 (v0.18): 기존 이벤트 저장소 계약을 유지하면서 stdio MCP 서버를 마이그레이션.

• Resilient delivery (v0.16.4): 지터가 있는 with bounded retry, 마지막 재시도 시 dead letters 및 SQLite 동시성을 위한 파일 유출.

• Async suspend/resume (v0.16): durable waits 및 correlated wake events로 headless agents가 busy polling 없이 yield할 수 있습니다.

• Headless runners (v0.15): 다양한 CLI 에이전트를 위한 opt-in adapters로서 with bounded chain behavior and structured acknowledgements.

• Wake plane and Go helpers (v0.12-v0.13): platform-packaged workers, role leases, wake ingress, webhook delivery.

• Jupyter async client (v0.11): from agentbus.jupyter import AsyncAgentBus + %agentbus start — 논블로킹 폴이 노트북 이벤트 루프에 양보합니다.

• TypeScript client (v0.11): packages/js/agentbus-client — Node EventEmitter + MCP stdio spawn(@agentbus/agentbus-client, 지금은 경로 설치).

• God View Mesh (v0.9): Passive OS + MCP 관측으로 조용한 에이전트가 여전히 버스에 발자국을 남깁니다 (system/mcp, system/fs, system/shell, system/monologue).

• Mission Control TUI (v0.8+): 키보드로 조작하는 풍부한 Textual 대시보드(agentbus monitor). Trace waterfall, HITL, Wiretap pane, Dark Agent 경고.

• Pluggable Pydantic Schemas (v0.7): 코드 우선 @bus.topic 데코레이터로 삽입 계층에서 엄격한 JSON 스키마를 강제합니다.

• Distributed Context (v0.6): --attach 로 대용량 컨텍스트(예: git diff)를 전달하세요. 1MB 하드 페이로드 제한으로 컨텍스트 창 폭발을 방지합니다.

• Agentic Observability (v0.5): 네이티브 OpenTelemetry 스타일의 trace_id 및 parent_span_id 계통.

• SLA Timeouts & Dead-Letter (v0.4): 유령 데드락 방지. 에이전트가 스웜을 유령처럼 방황하면 SLA 지연이 스웜을 유령처럼 흐려, 라우터가 페이로드를 okf/dead-letter 로 보냅니다.

• Swarm RBAC & Droid Proofs (v0.3): 암호화 JWT/UUID 토큰으로 인증된 에이전트만 제한된 주제에 를 발행할 수 있습니다.

• HITL Intercepts (v0.3): 위험한 페이로드(예: DROP TABLE) 를 잡아내고 TUI를 통해 위험을 확인합니다.

설치

가장 빠른 방법 (IGID 사용 함 및 자동 연결):

curl -sSL https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash

또는 pip를 통해 수동 설치:

pip install -U "okf-agentbus[devex,sdk]"
agentbus init --apply --producer-id my-agent

Jupyter 노트북에서의 설정:

pip install -U "okf-agentbus[jupyter]"

%load_ext agentbus.jupyter
%agentbus start
# or
from agentbus.jupyter import AsyncAgentBus
bus = AsyncAgentBus()  # AGENTBUS_WORKSPACE or cwd
bus.on_event(print)
await bus.start_background(interval=1.0)

TypeScript (monorepo 체크아웃에서 ):

cd packages/js/agentbus-client && npm install && npm test
# set AGENTBUS_WORKSPACE + agentbus on PATH, then use createStdioMcpClient / AgentBus

빠른 시작 및 예제

AgentBus를 이해하는 가장 좋은 방법은 복사-붙여넣기 가능한 예제를 읽는 것입니다.

기본 Pub/Sub부터 Pydantic 스키마 및 SLA 타임아웃까지 모든 기능을 포함하는 7개봉어러운 격리된 Python 스크립트가 있는 examples/ 디렉토리를 참조하세요.

# Terminal A — Launch the Mission Control TUI
agentbus monitor

# Terminal B — Publish a handoff
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"cursor","to":"hermes","summary":"Write tests"}'

** god View Observability (v0.9.0):**

조용한 에이전트를 도청해 추적하세요:

# Intercept MCP tool calls
mcp-serve --wiretap

# Watch file edits and command executions
agentbus watch

# Tail internal agent reasoning logs
agentbus tail

이벤트는 system/mcp, system/fs, system/shell, system/monologue 주제에 대해 TUI의 Wiretap 사용자 정의 창으로 흘러 들어갑니다.

📦 워크스페이스 격리 (.agentbus 디렉토리)

AgentBus는 워크스페이스 격리 개념으로 작동합니다(.git 대비 docker-compose.yml 대비 docker-compose.yml 과 유사).

버스와 그 이벤트는 실행 중인 디렉터리에 물리적으로 범위가 제한됩니다. 스웜이 전체 운영 체제를 추적하거나 다른 프로젝트를 서로 오염시키는 것을 방지합니다.

특정 프로젝트 폴더로 이동하여 agentbus init 또는 agentbus up 을 실행하면 해당 디렉토리에 대해 특별히 로컬 .agentbus/events.db SQLite 데이터베이스가 생성됩니다.

1-Click Swarm Orchestration (v0.10.0)

5개의 tmux panes를 직접 열어 에이전트와 관측 데몬을 실행하는 대신 새 오케스트레이터를 사용하세요:

cd /path/to/my-project

# 1. Generate a boilerplate .agentbus/swarm.yaml
agentbus up --init

# 2. Boot the swarm (Watchers, Agents, and TUI) in one click
agentbus up

# 3. View running background agents
agentbus ps

# 4. Safely kill the entire swarm
agentbus down

문서

전체 아키텍처 문서는 docs/ 디렉토리를 참조하세요.

• Roadmap

• v0 이 문서와 크로스 머신 Swarm handoff

• MCP 스키마

• 릴리스 프로세스

라이선스

MIT — LICENSE 참조.