Microsoft Entra Agent ID
Fundamentals

Learn how agent identity deletion works

In brief

The documentation now states that Microsoft Graph documents deletion, soft deletion, and recovery for individual agent identity and application objects, but does not specify whether deleting a blueprint also deletes child identities or agent users.

What Entra admins need to know

Administrators should not assume related objects are automatically removed; plan cleanup and recovery based on the documented operation for each object.

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.

Agent identity deletion

When youMicrosoft Graph documents soft deletion and recovery for agent identity and application objects. Its public delete API references don't specify whether deleting an agent identity blueprint or its principal, Microsoft Entra automatically cleans up allblueprint principal also deletes child agent identities and agents'or associated agent user accounts withaccounts. Don't rely on a cascade cleanup process. You don't need to manually query and delete each one. Understanding when and how this cascade cleanup happens helps you planunless Microsoft confirms the behavior for restoration if needed.your scenario.

Agent identity blueprints and their associated objects follow the same soft For general application soft-deletion and hard deletion behavior as other app registrations and service principals in Microsoft Entra. For a full overview of that process,behavior, see Deleting and recovering applications FAQ. This article focuses on whatseparates the behavior documented for individual Graph objects from related-object behavior that isn's unique to agent identity deletion.t specified in those API references.

Object relationships

The following objects are involved in the agent identity deletion lifecycle. The cascade cleanup process is based on these relationships.

Object Directory object type RelationshipDocumented relationship or operation
Agent identity blueprint Application Parent ofDelete the blueprint principalapplication object by using the Graph application delete API.
Agent identity blueprint principal Service principal TheDelete the service principal forby using the blueprintGraph servicePrincipal delete API.
Agent identity ServiceagentIdentity service principal Child ofThe agentIdentityBlueprintId property identifies its blueprint. Delete an agent identity by using the blueprint principalGraph agentIdentity delete API.
Agent's useragentUser, a specialized user accountsubtype UserPaired 1:1The agentUser resource has a one-to-one relationship with ana parent agent identityidentity. The agentIdentity delete API doesn't specify what happens to the associated agent user. Check that object separately.

Disable versus delete

Before deleting a blueprint, consider whether disabling is the right action instead.

  • Disable: Prevents the blueprint principal or its agent identities from authenticating, but leaves all objects in place. Use this when you want to temporarily stop agent activity,activity or investigate an issue, or decommission agents gradually. Objects remain in the directory and count toward quota.issue. For more information, see Disable agent identities.
  • Delete: RemovesSends a delete request for the specific Graph object addressed. The application delete API documents a 30-day recovery period for deleted applications. The agentIdentity delete API documents the same period for deleted agent identities.

Related-object cleanup and restoration

Use the API that matches the object you intend to delete:

  • Delete a blueprint application with DELETE /applications/{applicationObjectId}.
  • Delete a blueprint principal with DELETE /servicePrincipals/{servicePrincipalId}.
  • Delete one agent identity with DELETE /servicePrincipals/{id}/microsoft.graph.agentIdentity.

The public Graph API references describe deletion of the addressed object. They don't specify whether deleting a blueprint application or its agent identity blueprint principal from the directory and triggers cascade cleanup of child agent identities. Use this when you're permanently retiring a blueprint and all agents created from it. Deletion canidentities or associated agent users. The Graph restore API specifies that restoring an application doesn't be undone afterautomatically restore its associated service principal; restore that principal separately. The API references don't specify cleanup timing, an internal cleanup actor, or whether restoring a parent restores or reverses changes to child objects.

Before deletion, record the 30-day soft-deletion window expires.

For information on disabling agent identities, see Disable agent identities.

Cascade cleanup

Whenobject IDs you deletemight need to recover. After the operation, check each related object independently. If an agent identityobject was soft deleted, restore that object by its own ID; don't assume that restoring a blueprint or its agent identity blueprint principal, Microsoft Entra automaticallyprincipal restores related objects.

For restore steps, see Delete and restore agent identity objects.

Audit logs

Review the tenant's Microsoft Entra audit logs to investigate recorded directory operations. The Graph delete API references don't specify a particular internal cleanup actor or audit sequence for related objects.

Quota considerations

The public Graph API references document soft deletes all associated childdeletion and a 30-day recovery period for agent identities and agentsapplications. They don' user accounts. This cleanup is asynchronous.

The cascade process works as follows:

  1. You delete thet specify an agent identity blueprintidentity-specific quota, a maximum number of agent identities per blueprint, a maximum number of inheritable resource apps, or agent identity blueprint principal: The object is soft deleted and moves to the recycle bin.
  2. when quota becomes available after deletion. Check current Microsoft Entra triggers automatic cleanup: A background taskservice limits and confirm Agent ID-specific limits before capacity planning. Don't assume that soft deletes all child agent identities and agents' user accounts associated with the deleted blueprint.
  3. Objects are restorable for 30 days: Soft-deleted objects can be restored within 30 days. After that, they're permanently deleted.

Cascade cleanup in audit logs

When the background cleanup task deletes agent identities, the deletions appear in your tenant's Microsoft Entra audit logs. These entries have the following characteristics:

Audit log fieldValue
ActivityDelete service principal
Initiated by (actor)Application: Delete Agent Identities Task
Actor App ID(blank)

The actor is shown as an application named Delete Agent Identities Task with no app ID. This is expected because the cleanup is performed by an internal Microsoft Entra background process, not by an external application or user.

Orphaned objects and quota considerations

When an agent identity blueprint principal is permanently deleted, any associated agent identities and agents' user accounts that weren't deleted become orphaned objects and become soft-deleted. Orphaned objects can't authenticate but continue to count toward directory quota until they're permanently deleted after the 30-day retention period expires.

Agent identity deletion follows the same quota rules as other Microsoft Entra objects. Soft-deleted objects continue to count toward quota limits until permanently deleted. For general quota information, see Microsoft Entra service limits and restrictions.deletion immediately frees quota.

One consideration specific to agent identities: if you're using app-only permissions and are at the 250 agent identity limit for a blueprint, deleting an agent identity doesn't free up space until it's permanently deleted. By default, permanent deletion happens automatically after the 30-day retention period expires. If you need to free up quota immediately, you can force permanent deletion of soft-deleted agent identities. For steps,general directory limits, see Permanently delete agent identity objectsMicrosoft Entra service limits and restrictions. Agent identity blueprints also follow this 250 limit when using app-only permissions.

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…