Migreer Copilot Studio-agenten naar Microsoft Entra Agent-ID

Dit artikel beschrijft hoe bestaande Copilot Studio-agenten optioneel kunnen migreren van de legacy app-registratieidentiteit naar een Microsoft Entra Agent-ID voorafgaand aan automatische migratie.

Gebruik de aanbeveling in het Power Platform admin center om in aanmerking komende agenten te identificeren, migratiebatches te plannen en één of meer agenten te migreren. Deze op Advisor gebaseerde ervaring is de aanbevolen handmatige migratiemethode. Je kunt ook Power Platform API-endpoints gebruiken om je eigen migratieproces te creëren.

Wanneer je een agent migreert naar Microsoft Entra Agent-ID, krijg je:

• Een eersteklas agentidentiteit die beheerders kunnen bekijken en beheren in Microsoft Entra.
• Conditionele toegang en andere toegangsbeleidslijnen zijn ontworpen voor agentische workloads en worden beperkt tot agents in plaats van geërfd van app-registraties.
• Een consistent identiteitsmodel over de diensten die met je agenten werken.

Lees meer over agentidentiteiten en authenticatie voor Copilot Studio.

Over migratie van agentidentiteit

Migratie zet de bestaande app-registratieidentiteit van een agent om. De agent behoudt zijn applicatie-ID (client-ID), dus downstream-configuraties die die ID gebruiken, zoals kanaalregistraties en connectors, blijven worden opgelost naar dezelfde identifier. De agent krijgt ook een Microsoft Entra Agent-ID die beheerders kunnen beheren.

Migratie is een gecontroleerde, opt-in operatie. U kunt het volgende doen:

• Migrer één agent.
• Selecteer meerdere agenten en migreer ze als een batch.
• Migreer aanvullende batches volgens je eigen planning.
• Zet een agent terug naar de oorspronkelijke identiteit als deze de validatie niet doorstaat.

Prerequisites

• Je moet Power Platform Administrator, Dynamics 365 Administrator of Global Administrator zijn.
• Power Platform-inventaris moet ingeschakeld zijn voor je tenant zodat Advisor in aanmerking komende agenten kan identificeren.
• Stem een validatieperiode af met de makers die eigenaar zijn van de agenten die je wilt migreren.

Plan je migratiebatches

Het migreren van agentidentiteiten beïnvloedt live agents en kan authenticatie, connectors en integraties verstoren als je de migratie niet zorgvuldig plant. Gebruik de volgende gefaseerde aanpak:

1. Begin met een pilot: Selecteer een kleine set niet-kritieke agenten die de kanalen, authenticatiemodi, connectors, flows en integraties vertegenwoordigen die je moet valideren.
2. Stem af met makers: Informeer de betrokken makers en kom een validatiemoment overeen. Makers moeten beschikbaar zijn om hun agenten te testen zodra een migratiebatch is voltooid.
3. Migreren incrementeel: Migreer agenten afzonderlijk of in kleine batches. Migrer niet de hele nalatenschap in één keer.
4. Valideer end-to-end: Bevestig dat elke gemigreerde agent werkt via zijn geconfigureerde kanalen, acties, connectors, authenticatieflows en integraties.
5. Monitor en breid uit: Bekijk de Microsoft Entra-aanmeldlogs, inclusief resultaten van Conditional Access, voordat je een grotere batch migreert.

Agents migreren in het Power Platform-beheercentrum

Gebruik de aanbeveling van Advisor in het Power Platform admin center om in aanmerking komende agenten te bekijken en één of meer agenten te migreren.

1. Meld u aan bij het Power Platform-beheercentrum.

2. Selecteer in het linker navigatiepaneel Acties.

3. Selecteer onder Acties de optie Aanbevelingen.

4. Selecteer op het tabblad AanbevelingenActief.

5. Zoek naar en selecteer Copilot Studio-agents migreren naar Microsoft Entra Agent-ID voor verbeterd agentbeheer.

   

6. Breid in het aanbevelingspaneel Waarom is dit belangrijk? uit en bekijk de migratierichtlijnen.

7. Bekijk de in aanmerking komende makelaars. Gebruik Voorgestelde migratievolgorde en Migratienotities om een eerste pilot of de volgende migratiebatch te kiezen. De tabel geeft ook informatie zoals omgeving, omgevingstype, eigenaar, recente activiteit en authenticatiemethode.

8. Selecteer het selectievakje naast elke agent die je wilt migreren. Je kunt één agent of meerdere in aanmerking komende agenten kiezen.

   De knop Migreren wordt beschikbaar en de actiebalk toont het aantal geselecteerde agenten.

   

9. Selecteer Migreren, bekijk de bevestiging en bevestig de migratie.

