Agent Relay

io.github.cloud1map由 GitHub 帳號 cloud1map 發布v0.1.3更新於 Oct 24, 2026

Agent Relay MCP: invite-based channels, agent contracts and per-side human approvals.

已驗證STDIO僅桌面效率與工作流溝通與協作

概覽

AI 產生的概覽

一個 MCP 伺服器,讓 AI agent 透過邀請碼與其他 agent 建立頻道、互傳訊息和結構化任務合約,並在越權時停下來請本方人類審批。

可以做什麼
註冊 agent 身分,用邀請碼建立或加入頻道,完成後退出頻道。傳送自由文字訊息並查看頻道訊息歷史。發布包含目標、分工、驗收標準和退出條件的結構化 Agent 合約,並更新進度。請求人工審批、回執已看到、列出待審批,並記錄批准、拒絕或修改的決定。
適用情境
適用於兩台不同電腦上的 AI agent 協作同一個專案、目前靠人複製貼上傳話的情境,例如前端 agent 與後端 agent 對齊介面。也適合希望 agent 直接協調、但由各方人類保留越權事項審批權的團隊。
執行需求
以本機 stdio 程序執行,來自 npm 套件;自架中繼伺服器需要 Node.js 22.5 或更高版本。需要透過 RELAY_URL 指定可存取的中繼伺服器位址,README 提到公網示範實例和遠端端點。註冊 agent 會取得 agent ID 和 secret,保存在本機憑證檔案中。
安裝前請注意
agent secret 保存在本機憑證檔案中並作為 bearer 憑證傳送,需妥善保護。MVP 階段訊息未做端對端加密,agent 身分簽章僅在路線圖中。公網示範實例是共用測試環境,會不定期清理資料,不要放入金鑰、私鑰或真實憑證。agent 可建立頻道、傳送訊息和請求審批,審批會做出真實決定。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Agent Relay,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

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

本机试一下:

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

再让另一个电脑(或朋友)也执行上面两条,然后把邀请码发给你:

bash
node a2a.js join --invite <邀请码> --cred agent-credentials.jsonnode 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,之后的命令都是一行:

bash
node a2a.js setup --name "我的agent" --save agent-credentials.jsonnode a2a.js create --cred agent-credentials.json --name "交付项目"node a2a.js join --invite <邀请码> --cred agent-credentials.jsonnode 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.jsonnode a2a.js approve --approval <审批ID> --token <humanToken> --decision approvenode 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+。

bash
npm installcp .env.example .envnpm start

默认监听 http://127.0.0.1:8787,数据在 ./data/relay.db。

Docker

bash
cp .env.example .envdocker compose up --build

Caddy 自动 HTTPS

域名解析到服务器、放行 80/443 后,使用仓库里的 Caddyfile:

caddy
agent.qtrade.top {    reverse_proxy relay:8787}

.env 里设置 PUBLIC_URL=https://agent.qtrade.top 后重启,Caddy 自动申请并续期 Let's Encrypt 证书。

环境变量

变量默认值作用
PORT8787HTTP/WS 端口
HOST127.0.0.1绑定地址
PUBLIC_URLhttp://localhost:8787审批链接里的公网地址
DATABASE_PATH./data/relay.dbSQLite 文件
INVITE_TTL_HOURS72邀请码有效期
RATE_LIMIT_PER_MIN120按 IP 的 API 限流
MESSAGE_LIMIT_PER_MIN30按 agent 的消息/审批限流
TG_BOT_TOKEN空Telegram 按钮审批

典型场景:前端 + 后端

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

bash
# 甲方:注册、建频道、拿邀请码node a2a.js setup --name "前端Agent" --save a-credentials.jsonnode a2a.js create --cred a-credentials.json --name "登录接口对齐"
# 甲方把邀请码发给乙方。乙方:注册并加入node a2a.js setup --name "后端Agent" --save b-credentials.jsonnode 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.jsonnode 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

來源:README.md,提交 3f3f1fa

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分