Soluciona problemas de conectividad de Agent Gateway

Esta guía te ayuda a depurar y solucionar problemas de conectividad con la Gemini Enterprise Agent Platform, en especial cuando usas Agent Gateway, Agent Identity, las políticas de Identity and Access Management (IAM) y la autorización delegada con Service Extensions.

Soluciona problemas con la habilidad de solución de problemas de Agent Platform

Para diagnosticar problemas de conectividad, autorización y de inicio de forma interactiva con un asistente de programación de IA, puedes instalar la habilidad agent-platform-troubleshooting desde el repositorio de habilidades para agentes de Cloud de Confiance by S3NS .

Esta habilidad equipa a los agentes de IA con guías de diagnóstico específicas del dominio, filtros de registros y pasos de resolución en toda la pila de la Agent Platform, lo que incluye lo siguiente:

  • Denegaciones de salida de Agent Gateway: Diagnosticar errores de 403 Forbidden interceptados por la puerta de enlace y verificar las decisiones de autorización de IAP
  • Fallas en el inicio de Agent Runtime: Identifica los roles faltantes (como roles/browser o resourcemanager.projects.get) y las excepciones de arranque.
  • Problemas de destino del Agent Registry: Verificación de entradas de servicio, interfaces de extremos y configuraciones consolidadas de las APIs de Google
  • Políticas de acceso de IAM: Valida las vinculaciones de la política de acceso unificado (UAP), las expresiones de condición y el alcance del límite de acceso de la entidad (PAB).
  • Confianza en el contenedor: Diagnostica errores de certificado TLS y de protocolo de enlace para contenedores personalizados (BYOC) o autoridades certificadoras (CA) privadas.

Para instalar la habilidad en el entorno del agente, ejecuta el siguiente comando:

npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

Flujo de solicitud de salida

La Plataforma de agentes adopta una política de rechazo predeterminado para todo el tráfico saliente. Para que un agente se conecte a recursos externos, debes permitir explícitamente el acceso en cada capa de red y de identidad. Cuando Agent Gateway está habilitado, la puerta de enlace intercepta todas las solicitudes del agente y aplica las políticas configuradas.

Para que una solicitud se realice correctamente, debe cumplir con todas las siguientes condiciones:

  • Política de acceso de IAM: La identidad del agente asignada al agente debe tener el permiso iap.resources.egressViaIAP en el recurso de destino, ya sea directamente o a través de un conjunto de principales. Para obtener más detalles, consulta Crea políticas de agentes de IAM. Obtén más información para solucionar problemas de políticas de IAP.
  • Registro de agentes: Se recomienda registrar destinos en el registro de agentes para aplicar políticas de acceso detalladas por recurso y controles a nivel de la herramienta. Si el agente intenta llegar a un destino que no está registrado, debes otorgar el permiso iap.resources.egressViaIAP a la identidad del agente configurando una política para un endpoint no registrado.
  • Agent Gateway: La puerta de enlace debe estar asociada a una política de autorización que la segmenta de forma explícita. De forma predeterminada, la puerta de enlace usa IAP y Model Armor para proteger las solicitudes.
  • Autorización delegada con Service Extensions: Puedes delegar decisiones de autorización a un motor de autorización personalizado con Service Extensions. Según la política de autorización configurada, uno o más de estos motores de autorización permitirán o rechazarán la solicitud.

Problemas comunes

Revisa estos problemas habituales y sus soluciones cuando soluciones problemas de Agent Gateway.

Errores durante el inicio de Agent Runtime

Si tus instancias de Agent Runtime no se inician o no se implementan, es posible que IAP esté bloqueando el tráfico interno o que tu agente no tenga los roles básicos que necesita para inicializarse.

  1. Confirma que IAP no bloquee las llamadas a los servicios internos

    Síntoma: Errores 403 Forbidden durante el inicio.

    Causa: Agent Gateway usa una política de denegación predeterminada para todo el tráfico. Por lo tanto, cuando IAP está en modo de aplicación forzosa, bloquea las llamadas incluso a los servicios internos (como aiplatform o logging), a menos que estén registrados y el agente tenga los permisos de IAM necesarios.

    Corrección: Cambia temporalmente la IAP al modo de ejecución de prueba para ver qué conexiones fallan sin bloquear el inicio, o bien consulta Cloud Logging para identificar los nombres de host bloqueados exactos. Después de identificar los nombres de host del servicio de destino, regístralos en Agent Registry y otorga el permiso iap.resources.egressViaIAP al agente.

    Para encontrar nombres de host bloqueados específicos con Cloud Logging, ejecuta la siguiente consulta en el Explorador de registros:

    resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
