What is Relay?
The Big Picture
Relay is an AI messaging bridge — think of it like Twilio, but instead of routing phone calls to phone numbers, it routes messages to AI agents.
Apps and AI agents connect to Relay over WebSocket. When your app needs an AI agent to help, you send a message to Relay with the agent's ID. Relay delivers it. The agent responds. Relay streams the reply back to your app in real-time.
That's it. No webhooks. No HMAC signing. No polling. Just a persistent WebSocket connection, simple authentication, and message delivery.
Core Model: Agents Are Users
AI agents are treated like team members inside your app.
Just like you might @mention a human colleague in a comment, assign a task to a team lead, or ask someone to generate a report — your app can @mention an AI agent, assign work to it, or ask it to help. The app decides when and which agent to involve. Relay just delivers the message.
Portal app: "user mentioned @athena in a comment"
↓ (send event to Relay)
Relay
↓ (deliver to Athena via WebSocket)
Athena: "Got it. Processing..."
↓ (stream reply back)
Relay
↓ (deliver to app)
Portal app: "show Athena's response to the user"
This is fundamentally different from calling a language model API. With Relay, the app retains control. Your app decides the "why" and "when." The agent sees only what the app sends. The app sees only the agent's response.
Why Relay?
Before Relay (App calling an LLM directly)
Portal app LLM API
↓
└─→ [HTTP] "summarize this task"
↓
Process
↓
Response [HTTP] ←─┘
↑
(one-off call)
- App talks directly to one LLM service
- No routing to other agents
- No way to swap in a different AI provider
- No way to log what agents see across apps
- Hard to manage permissions (which apps can use which agents?)
With Relay (App → Relay → Agents)
Portal app Relay Athena
↓ ↓ ↓
└→ [WS] event ────┤ route
│ ┌─→ [WS] ←─┘
│ │
Flow app ──→ [WS] ──┼─→ Klyve → [WS] ←─┐
│ │
Studio app ──→ [WS] ──┼─→ Future Agent
│
(log, auth,
queue, scale)
- One integration for apps (Relay)
- Any agent can serve any app (if allowlisted)
- Relay handles auth, logging, rate limits, queuing
- Apps stay in control: they decide which agent to ping and what to send
- Relay never opens the payload — it's opaque to the bridge
The Three Principles
1. Agents Are Users
Your app @mentions an agent, assigns work to it, or asks for help. The app decides when and why. Relay just delivers.
Apps keep the intelligence. Relay is just the messenger.
2. Payload Is Sacred
Whatever your app puts in the payload field goes directly to the agent, untouched. Relay never parses it, never filters it, never cares what's inside.
Your app defines the shape. Could be a comment mention, a task assignment, a quiz question, a code review request — Relay doesn't know or care. It's just bytes.
The agent gets the payload. The agent responds. The response goes back to your app with the original payload echoed back, so your app knows which message it was replying to.
3. All WebSocket
Every connection is a persistent WebSocket. No HTTP requests, no webhooks, no HMAC signing, no polling.
App connects to Relay once. Stays connected. Sends events. Receives replies. All on the same pipe.
Agent connects to Relay once. Stays connected. Receives events. Sends replies. All on the same pipe.
This means:
- Real-time streaming. Agents can send tokens one at a time, so your app can show a "typing..." indicator.
- No authentication per-message. Auth happens once on handshake. Every message after that is already on a trusted channel.
- Bidirectional. Requests and responses flow on the same connection.
- Resilient. If a connection drops, reconnect with exponential backoff. Relay queues pending messages while waiting.
Architecture Diagram
┌──────────────────────────────────────────────────────────────┐
│ RELAY PLATFORM │
│ │
│ ┌────────────────────────┐ ┌────────────────────┐ │
│ │ Apps (WebSocket) │ │ Agents (WebSocket) │ │
│ │ │ │ │ │
│ │ • Portal │ │ • Athena │ │
│ │ • Flow │ │ • Klyve │ │
│ │ • Studio │ ◄─────►│ • Future Agents │ │
│ │ • Your App │ │ │ │
│ │ │ │ │ │
│ │ (send events) │ │ (receive events) │ │
│ │ (receive replies) │ │ (send replies) │ │
│ └────────────────────────┘ └────────────────────┘ │
│ ▲ ▲ │
│ │ │ │
│ ┌────────┴──────────────────────────────────────┴────────┐ │
│ │ │ │
│ │ • Authentication (tokens) │ │
│ │ • Allowlisting (who can talk to whom) │ │
│ │ • Event routing & queuing │ │
│ │ • Real-time message streaming │ │
│ │ • Session management & TTL │ │
│ │ • Audit logging │ │
│ │ • Rate limiting & scale │ │
│ │ │ │
│ └───────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
What Relay Does (and Doesn't Do)
Relay Handles
- Authentication. App tokens and agent tokens. Bearer auth on WebSocket handshake.
- Routing. Delivering events to the right agent based on agent_id.
- Permissions. Checking allowlists (which apps can send to which agents).
- Queuing. If an agent is offline, queue the event until it reconnects.
- Streaming. Token-by-token delivery for real-time agent responses.
- Sessions. Tracking thread_id and conversation continuity.
- Logging. Recording all events, replies, and errors for audit trails.
- Scale. Load balancing, resilience, uptime.
Relay Does NOT Handle
- Payload parsing. Relay never opens the payload. It's opaque.
- Routing logic. Relay doesn't decide which agent to use. The app does.
- Agent selection. Relay doesn't pick the "best" agent. The app picks it.
- Intelligence. Relay doesn't make decisions about content, filtering, or priority.
- Rate limiting on intelligence. App is responsible for not hammering agents.
Who Uses Relay?
For App Developers
You register your app on the Relay dashboard, get an API key, and connect a WebSocket. Start sending events to agents. That's it. Relay handles the rest.
You get:
- One integration that works with multiple AI agents
- Real-time streaming of agent responses
- Audit logs of all AI interactions
- Rate limiting and backoff handling
- No webhook setup needed
For Agent Operators
You register an agent on the Relay dashboard, get an agent token, and connect it to your agent server (via the OpenClaw plugin or a custom implementation). Start receiving events from allowlisted apps.
You get:
- One connection that serves multiple apps
- Credentials management (tokens, not API keys)
- Allowlist control (which apps can call you)
- Event queuing (messages wait if you're offline)
- Audit logging of all interactions
Next Steps
Ready to get started? Check out the Quick Start guide to spin up your first app and agent in 5 minutes.
Or dive deeper into the concepts behind Relay: