Administra agentes con Agent Gateway

Agent Gateway te permite controlar el tráfico saliente de los agentes de IA que creas y alojas en Cloud Run. Enrutando el tráfico de salida de tu servicio de Cloud Run a través de una Agent Gateway autoadministrada que se ejecuta en Secure Web Proxy, puedes aplicar políticas de acceso centralizadas, inspeccionar las cargas útiles para verificar la seguridad del contenido y recopilar telemetría de observabilidad en tus cargas de trabajo de agentes.

En este documento, se describe cómo configurar una arquitectura centralizada para Agent Gateway en Cloud Run y se explica cómo hacer lo siguiente:

Arquitectura

En una implementación centralizada autoadministrada, Secure Web Proxy actúa como el punto de aplicación de políticas y se ejecuta dentro de tu red de nube privada virtual (VPC). El contenedor sidecar de Ambient Networking intercepta el tráfico saliente de tu agente de Cloud Run y lo enruta a través de la salida de VPC directa a tu instancia de Secure Web Proxy. Secure Web Proxy aplica reglas de acceso y contenido desde puntos de decisión basadas en políticas, como Identity-Aware Proxy (IAP) y Model Armor.

Diagrama de arquitectura que muestra un servicio de Cloud Run con un contenedor de agente y un contenedor de proxy de sidecar ambiental que enruta el tráfico a través de la salida de VPC directa a una Agent Gateway autoadministrada respaldada por Secure Web Proxy dentro de una red de VPC.
Figura 1: Arquitectura de Agent Gateway autoadministrada para un agente de Cloud Run.

Para enrutar y controlar el tráfico en esta arquitectura, configura los siguientes componentes:

  • Salida de VPC directa y Ambient Networking: Tu servicio de Cloud Run se conecta a tu red de VPC con --vpc-egress=all y --ambient-networking, que usa el permiso regional de forma predeterminada y enruta todo el tráfico saliente a tu red de VPC.
  • Agent Gateway autoadministrada: Un recurso lógico de Agent Gateway en modo autoadministrado apunta a la instancia de Secure Web Proxy en tu red de VPC.
  • Política de enrutamiento de salida: Una política EgressRouting de la API de Network Services dirige el tráfico saliente desde tu servicio de Cloud Run hasta tu instancia de Secure Web Proxy.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Habilita la API de Cloud Run Admin, la API de Network Services, la API de seguridad de redes, la API de Service Extensions, la API de Model Armor, la API de Certificate Authority Service, la API de Certificate Manager, la API de Cloud Resource Manager, la API de App Hub, la API de Identity and Access Management, la API de Identity-Aware Proxy, la API de Compute Engine, la API de Traffic Director, la API de Cloud DNS, la API de Network Connectivity y las APIs de Agent Registry, si aún no están habilitadas.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar las API

  13. Crea una red de VPC y una subred con el Acceso privado a Google habilitado en la subred.
  14. Configura Agent Registry en tu proyecto u organización.
  15. Instala y, luego, inicializa Google Cloud CLI.
  16. Actualiza los componentes de gcloud CLI: 
    gcloud components update

Roles obligatorios

Para obtener los permisos que necesitas para configurar Agent Gateway para Cloud Run, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Si configuras una implementación entre proyectos con una VPC compartida, pídele a tu administrador que te otorgue roles/compute.xpnAdmin a nivel de la organización o de la carpeta.

Crea una Agent Gateway autoadministrada

Antes de crear el recurso de Agent Gateway, implementa y configura una instancia de Secure Web Proxy en tu red de VPC como se describe en Implementa Secure Web Proxy como un Agent Gateway:

  1. Configura la inspección de TLS y crea una política de seguridad de puerta de enlace que adjunte tu TlsInspectionPolicy. No necesitas reglas de política de seguridad de Secure Web Proxy ni listas de URLs.
  2. Crea un recurso ServerTlsPolicy con allowOpen: false y mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. No establezcas clientValidationTrustConfig.
  3. Implementa una instancia de Secure Web Proxy en el modo de enrutamiento de proxy explícito con addresses, ports, certificateUrls, gatewaySecurityPolicy y serverTlsPolicy configurados cuando creas la puerta de enlace para que Cloud Run pase la Workload Identity de la carga de trabajo de tu agente a Secure Web Proxy y a IAP a través de mTLS.

