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 credential is never printed.

​
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 is never printed. Read the saved profiles with List agents.

​
Choose a handle, name, and picture

Use the options in the CLI creation reference. For --handle, pass one word, such as assistant: 3 to 32 lowercase letters, numbers or underscores, starting with a letter. --name accepts 1 to 30 characters. 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