Microsoft Entra エージェント ID用の AI ガイド付きセットアップ

Microsoft Entra エージェント IDへのオンボードには、エージェント ID ブループリントの作成、資格情報の構成、識別子 URI とスコープの設定、ブループリント プリンシパルの作成、エージェント ID のプロビジョニングという複数の手順が含まれます。 各ステップには独自の前提条件、検証チェック、意思決定ポイントがあります。

この AI ガイド付きセットアップでは、AI コーディング エージェント (VS Code のGitHub Copilotなど) を使用して、ユーザーに代わって手順を実行することで、このワークフロー全体が自動化されます。 複数のドキュメントページを移動したり手動でコマンドを実行する代わりに、AIエージェントに単一の命令ファイルを提供し、インタラクティブにプロセスを案内してくれます。 この命令ファイルはスキルとして使用でき、複数の方法でアクセスできます。

特典

AIガイド付きセットアップは、手動ワークフローに比べていくつかの利点があります。

• 1 つのエントリ ポイント: 1 つの命令ファイルで、複数のドキュメント ページ間を移動する必要性が置き換えられます。 AIエージェントは手順を順番に追い、トランジションを自動的に処理します。
• 自動前提条件検証: AI エージェントは、適切なMicrosoft Entraロールがあること、必要なツールと Graph モジュールがインストールされていること、および API 呼び出しを行う前に管理者の同意を得て必要なアクセス許可が構成されていることを検証します。
• スマートな既定値と自動検出: AI エージェントは、既存のユーザー情報とリソースの詳細についてテナントにクエリを実行し、構成入力を収集するときにそれらの値を提案として使用します。
• 派生名前付け規則: エージェントの表示名を 1 つ指定すると、AI エージェントは、一貫したパターンを使用して関連するすべてのリソース名 (ブループリント、ブループリント プリンシパル、エージェント ID、識別子 URI) を派生させます。
• インライン エラー処理: コマンドが失敗すると、AI エージェントはエラーを分析し、修正プログラムを提案し、再試行します。トラブルシューティングドキュメントを検索する必要はなくなります。 このエラー処理は、アクセス許可の伝達の遅延や OData ヘッダーの要件などのエージェント ID 固有の落とし穴に特に役立ちます。
• べき等操作: AI エージェントは、リソースを作成する前にリソースが既に存在するかどうかをチェックし、以前の試行が中断された場合にセットアップを安全に再実行できるようにします。

前提条件

開始する前に、次の前提条件を満たしていることを確認してください。

必要なツール

AI ガイド付きセットアップには、ターミナル アクセスを備えた AI コーディング エージェントが必要です。

• Visual Studio CodeGitHub Copilot および GitHub Copilot Chat 拡張機能がインストールされています。
• VS Code で直接 Microsoft Entra エージェント ID スキルを提供する GitHub Copilot for Azure 拡張機能。

このスキルでは、2 つのプロビジョニング パスがサポートされています。 設定に応じて、いずれかまたは両方をインストールします。

• PowerShell を使用する方法: PowerShell 7 以降と Microsoft Graph PowerShell SDK が必要です。 Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force を使用してインストールします。
• Python パス: azure-identity および requests を含む Python 3.8 以降。 pip install azure-identity requests を使用してインストールします。

必要なアカウントとアクセス許可

• 次のいずれかのロールを持つ Microsoft Entra テナント へのアクセス。
  • エージェント ID 開発者はエージェント ID の設計図とエージェント ID を作成。 エージェント ID ブループリントの所有者は、エージェント ID ロールなしで、そのブループリントのエージェント ID を作成できます。
  • エージェント ID 管理者は、エージェント ID リソースへの完全な管理アクセスを提供します。

• アクセス許可付与の追加ロール:
  • 特権ロール管理者Microsoft Graphアプリケーションのアクセス許可を付与します。
  • Cloud アプリケーション管理者またはアプリケーション管理者は、委任された Microsoft Graph のアクセス許可を付与します。

必要なMicrosoft Graphアクセス許可

使用するクライアント (PowerShell またはカスタム アプリの登録) は、次の委任されたアクセス許可で承認されている必要があります。

必要なエージェント コード (省略可能)

