Resolver problemas de autenticação de identidade do agente

Neste documento, descrevemos como resolver erros comuns de autenticação usando a identidade do agente com o gerenciador de autenticação.

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 do desenvolvedor de terceiros corresponde exatamente ao URI gerado pelo gerenciador de autenticação.

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

gcloud alpha agent-identity connectors 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 o papel roles/iamconnectors.user no recurso do provedor de autenticação.

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

Problemas com o endpoint do emissor

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

Se não for possível buscar os metadados do OIDC ou o JWKS, verifique se o endpoint não está atrás de um firewall ou rede restrita. Google Cloud

Erro 401 UNAUTHENTICATED

Se o agente não puder ser autenticado, o seguinte erro poderá ocorrer. Esse erro geralmente é causado por uma política de acesso baseado no contexto gerenciada pelo Google que aplica a vinculação mTLS e as provas criptográficas 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, você pode desativar a política de acesso baseado no contexto padrão quando tiver requisitos específicos de compartilhamento de tokens 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 a 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 Google Cloud projeto ou as restrições da chave de API não permitem o acesso a esse serviço.

Para resolver esse erro, siga estas etapas:

  1. Noconsole, acesse a página APIs e serviços >Biblioteca e verifique se a API de destino está ativada. Google Cloud

    Acessar APIs e serviços >Biblioteca

  2. Noconsole, acesse a página APIs e serviços >Credenciais , edite a chave de API e verifique se as restrições de API permitem o acesso ao serviço. Google Cloud

    Acessar APIs e serviços >Credenciais

Chave de API inválida (API_KEY_INVALID)

Ao enviar solicitações a um serviço de terceiros, o seguinte erro poderá 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 noconsole e se nenhum espaço em branco inicial ou final foi incluído. Google Cloud

Permissão negada ao recuperar credenciais (iamconnectors.connectors.retrieveCredentials)

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

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

Esse erro ocorre porque a entidade 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 do conector (roles/iamconnectors.user) à entidade 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 o papel à entidade 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 de implantação

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

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

Para resolver esse erro, faça o seguinte:

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

A seguir