Edit

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.

Syntax

GetById (Default) 

Get-EntraAgentUser

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

GetByAgentId 

Get-EntraAgentUser

    -AgentId <String>
    [<CommonParameters>]

Description

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.

Examples

Example 1: Get an Agent User by ID

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

This example retrieves the Agent User with the specified ID.

Example 2: Get the Agent User from the current session

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.

Example 3: List all Agent Users for an Agent Identity

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.

Example 4: Get an Agent User with error handling

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.

Parameters

-AgentId

The ID of the Agent Identity to retrieve connected Agent Users for. Returns all agent users that are connected to the specified agent identity. Used with the GetByAgentId parameter set.

Parameter properties

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

Parameter sets

GetByAgentId
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 retrieve. If not provided, uses the stored agent user ID from the current session or prompts for one. Used with the GetById parameter set.

Parameter properties

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

Parameter sets

GetById
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.Object

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.

Notes

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