Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Soluciona problemas de autenticación de identidad del agente

Para resolver errores comunes cuando autenticas agentes con Agent Identity y el administrador de autenticación de Agent Identity, verifica la configuración de tu proveedor de autenticación, las vinculaciones de roles de Identity and Access Management (IAM), los permisos de OAuth y la configuración de verificación de tokens de OpenID Connect (OIDC).

Para administrar los proveedores de autenticación, consulta Administra los proveedores de autenticación de Agent Identity. Para verificar los tokens de ID de identidad del agente en servicios externos, consulta Autentica en servicios externos con la identidad propia de un agente.

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 autenticació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 authProviders 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/agentidentity.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 públicamente al extremo del emisor 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 produce debido 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_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Se bloqueó el servicio de clave 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 la API de destino (por ejemplo, la API de Cloud Translation) no se habilitó en tu proyecto de Google Cloud o las restricciones de la clave de API no permiten el acceso a este servicio.

Para resolver este error, sigue estos pasos:

En la consola de Google Cloud , ve a la página APIs y servicios >Biblioteca y asegúrate de que la API de destino esté habilitada.
Ve a APIs y servicios >Biblioteca.
En la consola de Google Cloud , ve a la página APIs y servicios >Credenciales, edita tu clave de API y verifica que sus restricciones de API permitan el acceso al servicio.
Ve a APIs y servicios >Credenciales

La clave de API no es válida (`API_KEY_INVALID`)

Cuando envías solicitudes a un servicio de terceros, puede producirse 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 clave de API que se pasa en el encabezado de la solicitud es incorrecta, tiene un formato incorrecto 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 hayas incluido espacios en blanco al principio ni al final.

Se denegó el permiso para recuperar las credenciales (`agentidentity.authProviders.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://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).

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

Para resolver este error, otorga el rol de Usuario de identidad del agente (roles/agentidentity.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).

Falla genérica de implementación

Cuando implementas tu agente con uv run adk deploy, es posible que el comando falle con 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:

Abre la consola de Google Cloud y dirígete a la página Explorador de registros.
Busca los registros del contenedor de implementación temporal (por ejemplo, maps_mcp_agent_tmp... o bigquery_mcp_agent_tmp...).
Verifica el seguimiento de Python para identificar errores de sintaxis o rastrear paquetes faltantes.
Asegúrate de que todos los paquetes obligatorios aparezcan en tu archivo requirements.txt.

Bucle de autenticación de ServiceNow o permisos inesperados

Cuando un agente se autentica en ServiceNow con OAuth de 3 etapas, el flujo de autenticación puede fallar o el agente puede ingresar a un bucle de solicitud.

Este problema se produce porque ServiceNow determina los permisos otorgados a nivel de la aplicación, en lugar de los permisos que solicita el agente. Si un administrador configura permisos específicos en la aplicación de ServiceNow (por ejemplo, useraccount), ServiceNow devuelve tokens que contienen solo esos permisos configurados, incluso si el agente solicitó permisos diferentes (como mcp_server). Si el agente espera o valida estrictamente los permisos solicitados, rechaza el token recibido y puede volver a solicitar credenciales en un bucle.

Para solucionar este problema, haz lo siguiente:

Accede a tu instancia de ServiceNow como administrador.
Ve a la configuración de la aplicación de OAuth de ServiceNow.
Asegúrate de que todos los permisos que requiere tu agente se agreguen de forma explícita a la lista de permisos permitidos para la aplicación.
Configura tu agente para que solicite solo los permisos habilitados en ServiceNow.

Para obtener más información, consulta Servicios de terceros compatibles.

Error de varios permisos de GitHub o Microsoft

Cuando configuras un proveedor de autenticación para GitHub o Microsoft, la autenticación falla si solicitas varios permisos de OAuth.

El administrador de autenticación admite integraciones de un solo permiso para GitHub y Microsoft. El administrador de autenticación no admite la solicitud de varios permisos de forma simultánea.

Para resolver este problema, configura tu agente o proveedor de autenticación para que solicite solo un permiso necesario para la integración.

Para obtener más información, consulta Servicios de terceros compatibles.

Errores de descubrimiento de OpenID Connect y del extremo de JWKS

Un servicio externo o una parte de confianza pueden consultar los extremos de OpenID Connect Discovery (/.well-known/openid-configuration) o JSON Web Key Set (/openid/jwks) de Security Token Service para verificar un token de ID de identidad del agente. Google Cloud Cuando se consultan estos extremos, la solicitud puede fallar con un error HTTP 400, 404, 429 o 500.

En la siguiente tabla, se describen las causas y las soluciones de estos errores:

Estado de HTTP	Causa	Solución
`400 Bad Request`	Este error se produce porque el nombre del recurso del grupo de identidades para cargas de trabajo en la URL de la solicitud no es válido o la solicitud incluye un encabezado HTTP `Authorization`.	Para resolver este error, haz lo siguiente: Verifica que el nombre del recurso del grupo de identidades para cargas de trabajo use un formato de dominio de confianza de agente compatible (`agents.global.org-ORGANIZATION_ID.system.id.goog` o `agents.global.proj-PROJECT_NUMBER.system.id.goog`). Quita cualquier encabezado `Authorization` o de OAuth de la solicitud. Los extremos `/.well-known/openid-configuration` y `/openid/jwks` son públicos y no están autenticados. Pasar encabezados de autenticación hace que la solicitud falle con un error `HTTP 400`.
`404 Not Found`	Este error se produce porque el ID de organización, el número de proyecto o el grupo de identidades para cargas de trabajo especificados no existen, o bien la ruta de URL es incorrecta.	Para resolver este error, confirma que el ID de organización, el número de proyecto y el dominio de confianza (ID del grupo de Workload Identity) en la URL sean correctos. Verifica también que la ruta de URL termine con `/.well-known/openid-configuration` o `/openid/jwks`.
`429 Too Many Requests`	Este error se produce porque tu verificador superó el límite de porcentaje de solicitudes consultando los extremos de descubrimiento o JWKS sin almacenar en caché la respuesta.	Para resolver este error, configura tu verificador para que almacene en caché el documento de descubrimiento y el JWKS durante un máximo de 24 horas según el encabezado de respuesta `Cache-Control: public, max-age=86400, must-revalidate`.
`500 Internal Server Error`	Este error se produce porque el servidor encontró un problema interno temporal mientras recuperaba las claves de firma públicas.	Para resolver este error, usa tu JWKS almacenado en caché si está disponible o vuelve a intentar la solicitud con una retirada exponencial.

La verificación de la firma del token falla después de la rotación de claves

Cuando un servicio externo verifica un token de ID de identidad del agente, la verificación de la firma puede fallar para los tokens emitidos recientemente, aunque los tokens anteriores del mismo agente hayan tenido éxito.

Este problema se produce porque Google Cloud rota de forma periódica las claves de firma privadas y públicas de los grupos de identidades para cargas de trabajo. Como resultado, es posible que el kid (ID de clave) del token entrante no esté en la caché de claves local del verificador.

Para resolver este problema, configura tu verificador de modo que, cuando reciba un token con un kid no reconocido, recupere un JWKS nuevo del extremo /openid/jwks antes de rechazar el token.