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

# エージェントの登録

> Auth0 Dashboard または Management API を使用してエージェントを作成・登録します

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "早期アクセス"
  };
  const stageText = stageTextMap[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 && <>この機能は{linkify(`${plans}プラン`, "https://auth0.com/pricing")}でご利用いただけます。 </>}
            {contact && "参加をご希望の場合は、" + contact + "までお問い合わせください。 "}
            {terms && <>この機能を使用することにより、Oktaの該当する無料トライアル規約および{linkify("Master Subscription Agreement", "https://www.okta.com/legal")}に同意したものとみなされます。</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>{feature}機能は現在、{linkify(stageText, prsLink)}です。</strong>
            </span>

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

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

Auth0 Dashboard または Management API を使用して、エージェントを Auth0 の第一級の ID として登録します。登録後は、[Management API](https://auth0.com/docs/api/management/v2) の標準的な CRUD 操作でエージェントを管理できます。

<h2 id="create-and-register-a-new-agent">
  新しいエージェントを作成して登録する
</h2>

Auth0 DashboardとManagement APIを使って、新しいエージェントを作成して登録します。

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. **Dashboard > Agents**に移動し、**Create New Agent**を選択します。
    2. エージェントの名前を入力します。
    3. **Create**を選択します。

    作成に成功すると、エージェントには`agt_`プレフィックスが付いた一意の`agent_id`が付与されます。エージェントの詳細を表示するには、**View Details**を選択します。
  </Tab>

  <Tab title="Management API">
    まず、Management APIのアクセストークンに`create:agents`権限があることを確認します。

    次に、以下のパラメーターを指定して`/api/v2/agents`に`POST`リクエストを送信します。

    <Tabs>
      <Tab title="Auth0 CLI">
        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">Auth0 CLIをお使いですか？まだの場合は、このコマンドを実行する前に[CLIセッションをセットアップして認証](/docs/ja-jp/deploy-monitor/auth0-cli)してください。</Callout>

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

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

    | フィールド | 必須 | 説明 |
    | - | - | - |
    | `name` | はい | 1〜255文字。 |
    | `client_id` | いいえ | エージェント作成時に[既存のクライアントを関連付けます](/docs/ja-jp/ai-agents-mcp/agent-as-principal/associate-agent-client)。 |
    | `external_agent_id` | いいえ | 作成時にのみ設定でき、作成後は変更できません。詳細については、[`external_agent_id`](#external_agent_id)をお読みください。 |
    | `metadata` | いいえ | JSON、上限10 KB。 |

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      `name`や`metadata`フィールドには、個人を特定できる情報 (PII) を含めないでください。これらの値はログに記録され、管理者やログストリーミングの送信先から参照される可能性があります。
    </Callout>

    成功すると、Auth0は次のようなエージェントオブジェクトを返します。

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

<h2 id="agent-object">
  エージェントオブジェクト
</h2>

登録すると、Auth0は次のオブジェクトスキーマでエージェントを保存します。

| フィールド | 型 | 説明 |
| - | - | - |
| `agent_id` | string | サーバーが生成します。形式は`agt_` + base58文字22文字です。変更できません。`external_agent_id`が設定されている場合でも、Management API経由でエージェントを指定する際には常にこの値を使用します。 |
| `external_agent_id` | string | 任意。顧客が指定する識別子です。作成時に設定する必要があり、後から追加や変更はできません。設定した場合、トークンのクレームやテナントログでは`agent_id`の代わりにこの値が使用されます。 |
| `name` | string | 1〜255文字。作成時に必須です。 |
| `metadata` | object | JSON、上限10 KB。 |
| `created_at` | string | ISO 8601形式のタイムスタンプ。 |
| `updated_at` | string | ISO 8601形式のタイムスタンプ。 |

エージェントオブジェクトは、`/api/v2/agents`のすべてのエンドポイントから返されます。

<h2 id="external_agent_id">
  `external_agent_id`
</h2>

`external_agent_id` を使うと、エージェントに独自の識別子を指定できます。これにより、トークンやログに表示されるエージェントのアイデンティティを、自社システムですでに使用している ID と一致させられます。`external_agent_id` はエージェントの作成時に指定する必要があり、後から追加したり変更したりすることはできません。

設定すると、発行されるトークン (`sub`、`act.sub`) やテナントログでエージェントのアイデンティティが表示される箇所では、`agent_id` に代わって `external_agent_id` が使用されます。`external_agent_id` を設定しているかどうかにかかわらず、Management API でエージェントを管理する際に使用する識別子は、引き続き内部の `agent_id` です。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `external_agent_id` には個人を特定できる情報 (PII) を含めないでください。この値はログに記録され、管理者やログストリーミングの送信先から参照される可能性があります。
</Callout>

<h2 id="next-steps">
  次のステップ
</h2>

* [エージェントをクライアントに関連付ける](/docs/ja-jp/ai-agents-mcp/agent-as-principal/associate-agent-client)ことで、エージェントのアイデンティティを持つトークンを発行できます