Migrera Copilot Studio-agenter till Microsoft Entra agent-ID

Den här artikeln beskriver hur man valfritt migrerar befintliga Copilot Studio-agenter från den äldre appregistreringsidentiteten till ett Microsoft Entra agent-ID innan automatisk migrering.

Använd rekommendationen i Power Platforms admincenter för att identifiera berättigade agenter, planera migreringsbatcher och migrera en eller flera agenter. Denna Advisor-baserade upplevelse är den rekommenderade manuella migreringsmetoden. Du kan också använda Power Platform API-endpoints för att skapa din egen migreringsprocess.

När du migrerar en agent till Microsoft Entra agent-ID får du:

• En förstklassig agentidentitet som administratörer kan se och styra i Microsoft Entra.
• Villkorad åtkomst och andra åtkomstprinciper som är utformade för agentbaserade arbetsbelastningar och gäller för agenter i stället för att ärvas från appregistreringar.
• En konsekvent identitetsmodell över de tjänster som arbetar med dina agenter.

Läs mer om agentidentiteter och autentisering för Copilot Studio.

Om migrering av agentidentitet

Migrering omvandlar en agents befintliga appregistreringsidentitet på plats. Agenten behåller sitt program-ID (klient-ID), så efterföljande konfigurationer som använder detta ID, till exempel kanalregistreringar och anslutningar, fortsätter att referera till samma identifierare. Agenten får också ett Microsoft Entra agent-ID som administratörer kan hantera.

Migrering är en kontrollerad, frivillig operation. Du kan:

• Migrera en agent.
• Välj flera agenter och migrera dem som en batch.
• Migrera fler batcher efter eget schema.
• Återställ en agent till dess äldre identitet om den inte klarar valideringen.

Förutsättningar

• Du måste vara Power Platform Administrator, Dynamics 365 Administrator eller Global Administrator.
• Power Platform-inventariet måste vara aktiverat för din hyresgäst så att Advisor kan identifiera berättigade agenter.
• Samordna ett valideringsfönster med de tillverkare som äger de agenter du planerar att migrera.

Planera dina migrationsbatcher

Att migrera agentidentiteter påverkar live-agenter och kan störa autentisering, kopplingar och integrationer om du inte planerar migreringen noggrant. Använd följande stegvisa tillvägagångssätt:

1. Börja med en pilot: Välj en liten uppsättning icke-kritiska agenter som representerar kanaler, autentiseringslägen, kopplingar, flöden och integrationer du behöver validera.
2. Samarbeta med tillverkare: Meddela berörda tillverkare och kom överens om ett valideringsfönster. Skapare bör vara tillgängliga för att testa sina agenter när en migreringsbatch är klar.
3. Migrera inkrementellt: Migrera agenter individuellt eller i små batcher. Migrera inte hela IT-miljön på en gång.
4. Validera från början till slut: Bekräfta att varje migrerad agent fungerar över sina konfigurerade kanaler, åtgärder, kopplingar, autentiseringsflöden och integrationer.
5. Övervaka och utöka: Gå igenom inloggningsloggar för Microsoft Entra, inklusive resultat för villkorlig åtkomst, innan du migrerar en större batch.

Migrera agenter i Power Platform-administrationscentret

Använd Advisor-rekommendationen i Power Platform-administrationscentret för att granska berättigade agenter och migrera en eller flera agenter.

1. Logga in på Power Platform-administratörscenter.

2. I vänstra navigationspanelen, välj Åtgärder.

3. Under Åtgärder, välj Rekommendationer.

4. På fliken Rekommendationer , välj Aktiv.

5. Sök efter och välj Migrera Copilot Studio-agenter till Microsoft Entra agent-ID för förbättrad styrning av agenter.

   

6. I rekommendationsrutan, expandera Varför är detta viktigt? och granska migrationsguiden.

7. Granska de berättigade agenterna. Använd Föreslagen migrationsordning och Migrationsanteckningar för att välja en initial pilot eller nästa migrationsbatch. Tabellen ger också information såsom miljö, miljötyp, ägare, senaste aktivitet och autentiseringsmetod.

8. Välj kryssrutan bredvid varje agent du vill migrera. Du kan välja en agent eller flera behöriga agenter.

   Flytta-knappen blir tillgänglig och åtgärdsfältet visar antalet valda agenter.

   

9. Välj Migrera, granska bekräftelsen och bekräfta migreringen.

