New-EntraAgentIDForAgentIdentityBlueprint

Module:

Microsoft.Entra.Applications Module v1.3

Creates a new Agent Identity using an Agent Identity Blueprint.

New-EntraAgentIDForAgentIdentityBlueprint

 -DisplayName <String>
 [-SponsorUserIds <String[]>]
 [-SponsorGroupIds <String[]>]
 [-OwnerUserIds <String[]>]
 [-AgentIdentityBlueprintId <String>]
 [<CommonParameters>]

The New-EntraAgentIDForAgentIdentityBlueprint cmdlet creates a new Agent Identity by posting to the Microsoft Graph v1.0 AgentIdentity endpoint using the specified or stored Agent Identity Blueprint ID and specified sponsors/owners. At least one sponsor (user or group) is required. Owners are optional. If the AgentIdentityBlueprintId parameter is not provided, the cmdlet uses the stored blueprint ID from a previous New-EntraAgentIdentityBlueprint call. If no stored ID exists, the cmdlet prompts interactively. If sponsors or owners are not provided as parameters, the cmdlet prompts interactively and suggests the current user as the default. All user IDs and UPNs are validated against the tenant before the Agent Identity is created. Duplicate entries are automatically removed.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', '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") -OwnerUserIds @("owner1@contoso.com")

This example creates an Agent Identity with the specified display name, sponsors, and owners using the Agent Identity Blueprint created in the current session.

Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "HR Agent" -SponsorUserIds @("hr-admin@contoso.com") -SponsorGroupIds @("aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb")

This example creates an Agent Identity with both user and group sponsors.

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

This example creates an Agent Identity. The cmdlet will prompt for sponsors and owners if not provided.

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 Identity object from the Microsoft Graph API response with the following properties:

• id — The unique identifier of the created Agent Identity (service principal).
• appId — The application ID associated with the Agent Identity.
• displayName — The display name of the Agent Identity.
• createdDateTime — The date and time the Agent Identity was created.
• AgentIdentityBlueprintId — The ID of the parent Agent Identity Blueprint.

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

This cmdlet requires the following Microsoft Graph permissions:

• AgentIdentity.Create.All

The cmdlet relies on the stored Agent Identity Blueprint ID ($script:CurrentAgentBlueprintId) set by New-EntraAgentIdentityBlueprint. If no blueprint ID is stored, the cmdlet fails with an error.

After creating the Agent Identity, the cmdlet stores the ID and AppId in module-level variables ($script:CurrentAgentIdentityId, $script:CurrentAgentIdentityAppId) and a global variable ($global:EntraCurrentAgentIdentityId) for use by other cmdlets.

The cmdlet uses the v1.0 Microsoft Graph endpoint (/v1.0/servicePrincipals/Microsoft.Graph.AgentIdentity) and includes retry logic (up to 10 attempts with 10-second waits) to handle propagation delays.

When sponsor or owner parameters are not provided, the cmdlet enters an interactive mode that:

• Looks up the current signed-in user and offers them as a default sponsor/owner
• Validates all user IDs and UPNs against the tenant, prompting for corrections if a user is not found
• Validates group IDs against the tenant, skipping any that are not found
• Allows adding additional sponsors/owners in iterative prompts