New-EntraBetaAgentIDUserForAgentId
Creates a new Agent User using an Agent Identity.
Syntax
Default (Default)
New-EntraBetaAgentIDUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
Description
The New-EntraBetaAgentIDUserForAgentId cmdlet creates a new Agent User by posting to the Microsoft Graph users endpoint using the current Agent Identity ID as the identity parent. The mailNickname is automatically derived from the userPrincipalName.
Examples
Example 1: Create an Agent User with all parameters
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AppRoleAssignment.ReadWrite.All', 'AgentIdentityBlueprint.ReadWrite.All', 'User.ReadWrite.All'
New-EntraBetaAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
New-EntraBetaAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity" -SponsorUserIds @("user1@contoso.com")
New-EntraBetaAgentIDUserForAgentId -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', 'AppRoleAssignment.ReadWrite.All', 'AgentIdentityBlueprint.ReadWrite.All', 'User.ReadWrite.All'
# Assumes Agent Identity Blueprint and Agent Identity are already created
New-EntraBetaAgentIDUserForAgentId -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', 'AppRoleAssignment.ReadWrite.All', 'AgentIdentityBlueprint.ReadWrite.All', 'User.ReadWrite.All'
New-EntraBetaAgentIdentityBlueprint -DisplayName "Finance Blueprint" -SponsorUserIds @("finance-admin@contoso.com")
New-EntraBetaAgentIDForAgentIdentityBlueprint -DisplayName "Finance Agent" -SponsorUserIds @("finance-user@contoso.com")
# Create first Agent User
New-EntraBetaAgentIDUserForAgentId -DisplayName "Finance Agent User 1" -UserPrincipalName "financeagent1@contoso.onmicrosoft.com"
# Create second Agent User for the same Agent Identity
New-EntraBetaAgentIDUserForAgentId -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', 'AppRoleAssignment.ReadWrite.All', 'AgentIdentityBlueprint.ReadWrite.All', 'User.ReadWrite.All'
$agentIdentity = New-EntraBetaAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity"
New-EntraBetaAgentIDUserForAgentId -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-EntraBetaAgentIDForAgentIdentityBlueprint. 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 |
-UserPrincipalName
The user principal name (email) for the Agent User (e.g., username@domain.onmicrosoft.com). Must be a valid email address format.
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 with properties including id, displayName, userPrincipalName, mailNickname, and accountEnabled.
Notes
Requires an Agent Identity ID, either provided via the -AgentIdentityId parameter or stored from a previous call to New-EntraBetaAgentIDForAgentIdentityBlueprint. The mailNickname is automatically derived from the userPrincipalName by extracting the part before the @ symbol. The Agent User is created with accountEnabled set to true.
This cmdlet requires the following Microsoft Graph permissions:
- AgentIdentityBlueprint.Create
- AgentIdentityBlueprintPrincipal.Create
- AppRoleAssignment.ReadWrite.All
- AgentIdentityBlueprint.ReadWrite.All
- User.ReadWrite.All