Migrer Copilot Studio-agenter til Microsoft Entra Agent ID

Denne artikkelen beskriver hvordan man eventuelt kan migrere eksisterende Copilot Studio-agenter fra den gamle appregistreringsidentiteten til en Microsoft Entra Agent ID før automatisk migrering.

Bruk anbefalingen i Power Platform-administrasjonssenteret for å identifisere kvalifiserte agenter, planlegge migreringsbatcher og migrere én eller flere agenter. Denne rådgiverbaserte opplevelsen er den anbefalte manuelle migreringsmetoden. Du kan også bruke Power Platform API-endepunkter for å lage din egen migreringsprosess.

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 tilgang og andre tilgangspolicyer som er utformet for agentbaserte arbeidsbelastninger og avgrenset til agenter i stedet for å arves fra appregistreringer.
• En konsistent identitetsmodell på tvers av tjenestene som samarbeider med agentene dine.

Lær mer i Agentidentiteter og autentisering for Copilot Studio.

Om migrasjon av agentidentitet

Migrasjon konverterer en agents eksisterende appregistreringsidentitet på plass. Agenten beholder sin applikasjons-ID, så nedstrøms konfigurasjoner som bruker denne ID-en, som kanalregistreringer og koblinger, fortsetter å løse til samme identifikator. Agenten får også en Microsoft Entra Agent ID som administratorer kan administrere.

Migrasjon er en kontrollert, frivillig operasjon. Du kan:

• Migrer én agent.
• Velg flere agenter og migrer dem som en batch.
• Migrer flere batcher etter din egen tidsplan.
• Tilbakefør en agent til sin legacy-identitet hvis den ikke består valideringen.

Forutsetninger

• Du må være Power Platform Administrator, Dynamics 365 Administrator eller Global Administrator.
• Power Platform-inventaret må være aktivert for leietakeren din slik at Advisor kan identifisere kvalifiserte agenter.
• Koordiner et valideringsvindu med produsentene som eier agentene du planlegger å migrere.

Planlegg dine migreringsbatcher

Migrering av agentidentiteter påvirker levende agenter og kan forstyrre autentisering, koblinger og integrasjoner hvis du ikke planlegger migreringen nøye. Bruk følgende trinnvise tilnærming:

1. Start med en pilot: Velg et lite sett med ikke-kritiske agenter som representerer kanalene, autentiseringsmodusene, koblingene, flytene og integrasjonene du må validere.
2. Koordiner med produsenter: Varsle berørte produsenter og bli enige om et valideringsvindu. Skapere bør være tilgjengelige for å teste agentene sine når en migreringsbatch er fullført.
3. Migrer gradvis: Migrer agenter individuelt eller i små batcher. Ikke flytt hele boet på én gang.
4. Valider ende-til-ende: Bekreft at hver migrert agent fungerer på tvers av sine konfigurerte kanaler, handlinger, koblinger, autentiseringsflyter og integrasjoner.
5. Overvåk og utvid: Gå gjennom Microsoft Entra-logger, inkludert resultater for betinget tilgang, før du migrerer en større batch.

Migrer agenter i Power Platform administrasjonssenter

Bruk anbefalingen fra Advisor i Power Platform-administrasjonssenteret for å gjennomgå kvalifiserte agenter og migrere én eller flere agenter.

1. Logg på Power Platform-administrasjonssenteret.

2. Velg Handlinger i venstre navigasjonspanel.

3. Under Handlinger, velg Anbefalinger.

4. På fanen Anbefalinger , velg Aktiv.

5. Søk etter og velg Migrer Copilot Studio-agenter til Microsoft Entra Agent ID for bedre agentstyring.

   

6. I anbefalingspanelet, utvid Hvorfor er dette viktig?, og se gjennom migrasjonsveiledningen.

7. Gå gjennom de kvalifiserte agentene. Bruk foreslått migrasjonsrekkefølge og migrasjonsnotater for å velge en innledende pilot eller neste migrasjonsbatch. Tabellen gir også informasjon som miljø, miljøtype, eier, nylig aktivitet og autentiseringsmetode.

8. Velg avkrysningsboksen ved siden av hver agent du vil migrere. Du kan velge én agent eller flere kvalifiserte agenter.

   Migrer-knappen blir tilgjengelig, og handlingslinjen viser antall valgte agenter.

   

