Migrate Copilot Studio agents to Microsoft Entra Agent ID

Important

This article contains Microsoft Copilot Studio preview documentation and is subject to change.

Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that you can get early access and provide feedback.

If you're building a production-ready agent, see Microsoft Copilot Studio Overview.

This article describes how to optionally migrate existing Copilot Studio agents from the legacy app-registration identity to a Microsoft Entra Agent ID ahead of automatic migration.

Important

Before May 2026, Copilot Studio automatically provisioned an Azure app registration in your tenant for each agent you created. After May 2026, Copilot Studio automatically creates a Microsoft Entra Agent ID for each new agent.

Existing agents that use an app-registration identity will be automatically migrated by Microsoft in a future update.

Governance capabilities work for both Entra Agent IDs and app registration IDs during this transition period and all agents will eventually be automatically migrated. However, you can optionally choose to manually migrate older agents to use Entra Agent IDs now to help validate that your agents work as expected with Microsoft Entra Agent IDs and conditional access policies before the automatic migration occurs.

Use the recommendation in the Power Platform admin center to identify eligible agents, plan migration batches, and migrate one or more agents. This Advisor-based experience is the recommended manual migration method. You can also use Power Platform API endpoints to create your own migration process.

When you migrate an agent to Microsoft Entra Agent ID, you get:

  • A first-class agent identity that administrators can view and govern in Microsoft Entra.
  • Conditional access and other access policies designed for agentic workloads and scoped to agents instead of inherited from app registrations.
  • A consistent identity model across the services that work with your agents.

Learn more in Agent identities and authentication for Copilot Studio.

About agent identity migration

Migration converts an agent's existing app-registration identity in place. The agent keeps its application (client) ID, so downstream configurations that use that ID, such as channel registrations and connectors, continue to resolve to the same identifier. The agent also gains a Microsoft Entra Agent ID that administrators can manage.

Migration is a controlled, opt-in operation. You can:

  • Migrate one agent.
  • Select multiple agents and migrate them as a batch.
  • Migrate additional batches on your own schedule.
  • Revert an agent to its legacy identity if it doesn't pass validation.

Prerequisites

Note

The manual Microsoft Entra Agent ID migration process is currently a preview feature.

Plan your migration batches

Migrating agent identities affects live agents and can disrupt authentication, connectors, and integrations if you don't plan the migration carefully. Use the following staged approach:

  1. Start with a pilot: Select a small set of noncritical agents that represents the channels, authentication modes, connectors, flows, and integrations you need to validate.
  2. Coordinate with makers: Notify affected makers and agree on a validation window. Makers should be available to test their agents when a migration batch completes.
  3. Migrate incrementally: Migrate agents individually or in small batches. Don't migrate the entire estate at one time.
  4. Validate end to end: Confirm that each migrated agent works across its configured channels, actions, connectors, authentication flows, and integrations.
  5. Monitor and expand: Review Microsoft Entra sign-in logs, including Conditional Access results, before you migrate a larger batch.

Migrate agents in the Power Platform admin center

Use the Advisor recommendation in the Power Platform admin center to review eligible agents and migrate one or more agents.

  1. Sign in to the Power Platform admin center.

  2. In the left navigation pane, select Actions.

  3. Under Actions, select Recommendations.

  4. On the Recommendations tab, select Active.

  5. Search for and select Migrate Copilot Studio agents to Microsoft Entra Agent ID for enhanced agent governance.

    The recommendation to migrate Copilot Studio agents to Microsoft Entra Agent ID on the Recommendations page.

  6. In the recommendation pane, expand Why is this important?, and review the migration guidance.

  7. Review the eligible agents. Use Suggested migration order and Migration notes to choose an initial pilot or the next migration batch. The table also provides information such as environment, environment type, owner, recent activity, and authentication method.

  8. Select the checkbox next to each agent you want to migrate. You can select one agent or multiple eligible agents.

    The Migrate button becomes available and the action bar shows the number of agents selected.

    The recommendation action bar with Migrate available and one agent selected.

  9. Select Migrate, review the confirmation, and confirm the migration.

  10. Review the Action, Action state, and Action date columns for each selected agent. To review actions across recommendations, select the Action history tab.

Note

Advisor recommendations can remain visible for up to one week after you act on them while the recommendation data refreshes.

Repeat these steps for each planned batch only after the previous batch passes validation.

Validate migrated agents

Before you migrate another batch, coordinate with the agents' makers and confirm that each migrated agent:

  • Responds correctly in every channel where it's published.
  • Runs its actions, connectors, flows, and integrations successfully.
  • Authenticates as expected, including custom authentication.
  • Works as expected with applicable agent access policies and Conditional Access policies.

Review the sign-in logs for the migrated agents in the Microsoft Entra admin center. Confirm successful authentication and investigate failures or unexpected Conditional Access results.

