New-EntraAgentUserForAgentId

New-EntraAgentUserForAgentId

    -DisplayName <String>
    [-UserPrincipalName <String>]
    [-MailNickname <String>]
    [-AgentIdentityId <String>]
    [<CommonParameters>]

The New-EntraAgentUserForAgentId cmdlet creates a new Agent User by posting to the Microsoft Graph users endpoint using an Agent Identity ID as the identity parent. The mailNickname is derived from the UserPrincipalName prefix by default but can be overridden with the -MailNickname parameter or interactively. If -UserPrincipalName is not provided, the cmdlet looks up the tenant's default domain and prompts interactively with a suggested UPN.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity" -SponsorUserIds @("user1@contoso.com")
New-EntraAgentUserForAgentId -DisplayName "Agent Identity 26192008" -UserPrincipalName "AgentIdentity26192008@contoso.onmicrosoft.com"

This example creates an Agent User with the specified display name and user principal name, using the Agent Identity created in the current session.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
# Assumes Agent Identity Blueprint and Agent Identity are already created
New-EntraAgentUserForAgentId -DisplayName "HR Agent User"

This example creates an Agent User. The cmdlet will prompt for the user principal name if not provided.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "Finance Blueprint" -SponsorUserIds @("finance-admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "Finance Agent" -SponsorUserIds @("finance-user@contoso.com")

# Create first Agent User
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 1" -UserPrincipalName "financeagent1@contoso.onmicrosoft.com"

# Create second Agent User for the same Agent Identity
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 2" -UserPrincipalName "financeagent2@contoso.onmicrosoft.com"

This example creates multiple Agent Users associated with the same Agent Identity.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
$agentIdentity = New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity"
New-EntraAgentUserForAgentId -DisplayName "Agent User" -UserPrincipalName "agentuser@contoso.onmicrosoft.com" -AgentIdentityId $agentIdentity.id

This example creates an Agent User by explicitly providing the Agent Identity ID, which is useful when calling from different module scopes or scripts.

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.

Returns the Agent User object from the Microsoft Graph API response with the following properties:

• @odata.type — microsoft.graph.agentUser
• id — The unique identifier of the created Agent User.
• displayName — The display name of the Agent User.
• userPrincipalName — The user principal name of the Agent User.
• mailNickname — The mail nickname (alias) of the Agent User.
• accountEnabled — Whether the account is enabled (always true).
• identityParentId — The ID of the parent Agent Identity.

Additional properties from the Graph API response may also be included.

This cmdlet requires the following Microsoft Graph permission:

• AgentIdUser.ReadWrite.All

The Agent Identity ID can be provided via the -AgentIdentityId parameter or is automatically retrieved from the global variable $global:EntraCurrentAgentIdentityId set by New-EntraAgentIDForAgentIdentityBlueprint. The global variable is used because this cmdlet is in a different module (Microsoft.Entra.Users) than the blueprint cmdlets (Microsoft.Entra.Applications).

The cmdlet stores the created Agent User ID in $script:CurrentAgentUserId for use by subsequent cmdlets.

The cmdlet includes retry logic (up to 10 attempts with 10-second waits) to handle propagation delays.

When -UserPrincipalName is not provided, the cmdlet:

• Queries the tenant's default domain via the organization API
• Suggests a UPN by concatenating the display name words as a prefix with the tenant domain
• Validates the UPN against a regex pattern and re-prompts if invalid

The -UserPrincipalName parameter validates input against the pattern ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.