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 estar familiarizado con 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. Usa 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 entorno de ejecución 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.

• Revisa las limitaciones asociadas con las implementaciones de entornos de ejecución que están asociadas 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:

1. Crea el Agent Gateway

   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 de agente a cualquier lugar (salida) o de cliente a agente (entrada).

   • Para el modo de cliente a agente (entrada), el agente y la puerta de enlace deben crearse en el mismo proyecto y región.
   • Para el modo de agente a cualquier lugar (salida), la puerta de enlace se puede crear en un proyecto diferente al del agente, pero se debe crear en la misma región. Ten en cuenta que los registros de Agent Registry y las vinculaciones de políticas de IAM asociados deben crearse en el mismo proyecto que Agent Gateway.

   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 de Agent Runtime.

2. Opcional: Configura el acceso a la puerta de enlace de salida entre proyectos

   Si tu puerta de enlace de agente a cualquier lugar (salida) se encuentra en un proyecto diferente al de tu agente de entorno de ejecución, realiza los siguientes pasos para otorgar al agente de servicio de entorno de ejecución acceso al proyecto de la puerta de enlace de salida:

   gcloud

   1. Crea un rol de IAM personalizado en el proyecto de Agent Gateway:

   gcloud iam roles create ar_agw_cross_project_sa \
       --project=AGENT_GATEWAY_PROJECT_ID \
       --title="Runtime Agent Gateway Cross-Project SA" \
       --description="Custom role for the cross-project service agent to access Agent Gateway" \
       --permissions="networkservices.agentGateways.get,networkservices.operations.get"

   Reemplaza AGENT_GATEWAY_PROJECT_ID por el ID del proyecto en el que se implementa el Agent Gateway.

   1. Asigna el rol personalizado en el proyecto de puerta de enlace al agente de servicio de Agent Runtime del proyecto de agente:

   gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
       --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
       --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

   Reemplaza AGENT_RUNTIME_PROJECT_NUMBER por el número del proyecto en el que se implementa el agente de Runtime.

   Terraform

   Para otorgar acceso entre proyectos desde varios proyectos de carga de trabajo de Runtime a un proyecto central de Agent Gateway de forma declarativa, crea el rol de IAM personalizado en el proyecto de puerta de enlace central y otórgalo al agente de servicio de Runtime de cada proyecto de carga de trabajo:

   variable "runtime_project_numbers" {
     type        = set(string)
     description = "Project numbers hosting cross-project Agent Runtime workloads"
     default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
   }
   
   resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     role_id     = "ar_agw_cross_project_sa"
     title       = "Runtime Agent Gateway Cross-Project SA"
     description = "Custom role for cross-project service agents to access Agent Gateway"
     permissions = [
       "networkservices.agentGateways.get",
       "networkservices.operations.get",
     ]
   }
   
   resource "google_project_iam_member" "ar_agw_cross_project_binding" {
     for_each = var.runtime_project_numbers
   
     project = "AGENT_GATEWAY_PROJECT_ID"
     role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
     member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com"
   }
   