If an agent doesn't pass validation, stop the batch rollout and revert that agent before you continue.

Optional: API operations for agent ID migration

If you prefer to build your own automation, you can call Power Platform API endpoints to migrate or revert (rollback) agents. Both operations are HTTP POST requests authorized with a bearer token for the Power Platform service.

Note

You need the botID and environmentID for the target agent. Each agent shows these values in the agent inventory in the Power Platform admin center under Manage > Copilot Studio.

Learn more in:

Get an OAuth2 bearer token for the Power Platform API

All the operations listed here require an OAuth2 bearer token for https://api.powerplatform.com. Include this token in your request under an Authorization header. The token must come from Microsoft Entra ID OAuth2 and be associated with a user account that has one of the admin roles listed in the prerequisites.

For example, use the Az PowerShell module to get the token and store it as $token for use in API requests:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

Migrate agent identity to Microsoft Entra Agent ID

Migrate an agent from app-registration ID to Entra Agent ID by sending a POST request to the migrate endpoint with the agent's details:

  • Endpoint: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
  • Authentication: Include a valid OAuth bearer token for Power Platform API in the Authorization header. The Power Platform API requires a bearer token from Microsoft Entra ID.
  • Body: Not required
  • Purpose: Migrate an agent from app-registration ID to Entra Agent ID
  • Response: Returns an AgentIdentityMigrationResult JSON object with a status value for the agent's ID migration:
    • Migrated
    • AlreadyMigrated

For example, the following script gets an authorization token, and then calls the migrate endpoint for a specific agent (<BotId>) in a specific environment (<EnvironmentId>) with that authorization:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

$environmentId = "<EnvironmentId>"
$botId = "<BotId>"

$uri = "https://api.powerplatform.com/copilotstudio/environments/$environmentId/bots/$botId/api/agentidentitymigration/migrate?api-version=2024-10-01"
Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $token"
    }

The following example response shows a successful migration:

{
  "status": "Migrated",
  "cdsBotId": "<bot-id>",
  "environmentId": "<environment-id>",
  "tenantId": "<tenant-id>",
  "agentIdentityId": "<agent-identity-id>",
  "applicationId": "<application-client-id>",
  "servicePrincipalObjectId": "<service-principal-object-id>",
  "managedIdentityId": "<managed-identity-id>",
  "completedAtUtc": "2026-08-21T12:00:00Z"
}

Revert or rollback agent identity to app-registration ID

To revert an agent, send a POST request to the revert endpoint with the agent's details:

  • Endpoint: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
  • Authentication: Include a valid OAuth bearer token for Power Platform API in the Authorization header. The Power Platform API requires a bearer token from Microsoft Entra ID.
  • Body: Not required
  • Purpose: Rollback (revert) an agent's ID from an Entra ID to an app-registration ID
  • Response: Returns an AgentIdentityRollbackResult JSON object with a terminal status value for the agent's ID migration:
    • NotMigrated
    • RolledBack

For example, the following script gets a token, and then calls the revert endpoint for a specific agent (<BotId>) in a specific environment (<EnvironmentId>) with that authorization:

$token = (Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com").Token

$environmentId = "<EnvironmentId>"
$botId = "<BotId>"

$uri = "https://api.powerplatform.com/copilotstudio/environments/$environmentId/bots/$botId/api/agentidentitymigration/rollback?api-version=2024-10-01"
Invoke-RestMethod `
    -Method Post `
    -Uri $uri `
    -Headers @{
        Authorization = "Bearer $token"
    }

The following example response shows a successful rollback:

{
  "status": "RolledBack",
  "cdsBotId": "<bot-id>",
  "environmentId": "<environment-id>",
  "tenantId": "<tenant-id>",
  "completedAtUtc": "2026-08-21T12:05:00Z"
}

Troubleshooting

The following table lists common issues and how to resolve them:

Symptom Cause Resolution
The agent inventory returns no agents. Power Platform inventory isn't enabled for the tenant, or your account doesn't have a required role. Confirm that agent inventory is enabled and that you signed in with a Power Platform Administrator, Dynamics 365 Administrator, or Global Administrator account.
You're prompted to reauthenticate, or a token error appears. Credentials expired, or multifactor authentication or conditional access requires interactive sign-in. Complete the sign-in prompts in the browser window the script opens.
An agent is skipped during migration. The agent already has a Microsoft Entra Agent ID, or you're missing EnvironmentId or BotId. This condition is expected for already-migrated agents.
A migrate or revert call fails for a single agent. The API returned an error for that agent, such as not eligible, access denied, or the service throttling requests. Review the agent inventory, confirm your role, permissions, and the agent's eligibility, wait and retry if throttled, then rerun the call.

Related content

  • Last updated on