Microsoft Entra Agent ID
Standards

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:
  1. Tag-based scan: Automatically identify all tagged agents. These agents are confirmed candidates.
  2. Heuristic analysis: Scan remaining untagged service principals for behavioral signals. Flag high-confidence matches as probable candidates.candidates with multiple supporting signals for review.
  3. CMDB reconciliation: Match remaining service principals against your asset inventory to catch agents registered under non-obvious names.
  4. 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:

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:

  1. Deploy a parallel instance of your agent configured with the new Agent ID.
  2. Route a percentagesmall, measured share of traffic to the new instance (start with 5–10%).instance. Choose the initial share based on the workload's risk and rollback capacity.
  3. Monitor both instances for errors, latency differences, and permission issues.
  4. Gradually increase traffic toafter reviewing telemetry and meeting your rollout criteria. Set observation periods based on the new instance over one to two weeks.workload.
  5. 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 than bulk-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.

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…