3. Configura tu agente para enrutar el tráfico a través de Agent Gateway

   Según si implementas un agente nuevo o configuras uno existente, elige una de las siguientes opciones:

   • Para agentes nuevos que usan el SDK de Python

     Especifica el recurso de puerta de enlace mientras implementas tu agente. Por ejemplo, para implementar el agente en Agent Runtime, usa client.runtimes.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ánticas con este agente, establece agent_gateway_config y identity_type=AGENT_IDENTITY en la llamada de creación, como se muestra en este ejemplo. El backend aplica identity_type = "AGENT_IDENTITY" a nivel de API cada vez que se especifica agent_gateway_config, lo que hace que la validación de la implementación falle si se omite o se configura de forma incorrecta la identidad de la instancia de Runtime.

     Del agente a cualquier lugar

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_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 lo siguiente:

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

     De cliente a agente

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "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 lo siguiente:

     • PROJECT_ID: Es el ID del proyecto en el que se implementan el agente y la puerta de enlace.
     • REGION: la región en la que se implementan el agente y la puerta de enlace
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: Es el nombre de el Agent Gateway que creaste en el modo de cliente a agente (entrada).

   • Para agentes nuevos que usan Terraform

     Cuando aprovisiones tu agente con Terraform, usa el proveedor google-beta y configura el bloque agent_gateway_config dentro del recurso google_vertex_ai_reasoning_engine. Para obtener detalles sobre la configuración de Terraform, consulta Aprovisiona agentes con Terraform.

     Del agente a cualquier lugar

     Usa la siguiente configuración de Terraform para asociar un agente con una puerta de enlace de Agent-to-Anywhere para la salida.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "AGENT_RUNTIME_PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           agent_to_anywhere_config {
             agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
           }
         }
       }
     }
     }

     Reemplaza lo siguiente:

     • AGENT_RUNTIME_PROJECT_ID: Es el ID del proyecto en el que se implementa el agente.
     • REGION: la región en la que se implementan el agente y la puerta de enlace
     • AGENT_DISPLAY_NAME: Es el nombre visible de tu agente.
     • AGENT_DESCRIPTION: Es una descripción de tu agente.
     • REPOSITORY: Es el repositorio de Artifact Registry que contiene tu imagen de contenedor.
     • IMAGE: Es el nombre de la imagen de contenedor.
     • TAG: la etiqueta de la imagen de contenedor
     • AGENT_GATEWAY_PROJECT_ID: Es el ID del proyecto en el que se implementa el Agent Gateway.
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: Es el nombre de el Agent Gateway que creaste en el modo Agent-to-Anywhere (salida).

     De cliente a agente

     Usa la siguiente configuración de Terraform para asociar un agente con una puerta de enlace de cliente a agente para la entrada.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           client_to_agent_config {
             agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
           }
         }
       }
     }
     }

     Reemplaza lo siguiente:

     • PROJECT_ID: Es el ID del proyecto en el que se implementan el agente y la puerta de enlace.
     • REGION: la región en la que se implementan el agente y la puerta de enlace
     • AGENT_DISPLAY_NAME: Es el nombre visible de tu agente.
     • AGENT_DESCRIPTION: Es una descripción de tu agente.
     • REPOSITORY: Es el repositorio de Artifact Registry que contiene tu imagen de contenedor.
     • IMAGE: Es el nombre de la imagen de contenedor.
     • TAG: la etiqueta de la imagen de contenedor
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: Es el nombre de la Agent Gateway que creaste en el modo de cliente a agente (entrada).

   • Para agentes existentes que usan la API de REST

     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 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/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
             }
           }
         }
       }
     }' \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

     Reemplaza lo siguiente:

     • AGENT_GATEWAY_PROJECT_ID: Es el ID del proyecto en el que se implementa la puerta de enlace.
     • AGENT_RUNTIME_PROJECT_ID: Es el ID del proyecto en el que se implementa el agente.
     • REGION: la región en la que se implementan el agente y la puerta de enlace
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: Es el nombre de el 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/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

     Reemplaza lo siguiente:

     • PROJECT_ID: Es el ID del proyecto en el que se implementan el agente y la puerta de enlace.
     • REGION: la región en la que se implementan el agente y la puerta de enlace
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: Es el nombre de la Agent Gateway que creaste en De cliente a Agent (entrada).
     • RESOURCE_ID: Es el ID del recurso del agente.

4. Registra el agente en Agent Registry

   Asegúrate de que el agente esté registrado en la instancia de Agent Registry en el mismo proyecto y la misma región que Agent Gateway.

   gcloud

   gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --location=REGION \
    --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
    --format="value(registryResource)"
   

   Reemplaza lo siguiente:

   • RUNTIME_AGENT_SERVICE_NAME: Es el nombre que deseas darle a la entrada del agente en el registro.
   • AGENT_GATEWAY_PROJECT_ID: Es el ID del proyecto en el que se implementa la puerta de enlace.
   • REGION: la región en la que se implementan el agente y la puerta de enlace
   • RUNTIME_AGENT_DISPLAY_NAME: Es el nombre visible legible por humanos de la entrada del agente en el registro.
   • RUNTIME_AGENT_PROJECT_NUMBER: Es el número del proyecto en el que se implementa el agente de entorno de ejecución.
   • ENGINE_ID: Es el ID del recurso del agente.

   Terraform

   resource "google_agent_registry_service" "runtime_agent_entry" {
     project      = "AGENT_GATEWAY_PROJECT_ID"
     location     = "REGION"
     service_id   = "RUNTIME_AGENT_SERVICE_NAME"
     display_name = "RUNTIME_AGENT_DISPLAY_NAME"
   
     endpoint_spec {
       no_spec {}
     }
   
     interfaces {
       url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
       protocol_binding = "jsonrpc"
     }
   }
   

   Para obtener más información, consulta Registra agentes. Para obtener información sobre el registro manual de agentes en configuraciones de varios proyectos, consulta Registra un agente desde otro proyecto.

