Migrate Custom App Registrations To Agent Id
In brief
The guide now requires access to Microsoft Graph v1.0 and the beta agent identity endpoint for Step 2. It also separates fleet and single-agent guidance and replaces fixed rollout, confidence, and deletion-batch values with evidence- and workload-based recommendations.
What Entra admins need to know
Admins performing the migration must ensure access to the beta endpoint and use the updated deployment, rollout, and decommissioning guidance.
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.
titleSuffix: Microsoft Entra Agent ID
description: Learn how to migrate AI agents from standard Microsoft Entra app registrations to Agent ID for agent-specific governance and security.
ms.topic: how-to
ms.date: 11/06/15/2026
ms.custom: msecd-doc-authoring-1013
ai-usage: ai-assisted
#customer intent: As a developer or IT admin who built AI agents using standard app registrations, I want to migrate them to Microsoft Entra Agent ID so that I can take advantage of agent-specific governance, Conditional Access, and audit capabilities.
- An existing AI agent that uses an app registration or service principal for authentication.
- Agent ID Developer or Agent ID Administrator role to create blueprints and agent identities.
- Privileged Role Administrator role to grant Microsoft Graph application permissions.
- Access to the Microsoft Graph v1.0
API.API and the beta agent identity endpoint used in Step 2. - Familiarity with Agent ID key concepts. For more information, see Agent identity concepts.
Licensing requirements
Identify agents through log and permission analysis
For service principals that don't have tags, use behavioral and configuration signals to identify likely agent identities. No single signal is definitive. Weight them in combination to produceReview signals together and document the evidence for each candidate. Don't assign a numeric confidence score.score unless your organization defines and validates a scoring method.
| Signal category | What to look for | Why it indicates an agent |
|---|---|---|
| Run these methods in order: |
- Tag-based scan: Automatically identify all tagged agents. These agents are confirmed candidates.
- Heuristic analysis: Scan remaining untagged service principals for behavioral signals. Flag
high-confidence matches as probable candidates.candidates with multiple supporting signals for review. - CMDB reconciliation: Match remaining service principals against your asset inventory to catch agents registered under non-obvious names.
- Developer attestation: Publish the residual unmatched list to application owners for final classification.
The blueprint and per-agent provisioning steps below follow the fleet pattern. If your deployment runs one agent with one configured identity, use Create a single-instance agent for identity setup and then follow the single-instance API tutorials. For a shared runtime that selects among agent identities, keep the fleet setup and per-request identity selection together. Record the old and new identifiers separately by using Record the identifiers for your scenario.
Step 1: Create an agent identity blueprint
To complete this step, you need the Agent ID Developer or Agent ID Administrator role to create blueprints and agent identities, and the Privileged Role Administrator role to grant Microsoft Graph application permissions.
Configure OBO support (interactive agents only)
If your fleet uses the on-behalf-of (OBO) flow to act on behalf of a user, expose the inbound scope on the blueprint and update the front-end application to request that scope instead of the previous resource's scope. Then authenticate and route user requests and call APIs as the user with the routed agent's identity. For the single-instance path, follow Call a custom API as a user with ASP.NET Core instead of copying the fleet's blueprint-audience configuration.
If your original app registration had Azure RBAC role assignments, assign the same roles to the new agent identity's service principal so it can access the required Azure resources at runtime:
Agent ID uses a two-stage token acquisition model. Your agent first acquires a bootstrap token by using the blueprint's credential, then exchanges it for an agent-specific token. For more information on updating your code, see these scenarios:
Autonomous agent authentication and authorization flowCall a custom API as an agent with ASP.NET Core for the complete app-only token acquisition walkthrough.Interactive agent authentication and authorization flowCall a custom API as a user with ASP.NET Core for interactiveagentsagent guidance, code samples, and token configuration. The token flow in these agents adds an OBO exchange where a user token is exchanged for an agent token with user context.
These two tutorials use one configured agent identity. For a fleet, use Call APIs as an agent in a fleet or Call APIs as a user in a fleet so each operation selects the correct agent identity from the runtime's directory.
Phase 4: Validate and decommission
For agents with high usage, run the old and new identities side by side before switching over:
- Deploy a parallel instance of your agent configured with the new Agent ID.
- Route a
percentagesmall, measured share of traffic to the newinstance (start with 5–10%).instance. Choose the initial share based on the workload's risk and rollback capacity. - Monitor both instances for errors, latency differences, and permission issues.
- Gradually increase traffic
toafter reviewing telemetry and meeting your rollout criteria. Set observation periods based on thenew instance over one to two weeks.workload. - Once 100% of traffic runs on the new identity, proceed to decommission.
Use feature flags or traffic-splitting infrastructure to control the rollout. This approach lets you revert to the old identity instantly if issues arise. After you validate the new Agent ID and it carries production traffic, decommission the old identity. Follow these safeguards to minimize risk:
- Pre-deletion snapshot: Export the service principal's metadata, permissions, and audit history before deletion. This export provides a rollback reference if anything was missed during validation.
- Phased batches: If you're decommissioning multiple identities, delete in
small batches (20-50 service principals per wave)small, reviewable waves. Set each wave size based on tested rollback capacity rather thanbulk-deleting all at once.an assumed platform limit. - Soft-delete first: Use Microsoft Entra's soft-delete capability (30-day recycle bin for applications) before hard deletion. This step gives you a recovery window.
@@ -3,7 +3,7 @@ title: Migrate custom app registrations to Agent ID titleSuffix: Microsoft Entra Agent ID description: Learn how to migrate AI agents from standard Microsoft Entra app registrations to Agent ID for agent-specific governance and security. ms.topic: how-to-ms.date: 06/15/2026+ms.date: 11/06/2026 ms.custom: msecd-doc-authoring-1013 ai-usage: ai-assisted #customer intent: As a developer or IT admin who built AI agents using standard app registrations, I want to migrate them to Microsoft Entra Agent ID so that I can take advantage of agent-specific governance, Conditional Access, and audit capabilities.@@ -20,7 +20,7 @@ This article shows you how to migrate agents where you own the code and the iden - An existing AI agent that uses an app registration or service principal for authentication. - **Agent ID Developer** or **Agent ID Administrator** role to create blueprints and agent identities. - **Privileged Role Administrator** role to grant Microsoft Graph application permissions.-- Access to the Microsoft Graph v1.0 API.+- Access to the Microsoft Graph v1.0 API and the beta agent identity endpoint used in Step 2. - Familiarity with Agent ID key concepts. For more information, see [Agent identity concepts](key-concepts.md). ### Licensing requirements@@ -69,7 +69,7 @@ For each candidate service principal, capture: ### Identify agents through log and permission analysis -For service principals that don't have tags, use behavioral and configuration signals to identify likely agent identities. No single signal is definitive. Weight them in combination to produce a confidence score.+For service principals that don't have tags, use behavioral and configuration signals to identify likely agent identities. No single signal is definitive. Review signals together and document the evidence for each candidate. Don't assign a numeric confidence score unless your organization defines and validates a scoring method. | Signal category | What to look for | Why it indicates an agent | |---|---|---|@@ -102,7 +102,7 @@ For tenants with large numbers of app registrations, publish the migration inven Run these methods in order: 1. **Tag-based scan:** Automatically identify all tagged agents. These agents are confirmed candidates.-1. **Heuristic analysis:** Scan remaining untagged service principals for behavioral signals. Flag high-confidence matches as probable candidates.+1. **Heuristic analysis:** Scan remaining untagged service principals for behavioral signals. Flag candidates with multiple supporting signals for review. 1. **CMDB reconciliation:** Match remaining service principals against your asset inventory to catch agents registered under non-obvious names. 1. **Developer attestation:** Publish the residual unmatched list to application owners for final classification. @@ -127,6 +127,8 @@ This phase covers the technical migration steps for agents whose identity was cr > [!IMPORTANT] > There's no in-place conversion that transforms an existing app registration or service principal into an agent identity. Migration requires creating a new agent identity alongside your existing identity, then transitioning your agent to use it. +The blueprint and per-agent provisioning steps below follow the fleet pattern. If your deployment runs one agent with one configured identity, use [Create a single-instance agent](create-single-instance-agent.md) for identity setup and then follow the single-instance API tutorials. For a shared runtime that selects among agent identities, keep the fleet setup and per-request identity selection together. Record the old and new identifiers separately by using [Record the identifiers for your scenario](key-concepts.md#record-the-identifiers-for-your-scenario).+ ### Step 1: Create an agent identity blueprint To complete this step, you need the **Agent ID Developer** or **Agent ID Administrator** role to create blueprints and agent identities, and the **Privileged Role Administrator** role to grant Microsoft Graph application permissions.@@ -228,7 +230,7 @@ To replicate Microsoft Graph application permissions, grant the same `appRoles` #### Configure OBO support (interactive agents only) -If your agent uses the on-behalf-of (OBO) flow to act on behalf of a user, you need to add a custom scope to the blueprint so that front-end applications can request tokens for it. After adding the scope, update your front-end application to request a token for the blueprint's resource instead of the previous resource. For the complete OBO configuration walkthrough, see [Interactive agent authentication and authorization flow](interactive-agent-authentication-authorization-flow.md).+If your fleet uses the on-behalf-of (OBO) flow to act on behalf of a user, expose the inbound scope on the blueprint and update the front-end application to request that scope instead of the previous resource's scope. Then [authenticate and route user requests](aspnet-core-fleet-authenticate-users.md) and [call APIs as the user with the routed agent's identity](aspnet-core-fleet-call-apis-as-user.md). For the single-instance path, follow [Call a custom API as a user with ASP.NET Core](aspnet-core-call-custom-api-as-user.md) instead of copying the fleet's blueprint-audience configuration. If your original app registration had Azure RBAC role assignments, assign the same roles to the new agent identity's service principal so it can access the required Azure resources at runtime: @@ -243,8 +245,10 @@ New-AzRoleAssignment ` Agent ID uses a two-stage token acquisition model. Your agent first acquires a bootstrap token by using the blueprint's credential, then exchanges it for an agent-specific token. For more information on updating your code, see these scenarios: -- [Autonomous agent authentication and authorization flow](autonomous-agent-authentication-authorization-flow.md) for the complete token acquisition walkthrough.-- [Interactive agent authentication and authorization flow](interactive-agent-authentication-authorization-flow.md) for interactive agents guidance, code samples, and token configuration. The token flow in these agents adds an OBO exchange where a user token is exchanged for an agent token with user context.+- [Call a custom API as an agent with ASP.NET Core](call-api-custom.md) for the complete app-only token acquisition walkthrough.+- [Call a custom API as a user with ASP.NET Core](aspnet-core-call-custom-api-as-user.md) for interactive agent guidance, code samples, and token configuration. The token flow in these agents adds an OBO exchange where a user token is exchanged for an agent token with user context.++These two tutorials use one configured agent identity. For a fleet, use [Call APIs as an agent in a fleet](aspnet-core-fleet-call-apis-as-agent.md) or [Call APIs as a user in a fleet](aspnet-core-fleet-call-apis-as-user.md) so each operation selects the correct agent identity from the runtime's directory. ## Phase 4: Validate and decommission @@ -267,9 +271,9 @@ After migrating an agent identity, validate that the new Agent ID works correctl For agents with high usage, run the old and new identities side by side before switching over: 1. Deploy a parallel instance of your agent configured with the new Agent ID.-1. Route a percentage of traffic to the new instance (start with 5–10%).+1. Route a small, measured share of traffic to the new instance. Choose the initial share based on the workload's risk and rollback capacity. 1. Monitor both instances for errors, latency differences, and permission issues.-1. Gradually increase traffic to the new instance over one to two weeks.+1. Gradually increase traffic after reviewing telemetry and meeting your rollout criteria. Set observation periods based on the workload. 1. Once 100% of traffic runs on the new identity, proceed to decommission. Use feature flags or traffic-splitting infrastructure to control the rollout. This approach lets you revert to the old identity instantly if issues arise.@@ -279,7 +283,7 @@ Use feature flags or traffic-splitting infrastructure to control the rollout. Th After you validate the new Agent ID and it carries production traffic, decommission the old identity. Follow these safeguards to minimize risk: - **Pre-deletion snapshot:** Export the service principal's metadata, permissions, and audit history before deletion. This export provides a rollback reference if anything was missed during validation.-- **Phased batches:** If you're decommissioning multiple identities, delete in small batches (20-50 service principals per wave) rather than bulk-deleting all at once.+- **Phased batches:** If you're decommissioning multiple identities, delete in small, reviewable waves. Set each wave size based on tested rollback capacity rather than an assumed platform limit. - **Soft-delete first:** Use Microsoft Entra's soft-delete capability (30-day recycle bin for applications) before hard deletion. This step gives you a recovery window. <a name="decommission-steps"></a> 