Siirrä Copilot Studion agentit Microsoft Entra -agenttitunnus:hen

Tässä artikkelissa kuvataan, miten olemassa olevat Copilot Studio -agentit voidaan valinnaisesti siirtää vanhasta sovelluksen rekisteröintiidentiteetistä Microsoft Entra -agenttitunnus:hen ennen automaattista siirtoa.

Käytä Power Platformin hallintokeskuksen suositusta tunnistaaksesi kelpoiset agentit, suunnittele siirtoerät ja siirrä yksi tai useampi agentti. Tämä neuvonantajapohjainen kokemus on suositeltu manuaalinen siirtomenetelmä. Voit myös käyttää Power Platform API:n päätelaitteita luodaksesi oman migraatioprosessisi.

Kun siirrät agentin Microsoft Entra -agenttitunnus:hen, saat:

• Ensiluokkainen agentti-identiteetti, jota ylläpitäjät voivat tarkastella ja hallita Microsoft Entra:ssa.
• Ehdollinen pääsy ja muut pääsykäytännöt, jotka on suunniteltu agenttisille työkuormille ja rajataan agenteille sen sijaan, että ne perittäisiin sovellusten rekisteröinneistä.
• Yhtenäinen identiteettimalli palveluiden välillä, jotka työskentelevät agenttesi kanssa.

Lue lisää Copilot Studio:n agenttihenkilöllisyydestä ja todennuksesta.

Tietoa agentin identiteetin migraatiosta

Migraatio muuntaa agentin olemassa olevan sovellusrekisteröinti-identiteetin paikoilleen. Agentti säilyttää sovelluksen (asiakas) ID:n, joten alavirran konfiguraatiot, jotka käyttävät tätä ID:tä, kuten kanavarekisteröinnit ja liittimet, ratkeavat edelleen samaan tunnisteeseen. Agentti saa myös Microsoft Entra -agenttitunnus:n, jota ylläpitäjät voivat hallita.

Migraatio on hallittu, vapaaehtoinen operaatio. Voit toimia seuraavasti:

• Siirrä yksi agentti.
• Valitse useita agentteja ja siirrä ne erässä.
• Siirrä lisää erät omaan aikatauluusi.
• Palauta agentti legacy-identiteettiinsä, jos se ei läpäise validointia.

Edellytykset

• Sinun tulee olla Power Platform -ylläpitäjä, Dynamics 365 -ylläpitäjä tai globaali ylläpitäjä.
• Power Platform -inventaario täytyy olla käytössä vuokralaisellesi, jotta neuvonantaja voi tunnistaa kelvolliset välittäjät.
• Sovita validointiikkuna niiden tekijöiden kanssa, jotka omistavat agentit, jotka aiot siirtää.

Suunnittele migraatioerät

Agenttien identiteettien siirtäminen vaikuttaa aktiivisiin agentteihin ja voi häiritä tunnistautumista, liittimiä ja integraatioita, jos siirtoa ei suunnitella huolellisesti. Käytä seuraavaa vaiheittaista lähestymistapaa:

1. Aloita pilotilla: Valitse pieni joukko ei-kriittisiä agentteja, jotka edustavat kanavia, todennusmuotoja, liittimiä, virtoja ja integraatioita, jotka sinun täytyy validoida.
2. Tee yhteistyötä valmistajien kanssa: Ilmoita asianomaisille valmistajille ja sovi validointiikkunasta. Valmistajien tulisi olla käytettävissä testaamassa agenttejaan, kun migraatioerä on valmis.
3. Siirry asteittain: Siirrä agentteja yksittäin tai pienissä erissä. Älä siirrä koko aluetta kerralla.
4. Vahvista alusta päähän: Varmista, että jokainen siirretty agentti toimii sen konfiguroitujen kanavien, toimintojen, liittimien, todennuskulujen ja integraatioiden välillä.
5. Seuraa ja laajenna: Tarkista Microsoft Entra:n kirjautumislokit, mukaan lukien ehdollisen pääsyn tulokset, ennen kuin siirrät isomman erän.

Siirtäkää agentteja Power Platformin hallintokeskuksessa

Käytä Power Platformin hallintokeskuksen neuvonantajasuositusta arvioidaksesi kelpoisia agentteja ja siirtääksesi yhden tai useamman agentin.

1. Kirjaudu Power Platform -hallintakeskukseen.

2. Vasemmasta navigointipaneelista valitse Toiminnot.

3. Toiminnot-kohdasta valitse Suositukset.

4. Valitse Suositukset-välilehdeltä Aktiivinen.

5. Etsi ja valitse Migrate Copilot Studio -agentit Microsoft Entra -agenttitunnus:hen parantaaksesi agentin hallintaa.

   

6. Suosituspaneelissa laajenna Miksi tämä on tärkeää? ja tutustu migraatio-ohjeisiin.

7. Tarkista kelvolliset agentit. Käytä Ehdotettua migraatiojärjestystä ja Migraatiomuistiinpanoja valitaksesi alkuperäisen pilotin tai seuraavan siirtymäerän. Taulukko sisältää myös tietoja, kuten ympäristön, ympäristötyypin, omistajan, viimeisimmän toiminnan ja todennusmenetelmän.

8. Valitse valintaruutu jokaisen agentin vierestä, jonka haluat siirtää. Voit valita yhden välittäjän tai useamman kelvollisen edustajan.

   Migrate-painike tulee saataville ja toimintopalkki näyttää valittujen agenttien määrän.

   

