Edit

Create and delete an agent's user account

An agent's user account is a specialized identity that lets an agent act as a digital worker—appearing to other systems as a user identity rather than a service principal. Agent user accounts aren't created automatically. You must explicitly create one and associate it with a specific agent identity.

For background on what an agent's user account is and when to use one, see The agent's user account in Microsoft Entra Agent ID.

Note

Creating an agent's user account through the Microsoft Graph API establishes the identity in Microsoft Entra but doesn't provision Microsoft 365 capabilities such as a mailbox or Teams presence. To provision a full digital worker with Microsoft 365 capabilities, create the agent through Microsoft Teams using the Agent 365 SDK.

Prerequisites

  • An agent identity blueprint and at least one agent identity created from it. Record the agent identity's object ID.
  • The blueprint app registration must have the AgentIdUser.ReadWrite.IdentityParentedBy application permission granted with admin consent. See Grant the blueprint permission to create agent user accounts.
  • An access token for the blueprint app registration with https://graph.microsoft.com/.default scope. The blueprint authenticates to Microsoft Graph to create and delete agent user accounts on behalf of the agent identity it parents.

The identityParentId value is the agent identity's object ID. The agent user's separate id is used to delete the user account. For identifier meanings, see Record the identifiers for your scenario.

Grant the blueprint permission to create agent user accounts

The blueprint app registration doesn't have permission to create agent user accounts by default. Add the AgentIdUser.ReadWrite.IdentityParentedBy application permission and grant admin consent before calling the creation API.

  1. Sign in to the Microsoft Entra admin center.
  2. Browse to Entra ID > App registrations and open the blueprint app registration.
  3. Select API permissions > Add a permission > Microsoft Graph > Application permissions.
  4. Search for and select AgentIdUser.ReadWrite.IdentityParentedBy.
  5. Select Add permissions, then select Grant admin consent.

Create an agent's user account

Create the agent's user account and associate it with an agent identity in a single call. The identityParentId property establishes the immutable 1:1 relationship between the user account and its parent agent identity.

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

{
  "accountEnabled": true,
  "displayName": "Sales Agent",
  "mailNickname": "SalesAgent",
  "userPrincipalName": "salesagent@contoso.com",
  "identityParentId": "<agent-identity-object-id>"
}
Property Description
accountEnabled Set to true to enable the account immediately.
displayName Display name shown in the directory.
mailNickname Alias used when provisioning a mailbox. Must be unique in the tenant.
userPrincipalName Sign-in name in user@domain format. Must use a verified domain in the tenant.
identityParentId Object ID of the agent identity that owns this user account. This value is immutable after creation.

A successful request returns 201 Created with the new agent user object:

{
  "@odata.type": "#microsoft.graph.agentUser",
  "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
  "displayName": "Sales Agent",
  "mailNickname": "SalesAgent",
  "userPrincipalName": "salesagent@contoso.com",
  "identityParentId": "<agent-identity-object-id>"
}

Record the id value. You need it to configure the agent's user account flow in your agent and to delete the account later.

Delete an agent's user account

When the agent is decommissioned, delete the user account to remove it from the directory.

DELETE https://graph.microsoft.com/v1.0/users/microsoft.graph.agentUser/<agent-user-id>
Authorization: Bearer <blueprint-access-token>

A successful request returns 204 No Content. The agent identity itself is not deleted by this call. To also remove the agent identity, see Create and delete agent identities.