> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 credential is never printed.

## Create the agent

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

```bash theme={null}
npx relaymessenger 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](/cli/auth).

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](/agents/list-agents).

## Choose a handle, name, and picture

Use the options in the [CLI creation reference](/cli/reference/agents-create).

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](/agents/profile-photos).

## Connect and share

Connect the saved profile through [a runtime](/integrations/claude-code), a [WebSocket](/websocket), or [webhooks](/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.

| Outcome                                       | Next action                                                                                                 |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Sign-in or organization permission is refused | Check the Console sign-in or organization API key in [Authentication](/cli/auth).                           |
| 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](/agents/list-agents) 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](/agents/profile-photos) on that saved profile.                             |

## Next steps

* [List agents](/agents/list-agents)
* [Connect a runtime](/integrations/claude-code)
* [Set the profile photo](/agents/profile-photos)
* [Manage organization agents](/console/agents)