エージェント ID が必要な作業エージェント プロジェクト (Python、Node.js、または.NET) が既にある場合は、プロジェクト ディレクトリを使用できます。 まだお持ちでない場合でも、ブループリントのセットアップを個別に完了できます。

概要

AI ガイド付きセットアップでは、スキルが使用されます。これは、すべての手順と検証チェックを含む 1 つの命令ファイルです。 スキルには、次の 2 つの方法のいずれかでアクセスできます。

• GitHub Copilot for Azure 拡張機能を使用する（推奨）: GitHub Copilot for Azure VS Code 拡張機能をインストールします。 Microsoft Entra エージェント ID スキルは、Copilot Chatでのエージェント ID の設定について質問すると自動的にアクティブになります。
• GitHub から間接的に: Copilot Chat プロンプトで参照することで、スタンドアロンの Microsoft Entra エージェント ID スキル を使用します。

手順 1: VS Code でプロジェクトを開く

Visual Studio Codeでエージェント プロジェクト ディレクトリ (または任意の作業ディレクトリ) を開きます。

手順 2: エージェント モードで GitHub Copilot Chatを開く

GitHub Copilot Chat パネルを開き、Agent モードに切り替えます。 エージェント モードを使用すると、GitHub Copilotターミナル コマンドの実行、ファイルの読み取り、環境との対話を行うことができます。これは、AI ガイド付きセットアップで必要になります。

手順 3: ガイド付きセットアップを開始する

Azure拡張機能のGitHub Copilotがインストールされている場合は、エージェント ID を設定するようにCopilotに依頼してください。 例えば次が挙げられます。

@azure Use the Agent ID Skill to set up an agent identity blueprint and create agent identities for my project using Microsoft Entra Agent ID.

拡張機能がない場合は、GitHubからスキルを直接参照します。

Follow the steps in https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/skills/entra-agent-id/SKILL.md

AI エージェントがスキルを読み取り、ガイド付きセットアップを開始します。 これは、次の手順を順番に実行します。

1. Validate の前提条件: Microsoft Entraの役割を確認し、必要なツール (Microsoft Graph モジュールを使用する PowerShell、または azure-identity を使用したPython) がインストールされていることを検証します。
2. Authenticate: 必要なスコープでMicrosoft Graphに接続します。 PowerShell の場合、スキルは明示的に委任されたスコープを持つ Connect-MgGraph を使用します。 Pythonでは、クライアント資格情報を使用した専用アプリの登録が使用されます。
3. エージェント ID ブループリントの作成: 表示名を収集し、スポンサー (ユーザー) を識別し、型指定されたエンドポイント (/applications/microsoft.graph.agentIdentityBlueprint) を使用してブループリントを作成し、 appIdを記録します。
4. 資格情報の構成: マネージド ID を持つフェデレーション ID 資格情報 (運用環境の場合) またはクライアント シークレット (ローカル開発/テスト用) をブループリントに追加します。
5. 識別子 URI とスコープの構成: identifierUris を api://{appId} に設定し、エージェント間およびユーザー間通信用の OAuth2 アクセス許可スコープを作成します。
6. ブループリント プリンシパルを作成する: 型指定されたエンドポイントを使用してブループリントのサービス プリンシパルを作成します (プリンシパルは自動作成 されないため 、明示的に行う必要があります)。
7. エージェント ID の作成: ブループリントの下に 1 つ以上のエージェント ID サービス プリンシパルを作成します。

エージェントがスキルを読み取ると、拡張機能やその他のツールをインストールするように求められる場合があります。 プロンプトに従って、環境の準備ができていることを確認します。

ステップ4:プロンプトに応答する

AIエージェントは特定のポイントで一時停止し、あなたから入力を収集します:

• 表示名: エージェント ID ブループリントの表示名 ("Contoso Budget Agent" など)。
• スポンサー: エージェントの責任を負うユーザーまたはグループ。 既定値は、現在サインインしているユーザーです。
• 所有者: ブループリントに技術的な変更を加えることができるユーザーまたはサービス プリンシパル。 省略可能ですが推奨されます。
• 資格情報の種類: マネージド ID (運用環境に推奨) を使用するか、証明書またはクライアント シークレット (ローカル開発用) を使用するか。
• エージェント ID の数: このブループリントの下に作成するエージェント ID の数。
• 派生値の確認: リソースが作成される前に、自動生成された名前と URI を確認します。

