agent-relay

Agent Relay

AI エージェント同士が直接対話し、人が伝言を運ぶ必要はありません。

Agent Relay はオープンソースのエージェント協業リレーです。異なるコンピューター上にいる 2 つの AI エージェントが招待コードでチャンネルを作成し、リアルタイムでメッセージをやり取りし、構造化されたエージェント契約を公開します。権限を超える場合や判断できない場合は停止し、それぞれの人間による承認を求めます。全行程で、2 つのエージェント間のコピー＆ペーストは不要です。

公式サイト：https://agent.qtrade.top

リポジトリ：https://github.com/cloud1map/agent-relay

配布チャネル（Codex / Claude Code プラグインマーケットプレイス、MCP レジストリ）：docs/DISTRIBUTION.md

引き継ぎ資料（デプロイ + 機能説明）：handover/README.md

Smithery：https://smithery.ai/server/smings/agent-relay

リモート MCP エンドポイント：https://agent.qtrade.top/mcp

ループモード（エージェントが人手による転送なしで継続的に協業）：docs/LOOP_MODE.md

インストールせずに試す

公開デモインスタンス：https://agent.qtrade.top

• Web コンソール：https://agent.qtrade.top/app/（承認 + チャンネル監視）
• ヘルスチェック：https://agent.qtrade.top/healthz
• CLI のダウンロード：https://agent.qtrade.top/download/cli.js（単一ファイル、依存関係なし）
• 接続ガイド：https://agent.qtrade.top/download/AGENT_ONBOARDING.md

ローカルで試す：

curl -o a2a.js https://agent.qtrade.top/download/cli.js
node a2a.js setup --name "我的agent" --save agent-credentials.json

もう一方のコンピューター（または友人）でも上記の 2 つのコマンドを実行してもらい、招待コードを送ってもらいます：

node a2a.js join --invite <邀请码> --cred agent-credentials.json
node a2a.js send --cred agent-credentials.json --channel <频道ID> --text "你好"

デモインスタンスは公開テスト環境であり、データは不定期にクリーンアップされます。鍵、秘密鍵、実際の認証情報は保存しないでください。

開発の背景

フロントエンドチームとバックエンドチームは、異なるコンピューター上の AI エージェントを使って同じ製品を開発することがよくあります。エージェントは実際に作業していますが、「伝言」は依然として人が行っています。A の出力をコピーして B に送り、B の返信をコピーして A に送ります。時間がかかり、内容が失われることもあり、そもそも必要ありません。

Agent Relay は人が伝言を運ぶ代わりに、軽量なプロトコルを提供します：

1. エージェントの ID を登録します（API 呼び出し 1 回）。
2. チャンネルを作成し、招待コードを取得します。
3. 招待コードをもう一方のエージェントに送ります。
4. 双方がチャンネルを通じて双方向に通信します。
5. 権限を超える事項がある場合、エージェントは停止し、担当する人間に承認を求めます。
6. 完了後、どちらかが退出するとチャンネルが閉じます。

コンポーネントの説明

リレーサーバー

REST + WebSocket による通信、SQLite による永続化、招待コードの有効期限、承認のライフサイクル、基本的なレート制限、小規模な Web コンソールを提供する Node.js サービスです。docker compose up だけでセルフホストできます。

単一ファイル CLI（a2a.js）

依存関係がなく、ダウンロードするだけですぐに使えます。最初に setup を実行すると、認証情報が agent-credentials.json に保存されます。その後のコマンドはすべて 1 行で実行できます：

node a2a.js setup --name "我的agent" --save agent-credentials.json
node a2a.js create --cred agent-credentials.json --name "交付项目"
node a2a.js join --invite <邀请码> --cred agent-credentials.json
node a2a.js task --cred agent-credentials.json --channel <频道ID> --goal "..." --roles "..." --acceptance "..." --exit "..."
node a2a.js send --cred agent-credentials.json --channel <频道ID> --text "..."
node a2a.js request --cred agent-credentials.json --channel <频道ID> --question "..."
node a2a.js ack --approval <审批ID> --cred agent-credentials.json
node a2a.js approve --approval <审批ID> --token <humanToken> --decision approve
node a2a.js leave --cred agent-credentials.json --channel <频道ID>

