entra-agent-id

Microsoft Entra Agent ID

使用 Microsoft Graph beta API 为 AI Agent 创建和管理支持 OAuth2 的身份。

预览版 API — 所有 Agent Identity 端点仅位于 /beta 下，不适用于 /v1.0。

开始之前

在 microsoft-docs MCP 中搜索最新的 Agent ID 文档：

• 查询：“Microsoft Entra agent identity setup”
• 验证：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

先决条件

PowerShell（交互式设置推荐）

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

Python（用于程序化预配）

pip install azure-identity requests

所需的 Entra 角色

以下角色之一：Agent Identity Developer、Agent Identity Administrator 或 Application Administrator。

环境变量

AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<app-registration-client-id>
AZURE_CLIENT_SECRET=<app-registration-secret>

身份验证

⚠️ 不支持 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",
    "User.Read"
)
Set-MgRequestContext -ApiVersion beta

$currentUser = (Get-MgContext).Account
$userId = (Get-MgUser -UserId $currentUser).Id

Python（应用程序权限）

import os
import 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/beta"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",  # Required for all Agent Identity API calls
}

核心工作流

第 1 步：创建 Agent Identity Blueprint

必须指定发起者，且其必须是 User 对象——ServicePrincipals 和 Groups 均会被拒绝。

import subprocess

# Get sponsor user ID (client_credentials has no user context, so use az CLI)
result = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
)
user_id = result.stdout.strip()

blueprint_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "[email protected]": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/applications", headers=headers, json=blueprint_body)
resp.raise_for_status()

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

第 2 步：创建 BlueprintPrincipal

此步骤为必需步骤。 创建 Blueprint 不会自动创建其 服务主体。若未执行此步骤，创建 Agent Identity 将失败，并显示错误： 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprintPrincipal",
    "appId": app_id,
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=sp_body)
resp.raise_for_status()

如果要实现幂等脚本，即使 Blueprint 已存在，也要检查并创建 BlueprintPrincipal （之前的运行可能已创建 Blueprint，但在创建 SP 之前发生崩溃）。

第 3 步：创建 Agent Identities

agent_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentity",
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "[email protected]": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=agent_body)
resp.raise_for_status()
agent = resp.json()

API 参考

操作	方法	端点	OData 类型
创建 Blueprint	POST	/applications	Microsoft.Graph.AgentIdentityBlueprint
创建 BlueprintPrincipal	POST	/servicePrincipals	Microsoft.Graph.AgentIdentityBlueprintPrincipal
创建 Agent Identity	POST	/servicePrincipals	Microsoft.Graph.AgentIdentity
列出 Agent Identities	GET	/servicePrincipals?$filter=...	—
删除 Agent Identity	DELETE	/servicePrincipals/{id}	—
删除 Blueprint	DELETE	/applications/{id}	—

所有端点使用的基础 URL：https://graph.microsoft.com/beta

所需权限

权限	用途
Application.ReadWrite.All	Blueprint CRUD（应用程序对象）
AgentIdentityBlueprint.Create	创建新的 Blueprint
AgentIdentityBlueprint.ReadWrite.All	读取/更新 Blueprint
AgentIdentityBlueprintPrincipal.Create	创建 BlueprintPrincipal
AgentIdentity.Create.All	创建 Agent Identity
AgentIdentity.ReadWrite.All	读取/更新 Agent Identity

共有 18 项 Agent Identity 专属 Graph 应用程序权限。发现所有权限：

az ad sp show --id 00000003-0000-0000-c000-000000000000 \
  --query "appRoles[?contains(value, 'AgentIdentity')].{id:id, value:value}" -o json

授予管理员同意（应用程序权限所必需）：

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

如果服务主体尚未完成复制，管理员同意可能会因 404 而失败。请以 10–40 秒的退避间隔重试。

清理

# Delete Agent Identity
requests.delete(f"{GRAPH}/servicePrincipals/{agent['id']}", headers=headers)

# Delete BlueprintPrincipal (get SP ID first)
sps = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '{app_id}'",
    headers=headers,
).json()
for sp in sps.get("value", []):
    requests.delete(f"{GRAPH}/servicePrincipals/{sp['id']}", headers=headers)

# Delete Blueprint
requests.delete(f"{GRAPH}/applications/{blueprint_obj_id}", headers=headers)

最佳实践

1. 始终在 Blueprint 之后创建 BlueprintPrincipal — 不会自动创建；请为两者实现幂等性检查
2. 使用 User 对象作为赞助方 — ServicePrincipals 和 Groups 会被拒绝
3. 处理权限传播延迟 — 管理员同意后，等待 30–120s；遇到 403 时采用退避策略重试
4. 在每个 Graph 请求中都包含 OData-Version: 4.0 标头
5. 在生产环境中使用 Workload Identity Federation 进行身份验证 — 本地开发时，在 Blueprint 上使用客户端密钥（参见 references/oauth2-token-flow.md）
6. 在使用 OAuth2 作用域之前，在 Blueprint 上设置 identifierUris（api://{app-id}）
7. 绝不要将 Azure CLI 令牌用于 API 调用 — 它们包含 Directory.AccessAsUser.All，会被直接拒绝
8. 创建前检查是否已有资源 — 实现幂等性配置

参考资料

文件	内容
references/oauth2-token-flow.md	生产环境（Managed Identity + WIF）和本地开发（客户端密钥）的令牌流
references/known-limitations.md	按类别整理的 29 个已知问题（摘自官方预览版已知问题页面）
references/sdk-sidecar.md	用于 AgentID 的 Microsoft Entra SDK — 端点、3P Agent 模式、Docker/K8s 部署、安全性

外部链接

资源	URL
官方设置指南	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
用于 AgentID 的 Microsoft Entra SDK — 端点	https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/endpoints