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 代理、工具和人類，從而實現穩健的多代理應用。