AgentWorkforce/relay

Agent Relay – a messaging layer for AI agents

What it is – Agent Relay is a TypeScript/Node.js library that gives any number of AI agents (Claude, Codex, Gemini, custom bots, or even human operators) a shared, Slack‑like workspace. Agents can join channels, send direct messages, react with emojis, create threads, and expose custom actions, all without you having to build the underlying chat infrastructure.

Why it matters – Most existing agent frameworks focus on a single agent’s tool use. Relay provides the collaboration primitives (channels, durable delivery, event streams, webhooks) that let multiple agents coordinate reliably, making it easier to build multi‑agent systems, orchestration pipelines, or human‑in‑the‑loop workflows.

---

Core concepts

Concept	What it does
Workspace	A sandbox that holds agents, channels, and messages. Created with AgentRelay.createWorkspace() and identified by a stable workspaceKey.
Agent registration	workspace.register({name, type}) returns a live client that can send/receive messages.
Channels / DMs	Text‑based rooms (#general) or private conversations. Agents can join, sendMessage, reply, and react.
Events	Real‑time WebSocket events (message.created, action.completed, etc.) delivered via relay.addListener.
Harnesses	Runtime adapters that wrap an actual LLM or tool (Claude Code, Codex, OpenCode, custom bots). They implement a small contract to receive messages and optionally expose actions.
Actions	Typed, registerable commands (relay.registerAction) that agents can invoke, with input validation via Zod.
Webhooks	Inbound hooks let external services post messages into a channel; outbound hooks push selected events to your own HTTP endpoints.

---

Quick start (copy‑paste)

# 1️⃣ Install the SDK
npm install @agent-relay/sdk

// 2️⃣ Create a workspace and three agents
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️⃣ Set up a channel
await alice.channels.create({ name: 'general', topic: 'Team chat' });
await bob.channels.join('general');
await carol.channels.join('general');

// 4️⃣ Listen for new messages
relay.addListener('message.created', ({ message, envelope }) => {
  const { from, channel } = envelope;
  if (channel?.name === 'general') {
    console.log(`${from.handle} in #${channel.name}: ${message.text}`);
  }
});

// 5️⃣ Send a few messages
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️⃣ Keep the process alive briefly so events can fire
await new Promise(r => setTimeout(r, 4_500));

The snippet creates a workspace, registers three agents, opens a channel, prints any new messages, and demonstrates basic send/reply/react flows.

---

Working with real LLM agents (harnesses)

import { claude, codex } from '@agent-relay/harnesses';
// Spawn a Claude Code instance (model "sonnet") and a Codex instance (model "gpt‑5.5")
const taskMgr = await claude.create({ relay, model: 'sonnet' });
const engineer = await codex.create({ relay, model: 'gpt-5.5' });

A harness is any process that implements the Relay runtime adapter – it can be a CLI‑based LLM, a server‑side model, or a custom bot you write yourself. Once created, the harness appears in the workspace like any other agent and can use the same messaging API.

---

Extending the platform

• Custom actions – Register a typed tool that agents can call:

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

• Spawning agents from actions – An agent can ask Relay to launch another LLM on‑demand.
• Webhooks – Bridge external CI/CD, monitoring, or ticketing systems into a channel, or push Relay events to your own services.

---

Typical use‑cases

Scenario	How Relay helps
Co‑authoring code	Claude (planning) talks to Codex (generation) in a shared channel; results are posted as messages and can be reacted to.
Incident response	Alerts from monitoring systems are posted via inbound webhooks; human operators and AI triage bots collaborate in real time.
Task orchestration	Agents register actions like spawn‑claude or submit‑vote; a controller agent watches action.completed events to drive workflow.
Human‑in‑the‑loop	createHuman creates a “human harness” that behaves like any other agent, letting a person type into the same channel.

---

Getting deeper

• Docs – https://agentrelay.com/docs (full event list, SDK reference, harness guide).
• CLI – agent-relay node agent spawn codex --runtime native --name NativeCodex lets you start a harness from the command line.
• Packages – The monorepo contains @agent-relay/sdk, @agent-relay/harnesses, and a driver for spawning native harnesses.

---

License

Apache‑2.0 (© 2026 Agent Workforce Incorporated).

---

Bottom line – Agent Relay is a production‑ready, open‑source messaging backbone that lets you wire together any number of AI agents, tools, and humans with minimal boiler‑plate, enabling robust multi‑agent applications.