Migrer les agents Copilot Studio vers Identifiant d’assistant Microsoft Entra

Cet article décrit comment migrer optionnellement les agents Copilot Studio existants de l’identité d’enregistrement de l’application héritée vers un Identifiant d’assistant Microsoft Entra avant la migration automatique.

Utilisez la recommandation du centre d’administration Power Platform pour identifier les agents éligibles, planifier les lots de migration et migrer un ou plusieurs agents. Cette expérience basée sur un conseiller est la méthode de migration manuelle recommandée. Vous pouvez également utiliser les points de terminaison de l’API Power Platform pour créer votre propre processus de migration.

Lorsque vous migrez un agent vers Identifiant d’assistant Microsoft Entra, vous obtenez :

• Une identité d’agent de premier ordre que les administrateurs peuvent consulter et gérer dans Microsoft Entra.
• Accès conditionnel et autres politiques d’accès conçues pour les charges de travail agentiques et axées sur les agents plutôt que héritées des enregistrements d’applications.
• Un modèle d’identité cohérent à travers les services qui travaillent avec vos agents.

En savoir plus sur les identités des agents et l’authentification pour Copilot Studio.

À propos de la migration de l’identité des agents

La migration convertit sur place l’identité d’inscription de l’application existante d’un agent. L’agent conserve son ID d’application (client), de sorte que les configurations en aval qui utilisent cet ID, telles que les enregistrements de canal et les connecteurs, continuent à pointer vers le même identifiant. L’agent obtient également un Identifiant d’assistant Microsoft Entra que les administrateurs peuvent gérer.

La migration est une opération contrôlée, avec option d’adhésion. Vous pouvez:

• Migrez un agent.
• Sélectionnez plusieurs agents et migrez-les en groupe.
• Migrez d’autres lots selon votre propre planning.
• Restaurez un agent à son ancienne identité s’il échoue à la validation.

Prerequisites

• Vous devez être administrateur Power Platform, administrateur Dynamics 365 ou administrateur global.
• L’inventaire de Power Platform doit être activé pour votre locataire afin que Advisor puisse identifier les agents éligibles.
• Coordonnez un créneau de validation avec les responsables des agents que vous prévoyez de migrer.

Planifiez vos lots de migration

La migration des identités des agents affecte les agents en temps réel et peut perturber l’authentification, les connecteurs et les intégrations si vous ne planifiez pas la migration avec soin. Utilisez l’approche progressive suivante :

1. Commencez par un projet pilote : sélectionnez un petit ensemble d’agents non critiques qui représentent les canaux, modes d’authentification, connecteurs, flux et intégrations à valider.
2. Coordonnez avec les fabricants : Informez les fabricants concernés et convenez d’une fenêtre de validation. Les fabricants devraient être disponibles pour tester leurs agents une fois le lot de migration terminé.
3. Migrer progressivement : migrer les agents individuellement ou en petits lots. Ne migrez pas tout le domaine en même temps.
4. Validez de bout en bout : Confirmez que chaque agent migré fonctionne à travers ses canaux, actions, connecteurs, flux d’authentification et intégrations configurés.
5. Surveillez et élargissez : examinez les journaux de connexion Microsoft Entra, y compris les résultats de l’Accès conditionnel, avant de migrer un lot plus important.

Migrer les agents dans le centre d’administration Power Platform

Utilisez la recommandation Advisor dans le centre d’administration Power Platform pour examiner les agents éligibles et migrer un ou plusieurs agents.

1. Connectez-vous au Centre d’administration Power Platform.

2. Dans le panneau de navigation de gauche, sélectionnez Actions.

3. Dans la section Actions, sélectionnez Recommandations.

4. Dans l’onglet Recommandations , sélectionnez Actif.

5. Recherchez et sélectionnez Migrer les agents Copilot Studio vers Identifiant d’assistant Microsoft Entra pour améliorer la gouvernance des agents.

   

6. Dans le panneau de recommandations, développez Pourquoi est-ce important ? et consultez les directives sur la migration.

7. Examinez les agents éligibles. Utilisez l’ordre de migration suggéré et les notes de migration pour choisir un pilote initial ou le prochain lot de migration. Le tableau fournit également des informations telles que l’environnement, le type d’environnement, le propriétaire, l’activité récente et la méthode d’authentification.

8. Sélectionnez la case à cocher à côté de chaque agent que vous souhaitez migrer. Vous pouvez choisir un ou plusieurs agents éligibles.

   Le bouton Migrer devient disponible et la barre d’actions affiche le nombre d’agents sélectionnés.

   

9. Sélectionnez Migrer, relisez la confirmation, puis confirmez la migration.

