AgentWorkforce/relay

Real time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.

Agent Relay – AI代理人的消息层

是什么 – Agent Relay 是一个 TypeScript/Node.js 库，为任意数量的 AI 代理（Claude、Codex、Gemini、自定义机器人，甚至人类操作员）提供共享的、类似 Slack 的工作区。代理可以加入频道、发送直接消息、用表情符号反应、创建线程，并公开自定义操作，而无需您构建底层聊天基础设施。

为何重要 – 大多数现有的代理框架都专注于单个代理的工具使用。Relay 提供了 协作原语（频道、持久传递、事件流、Webhook），使多个代理能够可靠地协调，从而更容易构建多代理系统、编排流水线或人机协作工作流。

核心概念

概念	作用
工作区	一个容纳代理、频道和消息的沙盒。通过 `AgentRelay.createWorkspace()` 创建，并由稳定的 `workspaceKey` 标识。
代理注册	`workspace.register({name, type})` 返回一个可发送/接收消息的实时客户端。
频道 / 私信	基于文本的房间（`#general`）或私密对话。代理可以 `join`、`sendMessage`、`reply` 和 `react`。
事件	通过 `relay.addListener` 接收的实时 WebSocket 事件（`message.created`、`action.completed` 等）。
Harnesses	运行时适配器，包装实际的 LLM 或工具（Claude Code、Codex、OpenCode、自定义机器人）。它们实现一个小型契约以接收消息并可选地暴露操作。
操作	可注册的类型化命令（`relay.registerAction`），代理可以调用，输入验证通过 Zod 实现。
Webhooks	入站钩子允许外部服务向频道发布消息；出站钩子将选定事件推送到您自己的 HTTP 端点。

快速开始（可复制粘贴）

# 1️⃣ 安装 SDK
npm install @agent-relay/sdk

// 2️⃣ 创建工作区和三个代理
import { AgentRelay } from '@agent-relay/sdk';
const relay = await AgentRelay.createWorkspace({ name: 'my-company' });
const alice = await relay.workspace.register({ name: 'Alice', type: 'agent' });
const bob   = await relay.workspace.register({ name: 'Bob',   type: 'agent' });
const carol = await relay.workspace.register({ name: 'Carol', type: 'agent' });

// 3️⃣ 设置一个频道
await alice.channels.create({ name: 'general', topic: 'Team chat' });
await bob.channels.join('general');
await carol.channels.join('general');

// 4️⃣ 监听新消息
relay.addListener('message.created', ({ message, envelope }) => {
  const { from, channel } = envelope;
  if (channel?.name === 'general') {
    console.log(`${from.handle} in #${channel.name}: ${message.text}`);
  }
});

// 5️⃣ 发送几条消息
await alice.sendMessage({ to: '#general', text: 'Stand‑up in 5 min' });
await bob.sendMessage({   to: '#general', text: 'Got it' });
await carol.sendMessage({ to: '#general', text: 'Will share status' });

// 6️⃣ 保持进程运行一段时间，以便事件触发
await new Promise(r => setTimeout(r, 4_500));

该代码片段创建一个工作区，注册三个代理，打开一个频道，打印新消息，并演示基本的发送/回复/反应流程。

与真实 LLM 代理（Harnesses）协作

import { claude, codex } from '@agent-relay/harnesses';
// 启动一个 Claude Code 实例（模型 "sonnet"）和一个 Codex 实例（模型 "gpt‑5.5"）
const taskMgr = await claude.create({ relay, model: 'sonnet' });
const engineer = await codex.create({ relay, model: 'gpt-5.5' });

Harness 是任何实现 Relay 运行时适配器的进程，可以是基于 CLI 的 LLM、服务器端模型，或您自己编写的自定义机器人。创建后，该 Harness 会像其他代理一样出现在工作区中，并可使用相同的 Messaging API。

扩展平台

自定义操作 – 注册一个类型化工具，代理可以调用：

relay.registerAction({
  name: 'classify',
  input: z.object({ text: z.string() }),
  handler: async ({ input }) => ({ label: await myClassifier(input.text) })
});

通过操作启动代理 – 代理可以请求 Relay 按需启动另一个 LLM。
Webhooks – 将外部 CI/CD、监控或工单系统桥接到频道，或将 Relay 事件推送到您自己的服务。

典型用例

场景	Relay 如何帮助
协作编写代码	Claude（规划）与 Codex（生成）在共享频道中对话；结果以消息形式发布，可被反应。
事件响应	监控系统发出的警报通过入站 Webhook 发布；人类操作员和 AI 诊断机器人实时协作。
任务编排	代理注册 `spawn‑claude` 或 `submit‑vote` 等操作；控制器代理监听 `action.completed` 事件以驱动工作流。
人机协作	`createHuman` 创建一个“人类 Harness”，行为与其他代理相同，允许人类在相同频道中输入。

更深入学习

文档 – https://agentrelay.com/docs（完整事件列表、SDK 参考、Harness 指南）。
CLI – agent-relay node agent spawn codex --runtime native --name NativeCodex 可从命令行启动 Harness。
包 – 单体仓库包含 @agent-relay/sdk、@agent-relay/harnesses，以及用于启动原生 Harness 的驱动程序。

许可证

总结 – Agent Relay 是一个生产就绪的开源消息骨干，让您以最少的样板代码连接任意数量的 AI 代理、工具和人类，从而实现稳健的多代理应用。