entra-agent-user

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SKILL: Creating Agent Users in Microsoft Entra Agent ID

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

Overview

概述

An agent user is a specialized user identity in Microsoft Entra ID that enables AI agents to act as digital workers. It allows agents to access APIs and services that strictly require user identities (e.g., Exchange mailboxes, Teams, org charts), while maintaining appropriate security boundaries.

Agent users receive tokens with

idtyp=user

, unlike regular agent identities which receive

idtyp=app

Agent用户是Microsoft Entra ID中的一种专用用户身份，可让AI agents以数字工作者的身份运作。它允许agents访问严格要求用户身份的API和服务（例如Exchange邮箱、Teams、组织架构图），同时维持适当的安全边界。

Agent用户获取的令牌包含

idtyp=user

声明，而普通Agent身份获取的令牌则是

idtyp=app

。

Prerequisites

前提条件

A Microsoft Entra tenant with Agent ID capabilities
An agent identity (service principal of type
```
ServiceIdentity
```
) created from an agent identity blueprint

One of the following permissions:

AgentIdUser.ReadWrite.IdentityParentedBy

(least privileged)

```
AgentIdUser.ReadWrite.All
```
```
User.ReadWrite.All
```

The caller must have at minimum the Agent ID Administrator role (in delegated scenarios)

Important: The
identityParentId
must reference a true agent identity (created via an agent identity blueprint), NOT a regular application service principal. You can verify by checking that the service principal has
@odata.type: #microsoft.graph.agentIdentity
and
servicePrincipalType: ServiceIdentity
.

具备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
来验证。

Architecture

架构

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)

Component	Type	Token Claim	Purpose
Agent Identity	Service Principal	`idtyp=app`	Backend/API operations
Agent User	User ( `agentUser` )	`idtyp=user`	Act as a digital worker in M365

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 Identity	服务主体	`idtyp=app`	后端/API操作
Agent User	用户（ `agentUser` ）	`idtyp=user`	在M365中作为数字工作者运作

Step 1: Verify the Agent Identity Exists

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

Before creating an agent user, confirm the agent identity is a proper

agentIdentity

type:

http

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

Verify the response contains:

json

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

创建Agent用户之前，需确认Agent身份为合法的

agentIdentity

类型：

http

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

验证响应是否包含：

json

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

PowerShell

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

Common mistake: Using an app registration's
appId
or a regular application service principal's
id
will fail. Only agent identities created from blueprints work.

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身份才有效。

Step 2: Create the Agent User

步骤2：创建Agent用户

HTTP Request

HTTP请求

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": "my-agent-user@yourtenant.onmicrosoft.com",
  "identityParentId": "<agent-identity-object-id>"
}

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": "my-agent-user@yourtenant.onmicrosoft.com",
  "identityParentId": "<agent-identity-object-id>"
}

Required Properties

必填属性

Property	Type	Description
`accountEnabled`	Boolean	`true` to enable the account
`displayName`	String	Human-friendly name
`mailNickname`	String	Mail alias (no spaces/special chars)
`userPrincipalName`	String	UPN — must be unique in the tenant ( `alias@verified-domain` )
`identityParentId`	String	Object ID of the parent agent identity

属性	类型	描述
`accountEnabled`	布尔值	设置为 `true` 以启用账户
`displayName`	字符串	易读的名称
`mailNickname`	字符串	邮件别名（不含空格/特殊字符）
`userPrincipalName`	字符串	UPN — 必须在租户中唯一（格式为 `别名@已验证域名` ）
`identityParentId`	字符串	父Agent身份的对象ID

PowerShell

powershell

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

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "my-agent-user@yourtenant.onmicrosoft.com"
  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

powershell

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

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "my-agent-user@yourtenant.onmicrosoft.com"
  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

Key Notes

关键说明

No password — agent users cannot have passwords. They authenticate via their parent agent identity's credentials.
1:1 relationship — each agent identity can have at most one agent user. Attempting to create a second returns
```
400 Bad Request
```
.
The
```
userPrincipalName
```
must be unique. Don't reuse an existing user's UPN.

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

Step 3: Assign a Manager (Optional)

步骤3：分配管理者（可选）

Assigning a manager allows the agent user to appear in org charts (e.g., Teams).

http

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