Cuando la instancia de Secure Web Proxy esté lista, crea un recurso de Agent Gateway autoadministrado que apunte a tu instancia de Secure Web Proxy:

  1. Crea un archivo de configuración YAML llamado my-agent-gateway.yaml:

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    Reemplaza lo siguiente:

    • AGENT_GATEWAY_NAME: Es el nombre que deseas asignar a tu recurso de Agent Gateway.
    • PROJECT_ID: Es el ID del proyecto que aloja tu instancia de Secure Web Proxy.
    • REGION: Es la región de tu instancia de Secure Web Proxy, como us-central1.
    • SWP_NAME: Es el nombre de tu instancia de Secure Web Proxy.

  2. Importa la configuración de Agent Gateway:

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. Verifica tu recurso de Agent Gateway:

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    Confirma que el resultado muestre tu configuración de selfManaged y el URI del recurso de tu instancia de Secure Web Proxy antes de continuar con la siguiente sección.

Configura Ambient Networking de Cloud Run para acceder a la API de Traffic Director

Cuando configuras un servicio de Cloud Run con la salida de VPC directa y --vpc-egress=all, todas las conexiones salientes de la instancia de contenedor se enrutan a través de tu red de VPC. Esto incluye la conexión del archivo adicional de Envoy a trafficdirector.REGION.rep.googleapis.com.

Para permitir que el archivo de complemento resuelva y alcance la API de Traffic Director, configura una zona privada de Cloud DNS en tu red de VPC según si tu entorno usa Controles del servicio de VPC:

Sin Controles del servicio de VPC

Si tu proyecto no usa los Controles del servicio de VPC, crea una zona del DNS privada de Cloud DNS que enrute las solicitudes de trafficdirector.REGION.rep.googleapis.com a la dirección IP de la puerta de enlace de Secure Web Proxy para que Secure Web Proxy permita el paso del tráfico:

  1. Recupera la dirección IP interna de tu puerta de enlace de Secure Web Proxy:

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    Reemplaza lo siguiente:

    • SWP_NAME: Es el nombre de tu instancia de Secure Web Proxy.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION: Es la región de tu implementación.

  2. Crea una zona administrada privada de Cloud DNS para la API de Traffic Director:

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    Reemplaza VPC_NETWORK_NAME por el nombre de la red de VPC.

  3. Agrega un registro A que apunte el dominio regional de la API de Traffic Director a tu dirección IP de Secure Web Proxy:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. Verifica que el conjunto de registros DNS esté activo en la zona privada:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    Confirma que el registro A de trafficdirector.REGION.rep.googleapis.com. se resuelva en tu dirección IP de Secure Web Proxy.

Con los Controles del servicio de VPC

Para los entornos de Controles del servicio de VPC, aprovisiona un extremo regional de Private Service Connect que se oriente a la API de Traffic Director regional dentro de tu subred de VPC y asigna el dominio con una zona privada de Cloud DNS:

  1. Crea un extremo regional de Private Service Connect orientado a la API de Traffic Director regional:

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION: Es la región de tu implementación.
    • VPC_NETWORK_NAME: Es el nombre de tu red de VPC.
    • VPC_SUBNET_NAME: Es el nombre de tu subred de VPC.

  2. Recupera la dirección IP interna del extremo regional:

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Crea una zona administrada privada de Cloud DNS para la API de Traffic Director:

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Agrega un registro A que resuelva el dominio regional de la API de Traffic Director a la dirección IP del extremo regional:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. Verifica tu extremo regional y el conjunto de registros DNS:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    Confirma que el registro A de trafficdirector.REGION.rep.googleapis.com. apunte a la dirección IP del extremo regional.

Implementa o actualiza un servicio de Cloud Run con Ambient Networking y salida de VPC directa

Para conectar tu agente de Cloud Run a la instancia de Secure Web Proxy en tu red de VPC, habilita la salida de VPC directa y Ambient Networking regional, y configura el servicio con una Agent Identity. Cuando implementas con --functional-type=agent y --identity-type=agent-identity, Cloud Run otorga roles/run.agentDefaultAccess, que incluye los permisos roles/trafficdirector.client y roles/cloudtrace.agent:

  1. Implementa un nuevo servicio de agente de Cloud Run o actualiza un servicio existente para habilitar Ambient Networking regional, la salida de VPC directa para todo el tráfico saliente y Agent Identity:

    Servicio nuevo

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Servicio existente

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run.
    • IMAGE_URL: una referencia a la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • VPC_NETWORK_NAME: Es el nombre de la red de VPC que aloja tu instancia de Secure Web Proxy. Para obtener información sobre cómo crear una red y una subred de VPC, consulta Crea y administra redes de VPC.
    • VPC_SUBNET_NAME: Es el nombre de la subred de VPC en la que se puede acceder a tu instancia de Secure Web Proxy.
    • REGION: la región de tu servicio.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

  2. Verifica que tu servicio de Cloud Run use Ambient Networking, la salida de VPC directa y la identidad del agente:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    Confirma que el resultado muestre la subred de salida de VPC directa, la salida de all-traffic, las redes Ambient Networking regionales y la principal de identidad del agente asignada.

