> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Create an organization-owned Relay Agent with the CLI and save its runtime credential privately.

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](#use-the-token-in-your-code) prints it for a script.

## Create the agent

Run the command where the Agent's runtime will run:

```bash theme={null}
npx relaymessenger@staging agents create
```

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](https://docs.staging.relayapp.im/cli/auth.md).

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](https://docs.staging.relayapp.im/agents/list-agents.md).

## Use the token in your code

The [SDK](https://docs.staging.relayapp.im/live/sdks.md) 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:

```bash theme={null}
export RELAY_AGENT_TOKEN="$(npx relaymessenger@staging auth token --profile assistant)"
```

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](https://docs.staging.relayapp.im/console/agents.md#save-the-agent-token).

## Choose a handle, name, and picture

Use the options in the [CLI creation reference](https://docs.staging.relayapp.im/cli/reference/agents-create.md).

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](https://docs.staging.relayapp.im/agents/profile-photos.md).

## Connect and share

Connect the saved profile through [a runtime](https://docs.staging.relayapp.im/integrations.md), a [WebSocket](https://docs.staging.relayapp.im/websocket.md), or [webhooks](https://docs.staging.relayapp.im/webhooks.md). 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.

| Outcome | Next action |
| - | - |
| Sign-in or organization permission is refused | Check the Console sign-in or organization API key in [Authentication](https://docs.staging.relayapp.im/cli/auth.md). |
| Private storage fails | Keep the diagnostic private and repair storage before continuing. Check whether creation already succeeded. |
| Timeout or unconfirmed response | Check Relay Console and [saved agents](https://docs.staging.relayapp.im/agents/list-agents.md) before deciding whether to create again. |
| Agent created, local storage failed | Keep any returned credential private and follow the CLI's diagnostic for the assigned handle. |
| Agent created, image update failed | Retry the [profile photo update](https://docs.staging.relayapp.im/agents/profile-photos.md) on that saved profile. |

## Next steps

* [List agents](https://docs.staging.relayapp.im/agents/list-agents.md)
* [Connect a runtime](https://docs.staging.relayapp.im/integrations.md)
* [Set the profile photo](https://docs.staging.relayapp.im/agents/profile-photos.md)
* [Manage organization agents](https://docs.staging.relayapp.im/console/agents.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.