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 agentes mismos.
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
- Un Agent Gateway no se puede vincular a los motores de razonamiento de 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-Xyegress-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 usanegress-gateway-Xo todos los agentes usanegress-gateway-Y. No puedes configuraragent-Apara que useegress-gateway-Xyagent-Bpara que useegress-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
queryystreamQueryde Agent Runtime. Para proteger otros métodos no admitidos (comoasyncQuery), 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.Los Controles del servicio de VPC no son compatibles con Agent Gateway.
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 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.
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.createpara pasar el objetolocal_agentjunto 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_configyidentity_type=AGENT_IDENTITYen la llamada de creación, como se muestra en este ejemplo. Sinidentity_type=AGENT_IDENTITY, eleffectiveIdentityde 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_NAMEpor el nombre del Agent Gateway 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_configy reemplazaAGENT_GATEWAY_CLIENT_TO_AGENT_NAMEpor el nombre del Agent Gateway que creaste para la entrada.Para agentes existentes
Del agente a cualquier lugar
Usa la siguiente solicitud a 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 del Agent Gateway 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 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: 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 del Agent Gateway que creaste en Client-to-Agent (entrada).RESOURCE_ID: Es el ID del 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: Es el nombre que deseas asignarle a tu recurso, por ejemplo,allow-aiplatform-region-eu3.PROJECT_ID: El ID del proyectoREGION: 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.
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 serprincipal://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 configuran 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 configuran 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 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.comhttps://REGION-aiplatform.mtls.googleapis.comhttps://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.
Verifica la configuración del agente.
Console
- En la Google Cloud consola, ve a la página Implementaciones de la 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 del Agent Gateway están disponibles en el campo Deployment spec.
gcloud
Usa la siguiente solicitud a la API de REST para validar que el agente ahora esté asociado a 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.
- En la Google Cloud consola, ve a la página Implementaciones de la Agent Platform.
Configura agentes de contenedores personalizados (BYOC) para Agent Gateway
Si deseas enrutar el tráfico saliente a través de un Agent Gateway de Agent-to-Anywhere (salida) para un agente implementado con una imagen de contenedor personalizada (Bring Your Own Container / 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.
Dado que Agent Gateway realiza la inspección y el descifrado 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. En el caso de 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 de clientes 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 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 puerta de enlace de Agent de salidaREGION: Es la región en la que se implementa la puerta de enlace.PROJECT_ID: Es 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 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 tu Agent Gateway en la 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 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
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
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 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.
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.
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_IDcon 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.
De cliente a agente
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
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 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.
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.
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_IDcon 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 de políticas de la organización, consulta Crea restricciones personalizadas.
¿Qué sigue?
Codelab: Govern agentic workloads with Agent Platform
Aprende a controlar las cargas de trabajo de agentes con Agent Gateway en Gemini Enterprise Agent Platform.
Delega la autorización para Agent Gateway
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.
Soluciona problemas de Agent Gateway
Obtén más información para solucionar problemas de conectividad de Agent Gateway.