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

En esta página, se describe cómo enrutar el tráfico de Gemini Enterprise 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 ocurran entre usuarios y agentes, agentes y herramientas, o entre los propios agentes.

Antes de comenzar

• Asegúrate de conocer los conceptos de Gemini Enterprise.
• Obtén más información sobre Agent Gateway. Ten en cuenta que Agent Gateway solo admite Gemini Enterprise en el modo de agente a cualquier lugar (salida). No se admite el tráfico de entrada.
• Implementar una app de Gemini Enterprise (también conocida como motor) En el procedimiento de esta página, se da por sentado que ya tienes una app implementada. Para obtener más información, consulta Crea una app.

Planifica tus asignaciones de ubicación y del registro de agentes

Antes de implementar Agent Gateway, elige la región en la que implementarás la puerta de enlace y el Agent Registry en el que registrarás tus recursos. Ten en cuenta los siguientes requisitos:

• Asignación de ubicación: Implementa la Agent Gateway en la región específica que corresponda a la ubicación de tu app de Gemini Enterprise para garantizar un enrutamiento adecuado.

• Asignación de registros: Asocia tu Agent Gateway con la instancia regional de Agent Registry en el mismo proyecto y región que la puerta de enlace. Consulta Planifica la implementación de Agent Gateway para obtener más orientación sobre los patrones de implementación.

Tabla: Ubicación de la app de Gemini Enterprise y asignaciones de Agent Registry

Ubicación de la app de Gemini Enterprise	Región de Agent Gateway obligatoria	Instancia de Agent Registry obligatoria para Agent Gateway
global	us-central1	us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
us	us-central1	us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
eu	europe-west1	europe-west1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/europe-west1)

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

Importante: Habilitar Agent Gateway enruta todo el tráfico de Gemini Enterprise, incluidas las llamadas a LLM, a través de la puerta de enlace. Luego, puedes proteger este tráfico con políticas de autorización.

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

1. Crea un recurso de Agent Gateway y asegúrate de cumplir con la región y el registro que seleccionaste en la sección anterior. Para obtener instrucciones, consulta Configura Agent Gateway.

   Verifica la configuración de la puerta de enlace. Usa la API de Network Services para recuperar la configuración de tu Agent Gateway y, luego, inspecciona los parámetros de configuración.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
   

   A continuación, se muestra un resultado de ejemplo para una puerta de enlace configurada de forma correcta:

   {
     "name": "projects/my-ge-project/locations/us-central1/agentGateways/my-egress-gateway",
     "description": "A full configuration for Agent Gateway for Gemini Enterprise egress",
     "googleManaged": {
       "governedAccessPath": "AGENT_TO_ANYWHERE"
     },
     "protocols": [
       "MCP"
     ],
     "registries": [
       "//agentregistry.googleapis.com/projects/my-ge-project/locations/us-central1"
     ]
   }
   

2. Vincula la puerta de enlace a tu app de Gemini Enterprise con la API de UpdateEngine. Ten en cuenta que, cuando completes este paso, todo el tráfico existente del agente se enrutará de inmediato a través de la Agent Gateway especificada.

   Console

   1. En la consola de Google Cloud , ve a la página Gemini Enterprise.

      Gemini Enterprise

   2. Haz clic en el nombre de la app que quieres asociar con un Agent Gateway.

   3. Haz clic en Seguridad.

   4. En la pestaña Configuración, en Configuración de Agent Gateway, ingresa el nombre completo del recurso de la puerta de enlace. Usa el formato: projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME.

   5. Haz clic en Guardar.

   REST

   1. Usa la siguiente solicitud para actualizar tu app.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -d '{
        "agentGatewaySetting": {
          "defaultEgressAgentGateway": {
            "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
          }
        }
      }' \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name"

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el ID del proyecto.
      • AGENT_GATEWAY_REGION: Es la región del Agent Gateway.
      • AGENT_GATEWAY_NAME: Es el nombre del Agent Gateway.
      • ENDPOINT_LOCATION: Es el prefijo multirregional para el extremo de API que coincide con GE_APP_LOCATION. Especifica global, us o eu. Por ejemplo, las apps de eu usan eu-discoveryengine.googleapis.com. En el caso de las apps de global, también se admite discoveryengine.googleapis.com sin prefijo.
      • PROJECT_NUMBER: Número del proyecto
      • GE_APP_LOCATION: Es la ubicación de la app de Gemini Enterprise. Especifica global, us o eu.
      • GE_APP_ID: Es el ID de la app de Gemini Enterprise.

   2. Para verificar la configuración de la app, usa el siguiente comando para recuperar tu configuración y, luego, inspecciona los parámetros:

      curl -s -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      -H "Content-Type: application/json" \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID" \
      | jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'
      

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el ID del proyecto.
      • ENDPOINT_LOCATION: Es el prefijo multirregional para el extremo de API que coincide con GE_APP_LOCATION. Especifica global, us o eu.
      • PROJECT_NUMBER: Número del proyecto
      • GE_APP_LOCATION: Es la ubicación de la app de Gemini Enterprise. Especifica global, us o eu.
      • GE_APP_ID: Es el ID de la app de Gemini Enterprise.

      A continuación, se muestra un ejemplo de resultado para una app configurada correctamente:

      {
      "name": "projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID",
      "displayName": "GE_APP_ID",
      "agentGatewaySetting": {
        "defaultEgressAgentGateway": {
          "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
        }
      }
      }
      

