Agent Relay: A Messaging Layer for Agents That Need to Wake on a Message

The Problem Relay Solves Is Message Delivery, Not Orchestration

Multi-agent setups tend to start with a shared file or a database table and end with a hand-written webhook fan-out. Each new agent adds another adapter, another retry path, and another place where a message silently disappears. Relay's answer is to make that plumbing a product: shared channels, threads, direct messages, reactions, files, search, and realtime events, exposed through one SDK. The README frames the pitch plainly, as letting Claude Code message Codex, or a Hyperagent talk to a Hermes agent.

The target user is an engineer who already has agents running and now needs them to address each other by handle rather than by hard-coded endpoint. That is a narrower audience than the word orchestration suggests. Relay handles who said what to whom and who is listening. It does not appear to decide what should happen next, which is the part most people mean when they say orchestration.

Workspaces, Registered Agents and a Single Event Stream

The data model is visible in the quickstart. AgentRelay.createWorkspace({ name: 'my-company' }) returns an object carrying a workspaceKey, and that key is the reconnect credential; the README shows persisting it and passing it back as new AgentRelay({ workspaceKey: relay.workspaceKey }). Inside a workspace, register({ name, type }) returns a live agent client, and that client is what you call methods on. Channels are created by one agent and joined by others: alice.channels.create({ name: 'general', topic: 'Team chat' }) followed by bob.channels.join('general').

Delivery is event-driven rather than request-response. relay.addListener('message.created', handler) receives one discriminated event object containing a message and an envelope, and the envelope carries from and channel, so the handler can read envelope.from.handle and envelope.channel.name. A wildcard listener, relay.addListener('*', ...), receives everything. Sending is addressed by string: to: '#general' for a channel, and messageId is returned so the sender can later call reply({ messageId, text }) or react({ messageId, emoji }). The reaction example uses the colon form, ':thumbsup:'. That is the whole loop: register, join, listen, send, reply, react.

Installing the SDK and Bringing Up an Agent from the CLI

Relay requires Node.js 22 or newer, and the SDK installs as npm install @agent-relay/sdk. The quickstart file imports AgentRelay from that package. Harnesses live in a separate package, @agent-relay/harnesses, which exports claude and codex; calling claude.create({ relay, model: 'sonnet' }) starts the agent in a CLI and joins it to the relay using the workspace key. The README notes that harnesses can run anywhere with internet access, and do not need to be on the same machine as the relay client.

There is also a local CLI with the same runtime selector. agent-relay node agent spawn codex --runtime native --name NativeCodex starts an agent, agent-relay node agent new claude --runtime native --name NativeClaude creates one, and agent-relay node agent attach NativeCodex --mode view --json attaches to it. The default is --runtime auto, which keeps dual-runtime harnesses on PTY while their native adapters are experimental. Pi and Deep Agents require an explicit --runtime native. Native attach supports view and line-oriented drive but not terminal passthrough, which is a real constraint if your tooling expects a raw terminal stream.

The Harness Contract Is the Interesting Part

A harness is any runtime boundary that implements the runtime adapter: a CLI agent, an OpenCode server, an OpenClaw or Hermes agent, a browser app, or your own hosted process. defineHarness({ name, create }) is the extension point, and create returns an object with identity, capabilities and receiveMessage. The README states the minimum contract is to receive a message and report what happened, returning something like { status: 'delivered', deliveryId: identity.id }. The full contract additionally declares lifecycle, delivery modes, observable events and optional actions.

The design note that matters most is that Relay does not need to own the process. CLI harnesses typically use injection and hooks to receive and MCP to send, but nothing forces that. This is the difference between Relay and a framework that spawns and supervises your agents. It also means delivery quality depends entirely on the harness: if your receiveMessage implementation drops a message, Relay has no way to know. The status field is the harness reporting on itself, not a platform-level acknowledgement.

Runtime Selection and the Experimental Edges

The README is unusually candid about maturity, and that candour is worth taking at face value. Claude Code, Codex and OpenCode retain PTY as their automatic runtime while their official AI SDK adapters are experimental. Pi and Deep Agents are described as experimental native-only harnesses. Native sessions expose structured attach output plus portable activity, capability, source and fidelity metadata through Relaycast, which is a name that appears once and is not explained further in the supplied material.

So the practical split is this: PTY is the conservative path and remains the default for the harnesses most people will use, while native gives you structured output at the cost of depending on an adapter the project itself labels experimental. If you are choosing a runtime for production, start on auto or pty and move a single agent to native to see whether the structured attach output is worth it. The absence of a documented stability table beyond these prose notes is a gap; you will be reading release notes rather than a compatibility matrix.

What Relay Does Not Do

Nothing in the README describes durable delivery guarantees, retry policy, ordering, or backpressure. Listeners fire and handlers run; if your process is not alive when a message arrives, the material does not say what happens. There is no mention of a scheduler, a task graph, or state that survives a restart beyond the workspaceKey, which is a credential rather than a checkpoint. Teams that need exactly-once handoff between agents will have to build that on top, and the SDK gives them no obvious hook for it.

There is a second, quieter limitation. Relay assumes every participant can reach the network and can receive a message. A harness that only runs as a batch job, or that sits behind a firewall with no inbound path, cannot be woken. The README is explicit that harnesses need internet access, so an air-gapped or strictly pull-based agent is out of scope. That is a design boundary, not a bug, but it rules out a class of deployments that people often assume a messaging layer will cover.

How This Compares to a Plain Message Broker

The obvious alternative is a general-purpose broker such as NATS or Redis Pub/Sub, or simply a shared database table that agents poll. Those give you transport and nothing else: you define subjects or tables, you write the presence model, you invent threads and reactions, and you build the client library for each agent framework yourself. Relay's difference is that the conversation semantics are the product. Threads, DMs, channel membership and reactions are API calls rather than schema decisions, and the event envelope already carries the sender handle and channel name so handlers do not have to join tables to render a line of text.

The trade is control. A broker lets you choose delivery semantics, retention and topology; Relay presents one model and one hosted endpoint at agentrelay.com. If your requirements are unusual, for example strict ordering per agent pair with replay from an offset, a broker will fit better because you can define the semantics. If your requirement is that five heterogeneous agents can talk this afternoon without you writing an adapter matrix, Relay is the shorter path. The two are not mutually exclusive, but stacking Relay on top of a broker means operating both.

Licence, Upgrade Cadence and What to Check First

Relay is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notices intact and understand the patent grant and termination terms in that licence. That is a permissive starting point, but it is not legal advice; if you are embedding the SDK in a shipped product, have counsel read the actual LICENSE file rather than a summary.

The release cadence is fast. Three releases landed between 2026-09-08 and 2026-09-10, including a major version bump to v12.0.0. A project moving that quickly will occasionally break APIs, and the README's own labelling of several harnesses as experimental suggests the surface is still settling. Pin your @agent-relay/sdk version, read the release notes before a major bump, and expect the harness packages to move independently of the SDK. If you need a compatibility matrix before upgrading, you will not find one in the README; you will be diffing changelogs.

Editorial conclusion

Adopt Relay if you have several agents from different vendors and you are currently gluing them together with a queue and a bespoke webhook table; the SDK replaces that with channels, threads and a single event stream. Do not adopt it if you need durable workflow state, retries or task graphs, because nothing in the README describes a scheduler or a persistence guarantee for in-flight work. Before committing, verify the event list at agentrelay.com/docs/events, confirm which harnesses you need are stable rather than experimental, and check whether your agents can be reached over the network at all, since a harness must be able to receive a message for Relay to be useful.

Official sources

1. AgentWorkforce/relay on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases