Get-EntraAgentUser

Module:

Microsoft.Entra.Users Module v1.3

Gets an Agent User by its ID, or lists all Agent Users connected to an Agent Identity.

Get-EntraAgentUser

 [-AgentUserId <String>]
 [<CommonParameters>]

Get-EntraAgentUser

 -AgentId <String>
 [<CommonParameters>]

The Get-EntraAgentUser cmdlet retrieves Agent Users from Microsoft Graph using the v1.0 API. When used with -AgentUserId, it returns a single agent user. When used with -AgentId, it returns all agent users connected to the specified Agent Identity. If no agent user ID is provided in the GetById parameter set, it uses the stored agent user ID from the current session or prompts for one.

Connect-Entra -Scopes 'User.Read.All'
Get-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

This example retrieves the Agent User with the specified ID.

Connect-Entra -Scopes 'AgentIdUser.ReadWrite.All'
New-EntraAgentUserForAgentId -DisplayName "My Agent User" -UserPrincipalName "myagent@contoso.onmicrosoft.com"
$agentUser = Get-EntraAgentUser
Write-Host "Agent User: $($agentUser.displayName)"

This example retrieves the Agent User that was created in the current session using the stored agent user ID.

Connect-Entra -Scopes 'User.Read.All'
$agentUsers = Get-EntraAgentUser -AgentId "cccccccc-3333-4444-5555-dddddddddddd"
$agentUsers | ForEach-Object { Write-Host "$($_.displayName) ($($_.userPrincipalName))" }

This example retrieves all Agent Users that are connected to the specified Agent Identity.

Connect-Entra -Scopes 'User.Read.All'
try {
 $agentUser = Get-EntraAgentUser -AgentUserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
 Write-Host "Agent User found: $($agentUser.displayName) ($($agentUser.userPrincipalName))"
} catch {
 Write-Host "Agent User not found or error occurred: $_"
}

This example demonstrates how to retrieve an Agent User with error handling to catch cases where the user doesn't exist.

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.

When using -AgentUserId, returns a single Agent User object. When using -AgentId, returns an array of Agent User objects. Each object includes properties such as id, displayName, userPrincipalName, mailNickname, accountEnabled, and identityParentId.

If the Agent User or Agent Identity with the specified ID is not found, the cmdlet will throw an error. When listing by Agent Identity, supports pagination to retrieve all results.

This cmdlet requires the following Microsoft Graph permissions:

• User.Read.All