entra-agent-id

Microsoft Entra Agent ID

Microsoft Graph ベータ API を使用して、AI エージェント向けの OAuth2 対応 ID を作成、管理します。

プレビュー API — Agent Identity エンドポイントはすべて /beta のみで提供されています。/v1.0 では利用できません。

始める前に

最新の Agent ID ドキュメントを microsoft-docs MCP で検索します。

• クエリ：「Microsoft Entra agent identity setup」
• 確認事項：API パラメーターが現在のプレビューの動作と一致していること

概念モデル

Agent Identity Blueprint (application)        ← one per agent type/project
  └── BlueprintPrincipal (service principal)   ← MUST be created explicitly
        ├── Agent Identity (SP): agent-1       ← one per agent instance
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

前提条件

PowerShell（対話型セットアップに推奨）

# Requires PowerShell 7+
Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force

Python（プログラムによるプロビジョニング用）

pip install azure-identity requests

必要な Entra ロール

Agent Identity Developer、Agent Identity Administrator、または Application Administrator のいずれかが必要です。

環境変数

AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<app-registration-client-id>
AZURE_CLIENT_SECRET=<app-registration-secret>

認証

⚠️ DefaultAzureCredential はサポートされていません。 Azure CLI トークンには Directory.AccessAsUser.All が含まれており、Agent Identity API では明示的に拒否されます（403）。 専用のアプリ登録と client_credentials フローを使用するか、 明示的な委任スコープを指定して Connect-MgGraph で接続する必要があります。

PowerShell（委任されたアクセス許可）

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "User.Read"
)
Set-MgRequestContext -ApiVersion beta

$currentUser = (Get-MgContext).Account
$userId = (Get-MgUser -UserId $currentUser).Id

Python（アプリケーションのアクセス許可）

import os
import requests
from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id=os.environ["AZURE_TENANT_ID"],
    client_id=os.environ["AZURE_CLIENT_ID"],
    client_secret=os.environ["AZURE_CLIENT_SECRET"],
)
token = credential.get_token("https://graph.microsoft.com/.default")

GRAPH = "https://graph.microsoft.com/beta"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",  # Required for all Agent Identity API calls
}

基本的なワークフロー

手順 1：Agent Identity Blueprint を作成する

スポンサーが必須です。スポンサーはUser オブジェクトでなければなりません。ServicePrincipals と Groups は拒否されます。

import subprocess

# Get sponsor user ID (client_credentials has no user context, so use az CLI)
result = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
)
user_id = result.stdout.strip()

blueprint_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "[email protected]": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/applications", headers=headers, json=blueprint_body)
resp.raise_for_status()

blueprint = resp.json()
app_id = blueprint["appId"]
blueprint_obj_id = blueprint["id"]

手順 2：BlueprintPrincipal を作成する

この手順は必須です。 Blueprint を作成しても、そのサービス プリンシパルは自動作成されません。 作成しない場合、Agent Identity の作成は次のエラーで失敗します。 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprintPrincipal",
    "appId": app_id,
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=sp_body)
resp.raise_for_status()

冪等性のあるスクリプトを実装する場合は、Blueprint がすでに存在するときも BlueprintPrincipal を確認し、必要に応じて作成してください（前回の実行で Blueprint は作成されたものの、SP の作成前にクラッシュした可能性があります）。

手順 3：Agent Identity を作成する

agent_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentity",
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "[email protected]": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=agent_body)
resp.raise_for_status()
agent = resp.json()

API リファレンス

操作	メソッド	エンドポイント	OData 型
Blueprint を作成	POST	/applications	Microsoft.Graph.AgentIdentityBlueprint
BlueprintPrincipal を作成	POST	/servicePrincipals	Microsoft.Graph.AgentIdentityBlueprintPrincipal
Agent Identity を作成	POST	/servicePrincipals	Microsoft.Graph.AgentIdentity
Agent Identity を一覧表示	GET	/servicePrincipals?$filter=...	—
Agent Identity を削除	DELETE	/servicePrincipals/{id}	—
Blueprint を削除	DELETE	/applications/{id}	—

すべてのエンドポイントで、ベース URL として https://graph.microsoft.com/beta を使用します。

必要なアクセス許可

アクセス許可	用途
Application.ReadWrite.All	Blueprint の CRUD（application オブジェクト）
AgentIdentityBlueprint.Create	新しい Blueprint の作成
AgentIdentityBlueprint.ReadWrite.All	Blueprint の読み取り／更新
AgentIdentityBlueprintPrincipal.Create	BlueprintPrincipal の作成
AgentIdentity.Create.All	Agent Identity の作成
AgentIdentity.ReadWrite.All	Agent Identity の読み取り／更新

Agent Identity 固有の Graph アプリケーション アクセス許可は18 種類あります。すべて確認するには、次のコマンドを実行します。

az ad sp show --id 00000003-0000-0000-c000-000000000000 \
  --query "appRoles[?contains(value, 'AgentIdentity')].{id:id, value:value}" -o json

管理者の同意を付与します（アプリケーションのアクセス許可に必須）。

az ad app permission admin-consent --id <client-id>

サービス プリンシパルがまだレプリケートされていない場合、管理者の同意に失敗し、404 が返ることがあります。10～40 秒のバックオフを入れて再試行してください。

クリーンアップ

# Delete Agent Identity
requests.delete(f"{GRAPH}/servicePrincipals/{agent['id']}", headers=headers)

# Delete BlueprintPrincipal (get SP ID first)
sps = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '{app_id}'",
    headers=headers,
).json()
for sp in sps.get("value", []):
    requests.delete(f"{GRAPH}/servicePrincipals/{sp['id']}", headers=headers)

# Delete Blueprint
requests.delete(f"{GRAPH}/applications/{blueprint_obj_id}", headers=headers)

ベストプラクティス

1. Blueprint の作成後、必ず BlueprintPrincipal を作成してください — 自動作成されないため、両方で冪等性チェックを実装してください
2. スポンサーには User オブジェクトを使用してください — ServicePrincipals と Groups は拒否されます
3. 権限の反映に時間がかかることを考慮してください — 管理者の同意後、30～120 秒待機し、403 が発生した場合はバックオフしながら再試行してください
4. すべての Graph リクエストに OData-Version: 4.0 ヘッダーを含めてください
5. 本番環境の認証には Workload Identity Federation を使用してください — ローカル開発では、Blueprint にクライアントシークレットを使用してください（references/oauth2-token-flow.md を参照）
6. OAuth2 のスコープ設定（api://{app-id}）を使用する前に、Blueprint に identifierUris を設定してください
7. API 呼び出しに Azure CLI のトークンを使用しないでください — これらのトークンには Directory.AccessAsUser.All が含まれており、厳格に拒否されます
8. リソースを作成する前に、既存のリソースを確認してください — 冪等性のあるプロビジョニングを実装してください

参考資料

ファイル	内容
references/oauth2-token-flow.md	本番環境（Managed Identity + WIF）とローカル開発（クライアントシークレット）のトークンフロー
references/known-limitations.md	カテゴリ別にまとめた既知の問題 29 件（公式プレビューの既知の問題ページより）
references/sdk-sidecar.md	AgentID 向け Microsoft Entra SDK — エンドポイント、3P エージェントのパターン、Docker/K8s へのデプロイ、セキュリティ

外部リンク

リソース	URL
公式セットアップガイド	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions
AI ガイド付きセットアップ	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup
AgentID 向け Microsoft Entra SDK — 概要	https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
AgentID 向け Microsoft Entra SDK — エンドポイント	https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/endpoints