Microsoft Entra Agent ID
Microsoft identity platform

Create an agent identity blueprint

In brief

The guide now distinguishes separately managed agent fleets from cloud or end-user agents, adds management-app authorization and PowerShell prerequisites, documents context validation and the default multi-instance setting, and requires recording both blueprint IDs.

What Entra admins need to know

Administrators creating fleet blueprints should use the separate management app with the specified tenant and scopes, validate the Graph context, and retain both the blueprint `id` and `appId`.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Create an agent identity blueprint

An agent identity blueprint is usedSet up the registration your fleet runtime uses to create agent identities and request tokens using thosefor them. You'll assign an owner and sponsor, configure the runtime credential, and expose an inbound scope if users or client applications call the fleet.

This procedure is for a platform that hosts separately managed agents. For a cloud agent identities. During the process for creatingor an agent identity blueprint, you setinstalled on an end-user device, use Create an identity for your agent instead.

Create the owner and sponsor of that blueprint, to establish accountability and administrative relationships. You also configure an identifier URI and define a scope for agents created from thisfleet's blueprint if the agent is designed to receive incoming requests from other agents and users.

You can create an agent identity blueprint in two ways:by using either approach:

  • Microsoft Entra admin center — Use the wizard for a quick setup that creates the blueprint and its principal.
  • Microsoft Graph API or PowerShell — Create and fully configure the blueprint programmatically, including credentials, identifier URIs, scopes, and the blueprint principal in a single workflow.

To create an agent identity blueprint, you need:

Prepare your environment

To streamlineBefore you create the process, takeblueprint, authorize the client that will call Microsoft Graph.

Identify the operator who creates objects and the administrator who approves the management client's permissions. Runtime API access is a few momentsseparate grant: completing blueprint setup doesn't authorize an agent to getcall Microsoft Graph or your environment set up for the right permissions.downstream API.

Authorize a client to create agent identity blueprints

The steps in this guide use all delegated permissions, but you can use application permissions for those scenarios that require them.

Use a separate public management app registered in your tenant, not the agent's runtime client ID. Follow Set up the management client, but request the four delegated permissions above and User.Read for this procedure. The linked section explains the public-client redirect URI, administrator consent, and Windows browser sign-in fallback; its single-instance preview enablement requirement doesn't apply to this fleet procedure.

Install Microsoft.Graph.Authentication and Microsoft.Graph.Users to use Connect-MgGraph, Invoke-MgGraphRequest, and Get-MgUser. Install Microsoft.Graph.Applications before using the application cmdlets in later sections.

To connect to all of the required scopes for Microsoft Graph PowerShell, run the following command:

Connect-MgGraph -ClientId "<management-app-client-id>" -Scopes "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.AddRemoveCreds.All", "AgentIdentityBlueprint.UpdateAuthProperties.All", "AgentIdentityBlueprintPrincipal.Create", "User.Read" -TenantId "<your-tenant-id>" -ContextScope Process

Check Get-MgContext before proceeding. Its account, tenant, client ID, and scopes must match this management setup. If context is empty or a scope is missing, stop and resolve sign-in or consent rather than retrying object creation. Retain the same -ClientId and tenant in later connections.

Use the identifier worksheet to keep object IDs separate from client IDs.

Create an agent identity blueprint

Agent identity blueprints must have a sponsor, which is the user or supported group that's accountable for the agent. An owner is recommended, which is the user or service principal that can make changes to the agent identity blueprint. For information, see Administrative relationships in Microsoft Entra Agent ID.

To create an agent identity blueprint using code, use the Microsoft Graph API or PowerShell.

The following Microsoft Graph v1.0 requests use the default multi-instance setting required by the fleet tutorials. Keep that default; the instance mode can't be changed after creation.

Microsoft Graph API

This step creates the agent identity blueprint, assigns an owner and sponsor, and requires the following details:


After creatingFrom the agent identity blueprint,`201 Created` response, record the value of theboth `id` (the blueprint object ID for application updates) and `appId` (the client ID for the next step.authentication and principal creation).

### [Microsoft Graph PowerShell](#tab/powershell)

- Create the agent identity blueprint application.

```powershell
Connect-MgGraph -ClientId "<management-app-client-id>" -Scopes "AgentIdentityBlueprint.Create","User.Read" -TenantId "<your-tenant-id>" -ContextScope Process

$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

After creating the agent identity blueprint, record the value of theRecord both id and appId from the output. The blueprint object id addresses /applications/{id}; appId identifies the OAuth client and is used to create its blueprint principal.


Configure credentials for the agent identity blueprint

ToFor a confidential-client blueprint, add a client credential to request access tokens using the agent identity blueprint, you must add a client credential.tokens. We recommend using a managed identity as a federated identity credential (FIC) for production deployments. Managed identities allow you to obtain Microsoft Entra tokens without having to manage any credentials. For more information, see Managed identities for Azure resources.

Don't distribute a blueprint credential with an agent installed on an end-user device. For that scenario, follow the public-client setup in Authenticate a local agent with Microsoft Entra ID.

Other kinds of app credentials including keyCredentials and passwordCredentials are supported, but not recommended for production. They can be convenient for local development and testing or where managed identities won't work, but these options don't align with security best practices. For more information, see Security best practices for application properties.

To send this request:

  • You need the AgentIdentityBlueprint.AddRemoveCreds.All permission.
  • Replace the <agent-blueprint-id> placeholder with the blueprint application's object id, not its application (client) appId of the agent identity blueprint..
  • Replace the <managed-identity-principal-id> placeholder with the ID of your managed identity.

Add a managed identity as a credential using the following request: This step includes the following distinct tasks:

  • Connect to your tenant with the AgentIdentityBlueprint.AddRemoveCreds.All scope.
  • Add a managed identity as a credential foron the blueprint application. This step doesn't require a blueprint principal and also applies to a blueprint created through the cloud-agent identity blueprint using the previously created agent identity blueprint principal.tutorial.

Set $applicationId to the blueprint application's object id, not its application (client) appId.

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

Connect-MgGraph -ClientId "<management-app-client-id>" -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId "<your-tenant-id>" -ContextScope Process

$applicationId = "<agent-blueprint-id>"


### [Microsoft Graph API](#tab/microsoft-graph-api)

To send this request, you first need to obtain an access token with the delegated permission `AgentIdentityBlueprint.AddRemoveCreds.All`. Replace `<future-expiration-in-UTC>` with a future UTC time in ISO 8601 format that complies with your tenant's credential lifetime policy.

```http
POST https://graph.microsoft.com/v1.0/applications/<agent-blueprint-id>/addPassword
{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z<future-expiration-in-UTC>"
  }
}