3. Si bien la administración de salida ahora está habilitada para tu app de Gemini Enterprise, esta no sabe automáticamente con qué recursos externos del registro de agentes puede interactuar.

   Debes importar de forma explícita los agentes, los endpoints y los servidores de MCP elegidos a tu app de Gemini Enterprise. Se debe hacer referencia al recurso importado con su nombre de recurso exacto basado en el registro. Para obtener instrucciones, consulta las siguientes guías:

   • Importa servidores de MCP desde Agent Registry
   • Importa agentes A2A desde Agent Registry.

4. Para verificar que la salida funcione correctamente, sigue estos pasos:

   1. Abre la aplicación web de Gemini Enterprise.
   2. Envía una consulta diseñada para activar una herramienta externa (por ejemplo, "Dame una lista de los problemas recientes de GitHub").
   3. Supervisa la ejecución para asegurarte de que la respuesta se recupere correctamente. Tras bambalinas, el agente de Gemini Enterprise empaqueta la solicitud, la enruta a través de tu Agent Gateway (que aplica las políticas de autorización configuradas) y recupera la respuesta del destino.

Restringe la vinculación de Gemini Enterprise a los Agent Gateways aprobados

Puedes crear restricciones de políticas de la organización personalizadas para limitar si una app de Gemini Enterprise puede vincularse a algunas o todas las Agent Gateways.

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

En este ejemplo, se crea una restricción personalizada que bloquea todas las vinculaciones entre las apps de Gemini Enterprise y los Agent Gateways.

Del agente a cualquier lugar

1. Para definir una restricción personalizada para el modo de agente a cualquier lugar (salida), crea un archivo llamado constraint-agent-gateway-egress.yaml.

   En el siguiente ejemplo, se muestra cómo aplicar un aislamiento de red estricto inhabilitando cualquier vinculación. El campo condition especifica que la operación se rechaza si se especifica un recurso de Agent Gateway (el campo está presente y no está vacío).

   name: organizations/ORGANIZATION_ID/customConstraints/custom.disallowGeminiEnterpriseAgentGatewayBinding
   resource_types:
   
   
   
   discoveryengine.googleapis.com/Engine
   condition: >-
   has(resource.agentGatewaySetting.defaultEgressAgentGateway.name) &&
   resource.agentGatewaySetting.defaultEgressAgentGateway.name != ''
   actionType: DENY
   displayName: "Disallow all Agent Gateway Bindings for Discovery Engines"
   description: "To enforce strict network isolation, Discovery Engines are not permitted to bind to any Agent Gateway."

Reemplaza lo siguiente:

• ORGANIZATION_ID: Es el ID de tu organización.
• PROJECT_ID: Es el ID del proyecto.
• REGION: Es la región en la que se creó la puerta de enlace.
• AGENT_GATEWAY_NAME: Es el nombre 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 personalizada creado 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/PROJECT_ID/policies/custom.disallowGeminiEnterpriseAgentGatewayBinding
   spec:
   rules:
   
   
   
   enforce: true

Reemplaza 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 creado en el paso anterior. La política tarda hasta 15 minutos en aplicarse.

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

¿Qué sigue?

Codelab

Codelab: Administra cargas de trabajo de agentes con Agent Platform

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

Guía

Delega la autorización para Agent Gateway

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

Guía

Supervisa Agent Gateway

Aprende a supervisar Agent Gateway.

Solución de problemas

Soluciona problemas de Agent Gateway

Aprender a solucionar problemas de conectividad de Agent Gateway