10. Gå igenom kolumnerna Åtgärd, Åtgärdstillstånd och Åtgärdsdatum för varje vald agent. För att granska åtgärder över rekommendationer, välj fliken Åtgärdshistorik .

Upprepa dessa steg för varje planerad omgång först efter att den föregående omgången har klarat valideringen.

Validera migrerade agenter

Innan du migrerar en ny batch, samordna med agenternas skapare och bekräfta att varje migrerad agent:

• Svarar korrekt i varje kanal där det publiceras.
• Kör sina åtgärder, kopplingar, flöden och integrationer framgångsrikt.
• Autentiserar som förväntat, inklusive anpassad autentisering.
• Fungerar som förväntat med tillämpliga agentåtkomstpolicyer och villkorlig åtkomstpolicy.

Gå igenom inloggningsloggarna för de migrerade agenterna i Microsoft Entra administrationscenter. Bekräfta lyckad autentisering och undersök fel eller oväntade resultat av villkorlig åtkomst.

Om en agent inte klarar valideringen, stoppa batchutrullningen och återställ agenten innan du fortsätter.

Valfritt: API-operationer för agent ID-migrering

Om du föredrar att bygga din egen automation kan du anropa Power Platform API-endpoints för att migrera eller återställa (rollback) agenter. Båda operationerna är HTTP POST-förfrågningar auktoriserade med en bärartoken för Power Platform-tjänsten.

Läs mer i:

• Power Platform API och SDK:er: Från UX-first till API-first (blogg) (Power Platform-utvecklarblogg)
• Översikt över programmering och utökningsbarhet (Power Platform-dokumentation)
• Kom igång med Power Platform API (Dokumentation om Power Platform)
• Copilot Studio operations API-referensdokumentation

Skaffa en OAuth2-bärertoken för Power Platform API:et

Alla operationer som listas här kräver en OAuth2-bärertoken för https://api.powerplatform.com. Inkludera denna token i din förfrågan under en Authorization rubrik. Token måste komma från Microsoft Entra ID OAuth2 och vara kopplad till ett användarkonto som har en av administratörsrollerna som anges i förkunskaperna.

Använd till exempel Az PowerShell-modulen för att hämta token och lagra den som $token för användning i API-förfrågningar:

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

Migrera agentidentitet till Microsoft Entra agent-ID

Migrera en agent från appregistrerings-ID till Entra agent-ID genom att skicka en POST-förfrågan till migreringsterminalen med agentens uppgifter:

• Slutpunkt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Autentisering: Inkludera en giltig OAuth-bärartoken för Power Platform API i Authorization headern. Power Platform API kräver en bärartoken från Microsoft Entra ID.
• Text: Inte obligatoriskt
• Syfte: Migrera en agent från appregistrerings-ID till Entra agent-ID
• Svar: Returnerar ett AgentIdentityMigrationResult JSON-objekt med ett status värde för agentens ID-migrering:
  • Migrated
  • AlreadyMigrated

Till exempel får följande skript en auktorisationstoken och anropar sedan migreringsändpunkten för en specifik agent (<BotId>) i en specifik miljö (<EnvironmentId>) med den auktorisationen:

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

Följande exempelsvar visar en lyckad 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"
}

Återställ eller rulla tillbaka agentidentitet till appregistrerings-ID

För att återställa en agent, skicka en POST-förfrågan till återställningsändpunkten med agentens uppgifter:

• Slutpunkt:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Autentisering: Inkludera en giltig OAuth-bärartoken för Power Platform API i Authorization headern. Power Platform API kräver en bärartoken från Microsoft Entra ID.
• Text: Krävs inte
• Syfte: Återställa (återställa) en agents ID från ett Entra ID till ett appregistrerings-ID
• Svar: Returnerar ett AgentIdentityRollbackResult JSON-objekt med ett terminalstatusvärde för agentens ID-migrering:
  • NotMigrated
  • RolledBack

Till exempel får följande skript en token och anropar sedan återställningsändpunkten för en specifik agent (<BotId>) i en specifik miljö (<EnvironmentId>) med den auktorisationen:

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

Följande exempelsvar visar en lyckad rollback:

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

Troubleshooting

Följande tabell listar vanliga problem och hur man löser dem:

Relaterat innehåll

• Exempelfrågor för inventering i Power Platform
• Copilot Studio-agentöversikt