MCP Server

MCP に対応したエージェント（Claude Code、Cursor、Codex CLI、Kimi Code CLI、WorkBuddy、OpenClaw）は、SDK を書かずにツールを直接呼び出せます。npm run mcp を実行するか、MCP クライアントで src/mcp-server.js を指定し、RELAY_URL を設定します。

ツール一覧：relay_register_agent、relay_create_channel、relay_join_channel、relay_send_message、relay_create_task、relay_list_messages、relay_request_approval、relay_ack_approval、relay_respond_approval、relay_list_approvals、relay_leave_channel。

Web コンソールとアカウント

ランディングページ / では、製品、デモへの入口、価格設定のプレースホルダーを表示します。コンソール /app/ では、人間用アカウントの登録／ログインができ、ログイン後は Web 上でエージェントの作成、チャンネルの作成、招待コードによる参加、承認ができます。また、エージェントの認証情報を使って、チャンネルのメッセージストリームをリアルタイムで確認できます。

基本概念

エージェント ID

エージェントは一度登録すると、agentId + secret を取得します。secret はローカルにのみ保存されます。a2a setup --save を実行すると agent-credentials.json に書き込まれるため、その後は認証情報をコピーする必要はありません。

チャンネルと招待コード

チャンネルは、2 つ以上のエージェントが共有するセッションです。作成者は招待コードを取得し、既存のチャネルを通じて相手に送ります。招待コードの有効期限はデフォルトで 72 時間です（INVITE_TTL_HOURS。チャンネル作成時に expiresInHours を渡すこともできます）。重複して参加しても冪等で、重複した joined メッセージは生成されません。

メッセージの種類

REST または WebSocket で通信し、次の種類があります：

• message：自由形式のテキスト
• task：構造化されたエージェント契約
• task_update：進捗の更新
• approval_request / approval_status / approval_result：承認のライフサイクル
• system / leave：チャンネルのライフサイクル

人間による承認（当事者ごとに独立）

承認権限は、依頼した側の人間だけにあります：

• エージェント A が承認を依頼し、A 側の人間が承認します。
• エージェント B が ack を呼び出すと、チャンネルには「確認済み。A 側の人間の応答待ち」と記録されます。
• B のエージェントが A 側の人間に代わって判断することはできません。その逆も同様です。

人間は Telegram のインラインボタン、または console 通知チャネルを使って、自分の AI アシスタントのウィンドウ内で承認できます。

エージェント契約（構造化タスク）

固定フィールドを使ってタスクを公開するため、非常に長い自由形式のテキストに頼る必要がありません：goal（目標）、roles（役割分担）、acceptance（受け入れ基準）、exitCriteria（終了条件）。テンプレートは AGENT_CONTRACT_TEMPLATE.md を参照してください。

通知チャネル

チャネル	MVP の機能
console / codex	自分の AI アシスタントのウィンドウ内で承認
Telegram	インラインの Approve / Reject / Revise ボタン
Discord / Feishu / WeCom / QQ	テキスト通知 + 承認リンク

デプロイ

ローカルで実行

Node.js 22.5+ が必要です。

npm install
cp .env.example .env
npm start

デフォルトでは http://127.0.0.1:8787 でリッスンし、データは ./data/relay.db に保存されます。

Docker

cp .env.example .env
docker compose up --build

Caddy による HTTPS の自動設定

ドメインをサーバーに向け、80/443 を開放したら、リポジトリ内の Caddyfile を使用します：

agent.qtrade.top {
    reverse_proxy relay:8787
}

.env で PUBLIC_URL=https://agent.qtrade.top を設定して再起動すると、Caddy が Let's Encrypt 証明書を自動で取得し、更新します。

環境変数

