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

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

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

特典

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

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

前提条件

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

必要なツール

Visual Studio Code GitHub Copilot および GitHub Copilot Chat 拡張機能がインストールされています。 AI誘導のセットアップには、端末アクセスを持つAIコーディングエージェントが必要です。
Microsoft Graph PowerShell モジュールには、PowerShell 7 以降が必要です。
Microsoft Graph PowerShell SDK (beta)Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force を使用してインストールされます。

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

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

注

エージェント ID ブループリントまたはエージェント ID ブループリントプリンシパルの所有者は、Microsoft Entra エージェント IDロールなしで、そのブループリントのエージェント ID を作成できます。エージェント ID ブループリント作成者は、ブループリントと関連するエージェント ID ブループリントプリンシパルの両方の所有者として自動的に設定されます。

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

必要なMicrosoft Graphアクセス許可

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

許可	Purpose
`AgentIdentityBlueprint.Create`	新しいエージェント ID ブループリントを作成する
`AgentIdentityBlueprint.AddRemoveCreds.All`	資格情報 (マネージド ID、シークレット、証明書) をブループリントに追加する
`AgentIdentityBlueprint.ReadWrite.All`	ブループリントのプロパティ (識別子 URI、スコープ) を更新する
`AgentIdentityBlueprintPrincipal.Create`	ブループリントのサービスプリンシパルを生成する
`User.Read`	サインインしているユーザーのプロファイルを読み取る (スポンサー割り当て用)

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

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

セットアップ手順のファイルを入手してください

AI ガイド付きセットアップでは、Microsoft Skills GitHub リポジトリに記載されている手順を使用します。

AIガイドのセットアップを実行してください

AI ガイド付きセットアップを開始するには、次の手順に従います。

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

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

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

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

Important

エージェントモードを使用する必要があります ([要求] モードまたは [編集] モードではありません)。 AIガイドのセットアップは、端末コマンドを実行し、環境とやり取りする能力を必要とします。

ステップ3:指示ファイルを添付して開始

Copilot Chat入力で、agent-id-setup-instructions.md ファイルを添付し、短いプロンプトで送信します。例えば次が挙げられます。

Follow the steps in #file:agent-id-setup-instructions.md

AIエージェントは命令ファイルを読み取り、ガイド付きセットアップを開始します。タスクリストを作成し、手順を順番に実行します。

前提条件を検証する: Microsoft Entra ロールをチェックし、PowerShell 7 以降と Microsoft Graph ベータ版モジュールがインストールされていることを検証します。
Authorize and connect: 必要なスコープでMicrosoft Graphに接続し、プロファイルをベータに設定します。
エージェント ID ブループリントの作成: 表示名を収集し、スポンサー (自分) を識別し、必要な @odata.type および OData-Version ヘッダーを含むブループリントを作成し、 appIdを記録します。
資格情報の構成: マネージド ID (運用用) または証明書またはクライアントシークレット (ローカル開発/テスト用) をブループリントに追加します。
識別子 URI とスコープの構成: identifierUris を api://{appId}に設定し、エージェント間およびユーザー間通信用の access_agent OAuth2 アクセス許可スコープを作成します。
ブループリントプリンシパルを作成する: ブループリントのサービスプリンシパルを作成します (プリンシパルは自動作成 されないため 、明示的に行う必要があります)。
エージェント ID の作成: ブループリントの下に 1 つ以上のエージェント ID サービスプリンシパルを作成します。

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

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

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

ヒント

AI エージェントは、構成入力を要求するときに、Microsoft Entra テナントからの実際の値を例として示します。提案を受け入れるか、自分の価値観を提示するかのどちらかです。

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

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

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

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

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

Stage	何が起きるか	関連ドキュメント
前提条件	Microsoft Entraロール、PowerShell モジュール、および Graph のアクセス許可を検証します	ブループリントの作成: 前提条件
環境のセットアップ	正しいスコープとベータプロファイルを使用してMicrosoft Graphに接続します	ブループリントを作成する: 環境を準備する
ブループリントの作成	スポンサーと所有者を使用してエージェント ID ブループリントを作成します	ブループリントを作成する
資格情報の構成	マネージド ID FIC またはクライアントシークレットをブループリントに追加します	資格情報を構成する
スコープの構成	識別子 URI と `access_agent` スコープを設定します	識別子 URI とスコープを構成する
プリンシパルの作成	エージェント ID の設計原則（サービスプリンシパル）を作成します	エージェントの設計図主要要素を作成する
エージェントのアイデンティティ	ブループリントに基づいてエージェント ID サービスプリンシパルを作成します	エージェント ID の作成

注

AI ガイド付きセットアップでは、エージェント ID をエージェントのコードに統合する必要性は置き換わりません。エージェントがトークンを取得し、そのエージェント ID を使用して操作を実行する方法を理解する必要があります。ガイド付きセットアップでは、エージェントコードで使用される ID インフラストラクチャが作成されます。

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

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

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

@odata.typeを使用するすべてのエージェント ID API 呼び出しには、OData-Version: 4.0 ヘッダーが必要です。このヘッダーを省略すると、 @odata.type フィールドは暗黙的に無視され、API はエージェント ID ブループリントではなく標準アプリケーションを作成します。 AI ガイド付きセットアップには、常にこのヘッダーが含まれます。

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

エージェント 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 エラーの最も一般的な原因:

アクセス許可の伝達の遅延: 管理者の同意を得てから 1 ~ 2 分待ってから再試行します。
管理者の同意がない: Microsoft Entra 管理センターでアプリの登録>クライアントアプリ>API 権限の必要なアクセス許可が管理者によって許可されているかを確認してください。

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

この結果は、 OData-Version: 4.0 ヘッダーが見つからないか、 @odata.type プロパティが省略されている場合に発生します。両方が要求に存在しているか確認します。 PowerShell コマンドレットを使用する場合は、ベータモジュールを使用し、正しい本体構造を渡していることを確認してください。

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

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

POST https://graph.microsoft.com/beta/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

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

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

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

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

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

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

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-01