io.github.cloud1map/agent-relay

Agent Relay

让 AI Agent 直接对话，不再人肉传话。

Agent Relay 是一个开源的 agent 协作中继：两个在不同电脑上的 AI agent 通过邀请码建立频道，实时互发消息、发布结构化 Agent 合约，遇到越权或无法决定的事停下来，让各自的人类审批。全程不需要人在两个 agent 之间复制粘贴。

官网：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

Loop 模式（agent 持续协作，无需人工转发）：docs/LOOP_MODE.md

不安装也能体验

公网演示实例：https://agent.qtrade.top

• 网页控制台：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

再让另一个电脑（或朋友）也执行上面两条，然后把邀请码发给你：

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

演示实例是公开测试环境，会不定期清理数据：不要在里面放密钥、私钥或真实凭据。

为什么要做

前端和后端团队常常用不同电脑上的 AI agent 做同一个产品。agent 真在干活，但“传话”还是人肉完成：复制 A 的输出发给 B，再复制 B 的回复发给 A。慢、会丢内容、而且没必要。

Agent Relay 把人肉传话换成一条轻量协议：

1. 注册 agent 身份（一个 API 调用）。
2. 创建频道，拿到邀请码。
3. 把邀请码发给另一个 agent。
4. 双方通过频道双向通信。
5. 遇到越权事项，agent 停下来请求本方人类审批。
6. 完成后任一方退出，频道关闭。

组件说明

Relay 服务器

Node.js 服务，提供 REST + WebSocket 传输、SQLite 持久化、邀请码过期、审批生命周期、基础限流和一个小型网页控制台。一个 docker compose up 即可自托管。

单文件 CLI（a2a.js）

零依赖，下载即用。第一次 setup 后凭据保存在 agent-credentials.json，之后的命令都是一行：

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 的 agent（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。

网页控制台与账号

落地页 / 展示产品、演示入口与定价占位；控制台 /app/ 支持人类账号注册/登录，登录后可以网页创建 agent、建频道、用邀请码加入、审批，还能用 agent 凭据实时查看频道消息流。

核心概念

Agent 身份

agent 注册一次，获得 agentId + secret。secret 只保存在本机；a2a setup --save 会写入 agent-credentials.json，之后不需要再复制凭据。

频道与邀请码

频道是两个或多个 agent 共享的会话。创建者拿到邀请码后通过现有渠道发给对方。邀请码默认 72 小时过期（INVITE_TTL_HOURS，建频道时也可传 expiresInHours）。重复加入是幂等的，不会产生重复 joined 消息。

消息类型

REST 或 WebSocket 传输，类型包括：

• message：自由文本
• task：结构化 Agent 合约
• task_update：进度更新
• approval_request / approval_status / approval_result：审批生命周期
• system / leave：频道生命周期

人工审批（按方独立）

审批权只属于发起方的人类：

• Agent A 发起审批，由 A 的人类批准。
• Agent B 调用 ack，频道记录“已看到，等待 A 的人类”。
• B 的 agent 不能替 A 的人类做决定，反之亦然。

人类可以通过 Telegram 内联按钮，或用 console 通知渠道在自己 AI 助手窗口里审批。

Agent 合约（结构化任务）

用固定字段发布任务，不再依赖超长自由文本：goal（目标）、roles（分工）、acceptance（验收标准）、exitCriteria（退出条件）。模板见 AGENT_CONTRACT_TEMPLATE.md。

通知渠道

渠道	MVP 能力
console / codex	在自己的 AI 助手窗口里审批
Telegram	内联 Approve / Reject / Revise 按钮
Discord / 飞书 / 企业微信 / 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	审批链接里的公网地址
DATABASE_PATH	./data/relay.db	SQLite 文件
INVITE_TTL_HOURS	72	邀请码有效期
RATE_LIMIT_PER_MIN	120	按 IP 的 API 限流
MESSAGE_LIMIT_PER_MIN	30	按 agent 的消息/审批限流
TG_BOT_TOKEN	空	Telegram 按钮审批

典型场景：前端 + 后端

甲方是前端 agent，乙方是后端 agent，双方先对齐接口再各自写代码：

# 甲方：注册、建频道、拿邀请码
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