分配管理者可让Agent用户显示在组织架构图中（例如Teams）。

http

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

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"

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"

Step 4: Set Usage Location and Assign Licenses (Optional)

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

A license is needed for the agent user to have a mailbox, Teams presence, etc. Usage location must be set first.

Agent用户如需拥有邮箱、Teams在线状态等功能，需要分配许可证。需先设置使用位置。

Set Usage Location

设置使用位置

http

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

{
  "usageLocation": "US"
}

http

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

{
  "usageLocation": "US"
}

List Available Licenses

列出可用许可证

http

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

Requires

Organization.Read.All

permission.

http

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

需要

Organization.Read.All

权限。

Assign a License

分配许可证

http

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

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

http

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

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

PowerShell (all in one)

PowerShell（一站式操作）

powershell

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

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"

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"


> **Tip:** You can also assign licenses via the **Entra admin center** under Identity → Users → All users → select the agent user → Licenses and apps.

---

$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用户 → 许可证和应用。

---

Provisioning Times

配置时间

Service	Estimated Time
Exchange mailbox	5–30 minutes
Teams availability	15 min – 24 hours
Org chart / People search	Up to 24–48 hours
SharePoint / OneDrive	5–30 minutes
Global Address List	Up to 24 hours

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

Agent User Capabilities

Agent用户功能

✅ Added to Microsoft Entra groups (including dynamic groups)
✅ Access user-only APIs (
```
idtyp=user
```
tokens)
✅ Own a mailbox, calendar, and contacts
✅ Participate in Teams chats and channels
✅ Appear in org charts and People search
✅ Added to administrative units
✅ Assigned licenses

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

Agent User Security Constraints

Agent用户安全限制

❌ Cannot have passwords, passkeys, or interactive sign-in
❌ Cannot be assigned privileged admin roles
❌ Cannot be added to role-assignable groups
❌ Permissions similar to guest users by default
❌ Custom role assignment not available

❌ 不能设置密码、密钥或进行交互式登录
❌ 不能分配特权管理员角色
❌ 不能添加至可分配角色的组
❌ 默认权限与来宾用户类似
❌ 不支持自定义角色分配

Troubleshooting

故障排除

Error	Cause	Fix
`Agent user IdentityParent does not exist`	`identityParentId` points to a non-existent or non-agent-identity object	Verify the ID is an `agentIdentity` service principal, not a regular app
`400 Bad Request` (identityParentId already linked)	The agent identity already has an agent user	Each agent identity supports only one agent user
`409 Conflict` on UPN	The `userPrincipalName` is already taken	Use a unique UPN
License assignment fails	Usage location not set	Set `usageLocation` before assigning licenses

错误	原因	解决方法
`Agent user IdentityParent does not exist`	`identityParentId` 指向不存在或非Agent身份的对象	验证该ID是否为 `agentIdentity` 服务主体，而非普通应用
`400 Bad Request` （identityParentId已关联）	该Agent身份已拥有一个Agent用户	每个Agent身份仅支持一个Agent用户
`409 Conflict` （UPN冲突）	`userPrincipalName` 已被占用	使用唯一的UPN
许可证分配失败	未设置使用位置	分配许可证前先设置 `usageLocation`

entra-agent-user

Original

Translation

SKILL: Creating Agent Users in Microsoft Entra Agent ID

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

Overview

概述

Prerequisites

前提条件

Architecture

架构

Step 1: Verify the Agent Identity Exists

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

PowerShell

PowerShell

Step 2: Create the Agent User

步骤2：创建Agent用户

HTTP Request

HTTP请求

Required Properties

必填属性

PowerShell

PowerShell

Key Notes

关键说明

Step 3: Assign a Manager (Optional)

步骤3：分配管理者（可选）

PowerShell

PowerShell

Step 4: Set Usage Location and Assign Licenses (Optional)

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

Set Usage Location

设置使用位置

List Available Licenses

列出可用许可证

Assign a License

分配许可证

PowerShell (all in one)

PowerShell（一站式操作）

Set usage location

设置使用位置

Assign license

分配许可证

Provisioning Times

配置时间

Agent User Capabilities

Agent用户功能

Agent User Security Constraints

Agent用户安全限制

Troubleshooting

故障排除

References

参考资料