Microsoft Entra Agent ID
Microsoft identity platform

Create and delete an agent's user account

In brief

New documentation explains how to create and delete an agent user account, associate it with an agent identity, grant the required application permission, and use the account identifier for deletion.

What Entra admins need to know

Administrators adopting agent user accounts must grant the blueprint app registration the AgentIdUser.ReadWrite.IdentityParentedBy permission with admin consent.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

new file mode 100644

title: Create and delete an agent's user account description: Learn how to create and delete an agent's user account using the Microsoft Graph API. titleSuffix: Microsoft Entra Agent ID ms.topic: how-to ms.date: 10/29/2026 ms.reviewer: dastrock

#customer-intent: As a developer or IT administrator, I want to create an agent's user account so that my agent can act as a digital worker in Microsoft Entra.

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.

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": "[email protected]",
  "identityParentId": "<agent-identity-object-id>"
}
PropertyDescription
accountEnabledSet to true to enable the account immediately.
displayNameDisplay name shown in the directory.
mailNicknameAlias used when provisioning a mailbox. Must be unique in the tenant.
userPrincipalNameSign-in name in user@domain format. Must use a verified domain in the tenant.
identityParentIdObject 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": "[email protected]",
  "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.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…