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](docs/DISTRIBUTION.md)

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

远程 MCP 端点：`https://agent.qtrade.top/mcp`

## 不安装也能体验

公网演示实例：[https://agent.qtrade.top](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.js
node a2a.js setup --name "我的agent" --save agent-credentials.json
```

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

```bash
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`，之后的命令都是一行：

```bash
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](docs/AGENT_CONTRACT_TEMPLATE.md)。

### 通知渠道

| 渠道 | MVP 能力 |
| --- | --- |
| `console` / `codex` | 在自己的 AI 助手窗口里审批 |
| Telegram | 内联 Approve / Reject / Revise 按钮 |
| Discord / 飞书 / 企业微信 / QQ | 文本通知 + 审批链接 |

## 部署

### 本地运行

要求 Node.js 22.5+。

```bash
npm install
cp .env.example .env
npm start
```

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

### Docker

```bash
cp .env.example .env
docker 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 证书。

### 环境变量

| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `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，双方先对齐接口再各自写代码：

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

## License

MIT