Codex Hermes A2A Bridge

ローカルブリッジはCodexを「受付」として機能させます。Codexはstdio経由でMCPツールを呼び出し、ブリッジはリクエストをA2A v1.0/JSON-RPCに変換してHermesのdefaultプロファイルへ送信し、会話/タスクのマッピングをSQLiteに保持します。Hermesは引き続き「頭脳」として、エージェントループ、メモリ、スキル、ツール、および内部オーケストレーションを実行します。

現在のバージョン: v0.1.1。ループバックのバインド/コールのみ対応。モデル変更、プラグイン、設定、更新、シェル、またはHermesサービス制御するツールはありません。

独立プロジェクト: これは独立したコュニティ・ソフトウェアであり、公式製品ではなく、スポンサーの提ずけもなく、Nous Research/Hermes Agentや OpenAI/Codexを代表するものでもありません。ブランド名は相互操作互の説明だけに用れていいます。

アーキテクチャ

Codex client --MCP stdio--> MCP server --> bridge core --> Hermes A2A :9900
                                      \--> SQLite context/task mapping

• Python 3.11と専用のvenvを使用し、Herm世界のvenvは使用しまません。

• 公式のPython MCP SDK、httpx async、Pydantic、SQLite stdlibを使用します。

• 各conversation_keyはHermesのcontextIdにマッピングできます。続の続いてのターンはそのマッピングを再利ます。

• 元のプロンプトは永続化されません。ブリッジは指紋、ルート、状態、結果、最小限のエラーを保存します。

Related MCP server: ccg-mcp

要件とクイックインストール

• Python 3.11。

• A2Aゲートウェイをループバックで動さたるHermes Agent 0.20.5。

• MCP stdio対応のCodexクライアント。

cd /absolute/path/to/codex-hermes-a2a-bridge
python3.11 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/codex-hermes-a2a-bridge doctor

コントリビューターは、python -m pip install -e '.[dev]でテスティンギツールを追加インストールできます。オーバライドについては.ee.exampleを参照してください。実の.envファイルはコミットしらないでください。

安全なデフォルト設定:

Hermes A2Aを有効にしてCodex2に登録する

ローカルにインストールられたHermes 0.20.5で:

hermes plugins enable a2a-platform --no-allow-tool-override
hermes config set gateway.platforms.a2a.enabled true
hermes gateway run --no-supervise

フォアグラウンドで実行する場合は、ユーザーサービスもインストールできます（sudoなし）:

hermes gateway install --start-now --start-on-login

Codexの共通MCP設定にブリッジを登録します:

codex mcp add codex-hermes-a2a-bridge -- \
  /absolute/path/to/codex-hermes-a2a-bridge/.venv/bin/codex-hermes-a2a-bridge serve
codex mcp get codex-hermes-a2a-bridge

新しいエントリを読み込むには、新しいCodexクライアントを開く・再起動する必要があります。MCP stdioはプロトコルフレームのみをstdoutに書き出し、診断はstderrに出力されます。

7つのMCPツール v0.1

調査ので既に示した4つのMVP操作（discover・send・get・continue）は完全なA2Aではありません。v0.1ではこれらを、会話・タスク向けの7つの高レベルツールに統合しています。プッシュ通知のCRUDやHermesの管理などの下位のA2A操作は直接公開していません。

サンプルワークフロー

1. Codexがhermes_statusを呼び出す。

2. Codexがhermes_chat(message=..., conversation_key=<安定した値>, mode="auto")を呼び出す。

3. タスクが実行中の場合は、hermes_task_waitかhermes_task_getを使います。曖昧なタイムアウト既定で無差別に再送信しないてください。

4. needs_input=trueの場合はユーザユーザに聞いてから、同じconversation_key/context_idでhermes_chatを呼び出す。

5. その後のターンは同じマッピングを引き続き使用します。hermes_contexts(action="close")はブリッジのマッピングのみを閉じます。

副作用のあるタスクには、idempotency_keyを指定してください。Hermes 0.20.5には電文レベルの冪等性はありません。そのため、ブリッジは配信結果が不明の場合にミューティング送信を再試行しません。

v0.1.1から全モードがSendStreamingMessageを使うため、最初のイベントでA2AタスクIDをすぐ受信します。syncはインライン最大30秒（timeoutに指定されあればその値）だけ待ってか次へ進みます。ストリームはコレーションタイムアウトまで生き続けます。A2A IDがない古いoutcome_unknownレコードは、hermes_task_get/hermes_task_waitが最初にListTasks(contextId)を試し、その後Hermesの公式である会話持続を確認します。ローカルの未解決タスクが1件と、リモート/ディスクの候補が1件である場合のみ、リカバリが結果をリコンサエルします。不明確な場合は文字に残し、再送も予測判断も行いません。ディスクフォールバックにはA2Aの状態がないため、警告を返し、既に保存されたエ一ジェントの応答はcompletedと見なます。

テストと運用

