Plan your agent identity architecture
In brief
The guide now directs cloud and local agent builders to integration tutorials, adds instance mode to architecture planning, clarifies Agent ID provisioning versus ordinary app registrations, and updates client-library and API guidance.
What Entra admins need to know
Administrators should use the updated tutorials and provisioning procedures when designing Agent ID deployments. No required action is stated.
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.
Plan your agent identity architecture
BeforeUse this guide when you integrate're designing identity boundaries for a platform or several separately managed agents. If you want to build a cloud or local agent, start with Choose an integration path. Its tutorials include the required identity setup; this planning guide isn't a prerequisite.
The guide helps you choose the identity type, operation pattern, and blueprint structure that match your AI agent with Microsoft Entra Agent ID, you need to make a series of design decisions. This guide walks you through each decision in order:access and lifecycle requirements.
- Which identity type your agent needs.
- Which operation pattern your agent uses, including how it acquires tokens and what context it acts in.
- How many blueprints your system requires.
- How many agent identities to create per blueprint.
Plan the identity boundaries
For architecture planning, consider:
Work through these decisions in order, because earlierEarlier choices shape later ones. Some single-agent deployments might onlyThe selected tutorial sets the instance mode during provisioning; it isn't a separate operating mode your users need the first two steps.to choose. For examples of how these decisions map to real-world agent architectures,architecture examples, see Agent ID design patterns.
Step 1: Choose an identity type
- Blueprint-managed credentials and lifecycle: you create, rotate, and delete agent identities through their parent blueprint, not individually.
- Support for ephemeral agent identities that are created at runtime with inheritable permissions already granted through the blueprint, and deleted when the task completes.
For a detailed comparison, see Agent identities, service principals, and applicationsAgent identities, service principals, and applications.
Why not a regular user account?
- Identity governance processes such as joiner-mover-leaver workflows, access packages, and access reviews aren't designed for agent lifecycle patterns and might incorrectly remove agent access.
- Your agents would appear in the Global Address List, Teams, and SharePoint alongside human employees, making it harder to distinguish AI agents from people.
Don't registerUse an appAgent ID for yourthe agent's runtime identity
If you're used to creating workload identities, your instinct might be to create anAn ordinary app registration or service principal for your agent — for example, by running az ad app create, New-MgApplication, New-AzADApplication, or a POST /applications Microsoft Graph request. Donisn't do this for AI agents. An identity created this way isan Agent ID. Use the supported Agent ID provisioning procedure rather than creating a standard application: it has no sponsor, no agent-specific audit entries, and no blueprint-managed lifecycle. Microsoft Entra doesn't govern it as an agent,application and labeling it an "agent identity"agent. Some supported blueprint requests use /applications with a derived @odata.type; the endpoint alone doesn't make it one.determine the object type. Preserve the request type and headers shown in your tutorial.
Instead, create anThe agent identity blueprint and then create agent identities from it. Agent identities areis a distinct Microsoft Entra object type (#Microsoft.Graph.AgentIdentity) created throughassociated with a blueprint. Separate management clients, front-end sign-in clients, and downstream APIs can still use ordinary app registrations. Don't replace those objects with the blueprint, not through the application registration APIs.agent's runtime identity.
| Instead of this (standard app registration) | Do this (agent identity) |
|---|---|
az ad app create |
Create an agent identity blueprint, then create agent identities from it |
New-MgApplication or New-AzADApplication |
Use a supported creation channel with the Agent ID Developer or Agent ID Administrator role |
An ordinary application creation request |
Follow the typed blueprint request in your scenario tutorial, |
In .NET,For a cloud ASP.NET Core agent, use the standard Microsoft.Identity.Web client APIs in Call a custom API as an agent. For a hosting platform with a fleet, use Microsoft.Identity.Web.AgentIdentities package: call builder.Services.AddAgentIdentities(), then acquire tokens with and explicit child-identity selection in the fleet tutorials. WithAgentIdentity(...)See Call custom APIs from an agent.For a local public client, use MSAL without a client credential.
For a full comparison, see Agent identities, service principals, and applications.
| Consent model | Admin consent required | User or admin consent |
| Token subject | Agent identity | User (with agent as actor) |
| Common scenarios | Background processing, scheduled tasks, system-to-system | Chat assistants, user-facing copilots, agents acting on user data |
| Access scope | Broad, tenant-wide accessPermissions granted to the agent, further constrained by the resource's authorization model. | Scoped toDelegated permissions and the signed-in user's dataaccess, further constrained by the resource's authorization model. |
Choose autonomous when your agent:
- Runs background or scheduled tasks.
Some agents need both. For example, an agent might run a nightly background sync using the autonomous pattern and also respond to user chat messages using the interactive pattern. In this case, implement both OAuth flows and select the appropriate token based on the operation.
- For autonomous agents, see
Request agent tokens for autonomous agentsCall a custom API as an agent with ASP.NET Core. - For interactive agents, see
Authenticate users in interactive agentsCall a custom API as a user with ASP.NET Core.
Step 3: Decide how many agent identity blueprints
An agent identity blueprint managesdefines authentication settings for all theits agent identities created from it. Theand holds credentials for confidential clients. A multi-instance blueprint holds theuses those credentials used to acquire tokens on behalfimpersonate its child identities. A compromise of those agent identities. Because of this capability, a blueprint compromiseshared credentials can affect every agent identity under it.that uses them. Choose your agent identity blueprint count based on your security boundaries.
Default: use one blueprint per trust boundary.
- Scale-out or replicas: Running multiple instances of the same agent doesn't require multiple blueprints.
- Memory or context separation: Agent memory is typically a shared data store filtered by session ID at retrieval time, which doesn't require separate blueprints.
For more information about blueprints, see Agent identity blueprintsAgent identity blueprints.
Step 4: Decide how many agent identities per blueprint
Multi-agent architectures where multiple agent identities are appropriate can include sequential pipelines with distinct agent roles and concurrent orchestrations with specialized domain workers. For more information, see AI agent orchestration patterns.
Step 5: Choose the instance mode
Choose the blueprint's mode before creating it. Single-instance mode represents one Agent ID per tenant, with the same OAuth client ID as the blueprint and no blueprint principal. Multi-instance mode supports separate child Agent IDs with distinct client IDs.
Registered public-client agents must use single-instance mode. Confidential agents can also use it when one identity is appropriate. If the blueprint needs to provision identities with independent permissions or lifecycles, use multi-instance mode.
Having only one child identity doesn't make an existing multi-instance blueprint single-instance. The setting is fixed at creation. For details, see Blueprint instance modes and Create a single-instance agent identity.
Related content
@@ -3,21 +3,28 @@ title: Plan your agent identity architecture titleSuffix: Microsoft Entra Agent ID description: Use this decision guide to choose the right identity type, operation pattern, and blueprint and agent identity structure for your AI agents in Microsoft Entra Agent ID. ms.topic: concept-article-ms.date: 04/03/2026+ms.date: 11/06/2026 ai-usage: ai-assisted #customer intent: As a developer or enterprise architect building AI agents, I want to determine which identity type, operation pattern, and blueprint structure to use so that I can design a secure and scalable agent identity architecture for my scenario. --- # Plan your agent identity architecture -Before you integrate your AI agent with Microsoft Entra Agent ID, you need to make a series of design decisions. This guide walks you through each decision in order:+Use this guide when you're designing identity boundaries for a platform or several separately managed agents. If you want to build a cloud or local agent, start with [Choose an integration path](choose-agent-integration-path.md). Its tutorials include the required identity setup; this planning guide isn't a prerequisite. -1. **Which identity type** your agent needs.-1. **Which operation pattern** your agent uses, including how it acquires tokens and what context it acts in.-1. **How many blueprints** your system requires.-1. **How many agent identities** to create per blueprint.+The guide helps you choose the identity type, operation pattern, and blueprint structure that match your access and lifecycle requirements. -Work through these decisions in order, because earlier choices shape later ones. Some single-agent deployments might only need the first two steps. For examples of how these decisions map to real-world agent architectures, see [Agent ID design patterns](concept-agent-id-design-patterns.md).+## Plan the identity boundaries++For architecture planning, consider:++- **Which identity type** your agent needs.+- **Which operation pattern** your agent uses, including how it acquires tokens and what context it acts in.+- **How many blueprints** your system requires.+- **How many agent identities** to create per blueprint.+- **Which instance mode** matches that identity relationship.++Earlier choices shape later ones. The selected tutorial sets the instance mode during provisioning; it isn't a separate operating mode your users need to choose. For architecture examples, see [Agent ID design patterns](concept-agent-id-design-patterns.md). ## Step 1: Choose an identity type @@ -39,7 +46,7 @@ Service principals are designed for deterministic, static workloads. Microsoft E - Blueprint-managed credentials and lifecycle: you create, rotate, and delete agent identities through their parent blueprint, not individually. - Support for ephemeral agent identities that are created at runtime with inheritable permissions already granted through the blueprint, and deleted when the task completes. -For a detailed comparison, see [Agent identities, service principals, and applications](identity-platform/agent-service-principals.md).+For a detailed comparison, see [Agent identities, service principals, and applications](agent-service-principals.md). ### Why not a regular user account? @@ -50,19 +57,19 @@ Don't use a regular Microsoft Entra user account for an AI agent. User accounts - **Identity governance** processes such as joiner-mover-leaver workflows, access packages, and access reviews aren't designed for agent lifecycle patterns and might incorrectly remove agent access. - Your agents would appear in the Global Address List, Teams, and SharePoint alongside human employees, making it harder to distinguish AI agents from people. -### Don't register an app for your agent+### Use an Agent ID for the agent's runtime identity -If you're used to creating workload identities, your instinct might be to create an app registration or service principal for your agent — for example, by running `az ad app create`, `New-MgApplication`, `New-AzADApplication`, or a `POST /applications` Microsoft Graph request. Don't do this for AI agents. An identity created this way is a standard application: it has no sponsor, no agent-specific audit entries, and no blueprint-managed lifecycle. Microsoft Entra doesn't govern it as an agent, and labeling it an "agent identity" doesn't make it one.+An ordinary app registration isn't an Agent ID. Use the supported Agent ID provisioning procedure rather than creating a standard application and labeling it an agent. Some supported blueprint requests use `/applications` with a derived `@odata.type`; the endpoint alone doesn't determine the object type. Preserve the request type and headers shown in your tutorial. -Instead, create an agent identity blueprint and then create agent identities from it. Agent identities are a distinct Microsoft Entra object type (`#Microsoft.Graph.AgentIdentity`) created through the blueprint, not through the application registration APIs.+The agent identity is a distinct Microsoft Entra object type (`#Microsoft.Graph.AgentIdentity`) associated with a blueprint. Separate management clients, front-end sign-in clients, and downstream APIs can still use ordinary app registrations. Don't replace those objects with the agent's runtime identity. | Instead of this (standard app registration) | Do this (agent identity) | |---|---| | `az ad app create` | Create an [agent identity blueprint](create-blueprint.md), then create agent identities from it | | `New-MgApplication` or `New-AzADApplication` | Use a supported [creation channel](agent-id-creation-channels.md) with the **Agent ID Developer** or **Agent ID Administrator** role |-| `POST https://graph.microsoft.com/v1.0/applications` | Grant `AgentIdentityBlueprint.Create`, then [create the blueprint and agent identities](create-delete-agent-identities.md) |+| An ordinary application creation request | Follow the typed blueprint request in your [scenario tutorial](choose-agent-integration-path.md), with that procedure's management permissions. | -In .NET, use the `Microsoft.Identity.Web.AgentIdentities` package: call `builder.Services.AddAgentIdentities()`, then acquire tokens with `WithAgentIdentity(...)`. See [Call custom APIs from an agent](call-api-custom.md).+For a cloud ASP.NET Core agent, use the standard `Microsoft.Identity.Web` client APIs in [Call a custom API as an agent](call-api-custom.md). For a hosting platform with a fleet, use `Microsoft.Identity.Web.AgentIdentities` and explicit child-identity selection in the [fleet tutorials](plan-agent-fleet.md). For a local public client, use [MSAL](authenticate-local-agent.md) without a client credential. For a full comparison, see [Agent identities, service principals, and applications](agent-service-principals.md). @@ -77,7 +84,7 @@ An agent's operation pattern determines how it acquires tokens and what context | **Consent model** | Admin consent required | User or admin consent | | **Token subject** | Agent identity | User (with agent as actor) | | **Common scenarios** | Background processing, scheduled tasks, system-to-system | Chat assistants, user-facing copilots, agents acting on user data |-| **Access scope** | Broad, tenant-wide access | Scoped to the signed-in user's data |+| **Access scope** | Permissions granted to the agent, further constrained by the resource's authorization model. | Delegated permissions and the signed-in user's access, further constrained by the resource's authorization model. | Choose **autonomous** when your agent: - Runs background or scheduled tasks.@@ -91,12 +98,12 @@ Choose **interactive** when your agent: Some agents need both. For example, an agent might run a nightly background sync using the autonomous pattern and also respond to user chat messages using the interactive pattern. In this case, implement both OAuth flows and select the appropriate token based on the operation. -- For autonomous agents, see [Request agent tokens for autonomous agents](identity-platform/autonomous-agent-request-tokens.md).-- For interactive agents, see [Authenticate users in interactive agents](interactive-agent-authentication-authorization-flow.md).+- For autonomous agents, see [Call a custom API as an agent with ASP.NET Core](call-api-custom.md).+- For interactive agents, see [Call a custom API as a user with ASP.NET Core](aspnet-core-call-custom-api-as-user.md). ## Step 3: Decide how many agent identity blueprints -An agent identity blueprint manages authentication for all the agent identities created from it. The blueprint holds the credentials used to acquire tokens on behalf of those agent identities. Because of this capability, a blueprint compromise can affect every agent identity under it. Choose your agent identity blueprint count based on your security boundaries.+An agent identity blueprint defines authentication settings for its agent identities and holds credentials for confidential clients. A multi-instance blueprint uses those credentials to impersonate its child identities. A compromise of shared credentials can affect every identity that uses them. Choose your agent identity blueprint count based on your security boundaries. **Default: use one blueprint per trust boundary.** @@ -114,7 +121,7 @@ The following factors are *not* reasons to add more blueprints: - **Scale-out or replicas**: Running multiple instances of the same agent doesn't require multiple blueprints. - **Memory or context separation**: Agent memory is typically a shared data store filtered by session ID at retrieval time, which doesn't require separate blueprints. -For more information about blueprints, see [Agent identity blueprints](identity-platform/agent-blueprint.md).+For more information about blueprints, see [Agent identity blueprints](agent-blueprint.md). ## Step 4: Decide how many agent identities per blueprint @@ -133,8 +140,16 @@ The following factors are *not* reasons to add more agent identities: Multi-agent architectures where multiple agent identities are appropriate can include sequential pipelines with distinct agent roles and concurrent orchestrations with specialized domain workers. For more information, see [AI agent orchestration patterns](/azure/architecture/ai-ml/guide/ai-agent-design-patterns). +## Step 5: Choose the instance mode++Choose the blueprint's mode before creating it. Single-instance mode represents one Agent ID per tenant, with the same OAuth client ID as the blueprint and no blueprint principal. Multi-instance mode supports separate child Agent IDs with distinct client IDs.++Registered public-client agents must use single-instance mode. Confidential agents can also use it when one identity is appropriate. If the blueprint needs to provision identities with independent permissions or lifecycles, use multi-instance mode.++Having only one child identity doesn't make an existing multi-instance blueprint single-instance. The setting is fixed at creation. For details, see [Blueprint instance modes](agent-blueprint.md#instance-modes-preview) and [Create a single-instance agent identity](create-single-instance-agent.md).+ ## Related content - [Agent ID design patterns](concept-agent-id-design-patterns.md)-- [Agent identity blueprints](identity-platform/agent-blueprint.md)-- [Agent identities, service principals, and applications](identity-platform/agent-service-principals.md)+- [Agent identity blueprints](agent-blueprint.md)+- [Agent identities, service principals, and applications](agent-service-principals.md) 