Create and connect an agent

Create an agent in Relay, point your backend at it with the Agent Token, and let people install it from its handle or share link.

Create the agent

Agents are created in Relay for Business, by the creator organization accountable for them. Creation sets the agent’s handle, display name, and presentation identity, and issues its Agent Token.

Rule	Detail
Name format	3 to 32 lowercase letters, numbers, or underscores, starting with a letter. New names cannot end with an underscore or repeat underscores; names created before this rule keep working. A dot is refused: it is the joint between a name and its owner, never part of either
Address	The name you chose plus its owner’s, joined by a dot — `scheduler.yourname`. Relay derives it when the agent is read, so renaming the owner moves every agent it made and no other call is needed. A system agent and a brand’s front-door agent wear a flat name instead
Reserved handles	Product and legal route names such as `dashboard`, `mac`, `privacy`, `support`, `terms`, and impersonation words such as `everyone`, `moderator`, `verified`. Lookalikes that swap in digits or pad with underscores (`re1ay`, `adm1n`, `r_elay`) are refused too
Creator	Every agent belongs to one creator organization, which the profile names
Agent Token	Displayed once at creation and never shown again

Creation does not configure a model, prompt, backend, or hosting provider. Those stay in your own runtime. The opening message, when the agent has one, follows two rules:

Sends once as the agent, when a person first installs it.
Stays silent on reinstall, because that person has already read it.

Connect the backend

The Agent Token authenticates your backend as this agent. Verify it, then use the returned agent ID and handle in your logs and configuration.

curl -sS "$RELAY_API_URL/v1/agents/me" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

No backend yet? The Cloudflare Workers starter deploys a complete signed-webhook backend you customize afterwards.

Profile and distribution

Every live handle owns a profile at relayapp.im/handle carrying display identity only. Anyone who knows the handle or holds the share link can open it and install the agent. A suspended or retired agent answers 404.

Agent Tokens, prompts, model and provider choices, runtime details, backend configuration, and opening-message configuration are never part of a public profile.

Installation

A user explicitly adds an agent before messaging it. Installation creates or reuses one direct conversation between that user and agent. Relay accepts a backend message only while both of these hold:

The agent is a participant in the target conversation.
The agent is still installed for that user.

Action	Effect
Remove an ordinary agent	Ends the installation and blocks new messages from it
Add it again	Reuses the existing direct conversation, no duplicate thread
Block or report	Available for every agent, ends the installation, and overrides a built-in’s `canRemove: false`
Built-in Relay agent	Preinstalled on every account, with no ordinary Remove action

Conversation creation and arbitrary user lookup are not part of the preview. The developer API continues from conversation IDs Relay delivers to the agent.

Next steps

Quickstart to receive and reply to the first message
Webhooks to register the agent’s receiver
Authentication for token storage and rotation
Conversation lifecycle
Developer data access and retention

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Create and connect an agent

Create the agent

Connect the backend

Profile and distribution

Installation

Next steps

​Create the agent

​Connect the backend

​Profile and distribution

​Installation

​Next steps

Create the agent

Connect the backend

Profile and distribution

Installation

Next steps