Microsoft Entra Agent ID
General

How to delete and restore agent identity objects

In brief

The documentation no longer states that deleting a blueprint automatically soft-deletes child agent identities and agent user accounts. It now treats blueprint applications and principals as separate delete targets, and lists separate permissions for deletion, restoration, and permanent deletion.

What Entra admins need to know

Do not assume deletion or restoration cascades to related objects. Record related object IDs and verify them independently, and review the listed permissions for your operations.

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.

After you deleteThe public Graph API references describe deletion of the blueprint or its principal, Microsoft Entra automatically soft deletes all associatedaddressed object, but don't specify cascade behavior for child agent identities and agents'or associated agent user accounts. Record their object IDs before deletion and check their states independently afterward. For more information on this process,information, see Agent identity deletion.

Delete an agent identity

Use the agentIdentity-specific Graph operation to delete one agent identity. The API moves the object to a temporary container, where it can be restored within 30 days.

DELETE https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-object-id}/microsoft.graph.agentIdentity

For the API's permissions and current behavior, see Delete agentIdentity.

Restore a blueprint principal

You can restore a soft-deleted blueprint principal within 30 days. Restoring an application doesn't automatically restore its associated service principal, so restore the blueprint principal separately. Restoring agent identity objects isn't supported in the Microsoft Entra admin center. Use Microsoft Graph API or Microsoft Entra PowerShell. For details, see Restore deleted items.

Microsoft Graph API

Microsoft Entra PowerShell

Connect-Entra -Scopes 'Application.ReadWrite.AgentIdentityBlueprintPrincipal.DeleteRestore.All'
Restore-EntraDeletedDirectoryObject -Id '<blueprint-principal-object-id>'

Restore child agent identities

If the cascade cleanup already ran and childan agent identities wereidentity is soft deleted, restore each one individually.it by its own object ID.

Get-EntraDeletedServicePrincipal

Restore each agent identity individually

Restore-EntraDeletedDirectoryObject -Id ''


---

## Permanently delete agent identity objects

The Graph API references don't specify an agent identity-specific quota or when quota becomes available after deletion. Check current Microsoft Entra service limits before capacity planning.

DELETE https://graph.microsoft.com/v1.0/directory/deletedItems/{agent-identity-object-id}


Permanently delete a soft-deleted blueprint application:principal:

```http
DELETE https://graph.microsoft.com/v1.0/directory/deletedItems/{blueprint-principal-object-id}

Permanently delete a soft-deleted blueprint application:


```powershell
Connect-Entra -Scopes 'AgentIdentity.ReadWrite.All'
Remove-EntraDeletedDirectoryObject -DirectoryObjectId '<agent-identity-object-id>'

Permanently delete a soft-deleted blueprint principal:

Connect-Entra -Scopes 'AgentIdentityBlueprintPrincipal.ReadWrite.All'
Remove-EntraDeletedDirectoryObject -DirectoryObjectId '<blueprint-principal-object-id>'

Permanently delete a soft-deleted blueprint application:

Connect-Entra -Scopes 'Application.ReadWrite.All'
Remove-EntraDeletedDirectoryObject -DirectoryObjectId '<blueprint-app-object-id>'

Agents' user accounts

AgentsThe agentIdentity delete API doesn't specify what happens to an associated agent user's account. Check the user accounts are paired 1:1 with agent identities.object independently. If agents' user accounts aren't automatically cleaned up as part of cascade deletion,you confirm that the account is no longer needed, delete them manually.it separately:

Microsoft Graph API

DELETE https://graph.microsoft.com/v1.0/beta/users/microsoft.graph.agentUser/{agent-user-object-id}

For the API's permissions and current behavior, see Delete agentUser.

Microsoft Entra PowerShell

Connect-Entra -Scopes 'User.AgentIdUser.ReadWrite.AllIdentityParentedBy'
Remove-EntraUser -UserId '<agent-user-object-id>'

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…