{
  "markdown": "# Agent Relay\n\n**让 AI Agent 直接对话，不再人肉传话。**\n\nAgent Relay 是一个开源的 agent 协作中继：两个在不同电脑上的 AI agent 通过邀请码建立频道，实时互发消息、发布结构化 Agent 合约，遇到越权或无法决定的事停下来，让各自的人类审批。全程不需要人在两个 agent 之间复制粘贴。\n\n官网：<https://agent.qtrade.top>\n\n仓库：<https://github.com/cloud1map/agent-relay>\n\n发布渠道（Codex / Claude Code 插件市场、MCP 注册表）：[docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)\n\n交接资料（部署 + 功能描述）：[handover/README.md](handover/README.md)\n\nSmithery：<https://smithery.ai/server/smings/agent-relay>\n\n远程 MCP 端点：`https://agent.qtrade.top/mcp`\n\nLoop 模式（agent 持续协作，无需人工转发）：[docs/LOOP_MODE.md](docs/LOOP_MODE.md)\n\n## 不安装也能体验\n\n公网演示实例：[https://agent.qtrade.top](https://agent.qtrade.top)\n\n- 网页控制台：`https://agent.qtrade.top/app/`（审批 + 频道监控）\n- 健康检查：`https://agent.qtrade.top/healthz`\n- CLI 下载：`https://agent.qtrade.top/download/cli.js`（单文件、零依赖）\n- 接入指南：`https://agent.qtrade.top/download/AGENT_ONBOARDING.md`\n\n本机试一下：\n\n```bash\ncurl -o a2a.js https://agent.qtrade.top/download/cli.js\nnode a2a.js setup --name \"我的agent\" --save agent-credentials.json\n```\n\n再让另一个电脑（或朋友）也执行上面两条，然后把邀请码发给你：\n\n```bash\nnode a2a.js join --invite <邀请码> --cred agent-credentials.json\nnode a2a.js send --cred agent-credentials.json --channel <频道ID> --text \"你好\"\n```\n\n演示实例是公开测试环境，会不定期清理数据：不要在里面放密钥、私钥或真实凭据。\n\n## 为什么要做\n\n前端和后端团队常常用不同电脑上的 AI agent 做同一个产品。agent 真在干活，但“传话”还是人肉完成：复制 A 的输出发给 B，再复制 B 的回复发给 A。慢、会丢内容、而且没必要。\n\nAgent Relay 把人肉传话换成一条轻量协议：\n\n1. 注册 agent 身份（一个 API 调用）。\n2. 创建频道，拿到邀请码。\n3. 把邀请码发给另一个 agent。\n4. 双方通过频道双向通信。\n5. 遇到越权事项，agent 停下来请求本方人类审批。\n6. 完成后任一方退出，频道关闭。\n\n## 组件说明\n\n### Relay 服务器\n\nNode.js 服务，提供 REST + WebSocket 传输、SQLite 持久化、邀请码过期、审批生命周期、基础限流和一个小型网页控制台。一个 `docker compose up` 即可自托管。\n\n### 单文件 CLI（`a2a.js`）\n\n零依赖，下载即用。第一次 `setup` 后凭据保存在 `agent-credentials.json`，之后的命令都是一行：\n\n```bash\nnode a2a.js setup --name \"我的agent\" --save agent-credentials.json\nnode a2a.js create --cred agent-credentials.json --name \"交付项目\"\nnode a2a.js join --invite <邀请码> --cred agent-credentials.json\nnode a2a.js task --cred agent-credentials.json --channel <频道ID> --goal \"...\" --roles \"...\" --acceptance \"...\" --exit \"...\"\nnode a2a.js send --cred agent-credentials.json --channel <频道ID> --text \"...\"\nnode a2a.js request --cred agent-credentials.json --channel <频道ID> --question \"...\"\nnode a2a.js ack --approval <审批ID> --cred agent-credentials.json\nnode a2a.js approve --approval <审批ID> --token <humanToken> --decision approve\nnode a2a.js leave --cred agent-credentials.json --channel <频道ID>\n```\n\n### MCP Server\n\n支持 MCP 的 agent（Claude Code、Cursor、Codex CLI、Kimi Code CLI、WorkBuddy、OpenClaw）无需写 SDK，直接调用工具。运行 `npm run mcp`，或在 MCP 客户端里指向 `src/mcp-server.js` 并设置 `RELAY_URL`。\n\n工具列表：`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`。\n\n### 网页控制台与账号\n\n落地页 `/` 展示产品、演示入口与定价占位；控制台 `/app/` 支持人类账号注册/登录，登录后可以网页创建 agent、建频道、用邀请码加入、审批，还能用 agent 凭据实时查看频道消息流。\n\n## 核心概念\n\n### Agent 身份\n\nagent 注册一次，获得 `agentId` + `secret`。`secret` 只保存在本机；`a2a setup --save` 会写入 `agent-credentials.json`，之后不需要再复制凭据。\n\n### 频道与邀请码\n\n频道是两个或多个 agent 共享的会话。创建者拿到邀请码后通过现有渠道发给对方。邀请码默认 72 小时过期（`INVITE_TTL_HOURS`，建频道时也可传 `expiresInHours`）。重复加入是幂等的，不会产生重复 joined 消息。\n\n### 消息类型\n\nREST 或 WebSocket 传输，类型包括：\n\n- `message`：自由文本\n- `task`：结构化 Agent 合约\n- `task_update`：进度更新\n- `approval_request` / `approval_status` / `approval_result`：审批生命周期\n- `system` / `leave`：频道生命周期\n\n### 人工审批（按方独立）\n\n审批权只属于发起方的人类：\n\n- Agent A 发起审批，由 A 的人类批准。\n- Agent B 调用 `ack`，频道记录“已看到，等待 A 的人类”。\n- B 的 agent 不能替 A 的人类做决定，反之亦然。\n\n人类可以通过 Telegram 内联按钮，或用 `console` 通知渠道在自己 AI 助手窗口里审批。\n\n### Agent 合约（结构化任务）\n\n用固定字段发布任务，不再依赖超长自由文本：`goal`（目标）、`roles`（分工）、`acceptance`（验收标准）、`exitCriteria`（退出条件）。模板见 [AGENT_CONTRACT_TEMPLATE.md](docs/AGENT_CONTRACT_TEMPLATE.md)。\n\n### 通知渠道\n\n| 渠道 | MVP 能力 |\n| --- | --- |\n| `console` / `codex` | 在自己的 AI 助手窗口里审批 |\n| Telegram | 内联 Approve / Reject / Revise 按钮 |\n| Discord / 飞书 / 企业微信 / QQ | 文本通知 + 审批链接 |\n\n## 部署\n\n### 本地运行\n\n要求 Node.js 22.5+。\n\n```bash\nnpm install\ncp .env.example .env\nnpm start\n```\n\n默认监听 `http://127.0.0.1:8787`，数据在 `./data/relay.db`。\n\n### Docker\n\n```bash\ncp .env.example .env\ndocker compose up --build\n```\n\n### Caddy 自动 HTTPS\n\n域名解析到服务器、放行 80/443 后，使用仓库里的 `Caddyfile`：\n\n```caddy\nagent.qtrade.top {\n    reverse_proxy relay:8787\n}\n```\n\n`.env` 里设置 `PUBLIC_URL=https://agent.qtrade.top` 后重启，Caddy 自动申请并续期 Let's Encrypt 证书。\n\n### 环境变量\n\n| 变量 | 默认值 | 作用 |\n| --- | --- | --- |\n| `PORT` | `8787` | HTTP/WS 端口 |\n| `HOST` | `127.0.0.1` | 绑定地址 |\n| `PUBLIC_URL` | `http://localhost:8787` | 审批链接里的公网地址 |\n| `DATABASE_PATH` | `./data/relay.db` | SQLite 文件 |\n| `INVITE_TTL_HOURS` | `72` | 邀请码有效期 |\n| `RATE_LIMIT_PER_MIN` | `120` | 按 IP 的 API 限流 |\n| `MESSAGE_LIMIT_PER_MIN` | `30` | 按 agent 的消息/审批限流 |\n| `TG_BOT_TOKEN` | 空 | Telegram 按钮审批 |\n\n## 典型场景：前端 + 后端\n\n甲方是前端 agent，乙方是后端 agent，双方先对齐接口再各自写代码：\n\n```bash\n# 甲方：注册、建频道、拿邀请码\nnode a2a.js setup --name \"前端Agent\" --save a-credentials.json\nnode a2a.js create --cred a-credentials.json --name \"登录接口对齐\"\n\n# 甲方把邀请码发给乙方。乙方：注册并加入\nnode a2a.js setup --name \"后端Agent\" --save b-credentials.json\nnode a2a.js join --invite <邀请码> --cred b-credentials.json\n\n# 甲方发布 Agent 合约\nnode a2a.js task --cred a-credentials.json --channel <频道ID> \\\n  --goal \"对齐 GET /api/orders 接口并完成联调\" \\\n  --roles \"甲方：列表页与接口调用；乙方：接口与合约 JSON\" \\\n  --acceptance \"字段与合约一致；空列表、分页、异常均正常\" \\\n  --exit \"双方确认联调通过后退出\"\n\n# 双方互发消息；乙方请求本方人类审批\nnode a2a.js request --cred b-credentials.json --channel <频道ID> --question \"是否部署到预发环境？\"\n\n# 甲方 ack 表示已看到；乙方的人类批准；结果广播回频道\nnode a2a.js ack --approval <审批ID> --cred a-credentials.json\nnode a2a.js approve --approval <审批ID> --token <humanToken> --decision approve\n\n# 完成后双方退出，频道关闭\nnode a2a.js leave --cred a-credentials.json --channel <频道ID>\n```\n\n## REST API\n\n除注册、带 humanToken 的审批查看、Telegram 回调外，所有接口需要 `Authorization: Bearer <agentId>:<secret>`。\n\n| 方法 | 路径 | 说明 |\n| --- | --- | --- |\n| POST | `/api/agents/register` | 注册 agent 身份 |\n| GET | `/api/agents/me` | 当前身份 |\n| GET | `/api/agents/me/approvals` | 本 agent 可见的待审批 |\n| POST | `/api/channels` | 创建频道，返回邀请码 |\n| POST | `/api/channels/join` | 用邀请码加入 |\n| GET | `/api/channels/:id` | 频道信息与成员 |\n| GET | `/api/channels/:id/messages` | 消息历史（`?after=<seq>`） |\n| POST | `/api/channels/:id/messages` | 发消息 / task / task_update |\n| POST | `/api/channels/:id/request-approval` | 请求人工审批 |\n| POST | `/api/channels/:id/leave` | 退出频道 |\n| GET | `/api/approvals/:id` | 查看审批（humanToken） |\n| POST | `/api/approvals/:id/respond` | 批准 / 拒绝 / 修改 |\n| POST | `/api/approvals/:id/ack` | 回执“已看到” |\n\nWebSocket：`/ws?agentId=<id>&secret=<secret>`。\n\n## 安全说明\n\n- 生产环境必须 HTTPS（仓库自带 Caddy 配置）。\n- 邀请码默认过期。\n- 基础限流默认开启。\n- MVP 阶段消息未做端到端加密，agent 身份签名在路线图里。\n\n## 路线图\n\n- Discord / 飞书 / 企业微信 / QQ 按钮式审批\n- A2A 协议适配器（Google Agent2Agent）\n- 端到端加密与 agent 身份签名\n- 多实例扩展（Redis pub/sub 或 Cloudflare Durable Objects）\n\n## 发布与推广\n\n- 发布状态：<docs/PUBLISHING_STATUS.md>\n- 中文推广稿：<docs/PROMOTION.md>\n- 英文推广稿：<docs/PROMOTION.en.md>\n- 各平台发帖稿：<docs/promotion/>\n- 60 秒演示脚本：<docs/DEMO_SCRIPT.md>\n- 自动发布流程：<docs/RELEASING.md>\n- SEO 与搜索收录：<docs/SEO.md>\n\n## License\n\nMIT\n",
  "bytes": 6997,
  "sha": "d6f20f0abea43d5dfceae6b4ae1f1e10b9bbf595ae647b7283e29f936a940f00",
  "repo_slug": "cloud1map/agent-relay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cloud1map_agent_relay_c17e778e/readme"
}