Edit

Remove-EntraAgentIdentityBlueprint

Module:
Microsoft.Entra.Applications Module v1.3

Deletes an Agent Identity Blueprint and all its associated Agent Identities and Agent Users.

Syntax

Default (Default) 

Remove-EntraAgentIdentityBlueprint

    -BlueprintId <String>
    [-Force]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

The Remove-EntraAgentIdentityBlueprint cmdlet performs a cascading delete of an Agent Identity Blueprint from Microsoft Entra. It:

  1. Finds all Agent Identities associated with the blueprint
  2. For each Agent Identity, finds and deletes all associated Agent Users
  3. Deletes each Agent Identity
  4. Deletes the Agent Identity Blueprint itself

The cmdlet requires confirmation before deleting unless the -Force switch is used. Use -WhatIf to preview which resources would be deleted without actually performing the deletion.

Examples

Example 1: Delete a Blueprint and all associated resources

Connect-Entra -Scopes 'AgentIdentityBlueprint.ReadWrite.All', 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentityBlueprint -BlueprintId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Force

This example deletes the blueprint, all its Agent Identities, and all associated Agent Users without prompting for confirmation.

Example 2: Preview deletion with WhatIf

Connect-Entra -Scopes 'AgentIdentityBlueprint.ReadWrite.All', 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentityBlueprint -BlueprintId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -WhatIf

This example shows which resources would be deleted without performing any deletions.

Example 3: Delete with confirmation and inspect results

Connect-Entra -Scopes 'AgentIdentityBlueprint.ReadWrite.All', 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
$result = Remove-EntraAgentIdentityBlueprint -BlueprintId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
Write-Host "Deleted Blueprint: $($result.BlueprintName)"
Write-Host "Deleted $($result.DeletedIdentities.Count) Agent Identity(ies)"
Write-Host "Deleted $($result.DeletedUsers.Count) Agent User(s)"

This example deletes the blueprint with interactive confirmation and inspects the results.

Parameters

-BlueprintId

The ID of the Agent Identity Blueprint to delete. The cmdlet will cascade-delete all Agent Identities and Agent Users associated with this blueprint.

Parameter properties

Type:System.String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:System.Management.Automation.SwitchParameter
Default value:True
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Force

Suppresses the confirmation prompt before deleting.

Parameter properties

Type:System.Management.Automation.SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Parameter properties

Type:System.Management.Automation.SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

None

Outputs

System.Collections.Hashtable

Returns a hashtable with properties: BlueprintId, BlueprintName, DeletedIdentities (array of deleted Agent Identity info), DeletedUsers (array of deleted Agent User info), and Status.

Notes

This cmdlet requires the following Microsoft Graph permissions:

  • AgentIdentityBlueprint.ReadWrite.All
  • AgentIdentity.DeleteRestore.All
  • AgentIdUser.ReadWrite.All

The cmdlet requires an active Microsoft Entra connection. Use Connect-Entra with the above scopes to connect first.

Deletion order: Agent Users are deleted first, then Agent Identities, and finally the blueprint itself. If an individual Agent User or Agent Identity deletion fails, a warning is displayed and the cmdlet continues with the remaining resources.

When the blueprint has many Agent Identities, the cmdlet supports pagination to ensure all are found.