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

# Register an Agent

> Create and register agents using the Auth0 Dashboard or Management API

> [!WARNING]
>
> **The Agent as Principal feature is in .**

Register an agent as a first-class identity in Auth0 using the Auth0 Dashboard or Management API. Once registered, you can manage the agent with the [Management API](https://auth0.com/docs/api/management/v2.md) using the standard CRUD operations.

## Create and register a new agent

Create and register a new agent with the Auth0 Dashboard and Management API.

**Auth0 Dashboard**

1. Navigate to **Dashboard > Agents** and select **Create New Agent**.
2. Enter a name for the agent.
3. Select **Create**.

Once successfully created, the agent should have a unique `agent_id` with the `agt_` prefix. To view the agent's details, select **View Details**.

**Management API**

First, make sure your Management API access token has the `create:agents` permission.

Then, make a `POST` request to `/api/v2/agents` with the following parameters:

**Auth0 CLI**

Using the Auth0 CLI? If you haven't already, [set up and authenticate your CLI session](https://auth0.com/docs/deploy-monitor/auth0-cli.md) before running this command.

```bash theme={null}
auth0 api post "agents" \
  --data '{
    "name": "recommendation-agent-prod",
    "external_agent_id": "my-org-agent-042",
    "metadata": {
      "env": "prod",
      "team": "personalization"
    }
  }'
```

**cURL**

```bash theme={null}
curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/agents' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MGMT_API_TOKEN' \
  --data '{
    "name": "recommendation-agent-prod",
    "external_agent_id": "my-org-agent-042",
    "metadata": {
      "env": "prod",
      "team": "personalization"
    }
  }'
```

| Field | Required | Description |
| - | - | - |
| `name` | Yes | 1–255 characters. |
| `client_id` | No | [Associate an existing client](https://auth0.com/docs/ai-agents-mcp/agent-as-principal/associate-agent-client.md) on agent creation. |
| `external_agent_id` | No | Can only be set at creation time. You cannot modify afterward. To learn more, read [`external_agent_id`](#external_agent_id). |
| `metadata` | No | JSON, limit 10 KB. |

Do not include personally identifiable information (PII) in the `name` or `metadata` fields. These values are recorded in logs and may be visible to administrators and log streaming destinations.

If successful, Auth0 returns an agent object like the following:

```json theme={null}
{
    "agent_id": "agt_sJsP2T4rLopMQMWz2eEGmW",
    "name": "recommendation-agent-prod",
    "metadata": {
        "env": "prod",
        "team": "personalization"
    },
    "created_at": "2026-07-28T21:40:01.395Z",
    "updated_at": "2026-07-28T21:40:01.395Z",
    "external_agent_id": "my-org-agent-042"
}
```

## Agent object

Once registered, Auth0 stores the agent with the following object schema:

| Field | Type | Description |
| - | - | - |
| `agent_id` | string | Server-generated. Format: `agt_` + 22 base58 characters. Not modifiable. Always used to address the agent via the Management API, even when `external_agent_id` is set. |
| `external_agent_id` | string | Optional. Customer-supplied identifier. Must be set at creation; it cannot be added or changed afterward. When set, it replaces `agent_id` in token claims and tenant logs. |
| `name` | string | 1–255 characters. Required on creation. |
| `metadata` | object | JSON, limit 10 KB. |
| `created_at` | string | ISO 8601 timestamp. |
| `updated_at` | string | ISO 8601 timestamp. |

The agent object is returned by all `/api/v2/agents` endpoints.

## `external_agent_id`

You can supply your own identifier for an agent using `external_agent_id`, so that the agent identity visible in tokens and logs matches an ID already in use in your own systems. You must specify the `external_agent_id` at agent creation; it cannot be added or changed afterward.

When set, the `external_agent_id` replaces `agent_id` wherever the agent's identity appears in issued tokens (`sub`, `act.sub`) and in tenant logs. The internal `agent_id` remains the identifier used to manage the agent through the Management API, regardless of whether you've set an `external_agent_id`.

Do not include personally identifiable information (PII) in `external_agent_id`. This value is recorded in logs and may be visible to administrators and log streaming destinations.

## Next steps

* [Associate agent with a client](https://auth0.com/docs/ai-agents-mcp/agent-as-principal/associate-agent-client.md) to issue tokens with agent identity