Migra gli agenti di Copilot Studio su Microsoft Entra Agent ID

Questo articolo descrive come migrare opzionalmente gli agenti Copilot Studio esistenti dall'identità di registrazione legacy dell'app a un Microsoft Entra Agent ID prima della migrazione automatica.

Usa la raccomandazione nel centro amministrazione Power Platform per identificare gli agenti idonei, pianificare i lotti di migrazione e migrare uno o più agenti. Questa esperienza basata su Advisor è il metodo di migrazione manuale raccomandato. Puoi anche utilizzare gli endpoint API di Power Platform per creare il tuo processo di migrazione.

Quando migri un agente a Microsoft Entra Agent ID, ottieni :

• Un'identità di agente di prima classe che gli amministratori possono visualizzare e gestire in Microsoft Entra.
• Accesso condizionato e altre politiche di accesso progettate per carichi di lavoro agentici e applicate agli agenti invece che ereditate dalle registrazioni delle app.
• Un modello di identità coerente tra i servizi che lavorano con i tuoi agenti.

Scopri di più su Identità degli agenti e autenticazione per Copilot Studio.

Informazioni sulla migrazione dell'identità dell'agente

La migrazione converte direttamente l'identità esistente di registrazione dell'applicazione di un agente. L'agente mantiene il suo ID applicativo (client), quindi le configurazioni a valle che utilizzano quell'ID, come le registrazioni dei canali e i connettori, continuano a risolversi con lo stesso identificatore. L'agente ottiene anche un Microsoft Entra Agent ID che gli amministratori possono gestire.

La migrazione è un'operazione controllata e a opt-in. È possibile:

• Migra un agente.
• Seleziona più agenti e migrali in blocco.
• Esegui la migrazione di altri lotti quando preferisci.
• Ripristina un agente alla sua identità precedente se non supera la convalida.

Prerequisiti

• Devi essere un Power Platform Administrator, Dynamics 365 Administrator o Global Administrator.
• L'inventario di Power Platform deve essere abilitato per il tuo tenant affinché Advisor possa identificare gli agenti idonei.
• Coordina una finestra di validazione con i produttori che possiedono gli agenti che intendi migrare.

Pianifica i tuoi lotti di migrazione

La migrazione delle identità degli agenti influisce sugli agenti attivi e può compromettere l'autenticazione, i connettori e le integrazioni se non si pianifica attentamente la migrazione. Usa il seguente approccio a tappe:

1. Inizia con un pilota: seleziona un piccolo insieme di agenti non critici che rappresenti i canali, le modalità di autenticazione, i connettori, i flussi e le integrazioni che devi validare.
2. Coordinarsi con i creatori: Notificare i produttori interessati e concordare una finestra di validazione. I produttori dovrebbero essere disponibili per testare i loro agenti quando un lotto di migrazione si completa.
3. Migra in modo incrementale: migra gli agenti individualmente o in piccoli lotti. Non migrare l'intero patrimonio in una volta.
4. Convalida end-to-end: Conferma che ogni agente migrato funzioni correttamente su tutti i canali, le azioni, i connettori, i flussi di autenticazione e le integrazioni configurati.
5. Monitora ed espandi: Rivedi i log di accesso Microsoft Entra, inclusi i risultati di Accesso Condizionale, prima di migrare un lotto più grande.

Migrare gli agenti nel centro di amministrazione di Power Platform

Usa la raccomandazione del Advisor nel centro amministrazione Power Platform per esaminare gli agenti idonei e migrare uno o più agenti.

1. Accedi all'interfaccia di amministrazione di Power Platform.

2. Nel pannello di navigazione a sinistra, seleziona Azioni.

3. Sotto Azioni, seleziona Raccomandazioni.

4. Nella scheda Raccomandazioni , seleziona Attivo.

5. Cerca e seleziona Migrare gli agenti di Copilot Studio a Microsoft Entra Agent ID per una governance degli agenti migliorata.

   

6. Nel pannello delle raccomandazioni, espandi Perché è importante? e consulta le linee guida sulla migrazione.

7. Esamina gli agenti idonei. Usa l'ordine di migrazione suggerito e le note di migrazione per scegliere un pilota iniziale o il prossimo lotto di migrazione. La tabella fornisce anche informazioni come ambiente, tipo di ambiente, proprietario, attività recente e metodo di autenticazione.

8. Seleziona la casella accanto a ogni agente che vuoi migrare. Puoi selezionare un agente o più agenti idonei.

   Il pulsante Migrate diventa disponibile e la barra delle azioni mostra il numero di agenti selezionati.

   

9. Seleziona Migra, rivedi la conferma e conferma la migrazione.

