Agente do Copilot Studio Usa Método de Autenticação Errado: Corrigir

Ao criar um agente personalizado no Copilot Studio, ele precisa se autenticar para acessar dados do Microsoft Graph ou APIs de terceiros. Se o agente usar o método de autenticação errado, retornará erros 401 Unauthorized, não conseguirá recuperar dados ou exibirá respostas genéricas em vez de informações específicas do usuário. Esse problema geralmente ocorre quando o agente é configurado com um tipo de autenticação incompatível, como usar o Azure AD SSO quando o conector exige OAuth 2.0 com credenciais de cliente, ou quando o aplicativo registrado no Microsoft Entra ID não tem as permissões de API corretas. Este artigo explica por que ocorre a incompatibilidade do método de autenticação e fornece instruções passo a passo para verificar e corrigir as configurações de autenticação no Copilot Studio.

Por que o Agente do Copilot Studio Usa o Método de Autenticação Errado

Os agentes do Copilot Studio podem usar vários métodos de autenticação: Azure AD SSO, fluxo implícito OAuth 2.0, fluxo de código de autorização OAuth 2.0, fluxo de credenciais de cliente OAuth 2.0 e autenticação por chave de API. Cada método atende a um cenário diferente.

A causa raiz do método de autenticação errado é quase sempre uma incompatibilidade de configuração entre a definição do conector no Copilot Studio e o aplicativo registrado no Microsoft Entra ID. Por exemplo, você cria um conector no Copilot Studio que espera um fluxo de código de autorização OAuth 2.0 com um URI de redirecionamento, mas o aplicativo registrado no Entra ID está configurado para usar o fluxo implícito. O conector tenta trocar um código de autorização por um token, mas o aplicativo do Entra ID rejeita a solicitação porque espera uma concessão implícita.

Outra causa comum é selecionar o tipo de autenticação errado ao adicionar um novo tópico ou ação. O Copilot Studio permite definir a autenticação por tópico. Se você criar um tópico que chama uma API do Microsoft Graph, deve selecionar Azure AD SSO. Se selecionar OAuth 2.0 genérico, o agente tentará usar o endpoint de token errado e falhará.

Uma terceira causa são permissões de API ausentes ou incorretas no aplicativo registrado. Mesmo que o método de autenticação esteja correto, o agente falhará se o aplicativo não tiver as permissões delegadas ou de aplicativo necessárias para a API de destino. Por exemplo, um agente que lê eventos de calendário do usuário precisa da permissão delegada Calendar.Read. Se o aplicativo tiver apenas Mail.Read, o agente retornará um erro 403 Forbidden.

Passos para Corrigir o Método de Autenticação no Copilot Studio

Siga estes passos em ordem. Cada passo pressupõe que você tenha acesso ao Copilot Studio e ao centro de administração do Microsoft Entra ID.

1. Abra o agente do Copilot Studio e vá para Tópicos
   No Copilot Studio, selecione seu agente na lista. No painel de navegação esquerdo, clique em Tópicos. Esta página lista todos os tópicos e tópicos do sistema para o agente. Cada tópico pode ter suas próprias configurações de autenticação.
2. Verifique o método de autenticação para cada tópico que chama uma API
   Clique em um tópico que aciona uma chamada de API ou conector. No editor do tópico, clique na guia Autenticação. O menu suspenso mostra o método de autenticação atual. Compare com o método exigido pelo conector ou API. Para APIs do Microsoft Graph, selecione Azure AD SSO. Para APIs de terceiros, selecione o método especificado na documentação da API.
3. Verifique as configurações de autenticação do conector
   No Copilot Studio, vá para Configurações > Conectores. Selecione o conector usado pelo agente. Clique em Editar e revise a seção Autenticação. O conector deve corresponder ao método configurado no aplicativo registrado. Por exemplo, se o conector usa o fluxo de código de autorização OAuth 2.0, o URI de redirecionamento no conector deve corresponder ao URI de redirecionamento no registro do aplicativo do Entra ID.
4. Abra o registro do aplicativo no Microsoft Entra ID
   Vá para o centro de administração do Microsoft Entra ID. Navegue até Registros de aplicativo. Encontre o registro do aplicativo que o Copilot Studio usa para este agente. O nome do aplicativo geralmente é o mesmo que o nome do agente ou do conector.
5. Verifique os endpoints de autenticação e o tipo de concessão
   No registro do aplicativo, clique em Autenticação no menu esquerdo. Em Configurações de plataforma, verifique se os URIs de redirecionamento correspondem aos do conector do Copilot Studio. Em Concessão implícita e fluxos híbridos, certifique-se de que as caixas de seleção correspondam ao método que seu conector usa. Para fluxo de código de autorização, não marque nenhuma caixa. Para fluxo implícito, marque Tokens de acesso e Tokens de ID.
