Skip to main content
Create an Agent in your organization with agents create. The CLI uses your Relay Console sign-in and saves the Agent Token privately on this computer. The command output never shows the token; use the token in your code prints it for a script.

​
Create the agent

Run the command where the Agent’s runtime will run:
The command checks and reuses saved Console credentials. With no saved Console credential, it starts browser OAuth sign-in automatically. You can also use the optional organization-key path in Authentication. Creation goes through Relay Console for the signed-in organization. --json prints metadata only; the Agent Token remains stored privately. profile is the name of the saved profile on this computer; pass it as --profile <name> to later commands. handle is the Agent’s address, and share_url is the link people open to start a chat. token reads stored: the credential stays in the profile, and agents create never prints it. Read the saved profiles with List agents.

​
Use the token in your code

The SDK and the API read the Agent Token from RELAY_AGENT_TOKEN. relay auth token prints the saved token and a newline, and nothing else, so a script can load it. It needs a CLI release that includes auth token, such as the one this line runs:
Replace assistant with the name on the Profile: line that agents create printed. With no saved token, the command prints nothing and exits 4. When RELAY_AGENT_TOKEN is already set, it prints that value instead of the saved one. To get a token without the CLI, open the agent in Relay Console and choose Rotate token in Settings. Relay shows the new token once, and every older token, including the one the CLI saved, stops working at once. Read Save the Agent Token.

​
Choose a handle, name, and picture

Use the options in the CLI creation reference. For --handle, pass one word, such as assistant: 2 to 32 lowercase letters, numbers or underscores, starting with a letter. --name accepts 1 to 30 characters. --subtitle <text> is required for every agent: the line under the agent’s name, 60 characters. --description <text> is what it can do, 2000 characters, and is required for public agents. To change the picture after creation, follow Profile photos.

​
Connect and share

Connect the saved profile through a runtime, a WebSocket, or webhooks. Share the link, send the agent a message from your phone, and confirm the reply arrives.

​
When it fails

A timeout can follow a creation that committed, and a local storage failure can follow a successful response. Treat an uncertain result as “maybe created” and check your organization in Relay Console before creating again.

​
Next steps