Edit

Share via

Create an agent identity blueprint

An agent identity blueprint is used to create agent identities and request tokens using those agent identities. This guide walks you through creating an agent identity blueprint using Microsoft Graph REST API and Microsoft Graph PowerShell.

Prerequisites

Before creating your agent identity blueprint, ensure you have:

  • understand agent identity blueprints
  • Privileged Role Administrator required to grant permissions
  • One of the following roles required to create a blueprint: Agent ID Developer or Agent ID Administrator. Prefer the Agent ID Administrator role.

Authorize a client to create agent identity blueprints

In this article, you use Microsoft Graph PowerShell or another client to create your agent identity blueprint. You must authorize this client to create an agent identity blueprint. The client requires one of the following Microsoft Graph permissions:

  • AgentIdentityBlueprint.Create (delegated permission)
  • AgentIdentityBlueprint.Create (application permission)

Only a Global Administrator or Privileged Role Administrator is able to grant these permissions to the client. To grant these permissions, an administrator can:

  • Use the Connect-MgGraph command.
  • Run a script to create an oAuth2PermissionGrant or appRoleAssignment in the tenant.

Create an agent identity blueprint

Creating a functional agent identity blueprint in your tenant requires two steps:

  1. Create an AgentIdentityBlueprint in the tenant.
  2. Create an AgentIdentityBlueprintPrincipal in the tenant.

The principal created in this case is different from the agent identity used by the agent.

First obtain an access token with the permission AgentIdentityBlueprint.Create. Once you have an access token, make the following request.

Tip

Always include the OData-Version header when using @odata.type.

POST https://graph.microsoft.com/beta/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>",
  ],
	"owners@odata.bind": [
	  "https://graph.microsoft.com/v1.0/users/<id>"
	]
}

After you create an agent identity blueprint, record its appId for upcoming steps in the guide. Next, create a service principal for your agent identity blueprint:

To create the service principal, you first need to obtain an access token with the permission AgentIdentityBlueprint.Create. Once you have an access token, make the following request:

Tip

Always include the OData-Version header when using @odata.type.

POST https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "appId": "<agent-blueprint-app-id>"
}

Configure credentials for the agent identity blueprint

To request access tokens using the agent identity blueprint, you must add a client credential. We recommend using a managed identity as a federated identity credential for production deployments. For local development and testing, use a client secret.

Add a managed identity as a credential using the following request:

To send this request, you first need to obtain an access token with the permission AgentIdentityBlueprint.AddRemoveCreds.All.

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "my-msi",
    "issuer": "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0",
    "subject": "<msi-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

In some tenants, other kinds of app credentials including keyCredentials, passwordCredentials, and trustedSubjectNameAndIssuers are also supported. These kinds of credentials aren't recommended for production, but can be convenient for local development and testing. To add a password credential:

To send this request, you first need to obtain an access token with the delegated permission AgentIdentityBlueprint.AddRemoveCreds.All

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Be sure to securely store the passwordCredential value generated. It can't be viewed after initial creation. You can also use client certificates as credentials; see Add a certificate credential.

Configure identifier URI and scope

To receive incoming requests from users and other agents, you need to define an identifier URI and OAuth scope for your agent identity blueprint:

To send this request, you first need to obtain an access token with the permission AgentIdentityBlueprint.ReadWrite.All.

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

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Related content

Create and delete agent identities

  • Last updated on