httpRequest.status=403

    Examina los campos httpRequest.requestUrl o jsonPayload.authzPolicyInfo en los resultados para encontrar los nombres de host de destino.

    Entre los servicios internos comunes que pueden requerir registro durante el inicio, se incluyen los siguientes:

    • Agent Platform (motor de razonamiento y sesiones): https://REGION-aiplatform.mtls.googleapis.com
    • Resource Manager: https://cloudresourcemanager.mtls.googleapis.com y https://cloudresourcemanager.mtls.googleapis.com/
    • Google Cloud Observability (si está habilitado): https://telemetry.mtls.googleapis.com/
    • Cloud Logging (si está habilitado): https://logging.googleapis.com/
    • Cloud Monitoring: https://monitoring.googleapis.com/ y https://monitoring.mtls.googleapis.com/
    • Cloud Trace: https://cloudtrace.googleapis.com/ y https://cloudtrace.mtls.googleapis.com/
    • Secret Manager: https://secretmanager.googleapis.com/ y https://secretmanager.mtls.googleapis.com/

  2. Confirma que la identidad del agente tenga los roles básicos necesarios

    Síntomas: En los registros de aiplatform.googleapis.com/reasoning_engine_stderr, ves errores como google.api_core.exceptions.Unknown: None o Failed to convert project number to project ID. El error aparece durante el inicio de Reasoning Engine.

    Causa. La identidad del agente no tiene el permiso resourcemanager.projects.get necesario para resolver el nombre del proyecto durante la inicialización.

    Corregir. Asegúrate de que la identidad del agente (o su conjunto de principales) tenga los permisos necesarios para leer su propia configuración de tiempo de ejecución. Se requieren los siguientes roles:

    • roles/aiplatform.agentDefaultAccess: Es el rol de agente predeterminado.
    • roles/aiplatform.user: Es obligatorio para ejecutar el agente.
    • roles/agentregistry.viewer: Es obligatorio para ver los recursos registrados.
    • roles/logging.logWriter y roles/monitoring.metricWriter: Obligatorio para la observabilidad.
    • roles/browser: Se requiere para ejecutar resourcemanager.projects.get durante la inicialización del SDK.

    Para verificar los roles asignados a la identidad del agente, ejecuta el siguiente comando:

    gcloud projects get-iam-policy PROJECT_ID \
--flatten="bindings[].members" \
--filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance .
    • AGENT_IDENTITY_PRINCIPAL: Es el principal de identidad del agente. Usa el siguiente formato: principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH

    Para aprender a otorgar roles, consulta Usa Agent Identity con Agent Runtime.

403 Forbidden errores

Si encuentras un error 403 Forbidden, confirma que esté relacionado con la salida de Agent Gateway. Este es un ejemplo de mensaje de error de salida:

{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}

Consulta los registros del agente en Logging para encontrar las llamadas con errores específicas:

resource.type="aiplatform.googleapis.com/ReasoningEngine"
resource.labels.location="LOCATION"
resource.labels.reasoning_engine_id="AGENT_ID"
textPayload:"403"

Reemplaza lo siguiente:

  • LOCATION: Es la región en la que se implementa el agente, por ejemplo, us-central1.
  • AGENT_ID: Es el ID del agente (motor de razonamiento).

Busca el mensaje Egress request is not authorized en el campo textPayload de la entrada de registro. Si el error 403 contiene texto diferente, es posible que el servicio de destino rechace la llamada directamente, en lugar de Agent Gateway.

También puedes ver los registros de tráfico de salida, incluidos los rechazos de 403, con el panel de observabilidad integrado.

No se pueden conectar los destinos de CA autofirmados o privados

  • Síntoma: El agente no se conecta a los destinos que presentan certificados autofirmados o emitidos por una AC privada.
  • Causa: De forma predeterminada, Agent Gateway solo confía en los certificados emitidos por AC de confianza pública. La conexión a destinos que usan CA privadas o certificados autofirmados requiere configuración adicional.
  • Mitigación: Para conectarte a destinos con AC privadas o certificados autofirmados, debes configurar anclas de confianza de TLS personalizadas con el parámetro de configuración tlsConfig en una plantilla de conectividad de agentes.