手順 5: Microsoft Entra 管理センターで確認する

セットアップが完了すると、AI エージェントはリソースを確認する方法について説明します。

1. Microsoft Entra 管理センターに少なくとも Agent ID Developer としてサインインします。
2. Entra ID>Agents>Agent ID に移動して、新しいエージェント ID ブループリントとその下に作成されたすべてのエージェント ID を確認します。
3. ブループリントに正しい資格情報、識別子 URI、およびスコープが構成されていることを確認します。

AIガイド付きセットアップがカバーしていること

AI ガイド付きセットアップでは、エージェント ID 統合の次のステージが自動化されます。

AI ガイド付きセットアップで対応する一般的な落とし穴

エージェント ID API には、AI ガイド付きセットアップで自動的に検出および解決されるいくつかの要件がありますが、明らかな要件ではありません。 これらの落とし穴を理解することは、問題をデバッグしたり、セットアップを拡張したりする必要がある場合に役立ちます。

OData-Version ヘッダーが必要です

すべてのエージェント ID API 呼び出しには、 OData-Version: 4.0 ヘッダーが必要です。 このヘッダーを省略すると、API によってエージェント ID ブループリントではなく標準アプリケーションが自動的に作成される可能性があります。 AI ガイド付きセットアップには、常にこのヘッダーが含まれます。 スキルでは、/applications/microsoft.graph.agentIdentityBlueprint プロパティを持つ生の/applicationsではなく、型指定されたエンドポイント (@odata.type など) も使用して、この問題のリスクを軽減します。

ブループリントのプリンシパルは自動的に作成されません。

エージェント ID ブループリント (POST /applications) を作成しても、そのブループリント プリンシパル (サービス プリンシパル) は自動的には作成 されません 。 ブループリント プリンシパルがない場合、後続のすべてのエージェント ID の作成は次の場合に失敗します。

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

AI ガイド付きセットアップでは、ブループリントの直後に常にブループリント プリンシパルが作成されます。 また、べき等ケースも処理します。 以前の実行でブループリントが作成されたが、プリンシパルを作成する前にクラッシュした場合、セットアップはこのイベントを検出し、不足しているプリンシパルを作成します。

スポンサーが必要です

スポンサーは必須であり、ユーザー、動的メンバーシップを持つグループ、または統合グループにすることができます。 ブループリントとエージェント ID の両方の作成には、 sponsors@odata.bind フィールドが必要です。 これを行わないと、次の情報が表示されます。

400: No sponsor specified. Please provide at least one sponsor.

AI ガイド付きセットアップでは、スポンサー割り当ての ユーザー オブジェクトのみを受け入れ、 /users/{objectId} URL 形式 ( /directoryObjects/ や /servicePrincipals/ではなく) を使用します。 セットアップでは、現在のユーザーのオブジェクト ID が解決され、既定のスポンサーとして使用されます。 ブループリントのスポンサーとして supported グループを割り当てるには、Microsoft Graph APIを直接使用します。

アクセス許可の伝達には 30 ~ 120 秒以上かかります

エージェント ID のアクセス許可に対して管理者の同意を付与すると、新しく付与されたアクセス許可はすぐにトークンに表示されません。 トークン エンドポイントはキャッシュされた要求を処理し、伝達には 30 ~ 120 秒以上かかることがあります。

AI ガイド付きセットアップでは、403 を受信したときに指数バックオフで操作を再試行することで、最近のアクセス許可の変更を処理します。 これを手動でスクリプト化する場合は、再試行ロジックを実装します。

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Scopes $scopes
        } else {
            throw
        }
    }
}

エージェント ID にパスワード資格情報を設定できない

エージェント ID は、アプリケーション オブジェクトをバッキングしないサービス プリンシパルです。 エージェント ID に passwordCredential を直接追加しようとすると、次の結果が得られます。

PropertyNotCompatibleWithAgentIdentity

