Partilhar via

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

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

Architecture

A autenticação da Microsoft oferece uma arquitetura simplificada, de navegador para SDK do Agente, optimizada para cenários de teste. Esta abordagem permite uma comunicação segura entre o seu ambiente de teste e os agentes do Copilot Studio sem necessidade de infraestrutura adicional de autenticação.

Arquitetura de fluxo

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

Diagrama que ilustra a arquitetura do SDK browser-para-agente para autenticação e testes.

Arquitetura de componentes

O diagrama seguinte ilustra os componentes-chave envolvidos no fluxo de autenticação da Microsoft para o Agent Test Runner.

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

Configurar autenticação Microsoft

O processo de configuração envolve registar a aplicação no portal Azure, obter identificadores de agente no Copilot Studio e criar um registo de configuração no Dataverse.

Azure portal

No portal Azure, crie um registo de aplicação, adicione o URL de redirecionamento e configure as permissões da 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ário para fazer isso por você.

  1. Criar um registo de app no portal Azure.

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

  2. Configurar permissões da API no portal Azure:

    1. No registro do aplicativo, vá para Permissões de API.

    2. Selecione Adicionar uma permissão.

    3. Selecione o separador APIs utilizadas pela sua organização.

    4. Procure por API da Power Platform.

      Observação

      Se não vir API do Power Platform na lista, tem de adicionar a API ao seu inquilino. Siga as instruções em Power Platform API Authentication Step 2.

    5. Selecione Permissões delegadas.

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

    7. Selecione Adicionar permissões.

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

  3. Adicione o URL de redirecionamento e configure as definições do token no portal Azure:

    1. Aceda a Autenticação no registo da sua aplicação.

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

    3. Selecione Aplicação de página única.

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

    5. Selecione tokens de acesso (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 suportados estão definidos como Contas apenas neste diretório organizacional.

Copilot Studio e Dataverse

Para o Copilot Studio, obtenha o ID de Ambiente e o Identificador do Agente para criar um registo de Configuração do Agente no Dataverse.

  1. No Copilot Studio:

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

    2. Selecione o agente que deseja testar e certifique-se de que ele esteja publicado.

    3. Em Configurações, selecione Metadados 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 do usuário Autenticação Microsoft
    ID de Cliente ID da aplicação (cliente) do passo 1 no portal Azure. 00001111-aaaa-2222-bbbb-3333cccc4444
    ID do Inquilino ID do diretório (inquilino) do passo 1 no portal Azure. 11112222-bbbb-3333-cccc-4444dddd5555
    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

Soluçã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: O URL de resposta especificado na solicitação não corresponde"

  • Causa: Incompatibilidade de URI de redirecionamento no registo da aplicação.

  • Solução:

    1. No portal Azure, vá a Registos de aplicações e selecione Gerir>Autenticação.
    2. Verifique se o URI de redirecionamento corresponde exatamente à URL do seu ambiente.
    3. Use o formato: https://[your-org].crm.dynamics.com

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

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

  • Solução:

    1. No portal do Azure, vá para Registos de aplicações e selecione Gerir>Permissões de API.
    2. Verifique se a permissão CopilotStudio.Copilots.Invoke foi adicionada.
    3. Selecione Conceder consentimento de administrador.

O pop-up de início de sessão aparece sempre

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

  • Solução:

    1. Certifique-se de que o seu navegador permite janelas pop-up para o seu domínio Dynamics.
    2. Verifique se o seu navegador está no modo de navegação anónima ou privado.
    3. Verifique se o seu navegador não está a bloquear 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 reautenticação.

Erro: "InteractionRequiredAuthError" no console do navegador

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

  • Comportamento esperado:

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

  • Ação necessária: Nenhuma.

Erros do SDK do agente

Erro: "404 não encontrado - agente não encontrado"

  • Causa: identificador de agente ou ID de ambiente incorreto.

  • Solução:

    1. Verifique o Identificador do Agente (nome do esquema) em Copilot Studio em Definições > Avançado > Metadados.
    2. Verifique se o 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 utilizador tem acesso ao ambiente do Copilot Studio.
    2. Verifique as permissões de registo da aplicação.
    3. Limpe o cache do navegador e tente autenticar novamente.

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 o direito de acesso do utilizador.
    3. Verifique as permissões do ambiente.

Erros de controle do Agent Test Runner

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

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

  • Solução:

    1. Verifique se todos os quatro valores de configuração estão corretos:
      • ID do Cliente
      • ID do inquilino
      • 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 utilizadores finais em aplicações orientadas por modelos:
      • Esse erro normalmente indica um problema de implantação ou configuração.
      • Entre em contato com o administrador do sistema ou desenvolvedor.
      • Nenhuma ação do usuário pode resolver esse problema, pois requer a intervenção do administrador ou do desenvolvedor.
    • Para administradores de sistema:
      • Verifique se as políticas de segurança organizacional bloqueiam chamadas externas.
      • Garante que as definições de firewall e proxy permitem ligações aos domínios Microsoft necessários.

Erros de rede e CORS

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

  • Causa: solicitação de origem cruzada bloqueada.

  • Solução:

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

Erro: "Falha ao obter"

  • 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 tráfego HTTPS de saída.
    3. Verifique as configurações de proxy, se aplicável.

Erros de execução de teste

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

  • Causa: o agente demora muito tempo a responder.

  • Solução:

    1. Verifica o desempenho dos agentes no Copilot Studio.
    2. Verifique se o agente está publicado e a funcionar.

Erro: "Não foi possível criar conversa"

  • Causa: Falha na inicialização do SDK do agente.

  • Solução:

    1. Verifique se o agente está publicado.
    2. Verifique a configuração do agente no Copilot Studio.
    3. Verifique se o agente suporta o cenário de teste.

Dicas de depuração

  1. Habilite as ferramentas de desenvolvedor do navegador:

    • Pressione F12 para abrir as ferramentas de desenvolvedor.
    • Verifique se há erros de JavaScript na guia Console.
    • Verifique o separador Rede para solicitações falhadas.

  2. Verifique o fluxo de autenticação:

    • Monitorize o separador Rede durante o início de sessão.
    • Verifique 200 respostas de login.microsoftonline.com.
    • Verifique a aquisição de tokens nos logs do console.

  3. Validar configuração:

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

  4. Teste isolado:

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