Microsoft Entra Agent ID

Microsoft Graph を使用して AI エージェント用の OAuth 2.0 対応 ID を作成・管理します。すべてのエージェント インスタンスには異なる ID、監査証跡、および独立したスコープの権限付与が割り当てられます。

クイック リファレンス

プロパティ	値
サービス	Microsoft Entra Agent ID
API	Microsoft Graph (https://graph.microsoft.com/v1.0)
必須ロール	Agent Identity Developer、Agent Identity Administrator、または Application Administrator
オブジェクト モデル	Blueprint (application) → BlueprintPrincipal (SP) → Agent Identity (SP)
ランタイム交換	2 ステップの fmi_path 交換 (自律および OBO)
.NET ヘルパー	Microsoft.Identity.Web.AgentIdentities
ポリグロット ヘルパー	Microsoft Entra SDK for AgentID (サイドカー コンテナ)

このスキルを使用する場合

• 新しい Agent Identity Blueprint および BlueprintPrincipal をプロビジョニングする場合
• Blueprint 内に per-instance Agent Identities を作成する場合
• Blueprint 上に資格情報 (FIC、Managed Identity、またはクライアント シークレット) を構成する場合
• 2 ステップの fmi_path ランタイム トークン交換 (自律または OBO) を実装する場合
• クロステナント エージェント トークン フロー
• ポリグロット エージェント (Python、Node、Go、Java) 用に Microsoft Entra SDK for AgentID サイドカー をデプロイする場合
• Agent Identity ごとのアプリケーション (appRoleAssignments) または委譲 (oauth2PermissionGrants) の権限を付与する場合
• AADSTS82001、AADSTS700211、または PropertyNotCompatibleWithAgentIdentity などの Agent ID エラーを診断する場合

MCP ツール

ツール	用途
mcp_azure_mcp_documentation	Microsoft Learn で現在の Agent ID セットアップ、Graph API スキーマ、および SDK 構成を検索します

現在、専用の Agent Identity MCP サーバーはありません。このスキルは直接 Microsoft Graph API 呼び出し (PowerShell または Python requests) をガイドします。実行前に mcp_azure_mcp_documentation を使用して、要求本体とエンドポイントを現在のドキュメントに対して検証してください。

開始する前に

mcp_azure_mcp_documentation ツールを使用して Microsoft Learn で現在の Agent ID ドキュメントを検索します。

• "Microsoft Entra Agent ID setup instructions"
• "Microsoft Entra SDK for AgentID"

インストール済みの SDK バージョンに対して要求本体とエンドポイントを検証します — Graph API スキーマは進化します。

概念モデル

Agent Identity Blueprint (application)         ← エージェント タイプ/プロジェクトごとに 1 つ
  └── BlueprintPrincipal (service principal)    ← 明示的に作成する必要があります
        ├── Agent Identity (SP): agent-1        ← エージェント インスタンスごとに 1 つ
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

概念	説明
Blueprint	エージェントのタイプ/クラスを定義するアプリケーション オブジェクトです。資格情報 (シークレット、証明書、フェデレーション ID) を保持します。
BlueprintPrincipal	テナント内の Blueprint のサービス プリンシパルです。自動作成されません。
Agent Identity	単一のエージェント インスタンス用のサービス プリンシパル専用の ID です。独自の資格情報を保持することができません。
Sponsor	ID の責任者である User (または Agent Identity の場合は Group) です。作成時に必須です。

前提条件

必須 Entra ロール

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

PowerShell (インタラクティブ セットアップ)

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

Python (プログラマティック プロビジョニング)

pip install azure-identity requests

認証

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",
    "AgentIdentity.Create.All",
    "User.Read"
)

Python (アプリケーション)

import os, 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/v1.0"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",
}

コア ワークフロー

ステップ 1: Agent Identity Blueprint を作成する

型指定されたエンドポイントを使用します。Sponsor は Blueprint 作成時に Users である必要があります。このスニペットは、上記の Python 認証ブロックの requests クライアントおよび headers dict を想定しています。

import subprocess
import requests

user_id = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
).stdout.strip()

blueprint_body = {
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/v1.0/users/{user_id}"
    ],
}
resp = requests.post(
    f"{GRAPH}/applications/microsoft.graph.agentIdentityBlueprint",
    headers=headers, json=blueprint_body,
)
resp.raise_for_status()

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

ステップ 2: BlueprintPrincipal を作成する

必須です。Blueprint を作成してもサービス プリンシパルは自動作成されません。このステップをスキップするとエラーが生じます。 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {"appId": app_id}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal",
    headers=headers, json=sp_body,
)
resp.raise_for_status()

