AgentBrain Handoffs

AgentBrain Handoffs

AI コーディングエージェント間で、正確かつ確実に引き継ぎます。各引き継ぎは、受信側の既存セッションに追加される新しいターンです。

_{デモの実際のスクリーンショットです。表示されているデータは架空のサンプルデータです。}

pip install .
handoffs demo

表示された URL（http://127.0.0.1:8765/）を開いてください。4 つのシミュレーションエージェントが互いに作業を引き継ぎます。Ctrl+C でデモを停止し、デモデータを削除します。

これが必要な理由

コーディングエージェントのチームには、すでにセッション、受信トレイ、ツールがあります。不足しているのは配信の仕組みです。つまり、適切なセッションに届き、エージェントが作業中の場合は待機し、一度だけ送信され、プロバイダーがメッセージを受け取れなかった場合には上限内で再試行されるメッセージです。

これがないと、引き継ぎが失われたり、二重に配信されたり、すでにターンの途中にあるセッションに貼り付けられたりします。AgentBrain Handoffs は配信レイヤーです。handoffs コマンド、ライブページ、MCP サーバーを備えたローカルの Python パッケージ（Python 3.9 以降、標準ライブラリのみ）です。

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。

自分のエージェントを含む、より詳しい手順はdocs/QUICKSTART.mdをご覧ください。

コンセプト

引き継ぎとは、登録済みの 1 つのエージェントを宛先とするメッセージです。配信エンジンはこれを、その引き継ぎが登録された時点でエージェントが使用していたセッションに、新しいターンとして 1 回だけ送信します。

作業契約とは、タイトル付きの引き継ぎです。受信側は結果（または阻害要因）を返し、送信側は承認、修正、またはブロックとして終了します。期限は任意です。期限を過ぎると、送信側に、相手を起こさないリマインダーが 1 回送られます。

配信状態を平易な言葉で説明すると：

状態	意味
WAITING	キューに登録されています。次のエンジン実行時に送信が試みられます。プロバイダーが停止している場合もこの状態のままです。詳細に保留理由が表示され、試行回数は消費されません。
BUSY	受信側がターンの途中です。送信は待機します。
HELD	意図的にブロックされています。接続がブロックされているか、配信が一時停止されています。試行回数は消費されません。
UNAVAILABLE	エージェントまたはそのセッションが存在しません。別の宛先には転送されません。
OWNER_REJECTED	セッションが書き込みを拒否しました。1 回だけ再試行できます。
SENDING	書き込みが進行中です。
UNCERTAIN	書き込みが反映された可能性がありますが、応答が失われたか、受理されたターンを 10 分間確認できませんでした。状態を確認し、再送信はしません。
ACCEPTED	受信側のセッションがターンを受け取りました。
RUNNING	ターンが進行中です。
RETURNED	ターンが終了しました。
FAILED	ターンが失敗または中断されたか、セッションが 2 回拒否しました（その場合、配信は一度も行われていません）。
ACKNOWLEDGED	受信側がメッセージを読みました。個別のターンは必要ありません。
CANCELLED	十分な回数の履歴スキャンで存在しないことが確認されたか、handoffs release によって人が解放しました。再送信はしません。
DUPLICATE	進行中の引き継ぎと同一です。

保証事項

1. 宛先を厳守。 ハンドオフは、登録時のエンドポイントにいる、指定されたエージェントにのみ配信されます。
2. 試行ごとに書き込みは1回。 送信前に試行が予約されます。返信が失われた場合は UNCERTAIN になり、状態の確認によって照合されます。書き込みが拒否された場合は1回だけ再試行され、2回目も拒否されると配信は FAILED となり、宛先を拘束しません。
3. 決して割り込みません。 対応中の宛先はそのターンを継続します。同じエージェントへの2つ目のハンドオフは BUSY として待機します。
4. 再送には上限があります。 エラーになったターンは最大2回、中断されたターンは作業がまだ未完了の場合に限り、10分後に1回再送されます。再送ごとに新しいリクエスト ID が割り当てられます。
5. 正確に解放。 1時間にわたる3回の完全な履歴スキャンで未受信と確認された UNCERTAIN 配信は、CANCELLED になります。受け入れられたターンが10分間誰にも確認されない場合も UNCERTAIN となり、同じルールが適用されます。停滞した配信の終了状態が分かっている場合は、handoffs release ID でキャンセルできます。どちらの場合も再送はされません。
6. 障害中は保留。 プロバイダーのステータスページによるガードで、試行を消費せずに配信を保留できます。
7. 期限。 期限を過ぎた作業については、送信者に一度だけ、起動を伴わない通知で警告します。

アダプター

プロバイダー	状態	接続先
demo	安定版	シミュレートされたエージェント。handoffs demo で使用します。
command	安定版	argv（シェル不使用）または HTTP POST。
codex	実験的	stdio 経由の codex app-server JSON-RPC。
claude-code	実験的	Claude Code ヘッドレス（claude -p --resume）。

設定、例、実験的機能に関する注意事項については、docs/ADAPTERS.md を参照してください。

MCP

各エージェントセッションは、それぞれ専用の MCP サーバーを起動します。ID は起動時に固定されるため、ツール呼び出しで別のエージェントとして動作することはできません。

Claude Code

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

me を、登録したエージェント 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 ファイルとして保存します。インストールして同じサーバーをライブラリに接続すると、各エージェントはハンドオフ用ツールとともに 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 を使用できます。プラグインはサーバーの固定エージェント ID で実行されるため、エージェントの記録は、そのエージェントがハンドオフを送信した場合に限り、そのエージェントによって作成されます。ライブラリがない場合、サーバーが提供するのはハンドオフ用ツールのみです。

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	エージェントを登録します。--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）を1件キャンセルし、宛先を解放します。送信は行われません。

セキュリティ

ライブページはループバックにバインドされ、ループバック以外のHostヘッダーを拒否します（DNSリバインディング対策）。POST /api/sendには、<db>.token（モード0600）のトークンが必要です。--public-demoはhandoffs demoでのみ使用でき（エージェントをシミュレートし、一時データを使用）、このページから送信することはできません。また、アダプターのエラーの代わりに、状態を示す簡潔な文が表示されます。MCPのIDは、起動時に指定した--agentです。完全なモデルについては、docs/SECURITY-MODEL.mdをご覧ください。

ロードマップ

• デモとコマンドアダプターを安定した状態に保ちます。
• アプリのプロトコルが固まり次第、CodexおよびClaude Codeのアダプターを強化します。
• outageGuard向けのステータスページのプリセットを増やします。
• 予定：Agent Roomsでは、この配信契約を使用します。

Dockerで実行

イメージは、AppleシリコンとIntel向けにghcr.io/willykeenan/agentbrain-handoffsで公開されています。

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のハンドオフデータベースに書き込みます。配信できるように、エージェントが稼働しているマシンでエンジン（handoffs serve）を実行してください。

ライセンス

Apache-2.0。著作権はKE Studiosに帰属します。

ソース：github.com/willykeenan/agentbrain-handoffs。ライブデモ：huggingface.co/spaces/willykeenan/agentbrain-handoffs。

AgentBrain Handoffsは、Agent Rooms（agentrooms.io）に登場するエージェントランタイム、AgentBrainのオープンな配信レイヤーです。