entra-agent-id

Microsoft Entra Agent ID

Microsoft Graph を使用して、OAuth 2.0 に対応した AI エージェントの ID を作成・管理します。各エージェントインスタンスには、個別の ID、監査証跡、独立したスコープのアクセス許可が付与されます。

クイックリファレンス

プロパティ	値
サービス	Microsoft Entra Agent ID
API	Microsoft Graph (https://graph.microsoft.com/v1.0)
必要なロール	Agent Identity Developer、Agent Identity Administrator、または Application Administrator
オブジェクトモデル	Blueprint（アプリケーション）→ BlueprintPrincipal（SP）→ Agent Identity（SP）
ランタイム交換	2 段階の fmi_path 交換（自律型および OBO）
.NET ヘルパー	Microsoft.Identity.Web.AgentIdentities
マルチ言語対応ヘルパー	Microsoft Entra SDK for AgentID（サイドカーコンテナー）

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

• 新しい Agent Identity Blueprint と BlueprintPrincipal のプロビジョニング
• Blueprint 配下でのインスタンスごとの Agent Identity の作成
• 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)         ← 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

概念	説明
Blueprint	エージェントの種類／クラスを定義するアプリケーションオブジェクトです。資格情報（シークレット、証明書、フェデレーション ID）を保持します。
BlueprintPrincipal	テナント内の Blueprint のサービスプリンシパルです。自動作成されません。
Agent Identity	単一のエージェントインスタンス専用のサービスプリンシパル ID です。独自の資格情報は保持できません。
スポンサー	ID に責任を持つユーザー（Agent Identity の場合はグループ）です。作成時に必須です。

前提条件

必要な 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 を作成する

型指定されたエンドポイントを使用してください。Blueprint の作成時、スポンサーはユーザーである必要があります。このスニペットでは、上記の Python 認証ブロックで定義した requests クライアントと headers 辞書を使用します。

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",
    "[email protected]": [
        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：エージェント ID を作成する

エージェント ID のスポンサーには、ユーザーまたはグループを指定できます。

agent_body = {
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "[email protected]": [
        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 Identity には設定しません）。

オプション	ユースケース	Blueprint の資格情報
Managed Identity + WIF	本番環境（Azure でホスト）	Federated Identity Credential
クライアントシークレット	ローカル開発／テスト	パスワード資格情報
Microsoft Entra SDK for AgentID	複数言語対応／サードパーティ製エージェント	サイドカ―コンテナーが 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 段階の交換を自動で処理します。パッケージの README は github.com/AzureAD/microsoft-identity-web の src/Microsoft.Identity.Web.AgentIdentities/ にあります。

アクセス許可の付与（Agent Identity ごと）

Agent Identity は、アプリケーションのアクセス許可（自律動作）と委任されたアクセス許可（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 Identity では機能しません。プログラムによる委任されたアクセス許可への同意には、oauth2PermissionGrants を使用してください。

テナント間の Agent Identity

Blueprint はマルチテナントにできます（signInAudience: AzureADMultipleOrgs）。テナント間でトークンを交換する場合：

親トークン交換のステップ 1 では、Blueprint のテナントではなく、Agent Identity のホームテナントを必ず指定してください。 テナントが間違っている場合、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 Identity の一覧を取得	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 Identity を作成する
AgentIdentity.ReadWrite.All	Agent Identity を読み取り／更新する
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 Identity にシークレットや証明書を保持することはできません（PropertyNotCompatibleWithAgentIdentity）。
4. すべての Graph リクエストに OData-Version: 4.0 を含めてください。
5. 本番環境では Workload Identity Federation を使用してください — クライアントシークレットはローカル開発専用です。
6. OAuth2 スコープの解決前に、Blueprint に identifierUris: ["api://{appId}"] を設定してください。
7. Agent Identity API には Azure CLI のトークンを使用しないでください — Directory.AccessAsUser.All により、必ず403エラーになります。
8. client_credentials では fmi_path を使用してください — RFC 8693 の urn:ietf:params:oauth:grant-type:token-exchange は使用しないでください（AADSTS82001 が返されます）。
9. 交換の両方のステップで必ず /.default スコープを使用してください — 個別のスコープでは失敗します。
10. クロステナントフローでは、ステップ1の対象を Agent Identity のホームテナントにしてください。
11. BlueprintPrincipal ではなく、Agent Identity ごとにアクセス許可を付与してください。
12. アクセス許可の反映遅延に対応してください — 管理者の同意後、30～120秒のバックオフを設けて403エラーを再試行してください。
13. AgentID 用 Entra SDK は localhost 上で使用してください — LoadBalancer や Ingress を介して公開しないでください。

トラブルシューティング

エラー	原因	対処方法
AADSTS82001	RFC 8693 の token-exchange grant を使用した	fmi_path を指定した client_credentials を使用する
AADSTS700211	ステップ1の親トークンの対象テナントが間違っている	Agent Identity のホームテナントを対象にする
AADSTS50013	OBO ユーザートークンの対象が Blueprint ではなく Graph になっている	api://{blueprint_app_id}/access_as_user を使用する
AADSTS65001	grant がないか、個別のスコープを使用した	/.default を使用し、oauth2PermissionGrants を確認する
403 Authorization_RequestDenied	この Agent Identity に grant がない	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（本番環境）、クライアントシークレット（ローカル開発）
references/obo-blueprint-setup.md	OBO 用の OAuth2 API として Blueprint を構成する方法
references/sdk-sidecar.md	AgentID 用 Microsoft Entra SDK — アーキテクチャ、構成、エンドポイント
references/sdk-sidecar-deployment.md	SDK のコードパターン（Python/TypeScript）、Docker/Kubernetes マニフェスト、セキュリティ、トラブルシューティング
references/known-limitations.md	カテゴリ別に整理した既知の不足事項

外部リンク

リソース	URL
エージェント 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
AgentID 用 Microsoft Entra SDK	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