Migre agentes do Copilot Studio para o ID do agente Microsoft Entra

Este artigo descreve como migrar opcionalmente agentes existentes do Copilot Studio da identidade legada de registro do aplicativo 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, planejar lotes de migração e migrar um ou mais agentes. Essa experiência baseada no Advisor é o método recomendado de migração manual. Você também pode usar endpoints da API do Power Platform para criar seu próprio processo de migração.

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

• Uma identidade de agente de primeira classe que os administradores podem visualizar e governar no Microsoft Entra.
• Acesso condicional e outras políticas de acesso projetadas para cargas de trabalho agênticas e aplicadas a agentes, em vez de herdadas de registros de aplicativo.
• Um modelo de identidade consistente em todos os serviços que trabalham com seus agentes.

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

Sobre a migração de identidade do agente

A migração converte, no local, a identidade existente de registro de aplicativo do agente. O agente mantém seu ID do aplicativo (cliente), portanto as configurações subsequentes que usam esse ID, como registros de canais e conectores, continuam apontando para o mesmo identificador. O agente também ganha um ID do agente Microsoft Entra que os administradores podem gerenciar.

A migração é uma operação controlada e com participação voluntária. É possível:

• Migre um agente.
• Selecione vários agentes e migre em lote.
• Migre lotes adicionais no seu próprio cronograma.
• Reverta um agente para sua identidade antiga se ele não passar pela validação.

Pré-requisitos

• Você deve ser um Administrador Power Platform, Administrador do Dynamics 365 ou Administrador Global.
• O inventário da Power Platform deve estar habilitado para seu locatário para que o Advisor possa identificar os agentes elegíveis.
• Coordene uma janela de validação com os criadores que possuem os agentes que você pretende migrar.

Planeje seus lotes de migração

Migrar identidades de agentes afeta agentes ativos e pode atrapalhar autenticação, conectores e integrações se você não planejar a migração com cuidado. Use a seguinte abordagem em etapas:

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 você precisa validar.
2. Coordenar com os fabricantes: Notifique os fabricantes afetados e concorde com uma janela de validação. Os fabricantes devem estar disponíveis para testar seus agentes quando um lote de migração for concluído.
3. Migre incrementalmente: migre agentes individualmente ou em pequenos lotes. Não migre todo o patrimônio de uma vez.
4. Valide de ponta a ponta: Confirme que cada agente migrado funciona em seus canais configurados, ações, conectores, fluxos de autenticação e integrações.
5. Monitore e amplie: Analise os logs de login 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 do Power Platform para revisar agentes elegíveis e migrar um ou mais agentes.

1. Entre no centro de administração do Power Platform.

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

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

4. Na aba Recomendações , selecione Ativo.

5. Pesquise e selecione Migrar agentes do Copilot Studio para o ID do agente Microsoft Entra para aprimorar a governança dos agentes.

   

6. No painel de recomendações, expanda Por que isso é importante? e revise as orientações de migração.

7. Revise 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. Selecione a caixa ao lado de cada agente que você deseja migrar. Você 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, revise a confirmação e confirme a migração.

10. Revise as colunas de Ação, estado da Ação e data de ação para cada agente selecionado. Para revisar as ações em todas as recomendações, selecione a aba Histórico de ações.

Repita essas etapas para cada lote planejado somente após o lote anterior passar na validação.

Validar agentes migrados

Antes de migrar outro lote, coordene com os criadores dos agentes e confirme que cada agente migrado:

• Responde corretamente em todos os canais onde é publicado.
• Executa 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.

Revise os logs de login dos agentes migrados no centro de administração do 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 o lançamento em lote e reverta esse agente antes de continuar.

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

Se preferir criar sua própria automação, você pode chamar os endpoints da API do Power Platform para migrar ou reverter (fazer rollback de) agentes. Ambas as operações são requisições HTTP POST autorizadas com um token portador para o serviço Power Platform.

Saiba mais em:

• API e SDKs do Power Platform: Do UX-first para o API-first (Blog) (Blog de desenvolvedor do Power Platform)
• Visão geral de 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 listadas aqui requerem um token portador OAuth2 para https://api.powerplatform.com. Inclua este token na sua requisição no cabeçalho Authorization. O token deve vir do Microsoft Entra ID OAuth2 e estar associado a uma conta de usuário que tenha um dos papéis de administrador listados nos pré-requisitos.

Por exemplo, use o módulo Az PowerShell para obter o token e armazená-lo como $token para uso em requisições 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 registro do aplicativo para o ID do agente Entra enviando uma solicitação POST para o endpoint de migração com os dados do agente:

• Ponto de extremidade: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 do Power Platform no Authorization cabeçalho. A API do Power Platform requer um token portador do Microsoft Entra ID.
• Corpo: Não é obrigatório
• Propósito: Migrar um agente do ID de registro do aplicativo 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 a seguir recebe um token de autorização e então chama o endpoint de migração para um agente específico (<BotId>) em um 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"
    }

A seguinte resposta de exemplo 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 a identidade do agente para o ID do registro do aplicativo

Para reverter um agente, envie uma solicitação POST para o endpoint de reverter com os dados do agente:

• Ponto de extremidade: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 do Power Platform no Authorization cabeçalho. A API do Power Platform requer um token portador do Microsoft Entra ID.
• Corpo: Não é obrigatório
• Propósito: Reverter (reverter) o ID de um agente de um Entra ID para um ID de registro de aplicativo
• Resposta: Retorna um AgentIdentityRollbackResult objeto JSON com um valor de status terminal para a migração do ID do agente:
  • NotMigrated
  • RolledBack

Por exemplo, o script a seguir recebe um token e então chama o endpoint de revert para um agente específico (<BotId>) em um 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 exemplo de resposta a seguir mostra um rollback bem-sucedido:

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

Solução de problemas

A tabela a seguir lista questões comuns e como resolvê-las:

Conteúdo relacionado

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