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 分