entra-agent-id

Microsoft Entra Agent ID

使用 Microsoft Graph 建立及管理具備 OAuth 2.0 能力的 AI 代理身分識別。每個代理執行個體都有獨立的身分識別、稽核軌跡及獨立範圍的權限授權。

快速參考

屬性	值
服務	Microsoft Entra Agent ID
API	Microsoft Graph (https://graph.microsoft.com/v1.0)
必要角色	Agent Identity Developer、Agent Identity Administrator 或 Application Administrator
物件模型	Blueprint (應用程式) → BlueprintPrincipal (服務主體) → Agent Identity (服務主體)
執行階段交換	兩步驟 fmi_path 交換（自主與 OBO）
.NET 輔助程式	Microsoft.Identity.Web.AgentIdentities
多語言輔助程式	適用於 AgentID 的 Microsoft Entra SDK（Sidecar 容器）

何時使用此技能

• 佈建新的 Agent Identity Blueprint 與 BlueprintPrincipal
• 在 Blueprint 下建立每個執行個體的 Agent Identity
• 在 Blueprint 上設定憑證（FIC、受控識別或用戶端密碼）
• 實作兩步驟 fmi_path 執行階段權杖交換（自主或 OBO）
• 跨租用戶代理權杖流程
• 為多語言代理（Python、Node、Go、Java）部署適用於 AgentID 的 Microsoft Entra SDK Sidecar
• 授予每個 Agent Identity 的應用程式權限（appRoleAssignments）或委派權限（oauth2PermissionGrants）
• 診斷 Agent ID 錯誤，例如 AADSTS82001、AADSTS700211 或 PropertyNotCompatibleWithAgentIdentity

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 設定指示"
• "適用於 AgentID 的 Microsoft Entra SDK"

根據安裝的 SDK 版本驗證要求主體與端點 — Graph API 形狀會隨時間演進。

概念模型

Agent Identity Blueprint (應用程式)         ← 每個代理類型/專案一個
  └── BlueprintPrincipal (服務主體)    ← 必須明確建立
        ├── Agent Identity (SP): agent-1    ← 每個代理執行個體一個
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

概念	說明
Blueprint	定義代理類型/類別的應用程式物件。持有憑證（密碼、憑證、同盟身分識別）。
BlueprintPrincipal	Blueprint 在租用戶中的服務主體。不會自動建立。
Agent Identity	單一代理執行個體的僅服務主體身分識別。無法持有自己的憑證。
贊助者	負責該身分識別的使用者（或 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",
    "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 Identity

Agent Identity 的贊助者可以是使用者或群組。

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 Identity 無法持有憑證）。

選項	使用案例	Blueprint 上的憑證
受控識別 + WIF	生產環境（Azure 託管）	同盟身分識別憑證
用戶端密碼	本機開發/測試	密碼憑證
適用於 AgentID 的 Microsoft Entra SDK	多語言/第三方代理	Sidecar 容器透過 HTTP 取得權杖

關於兩步驟 fmi_path 交換（父權杖 → 每個 Agent Identity 的 Graph 權杖），可為每個代理執行個體提供不同的 sub 宣告與稽核軌跡，請參閱 references/runtime-token-exchange.md。

關於 OBO（代理代表使用者行動），請參閱 references/obo-blueprint-setup.md。

關於容器化的多語言驗證 Sidecar（Python、Node、Go、Java — 無需嵌入 SDK），請參閱 references/sdk-sidecar.md。

關於 MI+WIF 與用戶端密碼設定的詳細資訊，請參閱 references/oauth2-token-flow.md。

.NET 快速路徑

對於 .NET 服務，請使用 Microsoft.Identity.Web.AgentIdentities — 它會為您處理同盟身分識別憑證管理與兩步驟交換。請參閱 github.com/AzureAD/microsoft-identity-web 下 src/Microsoft.Identity.Web.AgentIdentities/ 的套件 README。

授予權限（每個 Agent Identity）

Agent Identity 支援應用程式權限（自主）與委派權限（OBO）。授權範圍為每個 Agent Identity，而非 BlueprintPrincipal。

應用程式權限（自主）

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 必須指向 Agent Identity 的 home 租用戶，而非 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
新增 FIC 至 Blueprint	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）而非原始 /applications 搭配 @odata.type。
3. 憑證存放在 Blueprint 上 — Agent Identity 無法持有密碼/憑證（PropertyNotCompatibleWithAgentIdentity）。
4. 在每個 Graph 要求中包含 OData-Version: 4.0。
5. 在生產環境中使用工作負載身分識別同盟 — 用戶端密碼僅用於本機開發。
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 的 home 租用戶。
11. 為每個 Agent Identity 授予權限，而非授予 BlueprintPrincipal。
12. 處理權限傳播延遲 — 在管理員同意後，對 403 錯誤使用 30–120 秒的退避重試。
13. 將適用於 AgentID 的 Entra SDK 保留在本機 — 切勿透過 LoadBalancer 或 Ingress 公開。

疑難排解

錯誤	原因	修正
AADSTS82001	使用了 RFC 8693 token-exchange 授權類型	使用 client_credentials 搭配 fmi_path
AADSTS700211	步驟 1 父權杖指向錯誤的租用戶	指向 Agent Identity 的 home 租用戶
AADSTS50013	OBO 使用者權杖指向 Graph，而非 Blueprint	使用 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	兩步驟 fmi_path 交換：自主 + OBO、跨租用戶
references/oauth2-token-flow.md	MI + WIF（生產環境）與用戶端密碼（本機開發）
references/obo-blueprint-setup.md	將 Blueprint 設定為 OAuth2 API 以用於 OBO
references/sdk-sidecar.md	適用於 AgentID 的 Microsoft Entra SDK — 架構、設定、端點
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
適用於 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