> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging.auth0-mintlify.app/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

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Agents as Principal" stage="ea" contact="Auth0 Support" terms="true" />

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) using the standard CRUD operations.

## Create and register a new agent

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

<Tabs>
  <Tab title="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**.
  </Tab>

  <Tab title="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:

    ```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](/docs/ai-agents-mcp/agents-as-principal/associate-agent-client) 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.                                                                                                            |

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      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.
    </Callout>

    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"
    }
    ```
  </Tab>
</Tabs>

## 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`.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  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.
</Callout>

## Next steps

* [Associate agent with a client](/docs/ai-agents-mcp/agents-as-principal/associate-agent-client) to issue tokens with agent identity