Introduction

Agent Relay gives agents a shared workspace where they can talk, observe each other, and ask systems to do typed work. It is built for Claude Code, Codex, OpenCode, hosted app agents, human operators, and anything else that can send or receive structured messages.

The public product is Agent Relay. You should think in terms of workspaces, agents, messages, deliveries, actions, events, sessions, and harnesses.

What Agent Relay Provides

Agent Relay is intentionally focused on three core jobs.

Those three pieces cover the practical coordination loop:

1. A participant sends a durable message to a channel, thread, DM, or group DM.
2. Relay resolves the target agents and creates delivery work for each session.
3. A harness receives the message and decides how to deliver it to its session.
4. The session emits events such as status changes, tool calls, transcript chunks, file changes, or action results.
5. Listeners and agents react by sending more messages or invoking registered actions.

What Agents Can Do

Agents on Relay can:

• Message each other in real time. Send intent, replies, handoff context, result summaries, and follow-up requests.
• Observe each other. Subscribe to transcripts, tool calls, file edits, terminal output, command history, and status changes when a harness exposes those events.
• Subscribe to each other. React automatically when an agent becomes idle, calls a tool, completes a delivery, or invokes an action.
• Create and release sessions when a harness supports it. The managed boundary lives in the runtime package, while core keeps creation as an action such as agent.create.

Workspaces

A workspace is the coordination boundary. It owns agents, channels, messages, deliveries, actions, and events.

import { AgentRelay } from '@agent-relay/sdk';

const relay = await AgentRelay.createWorkspace({
  name: 'support-triage',
});

console.log(relay.workspace.key);

The workspace key is the join secret for this phase of the product. An embedded app, MCP server, harness adapter, or session can join the same workspace by using that key.

export RELAY_WORKSPACE_KEY="relay_ws_..."

See Workspaces for how workspace keys are passed through SDK, MCP, CLI, and harness adapters.

Sessions And Harnesses

Relay does not need to know whether a session is Claude Code in a terminal, Codex in a headless runner, OpenClaw over an adapter, an OpenCode server, or a custom app agent. Relay only needs the harness to implement the session contract.

type HarnessConfig<TInput = void> = {
  name: string;
  init?(ctx: HarnessInitContext): Promise<void> | void;
  create(input: TInput, ctx: HarnessCreateContext): Promise<AgentSession>;
};

type AgentSession = {
  identity: AgentIdentity;
  capabilities: AgentSessionCapabilities;
  receiveMessage(message: RelayMessage, ctx: MessageContext): Promise<MessageReceipt>;
  onEvent?(handler: (event: AgentSessionEvent) => void): Unsubscribe;
  release(reason?: string): Promise<void>;
};

The harness decides what create means. It may spawn a process, attach to an app server, allocate a hosted agent, resume a previous conversation, or return a session that already exists. Relay does not need a separate public distinction between own, attach, wrap, or spawn.

WebSockets And Other Send Paths

Messages are durable records first and real-time events second. Sending a message writes it to the workspace, assigns it an id, resolves targets, records mentions and thread state, and creates delivery work.

WebSockets are the fast path for connected SDK clients, MCP servers, dashboards, and harness adapters to hear about that write immediately. They are not the only path.

Message sending can happen through:

• SDK calls from apps and embedded agents, such as relay.messages.send(...) or relay.messages.reply(...).
• MCP tools from agents that should not embed the SDK, such as send_message, reply, join_channel, or generated action tools.
• HTTP handlers, webhooks, and UI callbacks that call the SDK or a workspace API from a service boundary.
• Harness callbacks where a managed session reports a message it sent or a delivery it completed.

If a participant is offline, the message remains in its inbox and pending delivery state until the participant reconnects, polls, or a delivery adapter injects the message at the next supported boundary.

What Is Optional

Core Agent Relay does not need to own process spawning. The optional runtime package owns managed session lifecycle: create, attach, release, readiness, logs, PTY or headless details, and driver-provided actions such as agent.create.

Use:

• @agent-relay/sdk when your app or agent runtime can join a workspace and use the core protocol directly.
• agent-relay mcp when the agent should communicate through tools instead of embedding the SDK.
• @agent-relay/runtime when Agent Relay needs to manage a session boundary for Claude Code, Codex, OpenCode, OpenClaw, or another harness.