entra-agent-user

SKILL：在 Microsoft Entra Agent ID 中创建 Agent 用户

概述

Agent 用户是 Microsoft Entra ID 中的一种专用用户身份，使 AI Agent 能够充当数字员工。它允许 Agent 访问严格需要用户身份的 API 和服务（例如 Exchange 邮箱、Teams、组织架构图），同时保持适当的安全边界。

Agent 用户收到的令牌带有 idtyp=user，而常规 Agent 身份收到的令牌带有 idtyp=app。

---

先决条件

• 一个具备 Agent ID 功能的 Microsoft Entra 租户
• 一个从 Agent 身份蓝图创建的 Agent 身份（类型为 ServiceIdentity 的服务主体）
• 以下权限之一：
  • AgentIdUser.ReadWrite.IdentityParentedBy（最小特权）
  • AgentIdUser.ReadWrite.All
  • User.ReadWrite.All
• 调用方必须至少具有 Agent ID 管理员角色（在委托场景中）

重要： identityParentId 必须引用真正的 Agent 身份（通过 Agent 身份蓝图创建），而不是常规的应用程序服务主体。你可以通过检查该服务主体是否具有 @odata.type: #microsoft.graph.agentIdentity 和 servicePrincipalType: ServiceIdentity 来验证。

---

架构

Agent Identity Blueprint (application template)
    │
    ├── Agent Identity (service principal - ServiceIdentity)
    │       │
    │       └── Agent User (user - agentUser) ← 1:1 relationship
    │
    └── Agent Identity Blueprint Principal (service principal in tenant)

组件	类型	令牌声明	用途
Agent 身份	服务主体	idtyp=app	后端/API 操作
Agent 用户	用户（agentUser）	idtyp=user	在 M365 中充当数字员工

---

步骤 1：验证 Agent 身份是否存在

在创建 Agent 用户之前，确认该 Agent 身份是正确类型的 agentIdentity：

GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id}
Authorization: Bearer <token>

验证响应中包含：

{
  "@odata.type": "#microsoft.graph.agentIdentity",
  "servicePrincipalType": "ServiceIdentity",
  "agentIdentityBlueprintId": "<blueprint-id>"
}

PowerShell

Connect-MgGraph -Scopes "Application.Read.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome
Invoke-MgGraphRequest -Method GET `
  -Uri "https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-id>" | ConvertTo-Json -Depth 3

常见错误： 使用应用注册的 appId 或常规应用程序服务主体的 id 会失败。只有从蓝图创建的 Agent 身份才有效。

---

步骤 2：创建 Agent 用户

HTTP 请求

POST https://graph.microsoft.com/beta/users/microsoft.graph.agentUser
Content-Type: application/json
Authorization: Bearer <token>

{
  "accountEnabled": true,
  "displayName": "My Agent User",
  "mailNickname": "my-agent-user",
  "userPrincipalName": "[email protected]",
  "identityParentId": "<agent-identity-object-id>"
}

必需属性

属性	类型	描述
accountEnabled	布尔值	true 表示启用该账户
displayName	字符串	便于人类识别的名称
mailNickname	字符串	邮件别名（不能包含空格/特殊字符）
userPrincipalName	字符串	UPN — 必须在租户中唯一（alias@verified-domain）
identityParentId	字符串	父 Agent 身份的对象 ID

PowerShell

Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "[email protected]"
  identityParentId  = "<agent-identity-object-id>"
} | ConvertTo-Json

Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/microsoft.graph.agentUser" `
  -Body $body -ContentType "application/json" | ConvertTo-Json -Depth 3

关键说明

• 没有密码 — Agent 用户不能设置密码。它们通过其父 Agent 身份的凭据进行身份验证。
• 1:1 关系 — 每个 Agent 身份最多只能有一个 Agent 用户。尝试创建第二个会返回 400 Bad Request。
• userPrincipalName 必须唯一。不要复用现有用户的 UPN。

---

步骤 3：分配经理（可选）

分配经理可使该 Agent 用户出现在组织架构图中（例如 Teams）。

PUT https://graph.microsoft.com/beta/users/{agent-user-id}/manager/$ref
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.id": "https://graph.microsoft.com/beta/users/{manager-user-id}"
}

PowerShell

$managerBody = '{"@odata.id":"https://graph.microsoft.com/beta/users/<manager-user-id>"}'
Invoke-MgGraphRequest -Method PUT `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/manager/`$ref" `
  -Body $managerBody -ContentType "application/json"

---

步骤 4：设置使用位置并分配许可证（可选）

Agent 用户需要许可证才能拥有邮箱、Teams 状态等。必须先设置使用位置。

设置使用位置

PATCH https://graph.microsoft.com/beta/users/{agent-user-id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "usageLocation": "US"
}

列出可用许可证

GET https://graph.microsoft.com/beta/subscribedSkus?$select=skuPartNumber,skuId,consumedUnits,prepaidUnits
Authorization: Bearer <token>

需要 Organization.Read.All 权限。

分配许可证

POST https://graph.microsoft.com/beta/users/{agent-user-id}/assignLicense
Content-Type: application/json
Authorization: Bearer <token>

{
  "addLicenses": [
    { "skuId": "<sku-id>" }
  ],
  "removeLicenses": []
}

PowerShell（一次完成）

Connect-MgGraph -Scopes "User.ReadWrite.All","Organization.Read.All" -TenantId "<tenant>" -NoWelcome

# Set usage location
Invoke-MgGraphRequest -Method PATCH `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>" `
  -Body '{"usageLocation":"US"}' -ContentType "application/json"

# Assign license
$licenseBody = '{"addLicenses":[{"skuId":"<sku-id>"}],"removeLicenses":[]}'
Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/assignLicense" `
  -Body $licenseBody -ContentType "application/json"

提示： 你也可以通过 Entra 管理中心在“身份” → “用户” → “所有用户” → 选择该 Agent 用户 → “许可证和应用”中分配许可证。

---

预配时间

服务	预计时间
Exchange 邮箱	5–30 分钟
Teams 可用性	15 分钟 – 24 小时
组织架构图 / 人员搜索	最长 24–48 小时
SharePoint / OneDrive	5–30 分钟
全局地址列表	最长 24 小时

---

Agent 用户能力

• ✅ 添加到 Microsoft Entra 组（包括动态组）
• ✅ 访问仅用户可用的 API（idtyp=user 令牌）
• ✅ 拥有邮箱、日历和联系人
• ✅ 参与 Teams 聊天和频道
• ✅ 出现在组织架构图和 People 搜索中
• ✅ 添加到管理单元
• ✅ 分配许可证

Agent 用户安全约束

• ❌ 不能有密码、通行密钥或交互式登录
• ❌ 不能被分配特权管理员角色
• ❌ 不能被添加到可分配角色的组
• ❌ 默认权限类似于来宾用户
• ❌ 无法进行自定义角色分配

---

故障排除

错误	原因	修复
Agent user IdentityParent does not exist	identityParentId 指向不存在的或非 Agent 身份的对象	验证该 ID 是 agentIdentity 服务主体，而不是常规应用
400 Bad Request（identityParentId 已链接）	该 Agent 身份已有 Agent 用户	每个 Agent 身份只支持一个 Agent 用户
UPN 上出现 409 Conflict	userPrincipalName 已被占用	使用唯一的 UPN
许可证分配失败	未设置使用位置	在分配许可证之前设置 usageLocation

---

参考

• Agent 身份
• Agent 用户
• Agent 服务主体
• 创建 Agent 身份蓝图
• 创建 Agent 身份
• agentUser 资源类型（Graph API）
• 创建 agentUser（Graph API）