O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Resolver problemas de autenticação de identidade do agente

Neste documento, descrevemos como resolver erros comuns ao usar o gerenciador de autenticação de identidade do agente.

Para instruções sobre como configurar provedores de autenticação, consulte Gerenciar provedores de autenticação de identidade do agente.

Falha na correspondência do URI de redirecionamento

Se você receber um erro redirect URI mismatch do aplicativo de terceiros durante o fluxo OAuth, verifique se o URI de redirecionamento registrado no portal do desenvolvedor de terceiros corresponde exatamente ao URI gerado pelo gerenciador de autenticação.

Para resolver esse problema, encontre o URI de redirecionamento gerado acessando os detalhes do provedor de autenticação no console Google Cloud ou executando o seguinte comando gcloud:

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

Função do usuário ausente

Se o agente não puder usar o provedor de autenticação, verifique se a identidade do agente tem a função roles/agentidentity.user no recurso do provedor de autenticação.

Para resolver esse problema, conceda o papel usando o console do Google Cloud ou execute o comando add-iam-policy-binding.

Problemas com o endpoint do emissor

Para provedores OIDC, verifique se o endpoint do emissor está acessível publicamente e se é compatível com o documento de descoberta .well-known/openid-configuration.

Se o Google Cloud não conseguir buscar os metadados OIDC ou JWKS, verifique se o endpoint não está atrás de um firewall ou em uma rede restrita.

Erro 401 UNAUTHENTICATED

Se o agente não conseguir se autenticar, o seguinte erro poderá ocorrer. Esse erro geralmente é causado por uma política de acesso baseado no contexto gerenciada pelo Google que impõe a vinculação de mTLS e provas criptográficas de DPoP:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

Para resolver esse erro, é possível desativar a política padrão de Acesso Baseado no Contexto quando você tiver requisitos específicos de compartilhamento de token ou precisar injetar o token diretamente no cabeçalho. Para desativar, defina a seguinte variável de ambiente ao implantar o agente:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Serviço de chaves de API bloqueado (`API_KEY_SERVICE_BLOCKED`)

Se você validar sua chave de API, o seguinte erro poderá ocorrer. Esse erro indica que o serviço está bloqueado:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

Esse erro ocorre porque o serviço de API de destino (por exemplo, a API Cloud Translation) não foi ativado no seu projeto Google Cloud ou as restrições da chave de API não permitem o acesso a esse serviço.

Para resolver esse erro, siga estas etapas:

No console do Google Cloud , acesse a página APIs e serviços >Biblioteca e verifique se a API de destino está ativada.
Acesse APIs e serviços >Biblioteca
No console Google Cloud , acesse a página APIs e serviços >Credenciais, edite sua chave de API e verifique se as restrições de API permitem o acesso ao serviço.
Acesse APIs e serviços >Credenciais

Chave de API inválida (`API_KEY_INVALID`)

Ao enviar solicitações para um serviço de terceiros, o seguinte erro pode ocorrer. Esse erro indica que a chave de API é inválida:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

Esse erro ocorre porque a string da chave de API transmitida no cabeçalho da solicitação está incorreta, malformada ou não existe nas credenciais do projeto.

Para resolver esse erro, verifique se você copiou a string correta da chave de API na página Credenciais do console Google Cloud e se não incluiu espaços em branco à esquerda ou à direita.

Permissão negada ao recuperar credenciais (`agentidentity.authProviders.retrieveCredentials`)

Ao executar o adk web localmente ou interagir com o agente implantado, o seguinte erro 403 Forbidden pode ocorrer:

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

Esse erro ocorre porque o principal que tenta invocar o provedor de autenticação não tem as permissões necessárias do IAM para recuperar credenciais.

Para resolver esse erro, conceda ao principal o papel Usuário da identidade do agente (roles/agentidentity.user):

Se esse erro ocorrer durante o desenvolvimento local (uv run adk web ou uvicorn), verifique se você concedeu o papel à sua conta de usuário pessoal (user:USER_EMAIL).
Se esse erro ocorrer ao interagir com um agente implantado, verifique se você concedeu a função ao principal do ID SPIFFE do agente (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Falha genérica na implantação

Ao implantar seu agente usando uv run adk deploy, o comando pode falhar com uma mensagem de erro genérica.

Esse erro ocorre devido a dependências do Python ausentes, erros de sintaxe em agent.py ou variáveis de ambiente mal configuradas.

Para resolver esse erro, faça o seguinte:

Abra o console do Google Cloud e acesse a página Análise de registros.
Pesquise os registros do contêiner de implantação temporário (por exemplo, maps_mcp_agent_tmp... ou bigquery_mcp_agent_tmp...).
Verifique o rastreamento de pilha do Python para identificar erros de sintaxe ou rastrear pacotes ausentes.
Verifique se todos os pacotes necessários estão listados no arquivo requirements.txt.

Loop de autenticação do ServiceNow ou escopos inesperados

Quando um agente se autentica no ServiceNow usando o OAuth de três etapas, o fluxo de autenticação pode falhar ou o agente pode entrar em um loop de solicitação.

Esse problema ocorre porque o ServiceNow determina os escopos concedidos no nível do aplicativo, em vez dos escopos solicitados pelo agente. Se um administrador configurar escopos específicos no aplicativo ServiceNow (por exemplo, useraccount), o ServiceNow vai retornar tokens que contêm apenas esses escopos configurados, mesmo que o agente tenha solicitado escopos diferentes (como mcp_server). Se o agente esperar ou validar estritamente os escopos solicitados, ele vai rejeitar o token recebido e poderá solicitar novamente as credenciais em um loop.

Para resolver esse problema, faça o seguinte:

Faça login na sua instância do ServiceNow como administrador.
Acesse a configuração do aplicativo OAuth do ServiceNow.
Verifique se todos os escopos exigidos pelo seu agente foram adicionados explicitamente à lista de escopos permitidos do aplicativo.
Configure o agente para solicitar apenas os escopos ativados no ServiceNow.

Para mais informações, consulte Serviços de terceiros compatíveis.

Erro de vários escopos do GitHub ou da Microsoft

Ao configurar um provedor de autenticação para GitHub ou Microsoft, a autenticação falha se você solicitar vários escopos do OAuth.

O gerenciador de autenticação oferece suporte a integrações de escopo único para GitHub e Microsoft. O gerenciador de autenticação não aceita a solicitação de vários escopos simultaneamente.

Para resolver esse problema, configure seu agente ou provedor de autenticação para solicitar apenas um escopo necessário para a integração.