Edit

Get-EntraAgentIdentity

Module:
Microsoft.Entra.Applications Module v1.3

Gets an Agent Identity by its ID, or lists all Agent Identities for an Agent Identity Blueprint.

Syntax

GetById (Default) 

Get-EntraAgentIdentity

    -AgentId <String>
    [<CommonParameters>]

GetByBlueprint 

Get-EntraAgentIdentity

    [-AgentIdentityBlueprintId <String>]
    [<CommonParameters>]

Description

The Get-EntraAgentIdentity cmdlet retrieves an Agent Identity from Microsoft Graph. When used with -AgentId, it returns a single agent identity. When used with -AgentIdentityBlueprintId, it returns all agent identities that are children of the specified blueprint. If no blueprint ID is provided, uses the stored blueprint ID from the current session or prompts for one.

Examples

Example 1: Get an Agent Identity by ID

Connect-Entra -Scopes 'Application.Read.All'
Get-EntraAgentIdentity -AgentId "27a3cf14-5bdc-4814-bb13-8f1740ca9a4f"

This example retrieves the Agent Identity with the specified ID.

Example 2: List all Agent Identities for a Blueprint

Connect-Entra -Scopes 'Application.Read.All'
$agents = Get-EntraAgentIdentity -AgentIdentityBlueprintId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
$agents | ForEach-Object { Write-Host "$($_.displayName) ($($_.id))" }

This example retrieves all Agent Identities that are children of the specified Agent Identity Blueprint.

Example 3: List Agent Identities for the current session Blueprint

Connect-Entra -Scopes 'Application.Read.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
$agents = Get-EntraAgentIdentity -AgentIdentityBlueprintId
$agents | ForEach-Object { Write-Host "$($_.displayName)" }

This example lists all Agent Identities for the blueprint created in the current session using the stored blueprint ID.

Example 4: Get an Agent Identity with error handling

Connect-Entra -Scopes 'Application.Read.All'
try {
    $agent = Get-EntraAgentIdentity -AgentId "27a3cf14-5bdc-4814-bb13-8f1740ca9a4f"
    Write-Host "Agent found: $($agent.displayName)"
} catch {
    Write-Host "Agent not found or error occurred: $_"
}

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

Parameters

-AgentId

The ID of the Agent Identity to retrieve. 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: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 to list child agent identities for. If not provided, uses the stored blueprint ID from the current session or prompts for one. Used with the GetByBlueprint parameter set.

Parameter properties

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

Parameter sets

GetByBlueprint
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 -AgentId, returns a single Agent Identity object. When using -AgentIdentityBlueprintId, returns an array of Agent Identity objects. Each object includes properties such as id, displayName, appId, and servicePrincipalType.

Notes

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

This cmdlet requires the following Microsoft Graph permissions:

  • Application.Read.All