Migrer Copilot Studio-agenter til Microsoft Entra-agent-id

Denne artikel beskriver, hvordan man eventuelt kan migrere eksisterende Copilot Studio-agenter fra den ældre app-registreringsidentitet til et Microsoft Entra-agent-id inden automatisk migrering.

Brug anbefalingen i Power Platform-administrationscentret til at identificere berettigede agenter, planlægge migrationsbatches og migrere en eller flere agenter. Denne rådgiverbaserede oplevelse er den anbefalede manuelle migrationsmetode. Du kan også bruge Power Platform API-endpoints til at oprette din egen migrationsproces.

Når du migrerer en agent til Microsoft Entra-agent-id, får du:

• En førsteklasses agentidentitet, som administratorer kan se og styre i Microsoft Entra.
• Betinget adgang og andre adgangspolitikker, der er designet til agentbaserede arbejdsbelastninger og afgrænset til agenter i stedet for at blive nedarvet fra appregistreringer.
• En ensartet identitetsmodel på tværs af de tjenester, der arbejder med dine agenter.

Lær mere om agentidentiteter og autentificering for Copilot Studio.

Om agentidentitetsmigration

Migration konverterer en agents eksisterende app-registreringsidentitet på plads. Agenten beholder sit applikations-(klient-)ID, så nedstrøms konfigurationer, der bruger dette ID, såsom kanalregistreringer og forbindelser, fortsætter med at blive løst til samme identifikator. Agenten får også et Microsoft Entra-agent-id, som administratorer kan administrere.

Migration er en kontrolleret, opt-in operation. Du kan:

• Migrer én agent.
• Vælg flere agenter og migrer dem som en batch.
• Migrer yderligere batches efter din egen tidsplan.
• Tilbagefør en agent til dens gamle identitet, hvis den ikke består valideringen.

Forudsætninger

• Du skal være Power Platform Administrator, Dynamics 365 Administrator eller Global Administrator.
• Power Platform-inventaret skal være aktiveret for din lejer, så Advisor kan identificere berettigede agenter.
• Koordiner et valideringsvindue med de skabere, der ejer de agenter, du planlægger at migrere.

Planlæg dine migrationsbatches

Migrering af agentidentiteter påvirker live agenter og kan forstyrre autentificering, forbindelser og integrationer, hvis du ikke planlægger migreringen omhyggeligt. Brug følgende trindelte tilgang:

1. Start med en pilot: Vælg et lille sæt ikke-kritiske agenter, der repræsenterer kanaler, autentificeringstilstande, forbindelser, flows og integrationer, du skal validere.
2. Koordiner med skaberne: Underret de berørte producenter og aftale et valideringsvindue. Producenter bør være tilgængelige for at teste deres agenter, når en migrationsbatch er færdig.
3. Migrer inkrementalt: Migrer agenter individuelt eller i små batches. Flyt ikke hele boet på én gang.
4. Valider ende-til-ende: Bekræft, at hver migreret agent fungerer på tværs af sine konfigurerede kanaler, handlinger, connectors, autentificeringsflows og integrationer.
5. Overvåg og udvid: Gennemgå Microsoft Entra-loginlogs, inklusive resultater af betinget adgang, før du migrerer en større batch.

Migrer agenter i Power Platform administrationscenter

Brug Advisor-anbefalingen i Power Platform-administrationscentret til at gennemgå berettigede agenter og migrere en eller flere agenter.

1. Log på Power Platform-administrationscenteret.

2. I venstre navigationspanel vælger du Handlinger.

3. Under Handlinger, vælg Anbefalinger.

4. På fanen Anbefalinger vælger du Aktiv.

5. Søg efter og vælg Migrer Copilot Studio-agenter til Microsoft Entra-agent-id for forbedret agentstyring.

   

6. I anbefalingspanelet skal du udvide Hvorfor er dette vigtigt?, og gennemgå migrationsvejledningen.

7. Gennemgå de kvalificerede agenter. Brug foreslået migrationsrækkefølge og migrationsnoter til at vælge en indledende pilot eller næste migrationsbatch. Tabellen giver også information som miljø, miljøtype, ejer, nylig aktivitet og autentificeringsmetode.

8. Vælg afkrydsningsboksen ved siden af hver agent, du vil migrere. Du kan vælge én agent eller flere kvalificerede agenter.

   Migrér-knappen bliver tilgængelig, og handlingslinjen viser antallet af valgte agenter.

   

