Migrar agentes do Copilot Studio para o ID do Agente Microsoft Entra

Este artigo descreve como migrar opcionalmente os agentes existentes do Copilot Studio da identidade de registo da aplicação legada para um ID do Agente Microsoft Entra antes da migração automática.

Use a recomendação no centro de administração do Power Platform para identificar agentes elegíveis, planear lotes de migração e migrar um ou mais agentes. Esta experiência baseada no Advisor é o método de migração manual recomendado. Também pode usar os endpoints da API do Power Platform para criar o seu próprio processo de migração.

Quando migra um agente para o ID do Agente Microsoft Entra, obtém:

• Uma identidade de agente de primeira classe que os administradores podem ver e gerir no Microsoft Entra.
• Acesso condicional e outras políticas de acesso concebidas para cargas de trabalho agênticas e aplicadas aos agentes, em vez de serem herdadas dos registos de aplicações.
• Um modelo de identidade consistente em todos os serviços que trabalham com os seus agentes.

Saiba mais sobre Identidades de Agentes e autenticação para o Copilot Studio.

Sobre a migração da identidade do agente

A migração converte, no próprio local, a identidade de registo de aplicação existente de um agente. O agente mantém o seu ID da aplicação (cliente), pelo que as configurações subsequentes que utilizam esse ID, como registos de canais e conectores, continuam a apontar para o mesmo identificador. O agente também ganha um ID do Agente Microsoft Entra que os administradores podem gerir.

A migração é uma operação controlada e opt-in. É possível:

• Migra um agente.
• Selecione vários agentes e migre-os em lote.
• Migre lotes adicionais ao seu próprio ritmo.
• Reverter um agente para a sua identidade legada se este não passar a validação.

Pré-requisitos

• Deve ser Administrador Power Platform, Administrador Dynamics 365 ou Administrador Global.
• O inventário da Power Platform deve estar ativado para o seu inquilino para que o Advisor possa identificar os agentes elegíveis.
• Coordena uma janela de validação com os criadores que possuem os agentes que planeias migrar.

Planeie os seus lotes de migração

Migrar as identidades dos agentes afeta agentes ativos e pode perturbar a autenticação, conectores e integrações se não planeares bem a migração. Use a seguinte abordagem faseada:

1. Comece com um piloto: Selecione um pequeno conjunto de agentes não críticos que represente os canais, modos de autenticação, conectores, fluxos e integrações que precisa de validar.
2. Coordenar com os criadores: Notificar os produtores afetados e acordar uma janela de validação. Os fabricantes devem estar disponíveis para testar os seus agentes quando um lote de migração terminar.
3. Migrar incrementalmente: Migrar agentes individualmente ou em pequenos lotes. Não migre todo o património de uma só vez.
4. Validar de ponta a ponta: Confirme que cada agente migrado funciona através dos seus canais configurados, ações, conectores, fluxos de autenticação e integrações.
5. Monitorize e expanda: Revise os registos de início de sessão do Microsoft Entra, incluindo os resultados do Acesso Condicional, antes de migrar um lote maior.

Migrar agentes no centro de administração do Power Platform

Use a recomendação do Advisor no centro de administração da Power Platform para rever agentes elegíveis e migrar um ou mais agentes.

1. Inicie sessão no Centro de administração do Power Platform.

2. No painel de navegação esquerdo, selecione Ações.

3. Em Ações, selecione Recomendações.

4. No separador Recomendações , selecione Ativo.

5. Pesquise e selecione Migrar agentes do Copilot Studio para o ID do Agente Microsoft Entra para uma melhor gestão dos agentes.

   

6. No painel de recomendações, expanda Porque é isto importante? e reveja as orientações de migração.

7. Analise os agentes elegíveis. Use a ordem de migração sugerida e as notas de migração para escolher um piloto inicial ou o próximo lote de migração. A tabela também fornece informações como ambiente, tipo de ambiente, proprietário, atividade recente e método de autenticação.

8. Seleciona a caixa de seleção ao lado de cada agente que queres migrar. Pode escolher um agente ou vários agentes elegíveis.

   O botão Migrar fica disponível e a barra de ações mostra o número de agentes selecionados.

   

9. Selecione Migrar, rever a confirmação e confirmar a migração.