プロビジョニング スクリプトをべき等にします — Blueprint が既に存在する場合でも、常に BlueprintPrincipal をチェックしてください。

ステップ 3: Agent Identities を作成する

Agent Identity の Sponsor は Users または Groups です。

agent_body = {
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/v1.0/users/{user_id}"
    ],
}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentity",
    headers=headers, json=agent_body,
)
resp.raise_for_status()
agent = resp.json()
agent_sp_id = agent["id"]

ランタイム認証

エージェントはランタイムで Blueprint (Agent Identity ではなく) に構成された資格情報を使用して認証します — Agent Identities は秘密/証明書を保持することができません (PropertyNotCompatibleWithAgentIdentity)。

オプション	ユースケース	Blueprint の資格情報
Managed Identity + WIF	本番環境 (Azure ホスト)	Federated Identity Credential
クライアント シークレット	ローカル dev/テスト	Password credential
Microsoft Entra SDK for AgentID	ポリグロット/3P エージェント	サイドカー コンテナが HTTP 経由でトークンを取得

各エージェント インスタンスに異なる sub クレームと監査証跡を与える 2 ステップの fmi_path 交換 (親トークン → Agent Identity ごとの Graph トークン) については、references/runtime-token-exchange.md を参照してください。

OBO (エージェントがユーザーに代わって行動) については、references/obo-blueprint-setup.md を参照してください。

コンテナ化されたポリグロット認証サイドカー (Python、Node、Go、Java — SDK 埋め込みなし) については、references/sdk-sidecar.md を参照してください。

MI+WIF およびクライアント シークレット セットアップの詳細については、references/oauth2-token-flow.md を参照してください。

.NET クイック パス

.NET サービスの場合は、Microsoft.Identity.Web.AgentIdentities を使用してください — Federated Identity Credential 管理と 2 ステップ交換を処理します。github.com/AzureAD/microsoft-identity-web の src/Microsoft.Identity.Web.AgentIdentities/ にあるパッケージ README を参照してください。

権限の付与 (Agent Identity ごと)

Agent Identities はアプリケーション権限 (自律) と委譲権限 (OBO) の両方をサポートします。付与は BlueprintPrincipal ではなく、Agent Identity ごと にスコープされます。

アプリケーション権限 (自律)

graph_sp = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'",
    headers=headers,
).json()["value"][0]

user_read_all = next(r for r in graph_sp["appRoles"] if r["value"] == "User.Read.All")

requests.post(
    f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments",
    headers=headers,
    json={
        "principalId": agent_sp_id,
        "resourceId": graph_sp["id"],
        "appRoleId": user_read_all["id"],
    },
).raise_for_status()

委譲権限 (OBO)

from datetime import datetime, timedelta, timezone

expiry = (datetime.now(timezone.utc) + timedelta(days=3650)).strftime("%Y-%m-%dT%H:%M:%SZ")

requests.post(
    f"{GRAPH}/oauth2PermissionGrants",
    headers=headers,
    json={
        "clientId": agent_sp_id,
        "consentType": "AllPrincipals",
        "resourceId": graph_sp["id"],
        "scope": "User.Read Tasks.ReadWrite Mail.Send",
        "expiryTime": expiry,
    },
).raise_for_status()

ブラウザ ベースの管理者同意 URL は Agent Identities では機能しません — プログラマティック委譲同意に oauth2PermissionGrants を使用してください。

クロステナント Agent Identities

Blueprint はマルチテナント (signInAudience: AzureADMultipleOrgs) にすることができます。クロステナント トークンを交換する場合:

親トークン交換のステップ 1 は Agent Identity のホーム テナント (Blueprint のテナントではなく) をターゲットにする必要があります。間違ったテナント → AADSTS700211: No matching federated identity record found。

完全なクロステナント例については、references/runtime-token-exchange.md を参照してください。

API リファレンス

操作	メソッド	エンドポイント
Blueprint を作成	POST	/applications/microsoft.graph.agentIdentityBlueprint
BlueprintPrincipal を作成	POST	/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
Agent Identity を作成	POST	/servicePrincipals/microsoft.graph.agentIdentity
Blueprint に FIC を追加	POST	/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials
Agent Identities をリスト	GET	/servicePrincipals/microsoft.graph.agentIdentity
アプリ権限を付与	POST	/servicePrincipals/{id}/appRoleAssignments
委譲権限を付与	POST	/oauth2PermissionGrants
Agent Identity を削除	DELETE	/servicePrincipals/{id}
Blueprint を削除	DELETE	/applications/{id}