Configura tu agente de Cloud Run para que confíe en Agent Gateway

Para que Secure Web Proxy inspeccione las cargas útiles de HTTPS y aplique políticas, debe finalizar las sesiones de TLS salientes de tu agente. El contenedor del agente de Cloud Run debe confiar en el certificado de la autoridad certificadora (AC) raíz o subordinada asociado con tu política de inspección de TLS de Secure Web Proxy en CA Service o en la PKI de tu empresa privada:

  1. Exporta el certificado de la AC codificado en PEM desde el grupo de CA Service para tu instancia de Secure Web Proxy:

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    Reemplaza lo siguiente:

    • CA_POOL_NAME: Es el nombre del grupo de AC asociado con tu política de inspección de TLS de Secure Web Proxy.
    • REGION: Es la región de tu grupo de AC.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

  2. Actualiza tu servicio de Cloud Run para pasar el contenido del certificado en una variable de entorno:

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run.
    • REGION: Es la región de tu servicio.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

    Por ejemplo, la siguiente secuencia de comandos de punto de entrada del contenedor de Debian o Ubuntu, entrypoint.sh, instala AGENT_GATEWAY_ROOT_CERT en el almacén de confianza del sistema y exporta las rutas de acceso del paquete de AC para los clientes de Python y gRPC antes de iniciar la aplicación:

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. Verifica que tu servicio configure la variable de entorno AGENT_GATEWAY_ROOT_CERT:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

Enruta el tráfico de salida a Agent Gateway

Después de configurar el servicio de Cloud Run y Agent Gateway, crea una política de la API de Network Services EgressRouting para dirigir el tráfico saliente del servicio de Cloud Run a la puerta de enlace de Secure Web Proxy:

  1. Crea el recurso EgressRouting:

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    Reemplaza lo siguiente:

    • REGION: Es la región de tu servicio y puerta de enlace de Cloud Run.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • SWP_NAME: Es el nombre de tu recurso Gateway de Secure Web Proxy subyacente, no el recurso AgentGateway.
    • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run. Para enrutar todos los servicios de Cloud Run del proyecto a través de la puerta de enlace con una sola política, establece workloadUri en //run.googleapis.com/projects/PROJECT_ID o //run.googleapis.com/projects/PROJECT_NUMBER.

    Después de que EgressRouting entre en vigencia, todo el tráfico saliente de tu servicio de Cloud Run se enrutará a través de Secure Web Proxy. Configura políticas en la siguiente sección para permitir y controlar las solicitudes salientes.

  2. Verifica que el recurso EgressRouting esté activo:

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    Confirma que sources enumere el URI de tu carga de trabajo de Cloud Run y que gateway haga referencia al recurso de puerta de enlace de Secure Web Proxy.

Configura políticas en Agent Gateway

Después de enrutar el tráfico de salida a través de Agent Gateway, administra las solicitudes salientes de tu agente adjuntando políticas de autorización y vinculaciones de extensiones de Service Extensions a tu recurso de Agent Gateway:

  • Filtrado de herramientas de MCP y tráfico de referencia: Permite extremos de modelos y métodos y herramientas aprobados del Protocolo de contexto del modelo (MCP) con políticas de autorización de ALLOW.
  • Control de acceso basado en identidades: Vincula IAP con un recurso de ExtensionBinding y configura una política de acceso unificado de IAM para controlar qué agentes pueden llamar a servidores de MCP, herramientas o extremos específicos.
  • Seguridad del contenido: Vincula Model Armor con un recurso de ExtensionBinding para inspeccionar y limpiar instrucciones y respuestas en busca de inyección de instrucciones, filtración de datos sensibles o incumplimientos de políticas.

Se ignoran las políticas de autorización o las reglas de política de seguridad de la puerta de enlace adjuntas al recurso Gateway de Secure Web Proxy subyacente. Después de crear o actualizar un recurso ExtensionBinding, los cambios pueden tardar hasta cinco minutos en propagarse a la puerta de enlace. Para conocer la secuencia de evaluación de reglas en las reglas de red, la inspección de TLS, las vinculaciones de extensiones y las reglas HTTP, consulta Orden de evaluación de las reglas de autorización.

Permitir el tráfico de salida de referencia y de MCP