9. Velg Migrer, gjennomgå bekreftelsen, og bekreft migreringen.

10. Gå gjennom kolonnene Handling, Handlingstilstand og Handlingsdato for hver valgt agent. For å gjennomgå handlinger på tvers av anbefalinger, velg fanen Handlingshistorikk .

Gjenta disse trinnene for hver planlagt batch kun etter at forrige batch har bestått valideringen.

Valider migrerte agenter

Før du migrerer en ny batch, koordiner med agentskaperne og bekreft at hver migrerte agent:

• Svarer riktig i alle kanaler hvor det publiseres.
• Kjører sine handlinger, koblinger, flyter og integrasjoner med suksess.
• Autentiseres som forventet, inkludert tilpasset autentisering.
• Fungerer som forventet med gjeldende agenttilgangspolicyer og betingelser for betinget tilgang.

Gå gjennom innloggingsloggene for de migrerte agentene i Microsoft Entra administrasjonssenter. Bekreft vellykket autentisering og undersøk feil eller uventede resultater av betinget tilgang.

Hvis en agent ikke består valideringen, stopp batch-rullingen og tilbakestill agenten før du fortsetter.

Valgfritt: API-operasjoner for migrering av agent-ID-er

Hvis du foretrekker å bygge din egen automatisering, kan du kalle Power Platform API-endepunkter for å migrere eller tilbakestille (tilbakerulle) agenter. Begge operasjonene er HTTP POST-forespørsler autorisert med en bærertoken for Power Platform-tjenesten.

Finn ut mer i:

• Power Platform API og SDK-er: Fra UX-først til API-først (blogg) (Power Platform-utviklerblogg)
• Oversikt over programmerbarhet og utvidbarhet (Power Platform-dokumentasjon)
• Kom i gang med Power Platform API (Power Platform-dokumentasjon)
• Copilot Studio operasjons-API-referansedokumentasjon

Få en OAuth2-bærertoken for Power Platform API-et

Alle operasjonene som er listet her krever en OAuth2-bærertoken for https://api.powerplatform.com. Inkluder dette tokenet i forespørselen din under en Authorization overskrift. Tokenet må komme fra Microsoft Entra ID OAuth2 og være knyttet til en brukerkonto som har en av administratorrollene som er oppført i forutsetningene.

For eksempel, bruk Az PowerShell-modulen for å hente tokenet og lagre det slik $token det brukes i API-forespørsler:

$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 å sende en POST-forespørsel til migreringsendepunktet med agentens detaljer:

• Endepunkt: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Autentisering: Inkluder en gyldig OAuth-bærertoken for Power Platform API i Authorization headeren. Power Platform API krever en bærertoken fra Microsoft Entra ID.
• Kropp: Ikke påkrevd
• Formål: Migrere en agent fra app-registrerings-ID til Entra Agent ID
• Svar: Returnerer et AgentIdentityMigrationResult JSON-objekt med en status verdi for agentens ID-migrering:
  • Migrated
  • AlreadyMigrated

For eksempel får følgende skript et autorisasjonstoken, og kaller deretter migrasjonsendepunktet for en spesifikk agent (<BotId>) i et spesifikt miljø (<EnvironmentId>) med den autorisasjonen:

$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 migrasjon:

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

Tilbakestill eller rull agentens identitet tilbake til app-registrerings-ID

For å reversere en agent, send en POST-forespørsel til reverseringsendepunktet med agentens detaljer:

• Endepunkt: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Autentisering: Inkluder en gyldig OAuth-bærertoken for Power Platform API i Authorization headeren. Power Platform API krever en bærertoken fra Microsoft Entra ID.
• Kropp: Ikke påkrevd
• Formål: Rulle tilbake (tilbakestille) en agents ID fra en Entra ID til en app-registrerings-ID
• Svar: Returnerer et AgentIdentityRollbackResult JSON-objekt med en terminalstatusverdi for agentens ID-migrering:
  • NotMigrated
  • RolledBack

For eksempel får følgende skript et token, og kaller deretter revert-endepunktet for en spesifikk agent (<BotId>) i et spesifikt miljø (<EnvironmentId>) med den autorisasjonen:

$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 tilbakerulling:

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

Feilsøking

Tabellen nedenfor viser vanlige problemer og hvordan man løser dem:

Relatert innhold

• Eksempelspørringer for Power Platform-inventar
• Copilot Studio-agentoversikt