Microsoft Graph PowerShell

Connect-MgGraph -ClientId "<management-app-client-id>" -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId "<your-tenant-id>" -ContextScope Process

$applicationId = "<agent-blueprint-application-id>"


## Configure identifier URI and scope

To receive incoming requests from users and other agents, like for any web API, you need to defineExpose an identifier URI and OAuthdelegated scope so clients can request access tokens for your agent identity blueprint:API. Use the blueprint's object ID to address the application and its client ID in the `api://` URI.

### [Microsoft Graph API](#tab/microsoft-graph-api)

To send this request:
- You need the permission `AgentIdentityBlueprint.UpdateAuthProperties.All`.
- Replace the `<agent-blueprint-object-id>` placeholder with the blueprint application's object `id` for the `/applications/` path.
- Replace `<agent-blueprint-app-id>` with the blueprint's application (client) `appId` ofin the agent identity blueprint.`api://` URI.
- You need a Globally Unique Identifier (GUID). In PowerShell, run `[guid]::NewGuid()` or use an online GUID generator. Copy the generated GUID and use it to replace the `<generate-a-guid>` placeholder.

The examples below configure a new blueprint with no existing scopes. For an existing blueprint, read `identifierUris` and `api.oauth2PermissionScopes` first and retain their existing entries in the update. These collections are replaced, not appended. If you arrived here from the cloud-agent walkthrough, use its management client to send the HTTP request; its consented `AgentIdentityBlueprint.ReadWrite.All` permission also permits the update.

```http
PATCH https://graph.microsoft.com/v1.0/applications/<agent-blueprint-object-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-app-id>"],
    "api": {
      "requestedAccessTokenVersion": 2,
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
- Configure the URI and scope for the new agent identity blueprint.

```powershell
Connect-MgGraph -ClientId "<management-app-client-id>" -Scopes "AgentIdentityBlueprint.UpdateAuthProperties.All" -TenantId "<your-tenant-id>

$AppId" -ContextScope Process

$blueprintObjectId = "<agent-blueprint-object-id>"
$blueprintAppId = "<agent-blueprint-app-id>"
$IdentifierUri = "api://<agent-blueprint-id>$blueprintAppId"
$ScopeId = [guid]::NewGuid()

# Construct the OAuth2 permission scope
    value = "access_agent"
}

Update-MgApplication -ApplicationId $AppId$blueprintObjectId `
    -IdentifierUris @($IdentifierUri) `
    -Api @{ requestedAccessTokenVersion = 2; oauth2PermissionScopes = @($scope) }

In this step, you create a principal for the agent identity blueprint. For more information, see Agent identities, service principals, and applications.

Microsoft Graph API

Microsoft Graph API

Replace the <agent-blueprint-app-id> placeholder with the appId you copied from the results of the previous step.

Microsoft Graph PowerShell

After creating the agent identity blueprint, create an agent identity blueprint principal using the newly created agent identity blueprintits appId.

Connect-MgGraph -ClientId "<management-app-client-id>" -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId "<your-tenant-id>

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId-ContextScope Process
$body = @{
    appId = "<agent-blueprint-client-app-id>"
}
Invoke-MgGraphRequest -Method POST `
        -Uri "https://graph.microsoft.com/v1.0/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal" `

---

Save the returned principal's `id` separately from the blueprint's `id` and `appId`. Check that its `appId` matches the blueprint's client ID before creating child identities. If you used the admin center wizard, it already created this principal; don't create another one.

Your agent blueprint isand principal are now ready and visible in the [Microsoft Entra admin center](https://entra.microsoft.com). In theprovisioned. The next step, you'll use this blueprintstep is to [create agent identities](create-delete-agent-identities.md). Token acquisition and an authorized call to the target API are later verification steps; visibility in the admin center alone doesn't prove runtime access.

## Register agents in the Agent 365 registry


### Use the Microsoft 365 Agents SDK (Recommended)

The [Microsoft 365 Agents SDK](/microsoft-365/agents-sdk/) is now generally available and is the recommended way to build and provision agents. The SDK The SDK handles agent identity creation and registration in the Agent 365 registry for you,registry, so your agent identities will appear automatically with no extrawithout separate registration code. If you are're starting a new agent project,project or have flexibility tocan migrate existing code, use the SDK. It's the simplest, most durable path and avoids the needSDK to coordinate multipleavoid coordinating these API calls yourself.

### Use the Agent 365 CLI

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…