Edit

Remove-EntraAgentIdentity

Module:
Microsoft.Entra.Applications Module v1.3

Deletes an Agent Identity by its ID, or deletes all Agent Identities (and their Agent Users) associated with an Agent Identity Blueprint.

Syntax

ByAgentId (Default) 

Remove-EntraAgentIdentity

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

ByBlueprintId 

Remove-EntraAgentIdentity

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

Description

The Remove-EntraAgentIdentity cmdlet deletes Agent Identities from Microsoft Entra using the v1.0 API. When used with -AgentId, it deletes a single Agent Identity and any associated Agent Users. When used with -AgentIdentityBlueprintId, it looks up all Agent Identities for the blueprint and deletes each one along with their associated Agent Users.

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 an Agent Identity by ID

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

This example deletes the Agent Identity and any associated Agent Users.

Example 2: Delete all Agent Identities for a Blueprint

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentity -AgentIdentityBlueprintId "cccccccc-3333-4444-5555-dddddddddddd" -Force

This example looks up all Agent Identities associated with the specified Blueprint, deletes their Agent Users, and then deletes the Agent Identities themselves.

Example 3: Preview deletion with WhatIf

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentIdentity -AgentIdentityBlueprintId "cccccccc-3333-4444-5555-dddddddddddd" -WhatIf

This example shows which Agent Identities and Agent Users would be deleted without performing the deletion.

Example 4: Delete with error handling

Connect-Entra -Scopes 'AgentIdentity.DeleteRestore.All', 'AgentIdUser.ReadWrite.All'
try {
    $result = Remove-EntraAgentIdentity -AgentId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Force
    Write-Host "Deleted Agent Identity: $($result.DisplayName)"
    Write-Host "Also deleted $($result.DeletedAgentUsers.Count) Agent User(s)"
} catch {
    Write-Host "Failed to delete: $_"
}

This example demonstrates how to delete an Agent Identity with error handling and inspect the deleted Agent Users.

Parameters

-AgentId

The ID of the Agent Identity to delete. The cmdlet will also delete any Agent Users associated with this Agent Identity. Used with the ByAgentId parameter set.

Parameter properties

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

Parameter sets

ByAgentId
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-AgentIdentityBlueprintId

The ID of the Agent Identity Blueprint. All Agent Identities associated with this blueprint will be deleted, along with their Agent Users. Used with the ByBlueprintId parameter set.

Parameter properties

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

Parameter sets

ByBlueprintId
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 (or array of hashtables when using -AgentIdentityBlueprintId) with properties: Id, DisplayName, AgentIdentityBlueprintId, DeletedAgentUsers (array of deleted user info), and Status.

Notes

This cmdlet requires the following Microsoft Graph permissions:

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

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

When deleting an Agent Identity, any associated Agent Users are deleted first. If Agent User deletion fails, the error is logged but the Agent Identity deletion still proceeds.

When using -AgentIdentityBlueprintId, the cmdlet supports pagination to handle blueprints with many Agent Identities.