Build your own agent

Run a complete agent backend on your laptop, then replace the echo turn with your own model and tools. Relay owns the messenger. Your process owns the brain. This path uses long polling, so you do not need a public HTTPS URL. Webhooks and long polling are mutually exclusive per Agent Token. For a public server, use the Quickstart webhook loop or the Vercel AI SDK package instead.

Prerequisites

Node.js 22.18 or newer
An Agent Token from Create and connect an agent
A checkout of relaymessenger/Relay-SDK

Run the showcase agent

git clone https://github.com/relaymessenger/Relay-SDK.git
cd Relay-SDK
npm ci
npm run build -w @relaymessenger/sdk
export RELAY_AGENT_TOKEN="rly_live_..."
npm start -w @relaymessenger/showcase-agent

Message the agent from the Relay app. The default turn replies with an echo. Owner-only filtering applies when GET /v1/agents/me returns an owner_user_id.

What the example enforces

Concern	Behavior
Transport	Durable long poll over `GET /v1/events`
Responding	Calls `/responding` before the reply
Idempotency	Derives `Idempotency-Key` from the inbound `event_id`
Typing	Stops typing in a `finally` block
Credentials	Reads the Agent Token from the environment only

Shared transport lives in @relaymessenger/sdk, a workspace inside that repository and a published npm package. Install it directly in your own project when you want the client, the Standard Webhooks verifier, the cursor, and the poll loop without forking an example. Raw HTTPS remains the public contract, and the package is a binding of it rather than a second one.

Replace the echo

Edit examples/showcase-agent/src/index.ts. Keep the receive and reply helpers. Swap the text you pass to reply.text(...) for your model output. For a host runtime that already owns sessions and routing, implement the channel plugin contract instead of forking the showcase agent.

Workspace	Role
`@relaymessenger/sdk`	Contract and transport: client, verify, cursor, poll loop. Published to npm
`@relaymessenger/showcase-agent`	Forkable long-poll agent
`@relaymessenger/raw-webhook-agent`	Minimal webhook server matching the quickstart
`relay-claude-channel`	The Claude Code channel plugin, an MCP stdio server. Published to npm and bundled in the CLI

Install paths for Claude Code, Codex, Hermes ACP, and OpenClaw remain on @relaymessenger/cli.

Next steps

Quickstart for the webhook receive-and-reply loop
Your own runtime for embedding Relay in a host
Hermes Agent for the local ACP bridge
Delivery model for long poll and recovery rules

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Build your own agent

Prerequisites

Run the showcase agent

What the example enforces

Replace the echo

Next steps

​Prerequisites

​Run the showcase agent

​What the example enforces

​Replace the echo

​Related workspaces in Relay-SDK

​Next steps

Prerequisites

Run the showcase agent

What the example enforces

Replace the echo

Related workspaces in Relay-SDK

Next steps