New-EntraAgentUserForAgentId
Creates a new Agent User using an Agent Identity.
Syntax
Default (Default)
New-EntraAgentUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-MailNickname <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
Description
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.
Examples
Example 1: Create an Agent User with all parameters
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.
Example 2: Create an Agent User with prompts
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.
Example 3: Create multiple Agent Users for the same Agent Identity
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.
Example 4: Create an Agent User with explicit Agent Identity ID
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.
Parameters
-AgentIdentityId
The Agent Identity ID to associate with this user. If not provided, the cmdlet uses the stored value from New-EntraAgentIDForAgentIdentityBlueprint. Use this parameter when calling from different module scopes or when you want to explicitly specify the Agent Identity.
Parameter properties
| Type: | System.String |
| Default value: | None |
| 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 |
-DisplayName
The display name for the Agent User.
Parameter properties
| Type: | System.String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MailNickname
The mail nickname (alias) for the Agent User. If not provided, it is derived from the UserPrincipalName prefix (the part before the @ symbol) and the user is prompted to confirm or override it.
Parameter properties
| Type: | System.String |
| Default value: | None |
| 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 |
-UserPrincipalName
The user principal name (email) for the Agent User (e.g., username@domain.onmicrosoft.com). Must be a valid email address format. If not provided, the cmdlet looks up the tenant's default domain and prompts interactively with a suggested UPN derived from the display name.
Parameter properties
| Type: | System.String |
| Default value: | None |
| 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 |
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
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.
Notes
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,}$.