AgentBrain Handoffs

AgentBrain 交接

在 AI 编码 Agent 之间进行精确、持久的交接。每次交接都会在接收方现有会话中开启一个新回合。

_{演示的真实截图；其中的数据是虚构的示例数据。}

pip install .
handoffs demo

打开输出的 URL（http://127.0.0.1:8765/）。四个模拟 Agent 会互相交接工作。按 Ctrl+C 可停止演示并删除演示数据。

为什么要做这个项目

一组编码 Agent 已经有了会话、收件箱和工具。它们缺少的是交付机制：消息能到达正确的会话，在 Agent 忙碌时等待，只发送一次，并在服务提供方丢弃消息时于限定次数内重试。

否则，交接可能会丢失、重复交付，或被粘贴到正在处理中途回合的会话里。AgentBrain Handoffs 是交付层。它是一个本地 Python 包（Python 3.9+，仅使用标准库），提供 handoffs 命令、实时页面和 MCP 服务。

60 秒快速入门

在克隆的此仓库中运行：

python3 -m venv .venv
.venv/bin/pip install .
.venv/bin/handoffs demo

或者，在 PyPI 上安装此软件包后运行：

pipx run agentbrain-handoffs demo

你应该会看到：

AgentBrain Handoffs demo
  Open http://127.0.0.1:8765/
  Four simulated agents (Planner, Engineer, Reviewer, Writer) hand work to each other.
  Nothing real is contacted. The demo data is temporary and deleted when you stop (Ctrl+C).

页面每隔几秒更新一次。交接会依次经过 Accepted → Working → Finished。工作会自动返回并关闭。--speed 4 会加快模拟回合的完成速度。

要在其他端口运行演示：handoffs demo --port 9876。

更详细的操作指南（包括使用你自己的 Agent）请参阅 docs/QUICKSTART.md。

概念

交接是发送给某个已注册 Agent 的消息。交付引擎会将其转化为该 Agent 的一个新回合，并发送到交接登记时所使用的会话。

工作契约是带有标题的交接。接收方会返回结果（或阻塞项）；发送方则将其标记为已接受、需要修改或受阻。截止时间为可选项；如果截止时间已过，发送方会收到一条不会唤醒 Agent 的提醒。

交付状态说明：

状态	含义
WAITING	已排队。引擎下一轮运行时会尝试发送。服务提供方中断时也会保持此状态：详情会说明暂停原因，且不会消耗尝试次数。
BUSY	接收方正在处理一个回合。此状态会等待。
HELD	已主动阻止：连接被阻止或交付已暂停。不会消耗尝试次数。
UNAVAILABLE	Agent 或其会话已不存在。不会改发到其他位置。
OWNER_REJECTED	会话拒绝了写入。允许重试一次。
SENDING	正在发送写入内容。
UNCERTAIN	写入可能已成功；回复丢失，或在 10 分钟内无法观察到已接受的回合。此状态会被观察，但不会重新发送。
ACCEPTED	接收方的会话已接收该回合。
RUNNING	回合正在进行。
RETURNED	回合已完成。
FAILED	回合失败或被中断，或会话两次拒绝该内容（此时从未交付）。
ACKNOWLEDGED	接收方已阅读该消息；无需单独开启回合。
CANCELLED	经过足够多次历史记录扫描后，确认消息不存在；或由人员使用 handoffs release 解除。不会重新发送。
DUPLICATE	与仍在进行的交接内容相同。

保证

1. 准确送达接收方。 移交只会发送给指定的 Agent，且发送到其注册时使用的端点。
2. 每次尝试只写入一次。 发送前会预留此次尝试。回复丢失时会进入 UNCERTAIN 状态，并通过观察进行核对。写入被拒绝时会重试一次；若再次被拒绝，则以 FAILED 状态结束送达，因此接收方不会因此被占用。
3. 绝不打断。 忙碌的接收方会继续当前轮次。向同一 Agent 发起的第二次移交会以 BUSY 状态等待。
4. 重发次数有限。 出错的轮次最多重发两次；被中断的轮次只重发一次，等待十分钟后，且仅当工作仍未完成时重发。每次重发都会使用新的请求 ID。
5. 如实释放。 如果连续三次完整历史扫描跨越一小时，证明 UNCERTAIN 状态的送达从未被接收，则会将其取消为 CANCELLED。若已接受的轮次在 10 分钟内无人观察到，也会进入 UNCERTAIN 状态，因此同样适用此规则。若你已知卡住的送达最终结果，可运行 handoffs release ID 将其取消；无论哪种情况，都不会重发。
6. 故障期间暂缓。 服务提供商状态页防护机制可在不消耗尝试次数的情况下暂缓送达。
7. 截止时间。 工作超过截止时间后，会向发送方发送一次提醒，且不会唤醒发送方。

适配器

提供商	状态	对接内容
demo	稳定	模拟 Agent。由 handoffs demo 使用。
command	稳定	argv（不使用 shell）或 HTTP POST。
codex	实验性	通过 stdio 使用 codex app-server JSON-RPC。
claude-code	实验性	Claude Code 无头模式（claude -p --resume）。

