Compartilhar via

Configurar a autenticação da Microsoft para testes do Copilot Studio Kit

Este artigo fornece uma visão geral da estrutura de teste do agente e instruções passo a passo para configurar a autenticação da Microsoft para testar agentes do Copilot Studio usando o PCF (Agent Test Runner Power Apps Component Framework).

Architecture

A autenticação da Microsoft fornece uma arquitetura simplificada do SDK de navegador para agente otimizada para cenários de teste. Essa abordagem permite a comunicação segura entre seu ambiente de teste e agentes do Copilot Studio sem a necessidade de infraestrutura de autenticação adicional.

Arquitetura de fluxo

O diagrama de sequência a seguir ilustra o fluxo de autenticação e execução de teste.

Diagrama ilustrando a arquitetura do SDK de navegador para agente para autenticação e teste.

Arquitetura de componentes

O diagrama a seguir ilustra os principais componentes envolvidos no fluxo de autenticação da Microsoft para o Executador de Testes do Agente.

Diagrama ilustrando os principais componentes envolvidos no fluxo de teste, incluindo o ambiente do navegador, os serviços do Power Platform e os serviços de autenticação.

Configurar a autenticação da Microsoft

O processo de instalação envolve a configuração do registro de aplicativo do Azure Active Directory, a obtenção de identificadores de agente do Copilot Studio e a criação de um registro de configuração no Dataverse.

portal do Azure

No portal do Azure, crie um registro de aplicativo, adicione a URL de redirecionamento e configure permissões de API.

Observação

Se você tiver direitos de administração de locatário, poderá configurar permissões de API. Caso contrário, você precisará pedir a um administrador de locatários que faça isso por você.

  1. Crie um registro de aplicativo no portal do Azure.

    Certifique-se de copiar tanto o ID do aplicativo (cliente) quanto o ID do diretório (inquilino). Você pode obter esses valores na página Visão geral .

  2. Configurar permissões de API no portal do Azure:

    1. No registro do aplicativo, acesse as permissões de API.

    2. Selecione Adicionar permissão.

    3. Selecione a guia APIs que minha organização usa.

    4. Pesquise a API do Power Platform.

      Observação

      Se você não vir a API do Power Platform na lista, precisará adicionar a API ao seu locatário. Siga as instruções na Etapa 2 de Autenticação da API do Power Platform .

    5. Selecione Permissões delegadas.

    6. Em CopilotStudio, selecione CopilotStudio.Copilots.Invoke.

    7. Selecione Adicionar permissões.

    8. Conceda consentimento do administrador selecionando Conceder consentimento do administrador para <sua organização>. Se o botão não estiver disponível, talvez seja necessário pedir a um administrador de locatários que o faça por você.

  3. Adicione a URL de redirecionamento, incluindo definir configurações de token no portal do Azure:

    1. Vá para Autenticação no registro do aplicativo.

    2. Em Configurações da plataforma, selecione Adicionar uma plataforma.

    3. Selecione Aplicativo de página única.

    4. Insira a URL do Ambiente usando o formato: https://[your-org].crm.dynamics.com

    5. Selecione tokens do Access (usados para fluxos implícitos) e tokens de ID (usados para fluxos implícitos e híbridos).

    6. Selecione Configurar.

    7. Confirme se os tipos de conta com suporte estão definidos apenas como Contas neste diretório organizacional.

Copilot Studio e Dataverse

No Copilot Studio, obtenha a ID do Ambiente do agente e o Identificador do Agente para criar um registro de Configuração do Agente no Dataverse.

  1. No Copilot Studio:

    1. Verifique se você está no ambiente correto.

    2. Selecione o agente que você deseja testar e verifique se ele foi publicado.

    3. Em Configurações, selecioneMetadados Avançados>.

    4. Copie os valores para ID do Ambiente e nome do esquema. O nome do esquema é o Identificador do Agente e usa o formato cr123_agentname.

  2. Crie um registro de Configuração do Agente no Dataverse com os valores das etapas anteriores:

    Campo Value Example
    Autenticação de Usuário Autenticação da Microsoft
    ID do cliente ID do aplicativo (cliente) da etapa 1 no portal do Azure. 12345678-1234-1234-1234-123456789012
    ID do locatário ID do diretório (locatário) da etapa 1 no portal do Azure. 87654321-4321-4321-4321-210987654321
    ID do Ambiente ID do ambiente da etapa anterior. 11111111-2222-3333-4444-555555555555
    Identificador do agente Nome do esquema da etapa anterior. cr123_testagent

Resolução de problemas

Esta seção fornece etapas de solução de problemas para erros comuns que você pode encontrar.

Erros de autenticação

Erro: "AADSTS50011: a URL de resposta especificada na solicitação não corresponde"

  • Causa: não correspondência de URI de redirecionamento no registro de aplicativo no Azure.

  • Solução:

    1. No portal do Azure, acesse registros de aplicativo e selecione Gerenciar>Autenticação.
    2. Certifique-se de que o URI de redirecionamento corresponda exatamente à URL do ambiente.
    3. Use o formato: https://[your-org].crm.dynamics.com

Erro: "AADSTS65001: o usuário ou o administrador não consentiu"

  • Causa: permissões de API ausentes ou consentimento do administrador.

  • Solução:

    1. No portal do Azure, acesse registros de aplicativo e selecione Gerenciar>permissões de API.
    2. Verifique se a permissão CopilotStudio.Copilots.Invoke foi adicionada.
    3. Selecione Conceder consentimento do administrador.