10. Rivedere le colonne Azione, Stato dell'Azione e Data dell'Azione per ogni agente selezionato. Per esaminare le azioni tra le raccomandazioni, seleziona la scheda Cronologia Azioni .

Ripeti questi passaggi per ogni lotto pianificato solo dopo che il lotto precedente è stato validato.

Valida gli agenti migrati

Prima di migrare un altro lotto, coordinati con gli sviluppatori degli agenti e conferma che ogni agente migrato:

• Risponde correttamente in ogni canale in cui è pubblicato.
• Esegue con successo le sue azioni, connettori, flussi e integrazioni.
• Autentica come previsto, inclusa l'autenticazione personalizzata.
• Funziona come previsto con le politiche di accesso agli agenti e le politiche di accesso condizionato applicabili.

Rivedi i log di accesso degli agenti migrati nel Interfaccia di amministrazione di Microsoft Entra. Conferma l'autenticazione riuscita e indaga su fallimenti o risultati di Accesso Condizionato inattesti.

Se un agente non supera la convalida, interrompi la distribuzione in batch e ripristina quell'agente prima di continuare.

Opzionale: operazioni API per la migrazione degli ID agenti

Se preferisci creare la tua automazione, puoi richiamare gli endpoint API di Power Platform per migrare o ripristinare (rollback) gli agenti. Entrambe le operazioni sono richieste HTTP POST autorizzate con un token portatore per il servizio Power Platform.

Ulteriori informazioni in:

• Power Platform API and SDKs: From UX-first to API-first (Blog) (blog per sviluppatori di Power Platform)
• Panoramica della programmabilità e dell'estendibilità (documentazione di Power Platform)
• Inizia a usare l'API Power Platform (documentazione di Power Platform)
• Documentazione di riferimento API delle operazioni di Copilot Studio

Ottieni un token portatore OAuth2 per l'API Power Platform

Tutte le operazioni elencate qui richiedono un token portatore OAuth2 per https://api.powerplatform.com. Includi questo token nella tua richiesta sotto un'intestazione Authorization (header). Il token deve provenire da Microsoft Entra ID OAuth2 ed essere associato a un account utente che abbia uno dei ruoli amministratori elencati nei prerequisiti.

Ad esempio, usa il modulo Az PowerShell per ottenere il token e memorizzarlo come $token per l'uso nelle richieste API:

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

Migra l'identità dell'agente a Microsoft Entra Agent ID

Migra un agente dall'ID di registrazione dell'app all'Entra Agent ID inviando una richiesta POST all'endpoint di migrazione con i dettagli dell'agente:

• Endpoint:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Autenticazione: Includere un token portatore OAuth valido per l'API Power Platform nell'intestazione Authorization . L'API Power Platform richiede un token portatore da Microsoft Entra ID.
• Corpo: Non necessario
• Scopo: Migrare un agente dall'ID di registrazione dell'app all'Entra Agent ID
• Risposta: restituisce un AgentIdentityMigrationResult oggetto JSON con un status valore per la migrazione dell'ID dell'agente:
  • Migrated
  • AlreadyMigrated

Ad esempio, il seguente script riceve un token di autorizzazione e poi chiama l'endpoint di migrazione per un agente specifico (<BotId>) in un ambiente specifico (<EnvironmentId>) con quell'autorizzazione:

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

Il seguente esempio di risposta mostra una migrazione di successo:

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

Ripristinare o riportare l'identità agente all'ID di registrazione dell'applicazione

Per ripristinare un agente, invia una richiesta POST all'endpoint di ripristino con i dettagli dell'agente:

• Endpoint:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Autenticazione: Includere un token portatore OAuth valido per l'API Power Platform nell'intestazione Authorization . L'API Power Platform richiede un token portatore da Microsoft Entra ID.
• Corpo: Non necessario
• Scopo: Annullare (rivertire) l'ID di un agente da un Entra ID a un ID di registrazione dell'app
• Risposta: Restituisce un AgentIdentityRollbackResult oggetto JSON con un valore di stato terminale per la migrazione dell'ID dell'agente:
  • NotMigrated
  • RolledBack

Ad esempio, il seguente script riceve un token e poi chiama l'endpoint di revert per un agente specifico (<BotId>) in un ambiente specifico (<EnvironmentId>) con quell'autorizzazione:

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

L'esempio di risposta seguente mostra un rollback riuscito:

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

Risoluzione dei problemi

La tabella seguente elenca i problemi comuni e come risolverli:

Contenuti correlati

• Query di esempio per l'inventario di Power Platform
• Inventario degli agenti di Copilot Studio