El agente implementado con un contenedor personalizado (BYOC) no se puede conectar a Agent Gateway

  • Síntoma: El agente BYOC no puede establecer conexiones cuando se enruta a través de Agent Gateway. Es posible que los registros muestren errores de protocolo de enlace TLS o de verificación de certificados.
  • Causa: El contenedor personalizado del agente no confía en la autoridad certificadora de Agent Gateway.
  • Solución: Asegúrate de haber agregado el certificado raíz del Agent Gateway al almacén de entidades certificadoras de tu contenedor. Consulta Configura agentes de contenedores personalizados (BYOC) para Agent Gateway.

La vinculación de políticas falla o simula un rechazo de administración

  • Síntoma: Fallan las configuraciones de vinculación de políticas, se te solicita de forma interactiva un etag cuando vinculas políticas o fallan las solicitudes con un error falso de rechazo de la administración (como "se rechazó correctamente el destino no registrado").
  • Causa: La API de Identity-Aware Proxy (iap.googleapis.com) está inhabilitada en tu proyecto.
  • Solución: Habilita la API de Identity-Aware Proxy.

Fallas cuando se administra Agent Gateway con la federación de identidades de personal

Es posible que encuentres este problema si administras Agent Gateway en la consola deCloud de Confiance o usas gcloud CLI cuando te autenticas con la federación de identidades de personal (WIF).

La consola muestra errores genéricos de carga o creación, como los siguientes:

  • “Se produjo un error durante la carga…”
  • "El servidor no pudo completar tu solicitud"
  • "No se pudo crear la puerta de enlace del agente"
  • "No se pudo cargar"

Además, los comandos gcloud (como gcloud network-services agent-gateways import) pueden mostrar un error interno, como error 13: an internal error has occurred.

Para resolver este problema, autentícate con una Cuenta de Google estándar administrada a través de Cloud Identity o Google Workspace que tenga los permisos necesarios, como roles/networkservices.admin.

Las identidades federadas tienen compatibilidad limitada en los servicios de Agent Platform Governance y Gateway en la versión preliminar. Otorgar roles de IAM más amplios a una principal federada no resuelve el problema.

Flujo de trabajo de depuración

Si falta alguna de las condiciones descritas en la sección Flujo de solicitudes de salida, es posible que se bloqueen tus solicitudes.

Revisa la decisión de la IAP

Para limitar la búsqueda de registros a las decisiones de salida de IAP, ejecuta la siguiente consulta en Logging:

protoPayload.serviceName="iap.googleapis.com"
protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
protoPayload.metadata.mcp_attributes.base_protocol_method="true"

Si no ves ninguna entrada de registro de IAP coincidente, es posible que la puerta de enlace haya rechazado la solicitud antes de que IAP la evaluara. Continúa con el siguiente paso.

Si ves una entrada de registro coincidente, revisa los siguientes campos:

  • protoPayload.authorizationInfo[].granted: Indica si la solicitud se permitió (true) o se rechazó (false).
  • protoPayload.authenticationInfo.principalSubject: Es el ID de SPIFFE o la identidad de principal://... del emisor. Verifica que coincida con la identidad de tu agente.
  • protoPayload.authorizationInfo[].resource: Es el recurso de destino registrado al que se resolvió la llamada.
  • labels."iap.googleapis.com/audited_resource_name": Si este valor es unregisteredResource, el nombre de host de destino no está registrado. Registra el nombre de host de destino en el Registro de agentes y asegúrate de que el agente tenga el permiso iap.resources.egressViaIAP para este destino.
  • Modo de aplicación forzosa: Revisa el modo de aplicación forzosa de la solicitud. Para filtrar las solicitudes de ejecución de prueba, puedes agregar protoPayload.metadata.iamEnforcementMode="DRY_RUN" a la consulta. En el modo DRY_RUN, IAP registra los rechazos, pero no los aplica. Por lo tanto, si el agente falla con un error 403 en el modo de ejecución de prueba, es probable que la denegación provenga del proxy de salida de la puerta de enlace o del recurso de destino.

Revisa la decisión de Agent Gateway

Para revisar cómo evaluó la solicitud Agent Gateway, consulta los registros de la puerta de enlace en Logging. En este ejemplo, filtramos los registros solo para los errores de 403:

resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"
httpRequest.status=403
-httpRequest.requestMethod="CONNECT"

Revisa los siguientes campos en la entrada de registro coincidente:

  • jsonPayload.authzPolicyInfo.policies.result: Es el resultado general de la autorización, que puede ser ALLOWED o DENIED.
  • httpRequest.requestUrl: Anota la URL de destino exacta a la que intentó acceder el agente. En el siguiente paso, verificamos si el nombre de host que usa el recurso de destino se registró en Agent Registry.

Verifica el registro del destino y la cobertura de la política de acceso de IAM