5. Crea una vinculación de política de IAM de agente a registro

   Realiza este paso en el mismo proyecto y la misma región que el Agent Gateway.

   gcloud

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

   Terraform

   resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     location    = "REGION"
     endpoint_id = "AGENT_ENDPOINT_ID"
     role        = "roles/iap.egressor"
     member      = "MEMBER"
   }
   

   Reemplaza lo siguiente:

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

   • MEMBER: Es la principal de identidad del agente a la que se le otorgará el rol. El formato de un motor de razonamiento individual es el siguiente: principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID.

     Si deseas otorgar acceso de salida a todos los agentes de un proyecto o de toda la organización en lugar de vincular instancias individuales, puedes vincular la política de IAM a un conjunto de principales:

     • Para otorgar acceso a todos los agentes de un proyecto, haz lo siguiente: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
     • Para otorgar acceso a todos los agentes de la organización, haz lo siguiente: principalSet://TRUST_DOMAIN/*

     En estas cadenas de principales, TRUST_DOMAIN suele ser agents.global.org-ORGANIZATION_ID.system.id.goog.

6. Agrega las APIs esenciales a la lista de entidades permitidas para las operaciones de entorno de ejecución

   En este punto, el tráfico de tu agente se dirige 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:

   La coincidencia de nombres de host en Agent Gateway es exacta. No se admiten comodines, como *.googleapis.com, ni formas de prefijo. Debes registrar cada variante de nombre de host estándar, regional y seguro (mTLS) que resuelva tu SDK de agente o aplicación cliente.

   Para habilitar ciertas funciones de Agent Platform y garantizar que la inicialización y la telemetría se realicen correctamente, debes permitir el tráfico a los siguientes extremos en el registro de agentes:

   Extremos esenciales de la plataforma

   En la siguiente tabla, se enumeran los endpoints de plataforma esenciales que tus agentes necesitan para las operaciones estándar, el registro de seguimiento, el registro y la resolución de metadatos:

   Nombre del servicio	Nombre de host estándar	Nombre de host de mTLS	Variantes regionales y de otro tipo
   Agent Registry	agentregistry.googleapis.com	—	—
   Cloud Logging	logging.googleapis.com	logging.mtls.googleapis.com	—
   Cloud Trace / telemetría	telemetry.googleapis.com	telemetry.mtls.googleapis.com	—
   API de Trace	cloudtrace.googleapis.com	cloudtrace.mtls.googleapis.com	—
   Cloud Monitoring	monitoring.googleapis.com	monitoring.mtls.googleapis.com	—
   Secret Manager	secretmanager.googleapis.com	secretmanager.mtls.googleapis.com	—
   Resource Manager	cloudresourcemanager.googleapis.com	cloudresourcemanager.mtls.googleapis.com	—
   Credenciales de IAM	iamcredentials.googleapis.com	iamcredentials.mtls.googleapis.com	—
   Agent Platform (aiplatform)	aiplatform.googleapis.com	aiplatform.mtls.googleapis.com	REGION-aiplatform.googleapis.com REGION-aiplatform.mtls.googleapis.com aiplatform.REGION.rep.googleapis.com

   Extremos específicos de funciones

   Además, si tus agentes usan funciones como Sesiones o Banco de memoria, debes asegurarte de que puedan comunicarse con los extremos específicos que usan estos servicios:

   • 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. Debido a que la puerta de enlace coincide con los nombres de host directamente, 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 se puede resolver 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 Registra extremos. Si tienes una configuración de varios proyectos, puedes registrar varios endpoints de API de Google centrales en un solo servicio de Agent Registry. Para obtener más información, consulta Registra un extremo de APIs de Google compuesto. También debes asegurarte de que el agente tenga el permiso iap.resources.egressViaIAP para estos endpoints. Para obtener instrucciones, consulta Crea una política de salida de agente a extremo.

