Cómo enrutar el tráfico de Agent Runtime a través de Agent Gateway

En esta página, se describe cómo enrutar el tráfico de Agent Runtime a través de Agent Gateway. Agent Gateway es un componente central de redes y seguridad del ecosistema de Gemini Enterprise Agent Platform. Proporciona conectividad segura y administrada para todas las interacciones de agentes, ya sea que se produzcan entre usuarios y agentes, agentes y herramientas, o entre los propios agentes.

Antes de comenzar

  • Asegúrate de conocer la implementación de agentes en Agent Runtime.

  • Obtén más información sobre Agent Gateway. Puedes usar Agent Gateway en el modo Agent-to-Anywhere (salida) para proteger y controlar todas las comunicaciones salientes con tráfico saliente a herramientas, modelos, APIs y otros agentes. Usas la puerta de enlace en el modo Cliente a agente (entrada) para controlar qué clientes pueden acceder a tus agentes. La puerta de enlace te permite elegir qué políticas de IAP y plantillas de Model Armor se deben aplicar a estas interacciones.

    Una sola instancia de Runtime puede vincularse a una puerta de enlace de Agent-to-Anywhere (salida) y a una puerta de enlace de Client-to-Agent (entrada) de forma simultánea.

Limitaciones

  • No se puede vincular una puerta de enlace de agentes a los motores de razonamiento del tiempo de ejecución creados antes del 29 de abril de 2026.

  • Si bien un solo proyecto y una sola región pueden alojar varias instancias de Agent Gateway de Agent-to-Anywhere (salida) y Client-to-Agent (entrada), todos los agentes de Agent Runtime implementados en ese mismo proyecto y región deben vincularse a las mismas instancias específicas de Agent Gateway de salida y entrada.

    Por ejemplo, si un proyecto y una región contienen egress-gateway-X y egress-gateway-Y, todos los agentes de ese proyecto y región deben configurarse para usar la misma puerta de enlace para el tráfico de salida. Es decir, todos los agentes usan egress-gateway-X o todos usan egress-gateway-Y. No puedes configurar agent-A para que use egress-gateway-X y agent-B para que use egress-gateway-Y.

    Esta misma regla de vinculación también se aplica a las puertas de enlace de entrada dentro de un proyecto y una región.

  • El servicio de detección de amenazas de Agent Engine de Security Command Center no está disponible cuando Agent Gateway está habilitado para un agente.

  • En el modo de cliente a agente (entrada), Agent Gateway solo puede controlar los métodos query y streamQuery de Agent Runtime. Para proteger otros métodos no admitidos (como asyncQuery), puedes aplicar plantillas de Model Armor directamente desde tu aplicación o agente. Consulta Cómo limpiar instrucciones y respuestas o este codelab sobre cómo crear un sistema de agentes seguro con Model Armor.

Enruta el tráfico de Agent Runtime a través de Agent Gateway