資格情報は、個々のエージェント ID ではなく、 ブループリントで構成する必要があります。 マネージド ID フェデレーション (推奨) を使用するか、ブループリントにシークレット/証明書を追加し、エージェント ID は偽装によって資格情報を継承します。

識別子 URI は明示的に設定する必要があります

ブループリントの identifierUris フィールドは、既定では設定されていません。 そうしないと、OAuth2 スコープ api://{appId}/.default は解決されず、エージェントのトークンの取得は失敗します。 AI ガイド付きセットアップでは、スコープのセットアップ手順の一部として常にこの値が構成されます。

ブループリントのフェデレーション ID 資格情報のパス

マネージド ID フェデレーション用のフェデレーション ID 資格情報 (FIC) を追加する場合は、エージェント固有の API パスを使用する必要があります。

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

/applications/{id}/federatedIdentityCredentials パスを使用すると、エージェント ID ブループリントで機能する場合がありますが、サポートされていないため、推奨されません。

トークン発行者はエンドポイントのバージョンによって異なります

エージェント バックエンドでトークンを検証する場合は、次のバリエーションに注意してください。

• v1.0 トークンは発行者https://sts.windows.net/{tenant-id}/を使用します
• v2.0 トークンは発行者 https://login.microsoftonline.com/{tenant-id}/v2.0 を使用する

トークン検証ロジックで両方の形式を受け入れます。

Troubleshooting

AIエージェントはターミナルコマンドを実行しません

AI エージェントがコマンドを記述しても実行しない場合は、GitHub Copilot Chat で Agent モードを使用していることを確認します。 AskモードとEditモードには端末アクセスがありません。

AIエージェントは検証ステップをスキップします

命令ファイルは厳密なステップ順序を強制します。 AIエージェントがステップを飛ばしているように見えたら、最初から指示に従うようリマインドしてください。 例えば次が挙げられます。

Please start from Step 1 in the setup instructions and work through each step in order.

Graph コマンドが 403-Forbidden で失敗する

403 エラーの最も一般的な原因:

• Azure CLIまたはDefaultAzureCredential トークンの使用: Azure CLIトークンには、Directory.AccessAsUser.Allが含まれます。エージェント ID API は完全に拒否します。 明示的に委任されたスコープで Connect-MgGraph を使用するか、 client_credentialsでの専用アプリの登録を使用します。 前提条件の 認証の警告 を参照してください。
• アクセス許可の伝達の遅延: 管理者の同意を得てから 1 ~ 2 分待ってから再試行します。 AI ガイド付きセットアップでは、再試行ロジックを使用してこれを自動的に処理します。
• 管理者の同意がない: Microsoft Entra 管理センターでアプリの登録>クライアント アプリ>API 権限の必要なアクセス許可が管理者によって許可されているかを確認してください。

ブループリントの作成は成功しますが、標準アプリケーションが返されます

この結果は、 OData-Version: 4.0 ヘッダーが見つからない場合に発生します。 この問題を回避するには、/applications/microsoft.graph.agentIdentityBlueprintで生の/applicationsではなく、型指定されたエンドポイント (@odata.type) を使用します。

エージェント ID の作成が "ブループリント プリンシパルが存在しない" で失敗する

ブループリントの後に、ブループリント プリンシパルは別の手順として作成する必要があります。 走れ

POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

{
  "appId": "<your-blueprint-app-id>"
}

資格情報の有効期間ポリシー エラー

テナントには、クライアント シークレットの最大有効期間を制限する資格情報ライフサイクル ポリシーがある場合があります。 パスワードを追加するときに資格情報の有効期間に関するエラーが発生した場合は、組織のポリシーに合わせて endDateTime の値を減らします。

構成値を変更する必要がある

セットアップ後に構成値を変更する必要がある場合は、次のことができます。

• 更新された値を使用して AI ガイド付きセットアップを再実行します。 べき等チェックでは、既に正しく存在するリソースがスキップされます。
• Microsoft Graph PowerShell を使用して、PATCH 要求で特定のプロパティを更新します。

次のステップ

• エージェント ID の作成と削除
• エージェント ID の管理関係 (所有者、スポンサー、およびマネージャー)
• エージェント ID、サービス プリンシパル、アプリケーション
• エージェント ID ブループリントの概念