用 Microsoft Entra Agent ID 为…

通过 Microsoft Graph 为每个 AI Agent 实例创建独立身份（Blueprint → BlueprintPrincipal → Agent Identity），并配置运行时 OAuth 2.0 令牌交换（fmi_path、OBO、跨租户）。

适用场景

解决思路

1. 使用 `mcp_azure_mcp_documentation` 工具在 Microsoft Learn 上搜索最新的 Agent ID 文档（如 "Microsoft Entra Agent ID setup instructions"、"Microsoft Entra SDK for AgentID"），并对照已安装的 SDK 版本核对请求体与端点，因为 Graph API 结构会演进。
2. 确保拥有以下 Entra 角色之一：Agent Identity Developer、Agent Identity Administrator 或 Application Administrator。
3. PowerShell 交互式安装：`Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force`（PowerShell 7+）。
4. Python 编程式安装：`pip install azure-identity requests`。
5. 不要使用 `DefaultAzureCredential`：Azure CLI 令牌携带 `Directory.AccessAsUser.All`，会被 Agent Identity API 硬拒绝（403）。改用带 `client_credentials` 的专用应用注册，或用 `Connect-MgGraph` 显式指定委派作用域。
6. PowerShell 委派认证：`Connect-MgGraph -Scopes @("AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentityBlueprintPrincipal.Create", "AgentIdentity.Create.All", "User.Read")`。
7. Python 应用认证：用 `ClientSecretCredential`（读取 `AZURE_TENANT_ID`、`AZURE_CLIENT_ID`、`AZURE_CLIENT_SECRET`）获取 `https://graph.microsoft.com/.default` 令牌，并设置请求头 `Authorization: Bearer <token>`、`Content-Type: application/json`、`OData-Version: 4.0`。
8. Step 1 创建 Agent Identity Blueprint：用 `az ad signed-in-user show --query id -o tsv` 获取当前用户 ID，向 `POST {GRAPH}/applications/microsoft.graph.agentIdentityBlueprint` 发送 `{"displayName": ..., "sponsors@odata.bind": ["https://graph.microsoft.com/v1.0/users/{user_id}"]}`。Blueprint 创建时 sponsors 必须是 User。
9. Step 2 创建 BlueprintPrincipal（强制步骤）：向 `POST {GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal` 发送 `{"appId": app_id}`。创建 Blueprint 不会自动创建其服务主体，跳过会报 `400: The Agent Blueprint Principal for the Agent Blueprint does not exist.`。让脚本幂等——即使 Blueprint 已存在也要检查 BlueprintPrincipal。
10. Step 3 创建 Agent Identity：向 `POST {GRAPH}/servicePrincipals/microsoft.graph.agentIdentity` 发送 `{"displayName": ..., "agentIdentityBlueprintId": app_id, "sponsors@odata.bind": [...]}`。Agent Identity 的 sponsors 可以是 User 或 Group。
11. 运行时认证：凭据配置在 Blueprint 上（不是 Agent Identity 上，Agent Identity 不能持有凭据）。生产环境用 Managed Identity + WIF（Federated Identity Credential）；本地开发/测试用 client secret；多语言/三方 Agent 用 Microsoft Entra SDK for AgentID sidecar 容器通过 HTTP 获取令牌。
12. 两步 `fmi_path` 交换（父令牌 → 每个 Agent Identity 的 Graph 令牌）让每个 Agent 实例获得独立的 `sub` 声明和审计轨迹，详见 references/runtime-token-exchange.md；OBO 见 references/obo-blueprint-setup.md；多语言 sidecar 见 references/sdk-sidecar.md；MI+WIF 与 client secret 见 references/oauth2-token-flow.md。
13. 对于 .NET 服务，使用 `Microsoft.Identity.Web.AgentIdentities`，它自动处理 Federated Identity Credential 管理和两步交换。
14. 授予应用权限（自主）：先 `GET {GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'` 获取 Graph SP，找到目标 appRole，再 `POST {GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments` 发送 `{"principalId": agent_sp_id, "resourceId": graph_sp["id"], "appRoleId": ...}`。
15. 授予委派权限（OBO）：`POST {GRAPH}/oauth2PermissionGrants` 发送 `{"clientId": agent_sp_id, "consentType": "AllPrincipals", "resourceId": graph_sp["id"], "scope": "User.Read Tasks.ReadWrite Mail.Send", "expiryTime": ...}`。基于浏览器的管理员同意 URL 对 Agent Identity 无效，必须用 `oauth2PermissionGrants` 进行编程式委派同意。
16. 权限授予按 Agent Identity 作用域，而不是授予 BlueprintPrincipal。
17. 跨租户：Blueprint 可多租户（`signInAudience: AzureADMultipleOrgs`）。父令牌交换的 Step 1 必须指向 Agent Identity 的归属租户，而不是 Blueprint 的租户，否则报 `AADSTS700211: No matching federated identity record found`。
18. 常用 API 端点：创建 Blueprint `POST /applications/microsoft.graph.agentIdentityBlueprint`；创建 BlueprintPrincipal `POST /servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`；创建 Agent Identity `POST /servicePrincipals/microsoft.graph.agentIdentity`；添加 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`。
19. 所需 Graph 权限：`AgentIdentityBlueprint.Create`、`AgentIdentityBlueprint.ReadWrite.All`、`AgentIdentityBlueprintPrincipal.Create`、`AgentIdentity.Create.All`、`AgentIdentity.ReadWrite.All`、`Application.ReadWrite.All`、`AppRoleAssignment.ReadWrite.All`、`DelegatedPermissionGrant.ReadWrite.All`。用 `az ad app permission admin-consent --id <client-id>` 授予管理员同意（应用权限必需）。
20. 最佳实践：始终在 Blueprint 后创建 BlueprintPrincipal；使用类型化端点而非带 `@odata.type` 的原始 `/applications`；凭据放在 Blueprint 上；每个 Graph 请求都带 `OData-Version: 4.0`；生产用 Workload Identity Federation，client secret 仅用于本地开发；在 OAuth2 作用域解析前在 Blueprint 上设置 `identifierUris: ["api://{appId}"]`；绝不用 Azure CLI 令牌；用 `fmi_path` 配 `client_credentials` 而非 RFC 8693 `urn:ietf:params:oauth:grant-type:token-exchange`（会返回 `AADSTS82001`）；两步交换都用 `/.default` 作用域；跨租户时 Step 1 指向 Agent Identity 归属租户；按 Agent Identity 授予权限；管理员同意后处理 30–120 秒的权限传播延迟，对 403 用指数退避重试；Entra SDK for AgentID 保持在 localhost，绝不经 LoadBalancer 或 Ingress 暴露。
21. 故障排查：`AADSTS82001` → 用了 RFC 8693，改用 `client_credentials` + `fmi_path`；`AADSTS700211` → Step 1 父令牌指向错误租户，改指 Agent Identity 归属租户；`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，执行核心工作流 Step 2；管理员同意时 `AADSTS650051` → SP 已因部分同意而存在，直接用 `appRoleAssignments` 授予。

适用边界 · 注意事项

• 标准 Entra 应用注册场景（应使用 entra-app-registration）。
• Microsoft Foundry agent 编写场景（应使用 microsoft-foundry）。