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 autenticar agentes com a Identidade do Agente e 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. Para instruções sobre como verificar tokens de ID de identidade do agente em serviços externos, consulte Autenticar em serviços externos usando a própria identidade de um agente.

Falha na correspondência do URI de redirecionamento

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

Para resolver esse problema, encontre o URI de redirecionamento gerado ao conferir os detalhes do provedor de autenticação no console do Google Cloud ou executar 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 a função 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 exige 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, desative a política padrão de Acesso Baseado no Contexto quando 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 seu agente:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "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 do 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 da chave de API correta da página Credenciais no console do 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 de 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 o papel Usuário da identidade do agente (roles/agentidentity.user) ao principal:

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 o 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ária (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, e não com base nos 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.

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

Erros de descoberta do OpenID Connect e do endpoint JWKS

Um serviço externo ou uma parte confiável pode consultar os endpoints do Google Cloud Security Token Service OpenID Connect Discovery (/.well-known/openid-configuration) ou JSON Web Key Set (/openid/jwks) para verificar um token de ID de identidade do agente. Ao consultar esses endpoints, a solicitação pode falhar com um erro HTTP 400, 404, 429 ou 500.

A tabela a seguir descreve as causas e as soluções para esses erros:

Status HTTP	Causa	Resolução
`400 Bad Request`	Esse erro ocorre porque o nome do recurso do pool de identidade da carga de trabalho no URL da solicitação é inválido ou porque a solicitação inclui um cabeçalho HTTP `Authorization`.	Para resolver esse erro, faça o seguinte: Verifique se o nome do recurso do pool de Identidade da carga de trabalho usa um formato de domínio de confiança do agente compatível (`agents.global.org-ORGANIZATION_ID.system.id.goog` ou `agents.global.proj-PROJECT_NUMBER.system.id.goog`). Remova todos os cabeçalhos `Authorization` ou OAuth da solicitação. Os endpoints `/.well-known/openid-configuration` e `/openid/jwks` são públicos e não autenticados. Transmitir cabeçalhos de autenticação faz com que a solicitação falhe com um erro `HTTP 400`.
`404 Not Found`	Esse erro ocorre porque o ID da organização, o número do projeto ou o pool de Identidade da carga de trabalho especificado não existe ou o caminho do URL está incorreto.	Para resolver esse erro, confirme se o ID da organização, o número do projeto e o domínio de confiança (ID do pool de identidades da carga de trabalho) no URL estão corretos. Verifique também se o caminho do URL termina com `/.well-known/openid-configuration` ou `/openid/jwks`.
`429 Too Many Requests`	Esse erro ocorre porque seu verificador excedeu o limite da taxa de solicitações ao consultar os endpoints de descoberta ou JWKS sem armazenar em cache a resposta.	Para resolver esse erro, configure seu verificador para armazenar em cache o documento de descoberta e o JWKS por até 24 horas, de acordo com o cabeçalho de resposta `Cache-Control: public, max-age=86400, must-revalidate`.
`500 Internal Server Error`	Esse erro ocorre porque o servidor encontrou um problema interno temporário ao buscar as chaves públicas de assinatura.	Para resolver esse erro, use o JWKS em cache, se disponível, ou tente de novo a solicitação com espera exponencial.

A verificação da assinatura do token falha após a rotação de chaves

Quando um serviço externo verifica um token de ID de identidade do agente, a verificação de assinatura pode falhar para tokens recém-emitidos, mesmo que os tokens anteriores do mesmo agente tenham sido bem-sucedidos.

Esse problema ocorre porque o Google Cloud alterna periodicamente as chaves de assinatura privadas e públicas para pools de identidade da carga de trabalho. Como resultado, o kid (ID da chave) do token de entrada pode não estar no cache de chaves local do verificador.

Para resolver esse problema, configure seu verificador para que, quando ele receber um token com um kid não reconhecido, ele busque um JWKS novo no endpoint /openid/jwks antes de rejeitar o token.