10. Revise as colunas de Ação, Estado da Ação e Data da Ação de cada agente selecionado. Para rever as ações em todas as recomendações, selecione o separador Histórico de ações.

Repita estes passos para cada lote planeado apenas depois de o lote anterior passar a validação.

Validar agentes migrados

Antes de migrar outro lote, articule-se com os desenvolvedores dos agentes e confirme que cada agente migrado:

• Responde corretamente em todos os canais em que é publicado.
• Executa as suas ações, conectores, fluxos e integrações com sucesso.
• Autentica como esperado, incluindo autenticação personalizada.
• Funciona como esperado com as políticas de acesso a agentes aplicáveis e políticas de Acesso Condicional.

Consulte os registos de início de sessão dos agentes migrados no centro de administração Microsoft Entra. Confirme a autenticação bem-sucedida e investigue falhas ou resultados inesperados de Acesso Condicional.

Se um agente não passar na validação, pare a implementação em lote e reverta esse agente antes de continuar.

Opcional: Operações de API para migração de ID de agente

Se preferir criar a sua própria automatização, pode invocar os pontos finais da API do Power Platform para migrar ou reverter agentes. Ambas as operações são pedidos HTTP POST autorizados com um token portador para o serviço Power Platform.

Saiba mais em:

• API e SDKs do Power Platform: de UX primeiro para API primeiro (Blogue) (Blogue para Programadores do Power Platform)
• Descrição geral da programabilidade e extensibilidade (documentação do Power Platform)
• Comece a usar a API do Power Platform (documentação do Power Platform)
• Documentação de referência da API de operações do Copilot Studio

Obtenha um token portador OAuth2 para a API do Power Platform

Todas as operações aqui listadas requerem um token portador OAuth2 para https://api.powerplatform.com. Inclua este token no seu pedido, num cabeçalho Authorization. O token deve vir do Microsoft Entra ID OAuth2 e estar associado a uma conta de utilizador que tenha um dos papéis de administrador listados nos pré-requisitos.

Por exemplo, use o módulo PowerShell do Az para obter o token e armazene-o como $token para uso em pedidos de API:

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

Migrar a identidade do agente para o ID do Agente Microsoft Entra

Migre um agente do ID de registo da aplicação para o ID do Agente Entra enviando um pedido POST para o endpoint de migração com os dados do agente:

• Ponto final:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/migrate?api-version=2024-10-01
• Autenticação: Inclua um token portador OAuth válido para a API Power Platform no Authorization cabeçalho. A API do Power Platform requer um token de portador do Microsoft Entra ID.
• Corpo: Não é obrigatório
• Propósito: Migrar um agente do ID de registo da aplicação para o ID do Agente Entra
• Resposta: Retorna um AgentIdentityMigrationResult objeto JSON com um status valor para a migração do ID do agente:
  • Migrated
  • AlreadyMigrated

Por exemplo, o script seguinte recebe um token de autorização e depois chama o endpoint de migração para um agente específico (<BotId>) num ambiente específico (<EnvironmentId>) com essa autorização:

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

O seguinte exemplo de resposta mostra uma migração bem-sucedida:

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

Reverter ou repor a identidade do agente para o ID do registo da aplicação

Para reverter um agente, envie um pedido POST ao endpoint de reverter com os dados do agente:

• Ponto final:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/agentidentitymigration/rollback?api-version=2024-10-01
• Autenticação: Inclua um token portador OAuth válido para a API Power Platform no Authorization cabeçalho. A API do Power Platform requer um bearer token do Microsoft Entra ID.
• Corpo: Não é obrigatório
• Objetivo: Reverter o ID de um agente de Entra ID para ID de registo da aplicação
• Resposta: Retorna um AgentIdentityRollbackResult objeto JSON com um valor de estado terminal para a migração do ID do agente:
  • NotMigrated
  • RolledBack

Por exemplo, o script seguinte recebe um token e depois chama o endpoint de revert para um agente específico (<BotId>) num ambiente específico (<EnvironmentId>) com essa autorização:

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

O seguinte exemplo de resposta mostra uma reversão bem-sucedida:

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

Solução de problemas

A tabela seguinte lista os problemas comuns e como os resolver:

Conteúdo relacionado

• Consultas de exemplo do inventário do Power Platform
• Inventário de agentes do Copilot Studio