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 ocurran entre usuarios y agentes, agentes y herramientas, o entre los agentes mismos.
Antes de comenzar
Asegúrate de estar familiarizado con la implementación de agentes en Agent Runtime.
Obtén información sobre Agent Gateway. Puedes usar Agent Gateway en el modo de agente a cualquier lugar (salida) para proteger y administrar todas las comunicaciones salientes con tráfico saliente a herramientas, modelos, APIs y otros agentes. Usas la puerta de enlace en el modo de 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 agente a cualquier lugar (salida) y a una puerta de enlace de cliente a agente (entrada) de forma simultánea.
Limitaciones
- No se puede vincular un Agent Gateway a los motores de razonamiento de Runtime creados antes del 29 de abril de 2026.
Si bien un solo proyecto y región pueden alojar varias instancias de Agent Gateway de agente a cualquier lugar (salida) y de cliente a agente (entrada), todos los agentes de Agent Runtime implementados dentro de 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-Xyegress-gateway-Y, todos los agentes de ese proyecto y región deben configurarse para usar la misma puerta de enlace para la salida. Es decir, todos los agentes usanegress-gateway-Xo todos los agentes usanegress-gateway-Y. No puedes configuraragent-Apara usaregress-gateway-Xyagent-Bpara usaregress-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 del motor de agentes 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 administrar los métodos
queryystreamQueryde Agent Runtime. Para proteger otros métodos no compatibles (comoasyncQuery), puedes aplicar plantillas de Model Armor directamente desde tu aplicación o agente. Consulta Desinfecta mensajes 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:
Crea un recurso de Agent Gateway y adjunta las políticas de autorización según sea necesario. Puedes crear una puerta de enlace en el modo de agente a cualquier lugar (salida) o en el modo de cliente a agente (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 a LLM, configura la puerta de enlace para permitir este acceso y evitar posibles fallas de implementación de Agent Runtime.
Configura tu agente para enrutar el tráfico a través de Agent Gateway.
Para agentes nuevos
Especifica el recurso de la puerta de enlace mientras implementas tu agente. Por ejemplo, para implementar el agente en Agent Runtime, usa
client.agent_engines.createpara pasar el objetolocal_agentjunto con cualquier configuración opcional.Si deseas usar funciones de la plataforma mediadas por la puerta de enlace, como Model Armor o las políticas de administración semántica con este agente, establece
agent_gateway_configyidentity_type=AGENT_IDENTITYen la llamada de creación, como se muestra en este ejemplo. Sinidentity_type=AGENT_IDENTITY,effectiveIdentityde la instancia de Runtime recurre a la cuenta de servicio predeterminada de Vertex AI, y las políticas de administración semántica filtran el agente de forma silenciosa 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_NAMEpor el nombre del Agent Gateway que creaste en el modo Agent-to-Anywhere (salida).Si creaste una puerta de enlace en el modo de cliente a agente (entrada), usa el campo
client_to_agent_configy reemplazaAGENT_GATEWAY_CLIENT_TO_AGENT_NAMEpor el nombre del Agent Gateway que creaste para la entrada.Para agentes existentes
Agente a cualquier lugar
Usa la siguiente solicitud a la API de REST para asociar un agente existente con una puerta de enlace de agente a cualquier lugar 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: El ID del proyectoREGION: La región en la que se implementa el agenteAGENT_GATEWAY_TO_ANYWHERE_NAME: El nombre del Agent Gateway que creaste en el modo Agent-to-Anywhere (salida)RESOURCE_ID: el ID de recurso del agente
Cliente a agente
Usa la siguiente solicitud a 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: El ID del proyectoREGION: La región en la que se implementa el agenteAGENT_GATEWAY_CLIENT_TO_AGENT_NAME: El nombre del Agent Gateway que creaste en el modo de cliente a agente (entrada)RESOURCE_ID: el ID de recurso del agente
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: El nombre que deseas asignar a tu recurso, por ejemplo,allow-aiplatform-region-eu3.PROJECT_ID: El ID del proyectoREGION: La región del registroDISPLAY_NAME: El nombre legible del extremo
Para obtener más información, consulta Registra un agente.
Crea una vinculación de política de IAM de agente a 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: El ID del extremo de servicio del agente registrado Lo obtienes del resultado del paso anterior.MEMBER: La principal de identidad del agente a la que se le otorgará el rol Por lo general, el formato es el siguiente:principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.
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 establecen las variables de entorno
GOOGLE_API_USE_CLIENT_CERTIFICATEyGOOGLE_API_USE_MTLS_ENDPOINT, asegúrate de que también se permita el tráfico ahttps://telemetry.mtls.googleapis.com/.Si Cloud Logging está habilitado, Agent Gateway debe permitir el tráfico al extremo
https://logging.googleapis.com/.Si se establecen las variables de entorno
GOOGLE_API_USE_CLIENT_CERTIFICATEyGOOGLE_API_USE_MTLS_ENDPOINT, asegúrate de que también se permita el tráfico ahttps://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 extremos que usan estos servicios. Por ejemplo:
- Para Sessions:
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. Debido a 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.comhttps://REGION-aiplatform.mtls.googleapis.comhttps://aiplatform.REGION.rep.googleapis.com
Para obtener información sobre cómo registrar extremos, consulta Registra 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 política.
Verifica la configuración de tu agente.
Console
- En la Google Cloud consola, ve a la página Implementaciones de Agent Platform.
Haz clic en el nombre del agente que implementaste.
Haz clic en Configuración del servicio. Se abrirá el panel Observabilidad del agente.
Haz clic en Detalles de la implementación. Las configuraciones de entrada y salida de Agent Gateway están disponibles en el campo Especificación de la implementación.
gcloud
Usa la siguiente solicitud a 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 Runtime 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: El ID del proyectoREGION: La región en la que se implementa el agenteRESOURCE_ID: el ID de recurso del agente
- En la Google Cloud consola, ve a la página Implementaciones de Agent Platform.
Configura agentes de contenedor personalizado (BYOC) para Agent Gateway
Si deseas enrutar el tráfico saliente a través de un Agent Gateway de agente a cualquier lugar (salida) para un agente implementado con una imagen de contenedor personalizada (Bring Your Own Container o BYOC), debes incorporar el certificado de la autoridad de certificación raíz de la puerta de enlace en el almacén de confianza de la imagen de contenedor personalizada.
Debido a que Agent Gateway realiza el desencriptado y la inspección de TLS en las comunicaciones salientes del agente, las implementaciones de agentes que no son BYOC (basadas en la fuente) insertan automáticamente el certificado de la CA durante la creación de la imagen. Para las imágenes de contenedor personalizadas, debes recuperar de forma explícita el certificado de la AC de la puerta de enlace, instalarlo en el almacén de confianza de la CA del sistema dentro de tu Dockerfile y establecer las variables de entorno del paquete de certificados que requieren los SDKs de Python, las bibliotecas cliente de HTTP y gRPC.
Para configurar una imagen de contenedor BYOC para la salida de Agent Gateway, sigue estos pasos:
Recupera los certificados raíz del recurso de Agent Gateway.
Exporta la cadena PEM del certificado raíz de la CA directamente desde el campo
agentGatewayCard.rootCertificatesde tu recurso de Agent Gateway:export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \ --location=REGION \ --project=PROJECT_ID \ --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")
Como alternativa, puedes usar la API de REST para recuperar el recurso de la puerta de enlace:
curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \ | jq -r '.agentGatewayCard.rootCertificates[]'
Reemplaza lo siguiente:
AGENT_GATEWAY_NAME: El nombre de tu Agent Gateway de salidaREGION: La región en la que se implementa la puerta de enlacePROJECT_ID: El ID del proyecto
Actualiza tu
Dockerfilepara confiar en el certificado de la AC.Agrega el argumento de compilación
AGENT_GATEWAY_ROOT_CERTIFICATESa tuDockerfile. Los comandos de compilación dividen los certificados en archivos separados, los instalan conupdate-ca-certificatesy establecen variables de entorno para que OpenSSL, las bibliotecas cliente de HTTP de Python (requests,httpx) y gRPC reconozcan la CA personalizada:# Install root certificates under root user USER root ARG AGENT_GATEWAY_ROOT_CERTIFICATES RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \ echo "Installing Agent Gateway root certificates..."; \ printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \ update-ca-certificates; \ fi # Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} # Switch back to application execution user USER 1000
Usa Cloud Build para compilar la imagen de contenedor.
Crea un archivo
cloudbuild.yamlpara pasar la cadena del certificado raíz a Cloud Build con sustituciones:steps: - name: 'gcr.io/cloud-builders/docker' args: - 'build' - '--build-arg' - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}' - '-t' - '$_IMAGE_URI' - '.' images: - '$_IMAGE_URI'Envía la compilación de la imagen de contenedor a Cloud Build:
export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest" gcloud builds submit \ --project=PROJECT_ID \ --region=REGION \ --config=cloudbuild.yaml \ --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \ .
Reemplaza
REPOSITORY_NAMEyIMAGE_NAMEpor los nombres de tu repositorio y tu imagen de Artifact Registry.Implementa tu agente en contenedores.
Especifica el URI de la imagen de contenedor compilada junto con la configuración de Agent Gateway en tu solicitud de implementación (con
agent_gateway_configenspec.deploymentSpeco con llamadas de implementación del SDK).
Restringe Agent Runtime a las puertas de enlace de agente aprobadas
Puedes crear restricciones personalizadas para las políticas de la organización para definir el conjunto de recursos de Agent Gateway aptos que se pueden usar mientras implementas 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.
Agente a cualquier lugar
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, el campo
conditionespecifica 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 aprobada previamente.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: Es el ID del 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.
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 que creaste en el paso anterior.
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: trueReemplaza
AGENT_PROJECT_IDpor el ID del proyecto.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.
Cliente a agente
Para definir una restricción personalizada para el modo de cliente a agente (entrada), crea un archivo llamado
constraint-agent-gateway-ingress.yaml.En el siguiente ejemplo, el campo
conditionespecifica 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 aprobada previamente.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: Es el ID del 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.
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 personalizada que creaste en el paso anterior.
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: trueReemplaza
AGENT_PROJECT_IDpor el ID del proyecto.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 para las políticas de la organización, consulta Crea restricciones personalizadas.
¿Qué sigue?
Codelab: Administra cargas de trabajo de agentes con Agent Platform
Obtén información para administrar cargas de trabajo de agentes con Agent Gateway en Gemini Enterprise Agent Platform.
Delega la autorización para Agent Gateway
Obtén información para delegar la autorización para Agent Gateway a IAP, Model Armor o tu propio servicio de autorización personalizado.
Soluciona problemas de Agent Gateway
Obtén información para solucionar problemas de conectividad de Agent Gateway.