El acceso a los destinos siempre requiere una política de permisos de IAM que otorgue el permiso iap.resources.egressViaIAP a la identidad del agente. Se recomienda registrar destinos en Agent Registry para aplicar políticas de acceso detalladas por recurso y garantizar la coincidencia precisa del nombre de host. En el caso de los destinos que no están registrados, verifica si una política para extremos no registrados otorga el permiso requerido a la identidad del agente.

Si dependes de políticas por recurso, cada nombre de host de destino y cualquier variación del nombre de host al que el agente intente acceder deben estar registrados en el Registro de agentes. Esto se debe a que una API de Google, como aiplatform.googleapis.com, se puede resolver a través de varios nombres de host según la versión del SDK, la configuración regional del cliente o el uso de mTLS (por ejemplo, us-central1-aiplatform.googleapis.com o us-central1-aiplatform.mtls.googleapis.com).

Debido a que la puerta de enlace coincide con los nombres de host de forma exacta, si registras aiplatform.googleapis.com, pero el agente llama a us-central1-aiplatform.googleapis.com, la puerta de enlace lo considera un recurso no registrado y rechaza la solicitud.

Ejecuta la siguiente secuencia de comandos de muestra para enumerar las entradas del registro según el tipo de recurso y verificar las entradas del nombre de host específico que usa la llamada del agente:

HOSTNAME="HOSTNAME"
PROJECT_ID="PROJECT_ID"
LOCATION="REGION"

echo "Checking Endpoints..."
gcloud agent-registry endpoints list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking MCP Servers..."
gcloud agent-registry mcp-servers list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking Agents..."
gcloud agent-registry agents list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

Reemplaza lo siguiente:

  • HOSTNAME: Es el nombre de host de destino al que el agente intenta acceder, por ejemplo, us-central1-aiplatform.mtls.googleapis.com.
  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance .
  • REGION: Es la ubicación de los recursos de Agent Registry y Agent Gateway, por ejemplo, us-central1.

Salida 1: El nombre de host ya está registrado

Si el nombre de host existe en una entrada de Agent Registry, verás un resultado similar al siguiente ejemplo:

Checking Endpoints...
  url: https://us-central1-aiplatform.mtls.googleapis.com
Checking MCP Servers...
Checking Agents...

Continúa con Verifica las vinculaciones de IAM en el recurso de destino para comprobar si una política por recurso o en todo el registro otorga acceso a la identidad del agente.

Resultado 2: El nombre de host no existe en el registro

Si el nombre de host no existe en el registro, verás un resultado similar al siguiente ejemplo:

Checking Endpoints...
Checking MCP Servers...
Checking Agents...

Si planeas usar políticas por recurso o para todo el registro, primero registra el destino en Agent Registry. Si usas políticas para extremos no registrados, continúa con Verifica las vinculaciones de IAM en el recurso de destino.

Verifica las vinculaciones de IAM en el recurso de destino

Asegúrate de que la identidad del agente o su conjunto principal tenga el permiso iap.resources.egressViaIAP en el destino.

Puedes configurar vinculaciones de políticas en tres permisos:

  • En todo el registro: Acceso a todos los agentes, servidores de MCP y endpoints registrados en el registro.
  • Por recurso: Restringe el acceso. Una vinculación por recurso reemplaza la vinculación en todo el registro para ese recurso específico en lugar de fusionarse con ella.
  • Políticas para endpoints no registrados: Acceso a destinos que no están registrados en Agent Registry.

Usa uno de los siguientes ejemplos para verificar las vinculaciones:

  • Para verificar las vinculaciones de políticas de IAM a nivel de registro, ejecuta el siguiente comando:

    curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \
-H "Content-Type: application/json"

  • Para verificar las vinculaciones de políticas de IAM por extremo, ejecuta el siguiente comando:

    export HOSTNAME=HOSTNAME

