Soluciona problemas de autenticación de identidad del agente

En este documento, se describe cómo resolver errores comunes de Authentication using Agent Identity with auth manager.

Los URI de redireccionamiento no coinciden

Si recibes un error redirect URI mismatch de la aplicación de terceros durante el flujo de OAuth, asegúrate de que el URI de redireccionamiento registrado en el portal para desarrolladores de terceros coincida exactamente con el URI generado por el administrador de autorización.

Para resolver este problema, busca el URI de redireccionamiento generado. Para ello, consulta los detalles del proveedor de autenticación en la consola de Google Cloud o ejecuta el siguiente comando de gcloud:

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

Falta el rol del usuario

Si tu agente no puede usar el proveedor de autenticación, verifica que la identidad del agente tenga el rol roles/iamconnectors.user en el recurso del proveedor de autenticación.

Para resolver este problema, otorga el rol con la consola de Google Cloud o ejecuta el comando add-iam-policy-binding.

Problemas con el extremo de la entidad emisora

En el caso de los proveedores de OIDC, verifica que se pueda acceder al extremo del emisor de forma pública y que admita el documento de descubrimiento .well-known/openid-configuration.

Si Google Cloud no puede recuperar los metadatos de OIDC o el JWKS, asegúrate de que el extremo no esté detrás de un firewall o una red restringida.

Error 401 UNAUTHENTICATED

Si tu agente no puede autenticarse, es posible que se produzca el siguiente error. Por lo general, este error se debe a una política de acceso adaptado al contexto administrada por Google que aplica la vinculación de mTLS y las pruebas 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 este error, puedes inhabilitar la política predeterminada de Acceso adaptado al contexto cuando tengas requisitos específicos de uso compartido de tokens o debas insertar el token directamente en el encabezado. Para inhabilitar esta opción, configura la siguiente variable de entorno cuando implementes tu agente:

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

Se bloqueó el servicio de claves de API (API_KEY_SERVICE_BLOCKED).

Si validas tu clave de API, es posible que se produzca el siguiente error. Este error indica que el servicio 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."
  }
]

Este error se produce porque el servicio de API de destino (por ejemplo, la API de Cloud Translation) no se habilitó en tu proyecto de Google Cloud o porque las restricciones de la clave de API no permiten el acceso a este servicio.

Para resolver este error, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página APIs & Services >Library y asegúrate de que la API de destino esté habilitada.

    Ir a APIs y servicios >Biblioteca

  2. En la consola de Google Cloud , ve a la página Credenciales >APIs y servicios, edita tu clave de API y verifica que sus restricciones de API permitan el acceso al servicio.

    Ir a APIs y servicios >Credenciales

Clave de API no válida (API_KEY_INVALID)

Cuando envías solicitudes a un servicio de terceros, es posible que se produzca el siguiente error. Este error indica que la clave de API no es vá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."
  }
]

Este error se produce porque la cadena de la clave de API que se pasó en el encabezado de la solicitud es incorrecta, tiene errores de formato o no existe en las credenciales de tu proyecto.

Para resolver este error, verifica que hayas copiado la cadena de clave de API correcta de la página Credenciales en la consola de Google Cloud y que no se haya incluido ningún espacio en blanco inicial o final.

Se denegó el permiso para recuperar credenciales (iamconnectors.connectors.retrieveCredentials)

Cuando ejecutas adk web de forma local o interactúas con tu agente implementado, puede ocurrir el siguiente error de 403 Forbidden:

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).

Este error se produce porque el principal que intenta invocar al proveedor de autenticación no tiene los permisos de IAM necesarios para recuperar credenciales.

Para resolver este error, otorga el rol de Usuario del conector (roles/iamconnectors.user) a la principal:

  • Si este error se produce durante el desarrollo local (uv run adk web o uvicorn), asegúrate de haber otorgado el rol a tu cuenta de usuario personal (user:USER_EMAIL).
  • Si este error se produce cuando interactúas con un agente implementado, asegúrate de haber otorgado el rol a la principal del ID de SPIFFE de tu agente (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Error genérico de implementación

Cuando implementas tu agente con uv run adk deploy, es posible que el comando falle y muestre un mensaje de error genérico.

Este error se produce debido a dependencias de Python faltantes, errores de sintaxis en agent.py o variables de entorno mal configuradas.

Para resolver este error, haz lo siguiente:

  1. Abre la consola de Google Cloud y ve a la página Explorador de registros.
  2. Busca los registros del contenedor de implementación temporal (por ejemplo, maps_mcp_agent_tmp... o bigquery_mcp_agent_tmp...).
  3. Revisa el registro de seguimiento de Python para identificar el error de sintaxis o rastrear los paquetes faltantes.
  4. Asegúrate de que todos los paquetes obligatorios aparezcan en tu archivo requirements.txt.

¿Qué sigue?