6. Verifique as permissões de API
   No registro do aplicativo, clique em Permissões de API. Confirme se a lista de permissões inclui as APIs que o agente precisa. Para o Microsoft Graph, adicione permissões delegadas como User.Read, Mail.Read ou Calendar.Read. Para permissões de aplicativo, adicione as apropriadas. Clique em Conceder consentimento do administrador se necessário.
7. Atualize o agente do Copilot Studio com o ID do aplicativo e segredo corretos
   No Copilot Studio, vá para Configurações > Segurança > Autenticação. Se você usar credenciais de cliente OAuth 2.0 ou fluxo de código de autorização, certifique-se de que o ID do cliente corresponda ao ID do aplicativo do registro do aplicativo no Entra ID. Insira o Segredo do cliente correto. Para Azure AD SSO, certifique-se de que o ID do locatário esteja correto.
8. Teste o agente no painel de teste
   No Copilot Studio, abra o painel Teste. Digite um prompt que acione a chamada de API. Verifique a resposta. Se ainda vir um erro 401, abra as ferramentas de desenvolvedor do navegador (F12) e observe a guia de rede para a solicitação de token. A mensagem de erro na resposta do token informará se o problema é tipo de concessão errado, URI de redirecionamento inválido ou permissões insuficientes.

Se o Agente Ainda Usar o Método de Autenticação Errado

Mesmo após seguir os passos principais, o agente pode continuar falhando. Os problemas a seguir são comuns e têm correções específicas.

Conector do Copilot Studio Mostra Erro “Cliente Inválido”

Esse erro significa que o ID do cliente ou segredo do cliente no conector não corresponde ao aplicativo registrado. Volte ao registro do aplicativo no Entra ID e copie o ID do aplicativo exato. No Copilot Studio, vá para as configurações do conector e cole o ID. Gere um novo segredo do cliente no Entra ID e copie-o imediatamente. Cole-o nas configurações do conector. Salve e teste novamente.

Agente Retorna Erro “AADSTS7000218”

O código de erro AADSTS7000218 significa que o corpo da solicitação contém um tipo de concessão não suportado. Isso acontece quando o conector espera o fluxo de código de autorização, mas o aplicativo registrado está configurado para fluxo implícito. No registro do aplicativo do Entra ID, vá para Autenticação. Em Concessão implícita e fluxos híbridos, desmarque ambas as caixas de seleção. Salve as alterações. No Copilot Studio, certifique-se de que o conector use o fluxo de código de autorização com o URI de redirecionamento correto.

Agente Retorna Dados Genéricos em Vez de Dados Específicos do Usuário

Esse problema ocorre quando o agente usa permissões de aplicativo em vez de permissões delegadas. Permissões de aplicativo concedem ao aplicativo acesso a todos os dados do locatário. O agente não sabe qual usuário está fazendo a pergunta. Para corrigir, altere as permissões de API no registro do aplicativo do Entra ID de permissões de aplicativo para permissões delegadas. No Copilot Studio, defina a autenticação do tópico como Azure AD SSO. Isso força o agente a autenticar o usuário e passar o contexto do usuário para a API.

Métodos de Autenticação no Copilot Studio: Comparação

Item	Azure AD SSO	Código de Autorização OAuth 2.0	Credenciais de Cliente OAuth 2.0
Melhor para	APIs do Microsoft Graph com contexto do usuário	APIs de terceiros com contexto do usuário	APIs servidor a servidor sem contexto do usuário
Configuração necessária no Entra ID	Permissões delegadas, URI de redirecionamento	Permissões delegadas, URI de redirecionamento, segredo do cliente	Permissões de aplicativo, segredo do cliente ou certificado
Tempo de vida do token	1 hora padrão, renovável	1 hora padrão, renovável com token de atualização	1 hora padrão, sem token de atualização
Identidade do usuário transmitida	Sim	Sim	Não
Erro comum se mal configurado	401 Unauthorized, AADSTS50011	AADSTS7000218, invalid_grant	401 Unauthorized, AADSTS700016

Selecione o método que atenda tanto aos requisitos da API quanto à necessidade de contexto do usuário. Se você precisar de dados específicos do usuário, use Azure AD SSO ou código de autorização OAuth 2.0. Se precisar de dados de todo o locatário, use credenciais de cliente.

Após corrigir o método de autenticação, teste o agente com várias contas de usuário para confirmar que ele retorna os dados corretos para cada usuário. Se o agente ainda falhar, revise os logs do conector no Copilot Studio em Configurações > Analytics > Erros do conector. Os logs mostram a solicitação e resposta HTTP exatas, incluindo a URL do endpoint do token e o payload de erro. Use essas informações para ajustar a configuração de autenticação no Entra ID ou no Copilot Studio.