ENDPOINT_ID=$(gcloud agent-registry endpoints list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$HOSTNAME" \
--format="value(name.basename())")

echo "ENDPOINT_ID=$ENDPOINT_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"

    Reemplaza HOSTNAME por el nombre de host del destino al que el agente intenta llegar, por ejemplo, us-central1-aiplatform.mtls.googleapis.com.

  • Para verificar las vinculaciones de políticas de IAM de servidor por MCP, ejecuta el siguiente comando:

    export MCP_SERVER=MCP_SERVER

MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$MCP_SERVER" \
--format="value(name.basename())")

echo "MCP_SERVER_ID=$MCP_SERVER_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"

    Reemplaza MCP_SERVER por la URL del servidor de MCP (por ejemplo, https://example-abc12345-uc.a.run.app/mcp).

En la información de la política que se devolvió, busca una vinculación con el permiso iap.resources.egressViaIAP que coincida con la identidad del agente o el conjunto de principales. Si el resultado que se muestra contiene un campo "etag", pero no tiene vinculaciones, significa que no existe una política de IAM.

Si existe una vinculación, pero incluye un condition, verifica que la expresión de Common Expression Language (CEL) no excluya al agente. Es posible que una condición que filtra por un atributo del que carece el agente lo excluya de forma silenciosa.

Si el destino no tiene una vinculación de política coincidente que otorgue el permiso iap.resources.egressViaIAP a la identidad del agente o al conjunto de principales, otorga el permiso con una de las siguientes opciones de política:

Inspecciona la política de autorización y la extensión

En esta sección, nos aseguramos de que haya una política de autorización que se dirija explícitamente a Agent Gateway asociado con el agente.

  1. Obtén los detalles de la extensión de autorización asociada a la puerta de enlace y confirma que la extensión que usas esté configurada según lo previsto.

    gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Reemplaza AUTHORIZATION_EXTENSION_NAME por el nombre de la extensión asociada a la puerta de enlace. Si no conoces el nombre de la extensión, puedes navegar a la página de detalles de la puerta de enlace en la consola de Cloud de Confiance Cloud de Confiance y anotar el valor del campo Nombre de la extensión en Service Extensions.

  2. Verifica que una política de autorización segmenta explícitamente el recurso de puerta de enlace y se vincula a la misma extensión de autorización. Puedes navegar a la página de detalles de la puerta de enlace en la consola de Cloud de Confiance Cloud de Confiance y anotar el valor del campo Nombre de la política en Service Extensions.

    Si ninguna política segmenta la puerta de enlace o si la asignación de puerta de enlace a política es incorrecta, no se ejecutará la extensión de autorización.

Verifica las políticas de límite de acceso de las principales

Las políticas de límite de acceso de las principales tienen prioridad sobre las políticas de permisos de IAM. Esto significa que, incluso si configuraste correctamente todas las vinculaciones de IAM, una solicitud fallará si hay una política de límite de acceso de la principal activa que excluye el recurso de destino del alcance del agente.

Para enumerar las políticas de toda la organización, ejecuta el siguiente comando:

gcloud iam principal-access-boundary-policies list \
  --organization="ORGANIZATION_ID" \
  --location=global

Para encontrar las políticas vinculadas al conjunto de principales del agente, ejecuta el siguiente comando:

gcloud iam policy-bindings search-target-policy-bindings \
  --project="PROJECT_ID" \
  --target="PRINCIPAL_SET"

Reemplaza lo siguiente:

  • ORGANIZATION_ID: Es el ID de tu organización Cloud de Confiance .
  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance .
  • PRINCIPAL_SET: Es el conjunto de principales de la identidad del agente.

Si existe una vinculación, inspecciona el campo details.rules[].resources[] para verificar que el destino esté dentro del alcance de tu agente.

Prueba la vinculación de principal frente a la vinculación de conjunto de principales

Si los permisos funcionan de manera incoherente o fallan de forma inesperada, el problema podría estar relacionado con la forma en que se configura la identidad del grupo de tu agente (el conjunto de principales). Los permisos basados en conjuntos de principales pueden fallar por los siguientes motivos:

  • Demoras en la sincronización: Cuando agregas una identidad a un conjunto, IAM puede tardar unos minutos en actualizarse y reconocer al nuevo miembro.
  • Atributos faltantes: Si la membresía en un conjunto principal requiere ciertos atributos, la identidad del agente debe incluir esos atributos exactos (por ejemplo, etiquetas de departamento o equipo). Si a la identidad le faltan estos atributos, es posible que el agente se excluya del grupo de forma silenciosa.

Para probar si el problema se debe a la membresía del grupo, otorga permisos directamente al agente específico agregando una vinculación principal:// directa en el recurso afectado. Si el agente se conecta correctamente con la vinculación directa, es probable que la causa raíz sea una falta de coincidencia de atributos o un retraso en la sincronización con el conjunto principal. Para resolver este problema, verifica y corrige los atributos de identidad del agente o usa vinculaciones directas de principal://.

¿Qué sigue?

Codelab

Aprende a controlar las cargas de trabajo de agentes con Agent Gateway en Gemini Enterprise Agent Platform.

Guía

Obtén información para supervisar Agent Gateway.