Agent Relay

代理中继

为不总是打开的AI代理提供轻量级消息中继。

问题

谷歌的 A2A协议 假设代理是永久可访问的HTTP服务。但是，许多现实世界的代理——像Claude Code这样的CLI工具、本地LLM运行器、cron触发的工作器、笔记本电脑绑定的助手——只有在终端会话打开或日程表触发时才存在。

Relay特工弥合了这一差距。它为来来往往的代理提供持久的消息队列、代理发现和结构化的任务切换。消息等待。任务跟踪生命周期。接力赛是唯一需要继续进行的比赛。

主要特点

• 线下先排队 --消息会一直持续到目标代理轮询或重新连接为止
• MCP本地 --附带MCP网桥，因此Claude Code代理不需要任何自定义客户端代码
• A2A对齐数据模型 --任务、消息和工件遵循A2A惯例，以备将来迁移
• 信任级别 --代理具有范围权限（可以从谁那里读取、发送给谁、访问什么工具）
• SQLite存储 --没有Postgres，没有Redis，没有Docker Compose。一个文件，碰撞安全WAL模式
• 尾秤友好 --为Tailscale网络上的私有代理网格设计
• 完整的审计追踪 --永久记录每条消息、传递和状态更改

快速开始

1.安装

git clone https://github.com/hazzap123/agent-relay.git
cd agent-relay
python3 -m venv venv && source venv/bin/activate
pip install -e .

2.配置

cp .env.example .env
# Edit .env — set API keys for your agents

3.跑步

uvicorn relay.server:app --host 0.0.0.0 --port 8400

4.注册克劳德代码（MCP）

claude mcp add relay -- python3 /path/to/agent-relay/relay/mcp_bridge.py

为网桥设置环境变量：

RELAY_URL=http://your-relay-host:8400
RELAY_API_KEY=your-agent-api-key
AGENT_ID=claude-code

API

14个REST端点 /api/v1:

MCP工具

MCP桥公开了10个Claude Code代理可以本机调用的工具：

• relay_inbox --检查待处理邮件
• relay_send_task --将任务委托给另一个代理
• relay_update_task --更新任务状态（已接受、正在工作、已完成等）
• relay_send_message --发送自由格式的消息
• relay_get_task --获取任务详细信息
• relay_list_tasks --使用筛选器查询任务
• relay_agents --列出注册代理人及其身份
• relay_broadcast --向所有代理发送消息
• relay_attach_artifact --将输出附加到任务
• relay_heartbeat --更新您的在线/离线状态

代理配置

复制 agents.example.json 并定义您的代理：

[
  {
    "agent_id": "claude-code",
    "name": "Claude Code",
    "capabilities": ["code", "analysis", "memory"],
    "trust_tier": 1,
    "contact": { "method": "poll" }
  },
  {
    "agent_id": "assistant",
    "name": "Assistant",
    "capabilities": ["email", "scheduling"],
    "trust_tier": 2,
    "contact": { "method": "webhook", "webhook_url": "http://..." }
  }
]

信任层控制权限：

• 第1级 --完全访问，可以读取和发送给所有代理
• 第2层 --范围访问，受限的读取/发送权限
• 第3层 --最低访问权限，高度沙盒化

部署

包括systemd服务文件和部署脚本：

DEPLOY_HOST=root@your-server RELAY_HOST=your-server-ip bash deploy.sh

看 agent-relay.service 对于systemd单元。

测试

python -m pytest tests/ -v

A2A对齐

Agent Relay借用了A2A的数据模型和生命周期状态，但没有实现完整的A2A JSON-RPC 2.0规范。这是故意的——A2A假设始终在线的HTTP服务，这与CLI代理或间歇性工作者不匹配。

数据模型的设计使得迁移到完全符合A2A是累加的，而不是重写。

建筑

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Agent A    │     │   Agent B    │     │   Agent C    │
│  (CLI tool)  │     │  (daemon)    │     │  (CLI tool)  │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │ MCP                │ HTTP/poll          │ MCP
       │                    │                    │
       ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────┐
│                     Agent Relay                         │
│  FastAPI · SQLite · Bearer auth · Trust tiers           │
│  Tailscale network — private, zero-config               │
└─────────────────────────────────────────────────────────┘

安全说明

• 无TLS --服务器绑定纯HTTP。专为在Tailscale（提供加密）或反向代理后面使用而设计。在没有TLS终止的情况下，不要直接暴露在互联网上。
• 无速率限制 --行为不端的特工可能会淹没接力赛。考虑添加 slowapi 或用于生产用途的反向代理速率限制器。
• SQLite并发 --在大量并发写入下，您可能会看到“数据库已锁定”错误。添加 PRAGMA busy_timeout=5000 如果发生这种情况。对于高吞吐量部署，请考虑PostgreSQL。
• Systemd以root身份运行 --包含的服务文件默认为 User=root为生产创建一个专门的服务用户(useradd -r -s /bin/false relay).

许可证

Apache 2.0——请参阅 许可证.