entra-agent-id

Microsoft Entra Agent ID

使用 Microsoft Graph 为 AI Agent 创建和管理支持 OAuth 2.0 的身份。每个 Agent 实例都有独立的身份、审计跟踪，以及作用范围独立的权限授权。

快速参考

属性	值
服务	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）
运行时交换	两步 fmi_path 交换（自主和 OBO）
.NET 助手	Microsoft.Identity.Web.AgentIdentities
多语言助手	Microsoft Entra SDK for AgentID（边车容器）

何时使用此技能

• 预配新的 Agent Identity Blueprint 和 BlueprintPrincipal
• 在 Blueprint 下为每个实例创建 Agent Identity
• 在 Blueprint 上配置凭据（FIC、Managed Identity 或客户端密钥）
• 实现两步 fmi_path 运行时令牌交换（自主或 OBO）
• 跨租户 Agent 令牌流
• 为多语言 Agent（Python、Node、Go、Java）部署 Microsoft Entra SDK for AgentID 边车
• 授予每个 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 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	定义 Agent 类型/类别的应用程序对象。保存凭据（密钥、证书、联合身份）。
BlueprintPrincipal	Blueprint 在租户中的服务主体。不会自动创建。
Agent Identity	单个 Agent 实例专用的服务主体身份。不能保存自己的凭据。
Sponsor	对该身份负责的用户（对于 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 时，Sponsor 必须是用户。此代码片段假设使用上方 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：创建 Agent 身份

Agent 身份的赞助者可以是用户或组。

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"]

运行时身份验证

Agent 在运行时使用配置在蓝图上的凭据进行身份验证（而非 Agent 身份上的凭据——Agent 身份无法持有凭据）。

选项	使用场景	蓝图上的凭据
托管标识 + WIF	生产环境（托管于 Azure）	联合身份凭据
客户端密码	本地开发 / 测试	密码凭据
Microsoft Entra SDK for AgentID	多语言 / 第三方 Agent	Sidecar 容器通过 HTTP 获取令牌

有关两步 fmi_path 交换（父令牌 → 每个 Agent 身份的 Graph 令牌）的详细信息，请参阅 references/runtime-token-exchange.md。该交换会为每个 Agent 实例提供不同的 sub 声明和审计跟踪。

有关 OBO（Agent 代表用户行事），请参阅 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 身份）

Agent 身份支持应用程序权限（自主运行）和委派权限（OBO）。授权范围为每个 Agent 身份，而非 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 身份——请使用 oauth2PermissionGrants 以编程方式授予委派同意。

跨租户 Agent 身份

蓝图可以是多租户的（signInAudience: AzureADMultipleOrgs）。跨租户交换令牌时：

父令牌交换的步骤 1 必须以 Agent 身份的主租户为目标，而非蓝图的主租户。租户错误 → AADSTS700211: No matching federated identity record found。

有关完整的跨租户示例，请参阅 references/runtime-token-exchange.md。

API 参考

操作	方法	端点
创建蓝图	POST	/applications/microsoft.graph.agentIdentityBlueprint
创建 BlueprintPrincipal	POST	/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
创建 Agent 身份	POST	/servicePrincipals/microsoft.graph.agentIdentity
将 FIC 添加到蓝图	POST	/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials
列出 Agent 身份	GET	/servicePrincipals/microsoft.graph.agentIdentity
授予应用程序权限	POST	/servicePrincipals/{id}/appRoleAssignments
授予委派权限	POST	/oauth2PermissionGrants
删除 Agent 身份	DELETE	/servicePrincipals/{id}
删除蓝图	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. 绝不使用 Azure CLI 令牌调用 Agent Identity API — 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. 按 Agent Identity 授予权限，而不是授予 BlueprintPrincipal。
12. 处理权限传播延迟 — 管理员同意后，出现 403 错误时使用 30–120 秒退避重试。
13. 将用于 AgentID 的 Entra SDK 保留在 localhost 上 — 绝不要通过 LoadBalancer 或 Ingress 对外公开。

故障排除

错误	原因	修复方法
AADSTS82001	使用了 RFC 8693 token-exchange 授权类型	使用带 fmi_path 的 client_credentials
AADSTS700211	步骤 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	执行核心工作流的步骤 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 配置为用于 OBO 的 OAuth2 API
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