.venv/bin/pytest --cov=codex_hermes_a2a_bridge --cov-report=term-missing
.venv/bin/codex-hermes-a2a-bridge doctor
.venv/bin/codex-hermes-a2a-bridge smoke \
  'Reply with exactly MY_MARKER and nothing else.' \
  --conversation-key manual-smoke
.venv/bin/python scripts/live_check.py manual-smoke

pytestは一時的なループバックPOSTでフェイクA2Aサーバーを使うため、実際のHermesは不要です。doctorとlive_check.pyは読み取り専用です。smokeコマンドは実際のタスクを送ります。無害な内容もので能動的手動実行してください。

Security and privacy

• v0.1.1ではループバック以外のルートエンドポイントとAgent Card URLを拒否し、リダイレクトは従わず、MCPツール引数からトークンを受け付いません。

• SQLiteは既定ではソースツリーの外のファイルに0600権限で置きます。マッピング、指紋、状態、結果/アーティフケート、最小限のエラーを保存します。結果には情価度の高い情報が含まれ得るため、適切な保持・バックアップ計画が必用です。

• 元のプロンプトはブリッジに永続化しませんが、Hermesは固有の会話・監査記録を書くこがあります。フォールバックの復旧は設定されたHermes会話ディレクトリを読取りのみでアクセス。

• MCPサーバーは信頼のおけるユーザー資格で実動してださい。7つのツールには、副作用のあるスキール/ツールを動作させるHermesを発動することが可能です。idempotency_keyを使用し、outcome_unknownでは行きあたりの再送しでください。

• ぜ弱性報告は SEC.RICY.md を従って下さい。トークン・トランスクリプト・SQLiteを issue に投稿しないでください。

補証と上游の制り

ブリッジは、ループバック・ポリシー、永続的なローカル・マッピング、曖味さの後のミューティンング送信の再行省略、および誠実な cancel のセマンティクスを保証します。ブリッジは、Hermes anticが計算を停止したこと、tokenレベルストリーミング、wireーレビル冪等性、そししHermes再起動間のタスク持続性を保証しません。

Hermes 0.20.5はイメモリ上の TaskStore とライフタイクルSSEを使用します。プロトコル Cancel は実行中のターンを中断しません。ブリッジの会話ストア・リカバリは条付の読取専用フォールバックであり、上游の永続タスクストア代替しません。検証済みの詳細は Hermes A2Aレファレンス をご覧ください。

Troublesholding

• a2a_unreachable: hermes gateway のstatusを実、行し、`http://127.0.0.1:9900/.well-known/agent-card.json のカードを確。

• A2Aプラグインが有効ではあるがポートがあるらない場合: hermes config get agentp.platforms.a2.a.enabledを確認し、サを再起動します。

• Codexがツールを見ない場合: codex mcp get codex-hermes-a2a-bridgeを実行し、新しいCodex clientト・プロセスを使してください。

• outcome_unknown: hermes_task_get/hermes_task_wait を呼び出してブリッジに整解させます。それでも明確でない場合、副作用のあるタスクを再送せず、ユーザーに質てください。

• turn_gs: マッピングを閉じて新しい会話を作成します。エージェントループを無限に続継させるだめにもバジェットを増やさないください。

• Hermes 0.20.5は再起動すると A2A TaskStore が消えます。ブリッジ側はローカルのタスク/結果れを保たまが、リモト側のリフレッシではタスクが見つかしいと報告ることがあります。

• 現在のmacOSで unchctl bootstrap が exit 5 を返した場合流、Hermes はデタッチのフォールバックします: 実動はしますが自動起動/自動再起動のしません。hermes gateway statusで確認してください。

ロールバック

scripts/rollback.sh を参照し。デフォルトでスクリーンは計画ツ用。 scripts/rollback.sh--apply は MCPエン etry と A2A設定/ぢラグインを解除しますンが、ゲートウェイ・サーが他プラットフー・のを務めて発する可能性があるため、ゲートウェイ・サーを保持します。ゲトウェイがそのロールアウントにののみでが設される場合にだけ、--include-gateway-service を追加してください。ソース、.venv`、SQLite、Hermes のトランスクプトは保持します。

構成ファイルの付近には、.pre-codex-hermes-a2a-bridge-v0.1.ak という接尾辞のスコープ付きバックアップが作らます。エーザーが変更したかも知れないファイル全体を自動復元せず、ファイル全体の自動レストアは行いません。

ドキュメント

• v0.1実装計画

• v0 .1 試験報文

• Hermes A2A v1.0 レファレンス

• MCP bridge のデザイン

• CHANGELOG

• コントリビュートガイ

• セキュリティ・ポリシー

• Apache License 2.0

公式の準拠: OpenAI Codex MCP、Hermes A2A guide、NousResearch/hermes-agent。矛盾する場は、ローカルの Hermes 0.20.5 ソリースのコミット d736f5d53f1d33fa0a5f17ce0070ebd38f618f8 を優先します。