O pop-up de entrada aparece toda vez que

  • Causa: a conta não está sendo armazenada em cache ou configurações do navegador impedindo o armazenamento de tokens.

  • Solução:

    1. Verifique se o navegador permite janelas pop-up para seu domínio do Dynamics.
    2. Verifique se o navegador está no modo incógnito ou privado.
    3. Verifique se o navegador não está bloqueando cookies de terceiros.
    4. Limpe o cache do navegador e tente novamente.
    5. Verifique se as políticas da organização estão forçando a autenticação novamente.

Erro: "InteractionRequiredAuthError" no console do navegador

  • Causa: comportamento normal quando a autenticação silenciosa falha e a entrada interativa é disparada.

  • Comportamento esperado:

    • Esse erro ocorre quando a autenticação silenciosa falha.
    • O sistema exibe automaticamente o pop-up de entrada.

  • Ação Necessária: Nenhuma.

Erros do SDK do agente

Erro: "404 Não Encontrado – Agente não encontrado"

  • Causa: Identificador de Agente incorreto ou ID de Ambiente.

  • Solução:

    1. Verifique o Identificador do Agente (nome do schema) no Copilot Studio em Configurações > Avançado > Metadados.
    2. Verifique se a ID do ambiente corresponde ao ambiente onde o agente está publicado.
    3. Confirme se o agente está publicado e acessível.

Erro: "401 Não autorizado"

  • Causa: problemas de token de autenticação.

  • Solução:

    1. Verifique se o usuário tem acesso ao ambiente do Copilot Studio.
    2. Verifique as permissões de registro de aplicativo do Azure.
    3. Limpe o cache do navegador e tente novamente a autenticação.

Erro: "403 Proibido"

  • Causa: permissões insuficientes para acessar o agente.

  • Solução:

    1. Verifique se o usuário tem funções de segurança apropriadas no Dataverse.
    2. Verifique se o agente permite a função de segurança do usuário.
    3. Verifique as permissões de ambiente.

Erros de controle do Test Runner do Agente

Erro: "Falha ao inicializar o serviço de autenticação"

  • Causa: configuração inválida no registro de Configuração do Agente.

  • Solução:

    1. Verifique se todos os quatro valores de configuração estão corretos:
      • ID do cliente
      • ID do locatário
      • ID do Ambiente
      • Identificador do agente
    2. Verifique se há espaços extras ou caracteres inválidos.

Erro: "Chamada de serviço externo bloqueada"

  • Causa: falta de uso de serviço externo.

  • Solução:

    • Para usuários finais em aplicativos controlados por modelos:
      • Esse erro normalmente indica um problema de implantação ou configuração.
      • Entre em contato com o administrador ou desenvolvedor do sistema.
      • Nenhuma ação do usuário pode resolver esse problema, pois requer intervenção do administrador ou do desenvolvedor.
    • Para administradores do sistema:
      • Verifique se as políticas de segurança organizacional bloqueiam chamadas externas.
      • Verifique se as configurações de firewall e proxy permitem conexões para domínios necessários da Microsoft.

Erros de rede e CORS

Erro: "Política de CORS: nenhum cabeçalho 'Access-Control-Allow-Origin'"

  • Causa: solicitação entre origens bloqueada.

  • Solução:

    1. Verifique se o URI de redirecionamento no Azure corresponde ao domínio exato.
    2. Use HTTPS para todas as URLs.
    3. Verifique se não há problemas de HTTP/HTTPS (conteúdo misto).

Erro: "Falha ao buscar"

  • Causa: problemas de conectividade de rede ou firewall.

  • Solução:

    1. Verifique a conectividade de rede para:
      • login.microsoftonline.com
      • api.powerplatform.com
    2. Verifique se o firewall permite o tráfego HTTPS de saída.
    3. Verifique as configurações de proxy, se aplicável.

Testar erros de execução

Erro: "Tempo limite de execução de teste"

  • Causa: o agente leva muito tempo para responder.

  • Solução:

    1. Verifique o desempenho do agente no Copilot Studio.
    2. Verifique se o agente está publicado e funcionando.

Erro: "Falha ao criar conversa"

  • Causa: falha na inicialização do SDK do Agente.

  • Solução:

    1. Certifique-se de que o agente esteja publicado.
    2. Verifique a configuração do agente no Copilot Studio.
    3. Verifique se o agente dá suporte ao cenário de teste.

Dicas de depuração

  1. Habilitar ferramentas de desenvolvedor do navegador:

    • Pressione F12 para abrir ferramentas de desenvolvedor.
    • Verifique a guia Console para verificar erros de JavaScript.
    • Verifique a aba de Rede para verificar solicitações que falharam.

  2. Verificar o fluxo de autenticação:

    • Monitore a guia da Rede durante o login.
    • Busque 200 respostas de login.microsoftonline.com.
    • Verifique a aquisição de token nos logs do Console.

  3. Validar a configuração:

    • Verifique todos os GUIDs e identificadores.
    • Verifique se não há espaços extras ou caracteres especiais.
    • Verifique a acessibilidade do ambiente e do agente.

  4. Teste isoladamente:

    • Experimente o agente diretamente no Copilot Studio.
  • Last updated on