9. Vælg Migrer, gennemgå bekræftelsen, og bekræft migreringen.

10. Gennemgå kolonnerne Handling, Handlingstilstand og Handlingsdato for hver udvalgt agent. For at gennemgå handlinger på tværs af anbefalinger, vælg fanen Handlingshistorik .

Gentag disse trin for hver planlagt batch først, efter at den forrige batch har bestået valideringen.

Valider migrerede agenter

Før du migrerer en ny batch, skal du koordinere med agenternes skabere og bekræfte, at hver migreret agent:

• Svarer korrekt i alle kanaler, hvor det bliver offentliggjort.
• Kører sine handlinger, forbindelser, flows og integrationer med succes.
• Autentificeres som forventet, inklusive brugerdefineret autentificering.
• Fungerer som forventet med gældende agentadgangspolitikker og betingede adgangspolitikker.

Gennemgå loginloggene for de migrerede agenter i Microsoft Entra-administrationscenter. Bekræft vellykket autentificering og undersøg fejl eller uventede resultater af betinget adgang.

Hvis en agent ikke består valideringen, så stop batch-udrulningen og tilbagefør agenten, før du fortsætter.

Valgfrit: API-operationer til agent-ID-migrering

Hvis du foretrækker at bygge din egen automatisering, kan du kalde Power Platform API-endpoints for at migrere eller gendanne (rollback) agenter. Begge operationer er HTTP POST-forespørgsler, der er autoriseret med en bærertoken for Power Platform-tjenesten.

Lær mere i:

• Power Platform API og SDK'er: Fra UX-first til API-first (Blog) (Power Platform Developer Blog)
• Oversigt over programmering og udvidelse (Power Platform-dokumentation)
• Kom i gang med Power Platform API (Power Platform-dokumentation)
• Copilot Studio operations API-referencedokumentation

Få en OAuth2 bærertoken til Power Platform API'en

Alle de operationer, der er nævnt her, kræver et OAuth2-bærertoken for https://api.powerplatform.com. Inkluder dette token i din anmodning under en Authorization overskrift. Tokenet skal komme fra Microsoft Entra ID OAuth2 og være tilknyttet en brugerkonto, der har en af de admin-roller, der er angivet i forudsætningerne.

For eksempel kan du bruge Az PowerShell-modulet til at hente tokenet og gemme det, som $token det bruges i API-forespørgsler:

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

Migrer agentidentitet til Microsoft Entra-agent-id

Migrer en agent fra app-registrerings-ID til Entra-agent-id ved at sende en POST-anmodning til migreringsendpointet med agentens oplysninger:

• Slutpunkt: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Autentificering: Inkluder en gyldig OAuth bærertoken for Power Platform API i Authorization headeren. Power Platform API kræver et bærertoken fra Microsoft Entra ID.
• Brødtekst: Ikke obligatorisk
• Formål: Migrer en agent fra app-registrerings-ID til Entra-agent-id
• Svar: Returnerer et AgentIdentityMigrationResult JSON-objekt med en status værdi for agentens ID-migration:
  • Migrated
  • AlreadyMigrated

For eksempel får følgende script et autorisationstoken og kalder derefter migreringsendpointet for en specifik agent (<BotId>) i et specifikt miljø (<EnvironmentId>) med denne 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"
    }

Følgende eksempelsvar viser en vellykket 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"
}

Tilbagefør eller rull agentens identitet tilbage til app-registrerings-ID

For at gendanne en agent skal du sende en POST-anmodning til genoprettelsesendepunktet med agentens oplysninger:

• Slutpunkt: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Autentificering: Inkluder en gyldig OAuth bærertoken for Power Platform API i Authorization headeren. Power Platform API kræver et bærertoken fra Microsoft Entra ID.
• Brødtekst: Ikke påkrævet
• Formål: Rulle (tilbagelægge) en agents ID fra et Entra ID til et app-registrerings-ID
• Svar: Returnerer et AgentIdentityRollbackResult JSON-objekt med en terminalstatusværdi for agentens ID-migration:
  • NotMigrated
  • RolledBack

For eksempel får følgende script et token og kalder derefter revert-endpointet for en specifik agent (<BotId>) i et specifikt miljø (<EnvironmentId>) med den 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"
    }

Følgende eksempelsvar viser en vellykket rollback:

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

Fejlfinding

Følgende tabel viser almindelige problemer og hvordan man løser dem:

Relateret indhold

• Eksempelforespørgsler i Power Platform-lager
• Copilot Studio-oversigt over agenter