9. Valitse Migrate, tarkista vahvistus ja vahvista siirto.

10. Tarkista kunkin valitun agentin Toiminto-, Toiminto-tila- ja Toimintapäivä-sarakkeet . Tarkastellaksesi toimintoja suositusten välillä, valitse Toimintohistoria-välilehti .

Toista nämä vaiheet jokaiselle suunnitellulle erälle vasta edellisen erän validoinnin jälkeen.

Validoi siirretyt agentit

Ennen kuin siirrät uuden erän, tee yhteistyötä agenttien tekijöiden kanssa ja varmista, että jokainen siirretty agentti:

• Vastaa oikein jokaisessa kanavassa, jossa se julkaistaan.
• Se suorittaa sen toiminnot, liittimet, virrat ja integraatiot onnistuneesti.
• Vahvistaa odotetusti, mukaan lukien räätälöity tunnistautuminen.
• Toimii odotetusti sovellettavien agenttien käyttöoikeuksien ja ehdollisen pääsyn politiikkojen kanssa.

Tarkista siirrettyjen agenttien kirjautumislokit Microsoft Entra -hallintakeskus -sivustolla. Varmista onnistunut todennus ja tutki epäonnistumisia tai odottamattomia ehdollisen pääsyn tuloksia.

Jos agentti ei läpäise validointia, pysäytä eräjulkaisu ja palauta kyseinen agentti ennen kuin jatkat.

Valinnainen: API-toiminnot agenttitunnuksen migraatiossa

Jos haluat rakentaa oman automaation, voit kutsua Power Platform API:n päätepisteitä agenttien siirtämiseen tai palauttamiseen (rollback). Molemmat toiminnot ovat HTTP POST -pyyntöjä, jotka on valtuutettu kantajatunnisteella Power Platform -palvelulle.

Lisätietoja:

• Power Platform -ohjelmointirajapinta ja SDK:t: UX-firstistä API-firstiin (blogi) (Power Platform Developer Blog)
• Ohjelmoitavuuden ja laajennettavuuden yleiskatsaus (Power Platform -dokumentaatio)
• Aloita Power Platform API :n (Power Platform -dokumentaatio) kanssa
• Copilot Studio Operations API -viitedokumentaatio

Hanki OAuth2-kantajatoken Power Platform API:lle

Kaikki tässä luetellut operaatiot vaativat OAuth2-kantajatokenin .https://api.powerplatform.com Sisällytä tämä token pyyntöösi otsikon alle Authorization . Tokenin on saatava Microsoft Entra ID OAuth2:sta ja sen on oltava yhteydessä käyttäjätiliin, jolla on yksi edellytyksissä mainituista ylläpitäjärooleista.

Esimerkiksi käytä Az PowerShell -moduulia saadaksesi tokenin ja tallentaaksesi sen $token API-pyyntöjä varten:

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

Siirrä agentin tunnistetiedot Microsoft Entra -agenttitunnus:hen

Siirrä agentti sovellusrekisteröintitunnuksesta Entra-agenttitunnus:hen lähettämällä POST-pyyntö siirtopäätepisteelle agentin tiedoilla:

• Päätepiste: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Tunnistautuminen: Sisällytä pätevä OAuth-kantajatoken Power Platform API:lle otsikkoon Authorization . Power Platform API vaatii kantajatokenin Microsoft Entra ID:ltä.
• Runko: Ei vaadittu
• Tarkoitus: Agentin siirtäminen sovellusrekisteröinti-ID:stä Entra-agenttitunnus:hen
• Vastaus: Palauttaa AgentIdentityMigrationResult JSON-objektin, jolla on status arvo agentin ID-migraatiolle:
  • Migrated
  • AlreadyMigrated

Esimerkiksi seuraava skripti saa valtuutustunnuksen ja kutsuu sitten siirto-päätepisteen tietylle agentille (<BotId>) tietyssä ympäristössä (<EnvironmentId>) kyseisellä valtuutuksella:

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

Seuraava esimerkkivastaus osoittaa onnistuneen siirtymän:

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

Palauta tai peruuta agentin identiteetti sovellusrekisteröinnin tunnukseksi

Agentin palauttamiseksi lähetä POST-pyyntö palautuspisteelle agentin tiedoilla:

• Päätepiste: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Tunnistautuminen: Sisällytä pätevä OAuth-kantajatoken Power Platform API:lle otsikkoon Authorization . Power Platform API vaatii kantajatokenin Microsoft Entra ID:ltä.
• Runko: Ei vaadittu
• Tarkoitus: Palauta (palauttaa) agentin ID Entra ID -tunnus:stä sovellusrekisteröintitunnukseen
• Vastaus: Palauttaa AgentIdentityRollbackResult JSON-objektin, jossa on terminaalitilaarvo agentin ID-migraatiolle:
  • NotMigrated
  • RolledBack

Esimerkiksi seuraava skripti saa tokenin ja kutsuu sitten palautuspäätepisteen tietylle agentille (<BotId>) tietyssä ympäristössä (<EnvironmentId>) kyseisellä valtuutuksella:

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

Seuraava esimerkkivastaus osoittaa onnistuneen palautuksen:

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

Vianmääritys

Seuraava taulukko listaa yleisiä ongelmia ja miten ne voidaan ratkaista:

Liittyvä sisältö

• Power Platform -varastomallikyselyt
• Copilot Studio -agenttiluettelo