10. Examinez les colonnes Action, État d’Action et Date d’Action pour chaque agent sélectionné. Pour examiner les actions entre recommandations, sélectionnez l’onglet Historique des actions .

Répétez ces étapes pour chaque lot prévu seulement après que le lot précédent ait passé la validation.

Valider les agents migrés

Avant de migrer un autre lot, coordonnez-vous avec les concepteurs des agents et confirmez que chaque agent migré :

• Répond correctement sur tous les canaux sur lesquels il est publié.
• Exécute ses actions, connecteurs, flux et intégrations avec succès.
• Authentifie comme prévu, y compris une authentification personnalisée.
• Fonctionne comme prévu avec les politiques d’accès aux agents et les politiques d’accès conditionnel applicables.

Consultez les journaux de connexion des agents migrés dans le centre d’administration centre d’administration Microsoft Entra. Confirmez l’authentification réussie et enquêtez sur les échecs ou les résultats inattendus d’accès conditionnel.

Si un agent ne passe pas la validation, arrêtez le déploiement par lots et rétablissez cet agent dans son état précédent avant de continuer.

Optionnel : opérations API pour la migration des identifiants d’agent

Si vous préférez créer votre propre automatisation, vous pouvez appeler les points de terminaison de l’API Power Platform pour migrer des agents ou les restaurer à l’état précédent. Les deux opérations sont des requêtes HTTP POST autorisées avec un jeton porteur pour le service Power Platform.

Pour en savoir plus :

• API Power Platform et SDK : De l’approche centrée sur l’UX à l’approche centrée sur l’API (blog) (blog du développeur Power Platform)
• Vue d’ensemble de la programmabilité et de l’extensibilité (documentation Power Platform)
• Commencez avec l’API Power Platform (documentation de Power Platform)
• Documentation de référence de l’API des opérations Copilot Studio

Obtenez un jeton porteur OAuth2 pour l’API Power Platform

Toutes les opérations listées ici nécessitent un jeton porteur OAuth2 pour https://api.powerplatform.com. Incluez ce jeton dans votre requête sous l’en-tête Authorization. Le jeton doit provenir de Microsoft Entra ID OAuth2 et être associé à un compte utilisateur ayant l’un des rôles d’administrateur listés dans les prérequis.

Par exemple, utilisez le module Az PowerShell pour obtenir le jeton et le stockez comme $token usage dans les requêtes API :

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

Migrer l’identité de l’agent vers Identifiant d’assistant Microsoft Entra

Migrez un agent de l'ID d'enregistrement de l'application vers l'Identifiant d’assistant Entra en envoyant une requête POST au point de terminaison de migration avec les coordonnées de l'agent :

• Point de terminaison :POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Authentification : Incluez un token porteur OAuth valide pour l’API Power Platform dans l’en-tête Authorization . L’API Power Platform nécessite un jeton porteur provenant de Microsoft Entra ID.
• Texte : Non requis
• Objectif : Migrer un agent de l’ID d’enregistrement de l’application vers l’Identifiant d’assistant Entra
• Réponse : Retourne un AgentIdentityMigrationResult objet JSON avec une status valeur pour la migration d’ID de l’agent :
  • Migrated
  • AlreadyMigrated

Par exemple, le script suivant reçoit un jeton d’autorisation, puis appelle le point de terminaison de migration pour un agent spécifique (<BotId>) dans un environnement spécifique (<EnvironmentId>) avec cette autorisation :

$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"
    }

L’exemple de réponse suivant montre une migration réussie :

{
  "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"
}

Restaurer ou revenir en arrière à l’identité de l’agent en identifiant d’enregistrement de l’application

Pour restaurer un agent, envoyez une requête POST au point de départ de retour avec les coordonnées de l’agent :

• Point de terminaison :POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Authentification : Incluez un token porteur OAuth valide pour l’API Power Platform dans l’en-tête Authorization . L’API Power Platform nécessite un jeton porteur provenant de Microsoft Entra ID.
• Corps du message : Facultatif
• Objectif : rétablir l’ID d’un agent d’un ID Entra vers un ID d’inscription d’application
• Réponse : Retourne un AgentIdentityRollbackResult objet JSON avec une valeur de statut terminal pour la migration de l’ID de l’agent :
  • NotMigrated
  • RolledBack

Par exemple, le script suivant reçoit un jeton, puis appelle le point de retour pour un agent spécifique (<BotId>) dans un environnement spécifique (<EnvironmentId>) avec cette autorisation :

$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"
    }

L’exemple de réponse suivant montre un retour en arrière réussi :

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

Résolution des problèmes

Le tableau suivant présente les problèmes courants et comment les résoudre :

Contenu connexe

• Exemples de requêtes d’inventaire Power Platform
• Inventaire des agents de Copilot Studio