AgentBus

基于 SQLite 的 MCP 事件总线与控制面，专为异构智能体集群打造。

当 Cursor、Claude、Antigravity 和终端智能体（如 Hermes）共享同一工作区时，它们通常通过脆弱的追加式文件（log.md）进行协调。这在不需要 SLA 超时、人在环路（HITL）拦截、严格模式校验或加密 RBAC 时还能凑合。

AgentBus 用 localhost 边车 取代了“传话游戏”：一个由 SQLite 支撑的 Python MCP 服务器。没有编排器运行时锁定，没有笨重的云端仪表盘。只有为顶级 AI 编排而生的超快本地发布/订阅。

v0.18.0（2026 年 8 月）： 迁移至 MCP Python SDK v2，紧随 v0.12-v0.16 中发布的无头运行器、异步挂起/恢复、唤醒平面和弹性投递功能。详见变更日志。

注意： 安装包名为 okf-agentbus（CLI 命令仍为 agentbus）。可选依赖：[obs,devex,jupyter,sdk]。

⚡ “顿悟”时刻：零重启集成

已经在 tmux 窗格中运行 Aider、OpenHands 或自定义智能体？不要终止你的会话。 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

为什么选择 AgentBus？

功能军火库（v0.3 - v0.18）

• MCP Python SDK v2（v0.18）： 迁移 stdio MCP 服务器，同时保留现有事件存储契约。

• 弹性投递（v0.16.4）： 带抖动的有界重试、重试耗尽后的死信以及针对 SQLite 争用的文件溢出。

• 异步挂起/恢复（v0.16）： 持久等待和关联唤醒事件让无头智能体无需忙轮询即可让出控制权。

• 无头运行器（v0.15）： 为异构 CLI 智能体提供可选适配器，具有有界链行为和结构化确认。

• 唤醒平面与 Go 辅助工具（v0.12-v0.13）： 平台打包的工作器、角色租约、唤醒入口和 Webhook 投递。

• Jupyter 异步客户端（v0.11）： from agentbus.jupyter import AsyncAgentBus + %agentbus start — 非阻塞轮询，让出给笔记本事件循环。

• TypeScript 客户端（v0.11）： packages/js/agentbus-client — Node EventEmitter + MCP stdio 生成（@agentbus/agentbus-client，目前为路径安装）。

• God View 网格（v0.9）： 被动 OS + MCP 可观测性，让沉默的智能体仍留下总线足迹（system/mcp、system/fs、system/shell、system/monologue）。

• Mission Control TUI（v0.8+）： 一个丰富的、键盘驱动的 Textual 仪表盘（agentbus monitor）。追踪瀑布、HITL、Wiretap 窗格、Dark Agent 警告。

• 可插拔 Pydantic 模式（v0.7）： 代码优先的 @bus.topic 装饰器，在插入层强制严格 JSON 模式。

• 分布式上下文（v0.6）： 通过 --attach 传递大型上下文（如 git diff）。1MB 硬性负载限制防止上下文窗口爆炸。

• 智能体可观测性（v0.5）： 原生 OpenTelemetry 风格的 trace_id 和 parent_span_id 谱系。

• SLA 超时与死信（v0.4）： 防止幽灵死锁。如果智能体从集群中消失，SLA 定时器会将负载路由到 okf/dead-letter。

• 集群 RBAC 与 Droid 证明（v0.3）： 加密 JWT/UUID 令牌确保只有授权智能体才能发布到受限主题。

• HITL 拦截（v0.3）： 捕获危险负载（例如 DROP TABLE）并将其置于 PENDING_APPROVAL 状态，供人类通过 TUI 审查。

安装

最快的方式（一步安装并自动配置你的 IDE）：

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 的最佳方式是阅读我们可复制粘贴的示例。

参见 examples/ 目录，其中有 7 个完美、独立的 Python 脚本，涵盖从基本发布/订阅到 Pydantic 模式和 SLA 超时的所有功能。

# 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 可观测性（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 使用 .git 或 Docker 使用 docker-compose.yml）。

总线和其事件在物理上限定于你运行它的目录。这可以防止你的集群追踪整个操作系统或不同项目之间的交叉污染。

当你导航到特定项目文件夹并运行 agentbus init 或 agentbus up 时，它会为该目录创建一个本地化的 .agentbus/events.db SQLite 数据库。

一键集群编排（v0.10.0）

无需手动打开 5 个 tmux 窗格来启动你的智能体和可观测性守护进程，使用新的编排器：

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/ 目录。

• 路线图

• v0.19 产品计划和跨机器集群交接

• MCP 模式

• 发布流程

许可证

MIT — 参见 LICENSE。