Microsoft Entra Agent ID
Authentication

Agent identity blueprints in Microsoft Entra Agent ID

In brief

The documentation introduces preview instance modes. Single-instance blueprints create one Agent ID per tenant, while multi-instance blueprints can create multiple identities with separate client IDs. Administrators select the mode at creation with `isSingleInstance`, and it cannot be changed later.

What Entra admins need to know

Mode selection affects identity, authentication, and permission design. The capability has no service-level agreement and isn't recommended for production workloads.

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.

:::image type="content" source="media/agent-blueprint/agent-blueprint.png" alt-text="Diagram showing relationship between agent identity and agent identity blueprint.":::

AgentBlueprints hold the configuration used to create and authenticate agent identities. The instance mode determines whether a blueprint represents one agent identity blueprints areor provides a powerful component of the Microsoft Entra Agent ID platform. They hold critical information about how agent identities are created and authenticated, and they serve as a containertemplate for managing agent identities at scale. multiple identities.

Agent identity blueprints

An agent identity blueprint is more than just a template for agent identities, just like a blueprint for a building is more than just a drawing. Where architectural blueprints include plumbing, electrical, and structural details, agent identity blueprints include important information about authentication,defines authentication settings, permissions, and activity logs. other properties shared by its agent identities.

A multi-instance blueprint can create multiple Agent identity blueprints can be used to deploy multiple agentsIDs of the same type. If multiple agents are created from one agenttype in a tenant. Each identity blueprint, each agent has its own identity, credentials,permissions, while credentials and permissions but they share common characteristics thatauthentication settings are defined byconfigured on the blueprint. This allows organizations to create a consistent configuration for all agents of a particular type, while still maintaining the flexibility to customize individual agents as needed.

An agent identity blueprint has the following properties that are shared across all its agent identities:

  • Description: A brief summary of the agent's purpose and functions.
  • App roles: DefineDeclare roles for access to the roles that can be given to users and other principals when usingagent API. For single-instance inbound user access, also publish the agent.same user role directly on the Agent ID service principal.
  • Verified publisher: The organization that built the agent.
  • Settings for authentication protocols: Configure which information is included in access tokens issued to the agent, such as OptionalClaims.

The full schema is available in the Microsoft Graph API reference documentation.

Instance modes (preview)

An agent identity blueprint has an instance mode that determines how many Agent IDs it can create in each tenant.

PropertySingle-instanceMulti-instance
Agent identities per blueprint in a tenantOne.One or more, each with a separate identity.
OAuth client IDThe blueprint and Agent ID share the blueprint's appId.Each Agent ID has its own client ID.
Blueprint principalNone.Represents the blueprint in the tenant.
Token acquisitionThe Agent ID requests a token directly, using the shared client ID.The blueprint obtains an exchange token to impersonate a child Agent ID.
PermissionsGranted directly to the Agent ID.Granted directly to the Agent ID or inherited from the blueprint principal.

The blueprint and Agent ID are separate directory objects in both modes. In single-instance mode, they share an OAuth client ID, not an object ID.

Choose the mode when you create the blueprint. In the Microsoft Graph beta API, set isSingleInstance to true for single-instance mode. If the property is false or omitted, the blueprint uses multi-instance mode. The setting can't be changed after creation.

When to use single-instance mode

Use single-instance mode when one Agent ID represents the agent in a tenant. For example, a local assistant can use that identity across its installations, or a hosted service can use it for background work or requests on behalf of signed-in users.

Public-client agents that run on endpoint devices must use single-instance mode. Every installation uses the same client ID; installing the agent on another device doesn't create another Agent ID. Single-instance mode also supports confidential clients. The mode describes the identity relationship, not whether the agent can protect a credential.

Use multi-instance mode when a blueprint needs to provision identities with separate permissions or lifecycles, such as a fleet of agents. A multi-instance blueprint with only one child identity is still multi-instance; the number of identities currently provisioned doesn't change the mode.

The mode doesn't count running processes, replicas, or user sessions. It also isn't the same as the blueprint's single-tenant or multitenant configuration.

Authentication and permissions

A single-instance Agent ID uses standard OAuth requests with the blueprint's appId as its client ID. It doesn't obtain a blueprint impersonation token first. Confidential clients authenticate with a credential configured on the blueprint. Public clients use authorization code flow with PKCE and don't send a client credential. Both client types can use the same blueprint with redirect URIs registered for their respective platforms.