Para enrutar el tráfico de Agent Runtime a través de Agent Gateway, sigue estos pasos:

  1. Crea un recurso de Agent Gateway y adjunta las políticas de autorización que sean necesarias. Puedes crear una puerta de enlace en el modo Agent-to-Anywhere (salida) o Client-to-Agent (entrada). Ten en cuenta que el agente y la puerta de enlace deben crearse en el mismo proyecto y región. Para obtener instrucciones, consulta Configura Agent Gateway.

    Asegúrate de que la puerta de enlace esté configurada para satisfacer las necesidades de tu implementación. Por ejemplo, si tu agente requiere acceso al LLM, configura la puerta de enlace para permitir este acceso y evitar posibles fallas en la implementación del entorno de ejecución del agente.

  2. Configura tu agente para que enrute el tráfico a través de Agent Gateway.

    • Para agentes nuevos

      Especifica el recurso de puerta de enlace cuando implementes tu agente. Por ejemplo, para implementar el agente en Agent Runtime, usa client.agent_engines.create para pasar el objeto local_agent junto con cualquier configuración opcional.

      Si quieres usar funciones de la plataforma mediadas por la puerta de enlace, como Model Armor o políticas de gobernanza semántica, con este agente, establece agent_gateway_config y identity_type=AGENT_IDENTITY en la llamada de creación, como se muestra en este ejemplo. Sin identity_type=AGENT_IDENTITY, el effectiveIdentity de la instancia de ejecución recurre a la cuenta de servicio predeterminada de Vertex AI, y las políticas de Gobernanza semántica filtran de forma silenciosa al agente del selector de creación de políticas.

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

      Reemplaza AGENT_GATEWAY_TO_ANYWHERE_NAME por el nombre de la puerta de enlace del agente que creaste en el modo Agent-to-Anywhere (salida).

      Si creaste una puerta de enlace en modo de cliente a agente (entrada), usa el campo client_to_agent_config y reemplaza AGENT_GATEWAY_CLIENT_TO_AGENT_NAME por el nombre de la puerta de enlace del agente que creaste para la entrada.

    • Para agentes existentes

      Del agente a cualquier lugar

      Usa la siguiente solicitud de la API de REST para asociar un agente existente con una puerta de enlace de Agent-to-Anywhere para la salida.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "agentToAnywhereConfig": {
          "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el ID del proyecto.
      • REGION: Es la región en la que se implementa el agente.
      • AGENT_GATEWAY_TO_ANYWHERE_NAME: Es el nombre de la puerta de enlace del agente que creaste en el modo Agent-to-Anywhere (salida).
      • RESOURCE_ID: Es el ID del recurso del agente.

      De cliente a agente

      Usa la siguiente solicitud de la API de REST para asociar un agente existente con una puerta de enlace de cliente a agente para la entrada.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "clientToAgentConfig": {
          "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el ID del proyecto.
      • REGION: Es la región en la que se implementa el agente.
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: Es el nombre de la puerta de enlace del agente que creaste en Client-to-Agent (entrada).
      • RESOURCE_ID: Es el ID del recurso del agente.

  3. Regístrate en la instancia de Agent Registry en el mismo proyecto y región que el agente y la puerta de enlace.

    gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es el nombre que deseas asignarle a tu recurso, por ejemplo, allow-aiplatform-region-eu3.
    • PROJECT_ID: El ID del proyecto
    • REGION: Es la región del registro.
    • DISPLAY_NAME: Es el nombre legible del extremo.

    Para obtener más información, consulta Cómo registrar un agente.

  4. Crea una vinculación de política de IAM del agente al registro para el agente.

    gcloud iap web add-iam-policy-binding \
  --resource-type=agent-registry \
  --endpoint=ENDPOINT_ID \
  --region=REGION \
  --project=PROJECT_ID \
  --member=MEMBER \
  --role=roles/iap.egressor

    Reemplaza lo siguiente:

    • ENDPOINT_ID: Es el ID del extremo de servicio del agente registrado. Obtienes este valor del resultado del paso anterior.

    • MEMBER: Es el principal de identidad del agente al que se le otorgará el rol. El formato suele ser principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

  5. En este punto, el tráfico de tu agente se dirigirá a través de Agent Gateway. Sin embargo, Agent Gateway adopta una política de denegación predeterminada. Para habilitar ciertas funciones de Agent Platform, debes asegurarte de que el agente pueda comunicarse con los siguientes extremos:

    • Si Cloud Trace está habilitado, Agent Gateway debe permitir el tráfico al extremo https://telemetry.googleapis.com/.

      Si se configuran las variables de entorno GOOGLE_API_USE_CLIENT_CERTIFICATE y GOOGLE_API_USE_MTLS_ENDPOINT, asegúrate de que también se permita el tráfico a https://telemetry.mtls.googleapis.com/.

    • Si Cloud Logging está habilitado, Agent Gateway debe permitir el tráfico al extremo https://logging.googleapis.com/.

      Si se configuran las variables de entorno GOOGLE_API_USE_CLIENT_CERTIFICATE y GOOGLE_API_USE_MTLS_ENDPOINT, asegúrate de que también se permita el tráfico a https://logging.mtls.googleapis.com/.

    Además, si tus agentes llaman a LLMs o usan funciones como Sessions y Memory Bank, debes asegurarte de que los agentes puedan comunicarse con los endpoints que usan estos servicios. Por ejemplo:

    • Para las sesiones: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
    • Para Memory Bank: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

    Por motivos de seguridad, te recomendamos que registres y agregues a la lista de entidades permitidas solo los URIs específicos a los que accede el agente. Dado que la puerta de enlace coincide directamente con los nombres de host, debes asegurarte de registrar todas las variantes que usa el SDK del agente. Por ejemplo, según la versión del SDK, la configuración regional del cliente o el uso de mTLS, una API de Google puede resolverse a través de los siguientes nombres de host de extremos:

    • https://REGION-aiplatform.googleapis.com
    • https://REGION-aiplatform.mtls.googleapis.com
    • https://aiplatform.REGION.rep.googleapis.com

    Para obtener información sobre cómo registrar extremos, consulta Cómo registrar extremos. También debes asegurarte de que el agente tenga el rol de IAP Egressor para estos extremos. Para obtener instrucciones, consulta Crea una política de salida de agente a extremo.

  6. Verifica la configuración del agente.

    Console

    1. En la consola de Google Cloud , ve a la página Implementaciones de la Plataforma de agentes.

      Ir a Implementaciones

    2. Haz clic en el nombre del agente que implementaste.

    3. Haz clic en Configuración del servicio. Se abrirá el panel Observabilidad del agente.

    4. Haz clic en Detalles de la implementación. Las configuraciones de entrada y salida de la puerta de enlace de agente están disponibles en el campo Deployment spec.

    gcloud

    Usa la siguiente solicitud de la API de REST para validar que el agente ahora esté asociado con la puerta de enlace. Si el resultado que se muestra es null, significa que el tiempo de ejecución no pudo vincularse a la puerta de enlace.

    curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto.
    • REGION: Es la región en la que se implementa el agente.
    • RESOURCE_ID: Es el ID del recurso del agente.

Restringe Agent Runtime a las puertas de enlace de agentes aprobadas

Puedes crear restricciones de políticas de la organización personalizadas para definir el conjunto de recursos aptos de Agent Gateway que se pueden usar durante la implementación de agentes.

Crea restricciones personalizadas para las políticas de la organización

En este ejemplo, se crean restricciones personalizadas que solo permiten el tráfico hacia y desde una lista de puertas de enlace aprobadas previamente.

Del agente a cualquier lugar

  1. Para definir una restricción personalizada para el modo Agent-to-Anywhere (salida), crea un archivo llamado constraint-agent-gateway-egress.yaml.

    En el siguiente ejemplo, el campo condition especifica que la operación solo se permite si se especifica un recurso de Agent Gateway (el campo está presente y no está vacío) y si la puerta de enlace especificada está en la lista de aprobación previa.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es el ID de tu organización.
    • AGENT_PROJECT_ID: el ID de tu proyecto
    • REGION: Es la región en la que se creó la puerta de enlace.
    • AGENT_GATEWAY_ID: Es el ID de tu puerta de enlace.

  2. Aplica la restricción personalizada.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Reemplaza EGRESS_CONSTRAINT_PATH por la ruta de acceso completa al archivo de restricción personalizado que creaste en el paso anterior.

  3. Crea la política de la organización para aplicar la restricción. Para definir la política de la organización, crea un archivo YAML de política llamado policy-agent-gateway-egress.yaml. En este ejemplo, aplicamos esta restricción a nivel del proyecto, pero también puedes configurarla a nivel de la organización o de la carpeta.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Reemplaza AGENT_PROJECT_ID con el ID del proyecto.

  4. Aplica la política de la organización.

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    Reemplaza EGRESS_POLICY_PATH por la ruta de acceso completa al archivo YAML de la política de la organización que creaste en el paso anterior. La política tarda hasta 15 minutos en aplicarse.

De cliente a agente

  1. Para definir una restricción personalizada para el modo Cliente a agente (entrada), crea un archivo llamado constraint-agent-gateway-ingress.yaml.

    En el siguiente ejemplo, el campo condition especifica que la operación solo se permite si se especifica un recurso de Agent Gateway (el campo está presente y no está vacío) y si la puerta de enlace especificada está en la lista de aprobación previa.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es el ID de tu organización.
    • AGENT_PROJECT_ID: el ID de tu proyecto
    • REGION: Es la región en la que se creó la puerta de enlace.
    • AGENT_GATEWAY_ID: Es el ID de tu puerta de enlace.

  2. Aplica la restricción personalizada.

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Reemplaza INGRESS_CONSTRAINT_PATH por la ruta de acceso completa al archivo de restricción personalizado que creaste en el paso anterior.

  3. Crea la política de la organización para aplicar la restricción. Para definir la política de la organización, crea un archivo YAML de política llamado policy-agent-gateway-ingress.yaml. En este ejemplo, aplicamos esta restricción a nivel del proyecto, pero también puedes configurarla a nivel de la organización o de la carpeta.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Reemplaza AGENT_PROJECT_ID con el ID del proyecto.

  4. Aplica la política de la organización.

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    Reemplaza INGRESS_POLICY_PATH por la ruta de acceso completa al archivo YAML de la política de la organización que creaste en el paso anterior. La política tarda hasta 15 minutos en aplicarse.

Para obtener más información sobre cómo usar restricciones personalizadas de políticas de la organización, consulta Crea restricciones personalizadas.

¿Qué sigue?

Codelab

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

Guía

Obtén más información para delegar la autorización de Agent Gateway a IAP, Model Armor o tu propio servicio de autorización personalizado.

Guía

Obtén más información para supervisar Agent Gateway.

Solución de problemas

Obtén más información para solucionar problemas de conectividad de Agent Gateway.