Remove-EntraAgentUser
Deletes an Agent User by its ID, or deletes all Agent Users associated with an Agent Identity.
Syntax
ByUserId (Default)
Remove-EntraAgentUser
-AgentUserId <String>
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ByAgentId
Remove-EntraAgentUser
-AgentId <String>
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The Remove-EntraAgentUser cmdlet deletes Agent Users from Microsoft Entra. When used with -AgentUserId, it deletes a single agent user by ID. When used with -AgentId, it looks up and deletes all agent users associated with the specified Agent Identity.
The cmdlet requires confirmation before deleting unless the -Force switch is used. Use -WhatIf to preview which users would be deleted without actually performing the deletion.
Examples
Example 1: Delete an Agent User by ID
Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
This example deletes the Agent User with the specified ID. You will be prompted for confirmation.
Example 2: Delete an Agent User by ID without confirmation
Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Force
This example deletes the Agent User without prompting for confirmation.
Example 3: Delete all Agent Users for an Agent Identity
Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentUser -AgentId "cccccccc-3333-4444-5555-dddddddddddd" -Force
This example looks up all Agent Users associated with the specified Agent Identity and deletes them.
Example 4: Preview deletion with WhatIf
Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
Remove-EntraAgentUser -AgentId "cccccccc-3333-4444-5555-dddddddddddd" -WhatIf
This example shows which Agent Users would be deleted without actually performing the deletion.
Example 5: Delete with error handling
Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
try {
$result = Remove-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Force
Write-Host "Deleted: $($result.DisplayName)"
} catch {
Write-Host "Failed to delete: $_"
}
This example demonstrates how to delete an Agent User with error handling.
Parameters
-AgentId
The ID of the Agent Identity whose associated Agent Users should be deleted. The cmdlet looks up all Agent Users connected to this Agent Identity and deletes them. 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 |
-AgentUserId
The ID of the Agent User to delete. Used with the ByUserId parameter set.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ByUserId
| 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 -AgentId) with the following properties: Id, DisplayName, AgentId, and Status.
Notes
This cmdlet requires the following Microsoft Graph permissions:
- AgentIdUser.ReadWrite.All
The cmdlet requires an active Microsoft Entra connection. Use Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All' to connect first.
When using -AgentId, the cmdlet first queries for all Agent Users associated with the Agent Identity, then deletes each one. If the Agent Identity has no associated Agent Users, a warning is displayed.