7. Verifica la configuración del agente

   Console

   1. En la consola de Cloud de Confiance , ve a la página Implementaciones de Agent Platform.
      

      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. Los parámetros de configuración de entrada y salida de 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 con la puerta de enlace. Si el resultado que se muestra es null, significa que el entorno de ejecución no se pudo vincular a la puerta de enlace.

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

   Reemplaza lo siguiente:

   • AGENT_RUNTIME_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.

Configura agentes de contenedores personalizados (BYOC) para Agent Gateway

Si quieres enrutar el tráfico saliente a través de una Agent Gateway de agente a cualquier lugar (salida) para un agente implementado con una imagen de contenedor personalizada (Trae tu propio contenedor o BYOC), debes incorporar el certificado de la autoridad de certificación (AC) 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 la desencriptación y la inspección de TLS en las comunicaciones salientes de los agentes, las implementaciones de agentes que no son BYOC (basadas en fuentes) insertan automáticamente el certificado de la AC 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 AC del sistema dentro de tu Dockerfile y establecer las variables de entorno del paquete de certificados que requieren los SDK de Python, las bibliotecas cliente HTTP y gRPC.

Para configurar una imagen de contenedor de BYOC para la salida de Agent Gateway, sigue estos pasos:

1. 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.rootCertificates de 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/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
      | jq -r '.agentGatewayCard.rootCertificates[]'

   Reemplaza lo siguiente:

   • AGENT_GATEWAY_NAME: Es el nombre de tu Agent Gateway de salida.
   • REGION: la región en la que se implementa la puerta de enlace
   • AGENT_GATEWAY_PROJECT_ID: Es el ID del proyecto en el que se implementa la puerta de enlace.

2. Actualiza tu Dockerfile para que confíe en el certificado de la AC.

   Agrega el argumento de compilación AGENT_GATEWAY_ROOT_CERTIFICATES a tu Dockerfile. Los comandos de compilación dividen los certificados en archivos separados, los instalan con update-ca-certificates y configuran variables de entorno para que OpenSSL, las bibliotecas cliente HTTP de Python (requests, httpx) y gRPC reconozcan la AC 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

3. Usa Cloud Build para compilar la imagen de contenedor.

   Crea un archivo cloudbuild.yaml para 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_NAME y IMAGE_NAME por los nombres de tu repositorio y de la imagen de Artifact Registry.

4. Implementar tu agente alojado 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_config en spec.deploymentSpec o con llamadas de implementación del SDK).

Restringe Agent Runtime a las puertas de enlace de Agent Gateway aprobadas

Puedes crear restricciones de políticas de la organización personalizadas para definir el conjunto de recursos de Agent Gateway aptos que se pueden usar cuando se implementan 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 desde y hacia una lista de puertas de enlace aprobadas previamente.

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.

Limitaciones

• La administración entre proyectos tiene las siguientes limitaciones:

  • Las vinculaciones entre proyectos entre agentes y puertas de enlace solo se admiten en el modo de agente a cualquier lugar (salida). En el modo de cliente a agente (entrada), el agente y el Agent Gateway deben estar en el mismo proyecto.
  • Debes usar la API de REST o gcloud para configurar la administración entre proyectos de extremo a extremo. La consola de Cloud de Confiance Cloud de Confiance no admite la creación de vinculaciones de políticas de IAM entre proyectos ni entradas de Agent Registry.

• No se puede vincular un Agent Gateway a los motores de razonamiento de entorno 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 agente a cualquier lugar (salida) y de cliente a agente (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 esa región deben configurarse para usar la misma puerta de enlace para la salida. Es decir, todos los agentes usan egress-gateway-X o todos los agentes usan egress-gateway-Y. No puedes configurar agent-A para que use egress-gateway-X ni 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 compatibles (como asyncQuery), puedes aplicar plantillas de Model Armor directamente desde tu aplicación o agente. Consulta Limpia instrucciones y respuestas o este codelab sobre cómo crear un sistema de agentes seguro con Model Armor.

• Cambiar una vinculación de Agent Gateway en un agente de entorno de ejecución archiva cada revisión preexistente del agente. El archivado es irreversible. Consulta Agent Gateway y revisiones.

  Para actualizar un agente sin cambiar su ID de motor de razonamiento ni romper las vinculaciones de políticas, actualiza la instancia del agente in situ, como se describe en Actualiza una instancia de Agent Runtime.

¿Qué sigue?