Permissions are granted to the Agent ID through consent or app role assignments. Single-instance blueprints don't support inheritable permissions because they don't have a blueprint principal. Declaring permissions in requiredResourceAccess doesn't grant them.

Inbound authorization is a separate configuration. For a single-instance agent API, declare the user-access role on the blueprint and publish the same role GUID and value on the Agent ID service principal, then assign it to users or groups. This role configuration isn't permission inheritance. See Control access to agents with app roles.

Single-instance provisioning in Microsoft Graph and single-instance authentication must both be enabled for the tenant. They are separate requirements. For the setup procedure, see Create a single-instance agent identity. For token requests, see Authenticate a single-instance agent identity.

Key characteristics of agent identity blueprints

In addition to standard properties, the agent identity blueprint includes key characteristics that are important to understand before creating agent identities from your agent identity blueprint.

Credentials

CredentialsFor confidential clients, credentials used to authenticate an agent identity are configured on the agent identity blueprint. When an AI agent wantsA multi-instance blueprint uses its credentials to perform an operation,impersonate a child Agent ID. A single-instance Agent ID uses the credentials configured oncredential directly with the agent identity blueprint are used to request an access token from Microsoft Entrashared client ID. OAuth permissions granted toPublic-client Agent IDs don't send a agent identity blueprint are granted to all agent identities created from that blueprint. There are several credentials types that can be used for agent identities.client credential. For more information on these,information, see credentials for agent identities and Agent ID authentication protocols. For auth protocols, see Agent ID authentication protocols

Security

Used to create agent identities

Blueprints don't just hold information. They're also a special identity type in a Microsoft Entra ID tenant. A blueprint can perform exactly one operation in the tenant: provision or deprovision agent identities.ID. All agent identities in a Microsoft Entra ID tenantAgent IDs are created from an agent identity blueprint. In the multi-instance topology, the blueprint principal provisions and deprovisions Agent IDs. To create an agent identity, aperform this operation, the blueprint has:

  • An OAuth client ID: a unique ID used to request access tokens from Microsoft Entra ID.
  • Credentials: used to request access tokens from Microsoft Entra ID.
  • AgentIdentity.CreateAsManager: a special Microsoft Graph permission that enables the blueprint to create agent identities in the tenant.

A service uses the multi-instance blueprint's client ID, credentials, and permissions to send agent identityAgent ID creation requests viathrough Microsoft Graph APIs. The agent identities created byFor a single-instance blueprint, an authorized management client creates the blueprint and then provisions its one Agent ID through Microsoft Graph. This process doesn't create a blueprint share common characteristics.principal or require a runtime credential for a public client.

For more information, see create agent identities.

Agent identity blueprints include two important permission-related configurations that control how agent identities access resources:

  • Required resource access declares the APIs and permissions the agent needs to function. This list is visible to administrators during consent review and helps them evaluate whether to approve the agent.
  • Inheritable permissions, available for multi-instance blueprints, define which resource apps can have their permissions automatically inherited by agent identities created from the blueprint. When an administrator grants permissions on the blueprint principal from an inheritable resource app, all agent identities created from that blueprint in thatthe organization receive those permissions automatically.

These configurations are declarations that don't grant authorization by themselves. Administrators must still consent to permissions on the blueprint principal or individual agent identities.

Agent identity blueprint principals

An agent identity blueprint principal is an object in Microsoft Entra Agent ID that represents the presence of an agent identitya multi-instance blueprint within a specific tenant. When an agent identityManaged creation experiences can create both objects. If you create the blueprint application is added to a tenant,through Microsoft Entra creates a corresponding principal object, which is the agent identityGraph, create an agent blueprint principal before creating child identities. A single-instance blueprint doesn't have this principal.

:::image type="content" source="media/agent-blueprint/agent-blueprint-principal.png" alt-text="Diagram showing illustration of an agent blueprint principal.":::

Agent identity blueprints are always created in a Microsoft Entra tenant. An agent identity blueprint is often used to create agent identities in that same tenant. These agent identity blueprints are called "single-tenant." Agent identity blueprints can also be configured as "multitenant" and published to potential customers via Microsoft catalogs. Customers can then add these blueprints to their tenant, so that they can be used to create agent identities.

In either case, an agent identity blueprint principal is always created when a blueprint is added to a tenant. The presence of this principal indicates that athe multi-instance blueprint exists in athe tenant and can be used to create agent identities. Customers can remove aAgent IDs. A single-instance blueprint from their tenant by deleting the agent identity blueprintdoesn't create this intermediate principal. For more information, see Instance modes.

Related content

Next steps

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…