有关设置、示例和实验性功能注意事项，请参阅 docs/ADAPTERS.md。

MCP

每个 Agent 会话都会启动自己的 MCP 服务。身份在启动时固定，因此工具调用无法冒充其他 Agent。

Claude Code

claude mcp add handoffs -- handoffs mcp --agent me

将 me 替换为你注册的 Agent ID（handoffs agent add me --provider claude-code ...）。

Codex（~/.codex/config.toml）

[mcp_servers.handoffs]
command = "handoffs"
args = ["mcp", "--agent", "me"]

Cursor（Cursor 设置中的 MCP 服务）

{
  "mcpServers": {
    "handoffs": {
      "command": "handoffs",
      "args": ["mcp", "--agent", "me"]
    }
  }
}

使用 --db 或 HANDOFFS_DB，让每个进程都指向同一个数据库。实际执行送达的是引擎（handoffs serve 或 handoffs run）；MCP 服务只会写入收件箱。详情请参阅 docs/MCP.md。

项目记忆：ContextLib 插件

ContextLib 会将项目的决策、事实和经验教训保存为纯 Markdown 文件。安装后，将同一服务指向一个知识库，每个 Agent 除了移交工具外，还会获得 context_* 工具（brief、search、get、record、supersede、review、capture、export、import、status）：

pip install "git+https://github.com/willykeenan/agentbrain-contextlib"
claude mcp add handoffs -- handoffs mcp --agent me --context-library "/Volumes/SSD/ContextLib"

可使用 $CONTEXTLIB_ROOT 代替该标志。该插件以服务固定的 Agent ID 运行，因此 Agent 的记录恰好由发送其移交的 Agent 撰写。若未配置知识库，该服务只会提供移交工具。

CLI

handoffs init
handoffs agent add planner --provider demo
handoffs agent add builder --provider demo --name Builder
handoffs send planner builder "Add a health check" --title "Health check" --due-minutes 30
handoffs serve                          # engine + live page on http://127.0.0.1:8765/
handoffs inbox builder
handoffs read ID --as builder
handoffs return ID --as builder --summary "Health check is green"
handoffs close ID --as planner accepted
handoffs status --json
handoffs tick                           # one delivery pass (Codex and Claude Code turns wait for run or serve)
handoffs release ID                     # stop tracking a stuck delivery; never resent
handoffs run                            # engine only
handoffs mcp --agent builder            # stdio MCP server

--db PATH 或 HANDOFFS_DB 用于选择数据库（默认值为 ./.handoffs/handoffs.sqlite3）。会输出记录的命令均接受 --json。用法错误时以状态码 2 退出。

命令	用途
init	创建数据库。
agent add|list|remove	注册 Agent。若 --set KEY=VALUE 的内容可解析为 JSON，则会按 JSON 处理。
allow / block	定向连接。
config KEY VALUE	enabled、enabledAfter、connections、outageGuard。
send FROM TO MESSAGE	收件箱消息；使用 --title 可将其设为工作项。--key 用于保证幂等性。
inbox / read / accept / return / close	工作生命周期。使用 --as 或 HANDOFFS_AGENT。
status / tick / run / serve / mcp / demo	检查并执行送达。
release ID	取消一项卡住的送达（例如 UNCERTAIN 状态），以释放其接收方。不会发送任何内容。

安全

实时页面绑定到 loopback，并拒绝非 loopback 的 Host 标头（防止 DNS 重绑定）。POST /api/send 需要 <db>.token 中的令牌（模式为 0600）。--public-demo 仅用于 handoffs demo（模拟 Agent、临时数据）；该页面无法发送内容，并会显示纯文本状态说明，而非适配器错误。MCP 身份由启动时使用的 --agent 指定。完整模型：docs/SECURITY-MODEL.md。

路线图

• 保持演示和命令适配器稳定。
• 随着 Codex 和 Claude Code 的应用协议逐渐稳定，强化相应适配器。
• 为 outageGuard 提供更多状态页面预设。
• 计划中：Agent Rooms 将使用此交付约定。

使用 Docker 运行

该镜像已发布到 ghcr.io/willykeenan/agentbrain-handoffs，支持 Apple 芯片和 Intel。

docker run --rm -p 8765:8765 ghcr.io/willykeenan/agentbrain-handoffs demo --host 0.0.0.0 --public-demo   # the live demo
claude mcp add handoffs -- docker run -i --rm -v ~/.handoffs:/data ghcr.io/willykeenan/agentbrain-handoffs mcp --agent me

MCP 服务会写入 ~/.handoffs 中的交接数据库；请在 Agent 所在的机器上运行引擎（handoffs serve），以便其进行交付。

许可证

Apache-2.0。版权所有 KE Studios。

源代码：github.com/willykeenan/agentbrain-handoffs。在线演示：huggingface.co/spaces/willykeenan/agentbrain-handoffs。

AgentBrain Handoffs 是 AgentBrain 的开放交付层。AgentBrain 是即将登陆 Agent Rooms（agentrooms.io）的 Agent 运行时。