Secure Web Proxy rechaza todo el tráfico saliente con errores 403 Forbidden de forma predeterminada hasta que un ALLOW AuthzPolicy en tu recurso de Agent Gateway lo permita.

Como tu servicio de Cloud Run usa --vpc-egress=all, todo el tráfico saliente del contenedor, incluidas las llamadas a la herramienta de MCP y las solicitudes de LLM, se enruta a través de la puerta de enlace. Adjunta políticas de autorización de ALLOW a tu recurso de Agent Gateway para ambos tipos de tráfico:

Configura las políticas de salida de IAP

Agent Gateway usa IAP como su motor de decisiones basadas en políticas para evaluar las políticas de acceso unificado de IAM. Para aplicar de manera forzosa las políticas de identidad de los agentes, define tus reglas de acceso en una política de acceso unificado de IAM y vincula IAP a tu puerta de enlace:

  1. Crea una política de acceso unificado de IAM con la principal Identidad del agente del servicio de Cloud Run, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME, y vincula la política a tu proyecto o puerta de enlace siguiendo los pasos que se indican en Crea políticas de acceso de IAM y Vincula una política de acceso unificado a un proyecto.
  2. Vincula IAP, iap.googleapis.com, a tu Agent Gateway con un ExtensionBinding siguiendo las instrucciones que se indican en Vincula IAP a tu Agent Gateway.

Debido a que --vpc-egress=all envía llamadas de modelo, como REGION-aiplatform.googleapis.com, a través de la puerta de enlace, asigna el permiso matchConditions en tu ExtensionBinding de IAP a prefix: "urn:mcp" para que las llamadas de modelo omitan la evaluación de IAP. Para controlar también el tráfico de agente a agente, agrega prefix: "urn:agent". Si la vinculación de la extensión coincide con otros hosts, agrega una regla de permiso para cada host en tu política de acceso unificado de IAM, como destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. Para ver un ejemplo, consulta Crea una política de agente a extremo no registrado.

Configura las políticas de Model Armor

Para inspeccionar y limpiar las instrucciones y respuestas que pasan por tu Agent Gateway, crea plantillas de Model Armor y vincúlalas a tu puerta de enlace:

  1. Crea plantillas de solicitud y respuesta regionales de Model Armor y otorga los roles necesarios al agente de servicio de extensiones de servicio siguiendo las instrucciones que se indican en Configura Model Armor en una puerta de enlace.
  2. Adjunta tus plantillas a tu Agent Gateway con un ExtensionBinding siguiendo las instrucciones que se indican en Vincula Model Armor para la limpieza de instrucciones y respuestas.

Configura una implementación centralizada entre proyectos con una VPC compartida

En una organización con varios proyectos, puedes implementar tus agentes de Cloud Run en uno o más proyectos de servicio mientras alojas una instancia de Agent Gateway, Secure Web Proxy y Agent Registry en un proyecto host de red dedicado con VPC compartida:

  • Proyecto A, proyecto de servicio del agente: Aloja el servicio del agente de Cloud Run y la política local de EgressRouting.
  • Proyecto B, proyecto host de puerta de enlace y redes: Actúa como el proyecto host de la VPC compartida y debe alojar la Agent Gateway, la instancia de Secure Web Proxy, el Agent Registry, los recursos de ExtensionBinding y las vinculaciones de políticas de IAM.
Diagrama de arquitectura entre proyectos que muestra el proyecto A, que aloja un servicio de Cloud Run y una política de enrutamiento de salida, conectado a través de una red de VPC compartida al proyecto B, que aloja el Agent Gateway, el Secure Web Proxy y el Agent Registry.
Figura 2: Implementación de Agent Gateway entre proyectos con la VPC compartida.

Antes de comenzar con estos pasos, habilita run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com y trafficdirector.googleapis.com en el proyecto A, junto con aiplatform.googleapis.com si tu agente llama a Vertex AI. En el proyecto B, implementa la instancia de Secure Web Proxy y el recurso de Agent Gateway en la red de VPC compartida, como se describe en Crea un Agent Gateway autoadministrado, y configura el enrutamiento de DNS o Private Service Connect, como se describe en Configura Ambient Networking de Cloud Run para acceder a la API de Traffic Director, de modo que los sidecars ambientales del proyecto A puedan acceder a la API de Traffic Director.