ベース URL: https://graph.microsoft.com/v1.0。

必須 Graph 権限

権限	目的
AgentIdentityBlueprint.Create	Blueprint を作成
AgentIdentityBlueprint.ReadWrite.All	Blueprint を読み取り/更新
AgentIdentityBlueprintPrincipal.Create	BlueprintPrincipal を作成
AgentIdentity.Create.All	Agent Identities を作成
AgentIdentity.ReadWrite.All	Agent Identities を読み取り/更新
Application.ReadWrite.All	Blueprint CRUD (アプリケーション オブジェクト)
AppRoleAssignment.ReadWrite.All	アプリケーション権限を付与
DelegatedPermissionGrant.ReadWrite.All	委譲権限を付与

管理者同意を付与します (アプリケーション権限に必須):

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

管理者同意後、トークンに新しいクレームが含まれるまで 30–120 秒かかる場合があります — エクスポーネンシャル バックオフで再試行してください。

ベスト プラクティス

1. Blueprint 後に必ず BlueprintPrincipal を作成 — 自動作成されません。
2. 型指定されたエンドポイント (/applications/microsoft.graph.agentIdentityBlueprint) を使用 — @odata.type を持つ生の /applications ではなく。
3. 資格情報は Blueprint に属する — Agent Identities は秘密/証明書を保持することができません (PropertyNotCompatibleWithAgentIdentity)。
4. すべての Graph 要求に OData-Version: 4.0 を含める。
5. 本番環境に Workload Identity Federation を使用 — クライアント シークレットはローカル dev のみ。
6. Blueprint に identifierUris: ["api://{appId}"] を設定 (OAuth2 スコープ解決前)。
7. Agent Identity API に Azure CLI トークンを使用しない — Directory.AccessAsUser.All は硬い 403 を引き起こします。
8. fmi_path を client_credentials で使用 — RFC 8693 urn:ietf:params:oauth:grant-type:token-exchange ではない (AADSTS82001 を返します)。
9. 交換の両ステップで常に /.default スコープを使用 — 個別スコープは失敗します。
10. ステップ 1 はクロステナント フローで Agent Identity のホーム テナントをターゲットに。
11. BlueprintPrincipal ではなく Agent Identity ごと に権限を付与。
12. 権限伝播遅延を処理 — 管理者同意後、30–120s バックオフで 403 を再試行します。
13. Entra SDK for AgentID をローカルホストに保つ — LoadBalancer または Ingress 経由で公開しないでください。

トラブルシューティング

エラー	原因	修正
AADSTS82001	RFC 8693 トークン交換グラントを使用	client_credentials を fmi_path で使用
AADSTS700211	ステップ 1 の親トークンが間違ったテナントをターゲット	Agent Identity のホーム テナントをターゲット
AADSTS50013	OBO ユーザー トークンが Blueprint ではなく Graph をターゲット	api://{blueprint_app_id}/access_as_user を使用
AADSTS65001	グラントがない、または個別スコープを使用	/.default を使用し、oauth2PermissionGrants を検証
403 Authorization_RequestDenied	この Agent Identity にグラントがない	appRoleAssignments または oauth2PermissionGrants で追加
PropertyNotCompatibleWithAgentIdentity	Agent Identity SP に資格情報を追加しようとした	資格情報を Blueprint に配置
Agent Blueprint Principal does not exist	BlueprintPrincipal が作成されていない	コア ワークフローのステップ 2
AADSTS650051 (管理者同意)	SP は部分的な同意から既に存在	appRoleAssignments 経由で直接付与

リファレンス

ファイル	内容
references/runtime-token-exchange.md	2 ステップの fmi_path 交換: 自律 + OBO、クロステナント
references/oauth2-token-flow.md	MI + WIF (本番環境) およびクライアント シークレット (ローカル dev)
references/obo-blueprint-setup.md	OBO の OAuth2 API として Blueprint を構成
references/sdk-sidecar.md	Microsoft Entra SDK for AgentID — アーキテクチャ、構成、エンドポイント
references/sdk-sidecar-deployment.md	SDK コード パターン (Python/TypeScript)、Docker/Kubernetes マニフェスト、セキュリティ、トラブルシューティング
references/known-limitations.md	カテゴリ別に整理されたドキュメント化されたギャップ

外部リンク

リソース	URL
Agent ID セットアップ ガイド	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
Microsoft Entra SDK for AgentID	https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
Microsoft.Identity.Web.AgentIdentities (.NET)	https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md