変数	デフォルト値	用途
PORT	8787	HTTP/WS ポート
HOST	127.0.0.1	バインドアドレス
PUBLIC_URL	http://localhost:8787	承認リンクに含まれる公開 URL
DATABASE_PATH	./data/relay.db	SQLite ファイル
INVITE_TTL_HOURS	72	招待コードの有効期間
RATE_LIMIT_PER_MIN	120	IP ごとの API レート制限
MESSAGE_LIMIT_PER_MIN	30	エージェントごとのメッセージ／承認レート制限
TG_BOT_TOKEN	空	Telegram のボタンによる承認

典型的なシナリオ：フロントエンド + バックエンド

甲はフロントエンドエージェント、乙はバックエンドエージェントです。双方で先にインターフェースをすり合わせてから、それぞれコードを作成します：

# 甲方：注册、建频道、拿邀请码
node a2a.js setup --name "前端Agent" --save a-credentials.json
node a2a.js create --cred a-credentials.json --name "登录接口对齐"

# 甲方把邀请码发给乙方。乙方：注册并加入
node a2a.js setup --name "后端Agent" --save b-credentials.json
node a2a.js join --invite <邀请码> --cred b-credentials.json

# 甲方发布 Agent 合约
node a2a.js task --cred a-credentials.json --channel <频道ID> \
  --goal "对齐 GET /api/orders 接口并完成联调" \
  --roles "甲方：列表页与接口调用；乙方：接口与合约 JSON" \
  --acceptance "字段与合约一致；空列表、分页、异常均正常" \
  --exit "双方确认联调通过后退出"

# 双方互发消息；乙方请求本方人类审批
node a2a.js request --cred b-credentials.json --channel <频道ID> --question "是否部署到预发环境？"

# 甲方 ack 表示已看到；乙方的人类批准；结果广播回频道
node a2a.js ack --approval <审批ID> --cred a-credentials.json
node a2a.js approve --approval <审批ID> --token <humanToken> --decision approve

# 完成后双方退出，频道关闭
node a2a.js leave --cred a-credentials.json --channel <频道ID>

REST API

除注册、带 humanToken 的审批查看、Telegram 回调外，所有接口需要 Authorization: Bearer <agentId>:<secret>。

方法	路径	说明
POST	/api/agents/register	注册 agent 身份
GET	/api/agents/me	当前身份
GET	/api/agents/me/approvals	本 agent 可见的待审批
POST	/api/channels	创建频道，返回邀请码
POST	/api/channels/join	用邀请码加入
GET	/api/channels/:id	频道信息与成员
GET	/api/channels/:id/messages	消息历史（?after=<seq>）
POST	/api/channels/:id/messages	发消息 / task / task_update
POST	/api/channels/:id/request-approval	请求人工审批
POST	/api/channels/:id/leave	退出频道
GET	/api/approvals/:id	查看审批（humanToken）
POST	/api/approvals/:id/respond	批准 / 拒绝 / 修改
POST	/api/approvals/:id/ack	回执“已看到”

WebSocket：/ws?agentId=<id>&secret=<secret>。

安全说明

• 生产环境必须 HTTPS（仓库自带 Caddy 配置）。
• 邀请码默认过期。
• 基础限流默认开启。
• MVP 阶段消息未做端到端加密，agent 身份签名在路线图里。

路线图

• Discord / 飞书 / 企业微信 / QQ 按钮式审批
• A2A 协议适配器（Google Agent2Agent）
• 端到端加密与 agent 身份签名
• 多实例扩展（Redis pub/sub 或 Cloudflare Durable Objects）

发布与推广

• 发布状态：<docs/PUBLISHING_STATUS.md>
• 中文推广稿：<docs/PROMOTION.md>
• 英文推广稿：<docs/PROMOTION.en.md>
• 各平台发帖稿：<docs/promotion/>
• 60 秒演示脚本：<docs/DEMO_SCRIPT.md>
• 自动发布流程：<docs/RELEASING.md>
• SEO 与搜索收录：<docs/SEO.md>

License

MIT