Para configurar una implementación entre proyectos, completa los siguientes pasos:

  1. Configura el proyecto B como un proyecto host de VPC compartida, adjunta el proyecto A como un proyecto de servicio y comparte la subred que aloja tu instancia de Secure Web Proxy. Para habilitar la VPC compartida y adjuntar proyectos de servicio, se requiere roles/compute.xpnAdmin a nivel de la organización o de la carpeta. Para obtener instrucciones, consulta Envía tráfico a una red de VPC compartida con salida de VPC directa y Aprovisiona una VPC compartida.

  2. En el proyecto B, otorga roles/compute.networkUser en la subred compartida al agente de servicio de Cloud Run del proyecto A:

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    Reemplaza lo siguiente:

    • SHARED_SUBNET_NAME: Es el nombre de la subred compartida en el proyecto B.
    • PROJECT_B_ID: el ID del proyecto B, la puerta de enlace y el proyecto host de la VPC compartida.
    • REGION: Es la región de la subred compartida.
    • PROJECT_A_NUMBER: Es el número del proyecto A, el proyecto de servicio del agente.

  3. Implementa el servicio del agente de Cloud Run en el proyecto A que apunta a la subred compartida en el proyecto B:

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run en el proyecto A.
    • PROJECT_A_ID: el ID del proyecto A, el proyecto de servicio del agente.
    • IMAGE_URL: una referencia a la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

    Después de implementar el servicio, configura tu agente en el proyecto A para que confíe en el certificado de la AC raíz de la instancia de Secure Web Proxy en el proyecto B. Para ello, sigue los pasos que se indican en Configura tu agente de Cloud Run para que confíe en Agent Gateway.

  4. Crea una política de EgressRouting en el proyecto A que haga referencia a la puerta de enlace de Secure Web Proxy en el proyecto B. Debes tener roles/networkservices.admin en el proyecto A:

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    Reemplaza CENTRAL_SWP_NAME por el nombre del Secure Web Proxy en el proyecto B. Para enrutar todos los servicios de Cloud Run del proyecto A a través de la puerta de enlace del proyecto B, establece workloadUri en //run.googleapis.com/projects/PROJECT_A_ID o //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. Confirma que el recurso EgressRouting entre proyectos esté activo en el proyecto A:

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Configura políticas de referencia, de IAP y de Model Armor centralizadas en el recurso de Agent Gateway en el proyecto B, como se describe en Configura políticas en Agent Gateway:

    • Permite el tráfico de MCP y de modelos de referencia en el recurso de Agent Gateway en el proyecto B siguiendo las instrucciones de Permite el tráfico de salida y de MCP de referencia.
    • Para autorizar al agente del proyecto A a llamar a los servidores de MCP registrados en el proyecto B, crea una política de acceso unificado de IAM en el proyecto B cuya lista principals haga referencia al número de proyecto del proyecto A, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME, vincula la política al proyecto B o a su recurso de Agent Gateway, y adjunta el ExtensionBinding de IAP en el proyecto B.
    • Para aplicar las protecciones centralizadas de Model Armor en el proyecto B, crea tus plantillas regionales de Model Armor, otorga los roles necesarios al agente de servicio de extensiones de servicio del proyecto B y adjunta el ExtensionBinding de Model Armor al recurso de Agent Gateway en el proyecto B.

Visualiza registros y seguimientos

Las interacciones de agentes salientes enrutadas a través de Agent Gateway generan registros y seguimientos distribuidos para que puedas supervisar las decisiones basadas en políticas y depurar el comportamiento de los agentes:

Si las solicitudes salientes fallan o omiten la puerta de enlace, consulta Soluciona problemas de Agent Gateway.

Regiones admitidas

Puedes usar Agent Gateway en Cloud Run en las siguientes regiones:

  • europe-west1
  • us-central1

Limitaciones

Además de las limitaciones de Ambient Networking y las consideraciones de Secure Web Proxy en Implementa Secure Web Proxy como un Agent Gateway, se aplican las siguientes limitaciones cuando usas Agent Gateway con Cloud Run:

  • Las solicitudes de agentes salientes enrutadas a través de una instancia de Secure Web Proxy que inspecciona TLS a los extremos *.mtls.googleapis.com y *.mtls.run.app fallan con errores 503 porque Secure Web Proxy finaliza y vuelve a originar sesiones de TLS sin reenviar el certificado de cliente.
  • Cada Agent Gateway regional autoadministrada admite, como máximo, un Agent Registry regional en su lista registries.
  • De forma predeterminada, cada proyecto admite hasta 10 recursos AgentGateway regionales y 10 recursos EgressRouting regionales por región. Los proyectos nuevos pueden comenzar con un límite de 2 por región. Para solicitar un aumento de cuota, comunícate con tu equipo de cuentas.
  • Debes exportar el certificado raíz o subordinado de tu grupo de Certificate Authority Service o PKI empresarial privada y configurar el contenedor de tu agente para que confíe en él.

¿Qué sigue?