10. Bekijk de kolommen Actie, Actiestatus en Actiedatum voor elke geselecteerde agent. Om acties in aanbevelingen te bekijken, selecteer je het tabblad Actiegeschiedenis .

Herhaal deze stappen voor elke geplande batch pas nadat de vorige batch de validatie heeft doorstaan.

Valideer gemigreerde agenten

Voordat je nog een batch migreert, stem je af met de ontwikkelaars van de agenten en bevestig je ervoor dat elke gemigreerde agent:

• Reageert correct in elk kanaal waar het wordt gepubliceerd.
• Voert acties, verbindingen, stromen en integraties met succes uit.
• Authenticeert zoals verwacht, inclusief aangepaste authenticatie.
• Werkt zoals verwacht met het toepasselijke beleid voor agenttoegang en beleid voor voorwaardelijke toegang.

Bekijk de aanmeldlogboeken van de geïmporteerde agenten in het Microsoft Entra-beheercentrum. Bevestig succesvolle authenticatie en onderzoek fouten of onverwachte resultaten van Conditional Access.

Als een agent niet door de validatie komt, stop dan de batch-uitrol en zet die agent terug voordat je verder gaat.

Optioneel: API-operaties voor agent-ID-migratie

Als je liever je eigen automatisering bouwt, kun je Power Platform API-endpoints aanroepen om agents te migreren of terug te zetten (rollback). Beide bewerkingen zijn HTTP POST-verzoeken die zijn geautoriseerd met een bearertoken voor de Power Platform-service.

Meer informatie vindt u in:

• Power Platform-API en SDK's: Van UX-first naar API-first (Blog) ( Power Platform Developer Blog)
• Overzicht van programmeerbaarheid en uitbreidbaarheid (Power Platform-documentatie)
• Begin met de Power Platform API (Power Platform-documentatie)
• Copilot Studio operations API-referentiedocumentatie

Haal een OAuth2 bearer token voor de Power Platform API

Alle hier vermelde bewerkingen vereisen een OAuth2 draagtoken voor https://api.powerplatform.com. Voeg dit token toe aan je verzoek onder een Authorization header. De token moet afkomstig zijn van Microsoft Entra ID OAuth2 en gekoppeld zijn aan een gebruikersaccount dat een van de beheerdersrollen heeft die in de vereisten zijn vermeld.

Gebruik bijvoorbeeld de Az PowerShell-module om het token te krijgen en op te slaan zoals $token voor gebruik in API-verzoeken:

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

Agent-id migreren naar Microsoft Entra Agent-ID

Migreer een agent van app-registratie-ID naar Entra Agent-ID door een POST-verzoek naar het migratie-endpoint te sturen met de gegevens van de agent:

• Eindpunt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Authenticatie: Voeg een geldig OAuth-draagtoken voor Power Platform API toe in de Authorization header. De Power Platform API vereist een draagtoken van Microsoft Entra ID.
• Lichaam: Niet vereist
• Doel: Een agent migreren van app-registratie-ID naar Entra Agent-ID
• Antwoord: Retourneert een AgentIdentityMigrationResult JSON-object met een status waarde voor de ID-migratie van de agent:
  • Migrated
  • AlreadyMigrated

Bijvoorbeeld, het volgende script krijgt een autorisatietoken en roept vervolgens het migratie-eindpunt aan voor een specifieke agent (<BotId>) in een specifieke omgeving (<EnvironmentId>) met die autorisatie:

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

Het volgende voorbeeldantwoord toont een succesvolle migratie:

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

Zet de agentidentiteit terug of rol terug naar app-registratie-ID

Om een agent terug te draaien, stuur je een POST-verzoek naar het terugdraaiende eindpunt met de gegevens van de agent:

• Eindpunt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Authenticatie: Voeg een geldig OAuth-draagtoken voor Power Platform API toe in de Authorization header. De Power Platform API vereist een draagtoken van Microsoft Entra ID.
• Lichaam: Niet vereist
• Doel: Rollback (terugdraaien) van een agent-ID van een Entra ID naar een app-registratie-ID
• Antwoord: Geeft een AgentIdentityRollbackResult JSON-object terug met een terminalstatuswaarde voor de ID-migratie van de agent:
  • NotMigrated
  • RolledBack

Bijvoorbeeld, het volgende script ontvangt een token en roept vervolgens het revert-eindpunt aan voor een specifieke agent (<BotId>) in een specifieke omgeving (<EnvironmentId>) met die autorisatie:

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

Het volgende voorbeeldantwoord toont een geslaagde rollback:

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

Troubleshooting

De volgende tabel geeft veelvoorkomende problemen weer en hoe deze op te lossen:

Verwante onderwerpen

• Voorbeeldquery’s voor de Power Platform-inventaris
• Copilot Studio agenteninventaris