Cómo controlar las cargas de trabajo basadas en agentes con Agent Gateway en Agent Platform de Gemini Enterprise

1. Introducción

Gemini Enterprise Agent Platform es una plataforma abierta para crear, escalar, administrar y optimizar agentes de IA de nivel empresarial basados en tus datos.

Agent Runtime proporciona el entorno de ejecución administrado para ejecutar agentes, como los que se compilan con el Kit de desarrollo de agentes (ADK) de código abierto, de forma segura en Google Cloud.

En este codelab, se explora cómo usar estos componentes básicos para controlar un agente iniciado por un usuario en Gemini Enterprise mientras se comunica de forma segura con herramientas internas.

Acerca de Agent Gateway

Agent Gateway es el componente de redes del paquete de Agent Governance de la plataforma. Actúa como punto de entrada y salida de la red para todas las interacciones del agente, lo que permite a los administradores de seguridad aplicar una gobernanza centralizada sin que los desarrolladores tengan que administrar primitivas de redes complejas.

Facilita dos rutas de acceso gobernado principales:

• Cliente a agente (entrada): Protege las comunicaciones entre clientes externos (como Cursor o la CLI de Gemini) y tus agentes.
• Agent-to-Anywhere (salida): Protege las comunicaciones entre los agentes que se ejecutan en Google Cloud y los servidores, las herramientas o las APIs que se ejecutan en cualquier lugar.

En este codelab, te enfocarás en el modo Agente a cualquier lugar (salida).

Para aplicar políticas de seguridad, Agent Gateway se integra estrechamente con el resto del ecosistema:

• Agent Registry: Es una biblioteca central de agentes y herramientas aprobados (incluidos los servidores de MCP de terceros).
• Identidad del agente: Es un personaje único y rastreable para cada agente, protegido automáticamente con mTLS de extremo a extremo.
• Identity-Aware Proxy (IAP) y IAM: Es la capa de aplicación predeterminada que valida la identidad del agente en función de los permisos detallados de IAM antes de permitir llamadas a herramientas específicas.
• Model Armor: Es un riel de seguridad de IA integrado a través de Service Extensions para sanear el contenido y proteger contra ataques de inyección de instrucciones o filtración de datos.

Modos de implementación (herramientas de redes públicas y privadas para Cloud Run)

Para que este codelab sea accesible, puedes elegir entre dos rutas de redes para tus herramientas internas (servidores de MCP) implementadas en Cloud Run:

1. Predeterminado (entrada pública): Los servidores de MCP se implementan en Cloud Run con nombres de host públicos (ingress=all). El tráfico se enruta desde el agente a las herramientas a través de URLs de *.run.app estándar. Esto no requiere dominios de DNS personalizados y es la forma más rápida de aprender los conceptos de gobernanza.
2. Segura (redes privadas): Es una arquitectura completamente privada y opcional. Los servidores de MCP están restringidos (ingress=internal-and-cloud-load-balancing) y se exponen a través de un balanceador de cargas de aplicaciones interno con un NEG sin servidores. Para aprovisionar un certificado administrado por Google, debes ser propietario de un dominio DNS público.

Seleccionarás la ruta de acceso que prefieras cuando configures Terraform.

Para obtener más información sobre la entrada de extremos de red para Cloud Run, lee nuestra documentación.

Actividades

• Aprovisiona la pila de infraestructura principal con Terraform
• Compila e implementa herramientas internas como servidores de MCP en Cloud Run
• Implementa un agente del ADK en Agent Runtime con la salida de la interfaz de PSC
• Configura extensiones de servicio de Agent Gateway para el acceso basado en identidades (IAM) y el análisis de contenido (Model Armor)
• Haz un seguimiento y valida la ejecución segura de extremo a extremo del agente

Requisitos

• Un navegador web, como Chrome
• Un proyecto de Google Cloud con la facturación habilitada y acceso de propietario
• Permisos de IAM a nivel de la organización (el codelab otorga roles con alcance de la organización)
• Un dominio que controlas y que se delegó en Cloud DNS (para el certificado administrado público)
• Conocimiento de Terraform, gcloud y redes básicas de Google Cloud

Topología del codelab

En este codelab, implementarás un agente de suscripción de hipotecas integral que se comunica de forma segura con tres herramientas internas.

Comenzarás por aprovisionar la red fundamental, incluida una VPC y un balanceador de cargas de aplicaciones interno configurado como tu puerta de enlace del agente. A continuación, implementarás tres servidores del Protocolo de contexto del modelo (MCP) en Cloud Run. Estas actúan como tus herramientas internas exclusivas:

• Administración de documentos (legacy-dms)
• Correo electrónico corporativo (corporate-email)
• Verificación de ingresos (income-verification)

Con las herramientas instaladas, implementarás un asistente hipotecario (mortgage-agent) creado con el ADK en Agent Runtime. Configurarás este agente para que use una interfaz de PSC para la salida privada y habilitarás la detección de herramientas en el tiempo de ejecución a través del registro de agentes.

Para proteger el flujo, configurarás tu Agent Gateway con dos extensiones de servicio. Primero, una extensión de REQUEST_AUTHZ verificará la identidad del agente en función de las políticas de IAM por herramienta, lo que garantizará que el agente solo acceda a las herramientas autorizadas. En segundo lugar, una extensión de CONTENT_AUTHZ que usa Model Armor filtrará las instrucciones y las respuestas del agente.

Por último, registrarás el agente en Gemini Enterprise, activarás una tarea de suscripción de hipotecas como usuario final y verificarás la ejecución segura y controlada con Cloud Trace.

Este codelab está dirigido a ingenieros de plataformas y seguridad de todos los niveles. Se estima que tardarás aproximadamente 100 minutos en completarlo.

2. Antes de comenzar

Crea un proyecto y autentícate

Crea un proyecto de GCP nuevo (o reutiliza uno) con la facturación habilitada y, luego, autentica Cloud Shell o tu máquina local:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Habilita las APIs de arranque

El módulo de base de Terraform habilita alrededor de 30 APIs en su primera aplicación, pero se requiere un pequeño conjunto de arranque para terraform init y el bucket de estado de GCS:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Instala las herramientas requeridas

Instala la cadena de herramientas. En Cloud Shell, la mayoría de estos ya están presentes; en una estación de trabajo:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

También necesitas Terraform >= 1.12.2, Python 3.12 o versiones posteriores y el SDK de Google Cloud (gcloud).

Configura las variables de entorno

En el resto del codelab, se supone que estos se exportaron en tu shell.

Si sigues la ruta de redes seguras opcional, define DOMAIN_NAME (p.ej., agw.example.com); de lo contrario, puedes ignorarlo.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com" 

Valida que todas tus variables se hayan propagado correctamente. Deberías ver tres valores devueltos.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Si no se completa automáticamente el ID de la organización, puedes buscarlo y configurarlo de forma manual.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Clona el repositorio

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Un breve recorrido por el contenido del directorio de demostración:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Crea el bucket de estado de Terraform y la configuración de backend

Crea un bucket de GCS para almacenar el estado remoto y, luego, copia la plantilla de backend:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Edita terraform/backend.conf con tus valores:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

terraform/backend.conf se ignora en Git. Cada usuario mantiene su propia copia.

5. (Opcional) Crea una zona pública de Cloud DNS

Omite este paso si usas la ruta predeterminada. Si deseas usar la configuración más simple con URLs públicas de Cloud Run, ve directamente al siguiente paso.

De forma predeterminada, para este lab, Cloud Run tiene su configuración de entrada establecida en all, y el registro de agentes registra cada servidor de MCP en su URL pública *.run.app, sin necesidad de DNS, certificados ni balanceadores de cargas adicionales. Si deseas cambiar a redes privadas (Cloud Run con ingress = internal-and-cloud-load-balancing detrás de un LB de aplicación interno), también necesitas una zona pública del DNS de Cloud para que Administrador de certificados pueda validar el certificado del LB.

Flujo general de redes privadas

Para usar el enfoque de redes privadas, haz lo siguiente:

1. Crea la zona pública de Cloud DNS. Administrador de certificados validará el certificado administrado regional escribiendo CNAMEs en él:

gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Terraform crea automáticamente la zona privada correspondiente para mcp.${DOMAIN_NAME} (que usa el LB interno de MCP y el intercambio de tráfico de DNS desde el tiempo de ejecución del agente), por lo que no es necesario que la crees de forma manual. Con las redes privadas desactivadas, no se aprovisiona la zona pública ni la privada.

Para obtener una explicación más detallada del patrón de DNS de horizonte dividido público y privado que usa esta demostración (configuración de zona administrada, intercambio de tráfico de DNS entre VPC, flujo de validación de certificados), consulta la guía de configuración de DNS.

6. Configura las variables de Terraform

Copia el ejemplo de tfvars y edítalo:

cp terraform/example.tfvars terraform/terraform.tfvars

Hay dos rutas de demostración, controladas por enable_cloud_run_private_networking.

Ruta de acceso predeterminada: Cloud Run con entrada pública

**La configuración más simple.**Para la ruta de acceso predeterminada, solo necesitas editar tres valores en terraform.tfvars. Todas las demás variables del archivo ya tienen un valor predeterminado apto para demostraciones.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:[e-mail]"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Configuraremos IAP en el modo de ejecución de prueba de solo auditoría para probar la política de autorización de IAP sin aplicarla. Una vez que validemos nuestra implementación, actualizaremos el modo de aplicación a "APLICADO".

Herramientas de redes privadas (opcional)

Configura enable_cloud_run_private_networking = true y agrega las siguientes variables para aprovisionar la pila segura completa:

• LB de aplicación interno
• Certificado administrado por Google
• Cloud Run con ingress = internal-and-cloud-load-balancing
• Intercambio de tráfico de DNS de Agent Gateway.

enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

Las imágenes de Cloud Run anteriores apuntan a un marcador de posición de Google. Esto es intencional: Terraform crea los servicios de Cloud Run con lifecycle { ignore_changes = [template[0].containers[0].image] }, por lo que las invocaciones posteriores de skaffold run reemplazan la imagen sin que Terraform las rechace.

agent_gateway_subnet_cidr debe ser al menos /28, RFC 1918 y no debe superponerse con 10.0.0.0/24, 10.0.1.0/24 ni 10.0.2.0/24. Estos rangos están reservados para la salida de la puerta de enlace de agente.

El LB interno del MCP entrega TLS para *.mcp.${DOMAIN_NAME} con el mismo certificado regional administrado por Google. No establezcas mcp_internal_dns_zone.domain en un sufijo no enrutable, como mcp-server.internal., mientras enable_agent_gateway = true Y enable_cloud_run_private_networking = true.

Actualmente, Agent Gateway no valida el certificado de resguardo autofirmado. La configuración de Terraform aplica esto con un bloque check en el momento de la planificación (se omite cuando las redes privadas están desactivadas, ya que no hay ningún certificado de LB para validar).

7. Implementa infraestructura con Terraform

Inicializa, revisa y aplica los cambios:

cd terraform
terraform init -backend-config=backend.conf
terraform plan
terraform apply

terraform apply aprovisiona alrededor de 40 recursos en la ruta predeterminada y tarda entre 8 y 10 minutos en un proyecto nuevo (alrededor de 60 recursos y entre 15 y 20 minutos cuando se usa enable_cloud_run_private_networking = true). Crea lo siguiente:

• Base del proyecto (APIs, identidades de servicio, cuotas)
• VPC, subredes (principal, solo proxy, PSC, interfaz de PSC, ubicación conjunta de la puerta de enlace del agente), Cloud NAT, reglas de firewall
• Repo de Artifact Registry para imágenes de Cloud Run
• Tres servicios de Cloud Run y SA de tiempo de ejecución por servicio (entrada = all de forma predeterminada; internal-and-cloud-load-balancing cuando la red privada está activada)
• Plantilla de Model Armor + IAM
• Puerta de enlace del agente, adjunto de red de PSC-I, extensiones de IAP y Model Armor, ambas políticas de autorización y el otorgamiento de roles/iap.egressor a nivel del proyecto
• Extremos de Agent Registry (Vertex AI, IAP, Discovery Engine, …) y los tres servidores de MCP (registrados en *.run.app/mcp de forma predeterminada; en ./mcp cuando la red privada está activada)

Solo cuando enable_cloud_run_private_networking = true:

• Balanceador de cargas de aplicaciones interno regional con NEG sin servidores (enrutamiento de máscara de URL) y registros A de DNS privados
• Zona DNS privada del MCP (mcp..) adjunta a la VPC
• Módulo de zona del DNS pública (autorizaciones de DNS del Administrador de certificados) y certificado administrado por Google regional
• Zona de DNS de la interfaz de PSC (huérfana cuando no hay nombres de host privados para resolver, por lo que también se limita con la marca principal)
• Intercambio de tráfico de DNS de Agent Gateway para mcp.. (se agrega automáticamente al principio)

8. Inspecciona los extremos del registro de agentes

Solo como referencia. El módulo agent-registry-endpoints de Terraform ya ejecutó los comandos de esta sección. Se muestran para que puedas ver exactamente cómo se registra un extremo detectable por MCP.

Agent Registry es un catálogo de servicios por proyecto (APIs de Google y tus propios servidores de MCP) que un agente descubre en el tiempo de ejecución. El agente hipotecario lo lee en el inicio y vincula herramientas de forma dinámica. No se incorporan URLs de MCP en el código del agente ni en su comando de implementación.

Extremos

Qué ejecutó Terraform en tu nombre: Para cada API de Google en agent_registry_google_apis, registró cinco variantes (global, global con mTLS, regional, regional con mTLS y regional con REP). Por ejemplo, para aiplatform:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

Servidores MCP

Terraform también registra los 3 servidores de MCP por ti. Para registrar otros servidores de MCP, puedes seguir los pasos de la documentación.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Verifica los extremos y los servidores de MCP registrados.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Fuente: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9. Revisa la configuración de Agent Gateway

Solo como referencia. Terraform ya importó esta puerta de enlace del agente. El siguiente código YAML es el equivalente literal de terraform/modules/agent-gateway/main.tf.

Agent Gateway es un plano de administración administrado por Google entre Agent Runtime y tus herramientas. En el modo AGENT_TO_ANYWHERE, se vincula al registro de agentes del proyecto y sale a través de una interfaz de PSC propiedad del cliente para que pueda llegar a los servidores MCP privados en tu VPC.

Si importaras esta puerta de enlace de forma manual, el archivo YAML se vería de la siguiente manera:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Verifica la puerta de enlace que creó Terraform:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

El terraform-provider-google-beta actual aún no expone network_config.dns_peering_config. Terraform lo aplica a través de un PATCH posterior a la aplicación en networkservices.googleapis.com/v1beta1. Verás esto en terraform_data.dns_peering en el módulo.

10. Cómo examinar la autorización de IAP y Model Armor

Solo como referencia. Terraform ya creó ambas extensiones y ambas políticas. Los siguientes comandos provienen directamente de terraform/modules/agent-gateway/main.tf.

Agent Gateway delega la autorización a las extensiones de servicio. En la demostración, se incluyen dos perfiles de políticas:

• REQUEST_AUTHZ: Se evalúa una vez por solicitud en la etapa de encabezados. Se usa aquí para llamar a IAP, que verifica si la identidad del agente de llamada tiene roles/iap.egressor en el servidor de MCP de destino.
• CONTENT_AUTHZ: Transmite eventos del cuerpo a la extensión para la limpieza del contenido. Aquí se usa para llamar a Model Armor, que filtra la inyección de instrucciones, los jailbreaks, los incumplimientos de la RAI y (opcionalmente) la PII a través de Sensitive Data Protection (SDP).

Extensión REQUEST_AUTHZ de IAP

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Vincúlalo a Agent Gateway con una política de REQUEST_AUTHZ:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Extensión CONTENT_AUTHZ de Model Armor

La extensión metadata.model_armor_settings contiene los IDs de plantilla de solicitud y respuesta que Model Armor usa para evaluar cada texto destacado:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Plantillas personalizadas de DLP

La función sdpSettings.basicConfig de Model Armor usa una lista de tipos de información integrada. Para tener un control más preciso (Infotipos personalizados, enmascaramiento parcial, reemplazo de sustitutos, ocultamiento por probabilidad), apunta Model Armor a tus propias plantillas de inspección y desidentificación de Cloud DLP a través de sdpSettings.advancedConfig.

Crea una plantilla de inspección que marque los números de seguridad social de EE.UU. con una probabilidad de POSSIBLE o superior:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Crea una plantilla de desidentificación que reemplace cada hallazgo por su token de tipo de información (p.ej., [US_SOCIAL_SECURITY_NUMBER]):

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Luego, apunta la configuración de respuesta de una plantilla de Model Armor al par a través de sdpSettings.advancedConfig (aquí es donde el módulo model_armor de Terraform establecería advanced_config si lo conectaras):

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

La extensión CONTENT_AUTHZ de Model Armor mencionada anteriormente detectará automáticamente estas plantillas de configuración avanzada la próxima vez que evalúe una respuesta, sin necesidad de cambiar la extensión. Asegúrate de que el agente de servicio de Model Armor (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) tenga roles/dlp.user y roles/dlp.reader en el proyecto (el módulo model-armor de Terraform ya otorga estos permisos).

IAM del agente de salida de IAP (solo por servidor de MCP)

Terraform no crea una vinculación de roles/iap.egressor a nivel del proyecto en el registro implícito del agente de IAP. La vinculación de REQUEST_AUTHZ de IAP que se evalúa en realidad es por servidor de MCP y por motor de razonamiento, y se otorga después de que se implementa el agente y conoces su ID. El paso "Otorga al agente salida por servidor de MCP" ejecuta scripts/grant_agent_mcp_egress.sh para ello.

11. Compila e implementa los servidores de MCP en Cloud Run

Los archivos cloudrun/*.yaml.tmpl y skaffold.yaml.tmpl hacen referencia a ${PROJECT_ID}, ${REGION} y ${MCP_INGRESS} (la anotación de entrada de Cloud Run). Obtén la fuente MCP_INGRESS de un resultado de Terraform para que los manifiestos renderizados se mantengan sincronizados con enable_cloud_run_private_networking y, luego, renderiza con envsubst:

Exporta la configuración de entrada de Cloud Run.

• all
• internal-and-cloud-load-balancing (cuando se usa el enfoque de redes privadas)

export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Cada servicio de Cloud Run se ejecuta como una SA de entorno de ejecución por servicio creada por Terraform (p.ej., mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Para implementar como esas SA, necesitas roles/iam.serviceAccountUser en ti mismo:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Compila con Cloud Build e implementa con Skaffold:

skaffold run

Skaffold compila tres imágenes (legacy-dms, corporate-email, income-verification-api) en tu repositorio de Artifact Registry y actualiza cada servicio de Cloud Run para que apunte al nuevo resumen.

Verifica lo que hiciste:

gcloud run services list --region=${REGION}

Deberías ver los tres servicios con el estado ACTIVE.

12. Implementa el agente hipotecario en Agent Runtime

Instala las dependencias del agente y realiza la implementación:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

El agente descubre las herramientas del MCP en el tiempo de ejecución enumerando mcpServers en Agent Registry en projects/${PROJECT_ID}/locations/${REGION}.

Cuando se complete la secuencia de comandos, copia el reasoningEngines/ impreso en tu shell:

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Otorga al agente salida por servidor de MCP

La extensión REQUEST_AUTHZ de IAP autoriza cada llamada a la herramienta verificando el roles/iap.egressor del agente en el servidor MCP específico o el extremo al que llama. Consulta Crea una política de salida del servidor del agente al MCP.

La secuencia de comandos (scripts/grant_agent_mcp_egress.sh) enumera los servidores de MCP en el registro de agentes en projects/${PROJECT_ID}/locations/${REGION} y combina una vinculación de roles/iap.egressor para el principal del agente en la política de IAM de cada servidor (lo que refleja la semántica de gcloud add-iam-policy-binding).

Caso de uso 1: Otorgamiento incondicional con alcance para servidores de MCP específicos

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Caso de uso 2: Otorgamiento condicional (CEL) con alcance en un servidor de MCP específico

Para restringir el agente a un subconjunto de herramientas en un solo servidor de MCP, adjunta una condición de IAM. La puerta de enlace del agente publica atributos por herramienta que IAP REQUEST_AUTHZ expone a CEL, incluidos los siguientes:

• iap.googleapis.com/mcp.toolName
• iap.googleapis.com/mcp.tool.isReadOnly
• iap.googleapis.com/request.auth.type.

Restringe el agente a herramientas de solo lectura en corporate-email:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Después de que se ejecute, las herramientas de escritura en corporate-email devolverán 403 PermissionDenied desde REQUEST_AUTHZ de IAP, y las herramientas de solo lectura seguirán funcionando.

Verifica las vinculaciones

Navega a la pestaña Policies y verás la lista de políticas creadas para los servidores de Endpoints y Mcp.

Casos de uso adicionales:

Concesión incondicional en cada servidor de MCP, con alcance para un agente

Ejecuta este comando después de cada nueva implementación del agente. Sin filtro ni condición, el agente con nombre obtiene roles/iap.egressor en cada servidor de MCP del registro:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Prueba el agente en la consola de Agent Platform

La consola de Agent Platform incluye un Playground que te permite chatear directamente con el agente implementado. Es la forma más rápida de realizar pruebas de humo de las llamadas a herramientas y de inspeccionar los registros antes de conectar el agente a Gemini Enterprise.

1. Abre la página Agent Platform Deployments en la consola de Google Cloud.
2. Usa el campo Filter si necesitas reducir la lista de tiempos de ejecución y, luego, haz clic en tu tiempo de ejecución de mortgage-agent.
3. Abre la pestaña Playground.
4. Escribe una instrucción para chatear con el agente:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Esto debería devolver una respuesta de la herramienta de administración de documentos y la herramienta de verificación de ingresos. Los números de seguridad social también deberían ocultarse en esta respuesta. 5. Escribe una pregunta adicional:

Can you send a summary of this to my email [e-mail]

El agente debe identificar que no tiene acceso a la herramienta send_email y responder en consecuencia.

Dado que el agente se implementó con la instrumentación de OpenTelemetry, Playground expone cuatro vistas de panel lateral entre las que puedes alternar a medida que el agente responde:

• Registro: Registros completos de la conversación, incluidos los intervalos de Agent Gateway, IAP REQUEST_AUTHZ y Model Armor CONTENT_AUTHZ
• Evento: Un gráfico de las herramientas invocadas y los detalles del evento del turno actual
• Estado: Es el estado de la sesión del agente y las entradas o salidas de la herramienta.
• Sesiones: Todas las sesiones que iniciaste en este tiempo de ejecución

Playground omite por completo la autenticación de Gemini Enterprise, lo que lo convierte en el lugar más rápido para confirmar que la extensión REQUEST_AUTHZ de la IAP otorga llamadas a herramientas correctamente. Si una herramienta devuelve 403 aquí, vuelve a ejecutar scripts/grant_agent_mcp_egress.sh antes de depurar más a fondo.

15. Aplica la autorización de IAP

Ahora que validamos la implementación, podemos actualizar el modo de aplicación de IAP a null para aplicar las políticas. Abre terraform.tfvars y actualiza el modo de DRY_RUN a null.

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = null

Aplica el cambio.

terraform apply

Regresa a Playground y vuelve a intentarlo.

1. Abre la página Agent Platform Deployments en la consola de Google Cloud.
2. Usa el campo Filter si necesitas reducir la lista de tiempos de ejecución y, luego, haz clic en tu tiempo de ejecución de mortgage-agent.
3. Abre la pestaña Playground.
4. Escribe una instrucción para chatear con el agente:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Esto debería devolver una respuesta de la herramienta de administración de documentos y la herramienta de verificación de ingresos. Los números de seguridad social también deberían ocultarse en esta respuesta. 5. Escribe una pregunta adicional:

Can you send a summary of this to my email [e-mail]

Si todo se configuró correctamente, el agente debería responder que no puede enviar el correo electrónico debido a la política de autorización.

16. Configuración y pruebas de Gemini Enterprise

Configura Gemini Enterprise

Sigue la guía para comenzar a usar Gemini Enterprise.

Registra nuestro agente de ADK en Gemini Enterprise

Sigue los pasos para registrar nuestro agente en Gemini Enterprise. Puedes seguir los pasos que se indican aquí.

1. En la consola de Google Cloud, navega a la página Gemini Enterprise.
2. Selecciona la app de Gemini Enterprise en la que está registrado el agente.
3. Abre la URL que se muestra en la sección Tu app web de Gemini Enterprise está lista.
4. Selecciona la pestaña Agent en el menú de la izquierda para abrir la Galería de agentes.
5. Selecciona Mortgage Assistant Agent y comienza a chatear.

Prueba las mismas instrucciones del Agent Runtime Playground:

Instrucción inicial:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Pregunta adicional de seguimiento:

Can you send a summary of this to my email [e-mail]

Si vuelves a la sección Implementación del agente en la consola, selecciona nuestra implementación del agente y ve a la pestaña de registros. Ahora verás el agente de Gemini Assistant en el intervalo que muestra que la llamada se originó en Gemini Enterprise.

17. Solución de problemas y correcciones habituales

• terraform apply falla en la puerta de enlace del agente con el mensaje "Se está creando el recurso y, por lo tanto, no se puede actualizar": El proyecto del arrendatario de la puerta de enlace tarda alrededor de 30 segundos en establecerse antes de que se puedan adjuntar las políticas de autorización. El time_sleep.wait_for_gateway del módulo se encarga de esto. Solo tienes que volver a ejecutar terraform apply.
• El agente informa que no se encontraron servidores de MCP o se inicia solo con herramientas de utilidad: Confirma enable_agent_registry_endpoints = true en terraform.tfvars y, luego, haz lo siguiente:

  gcloud alpha agent-registry mcp-servers list \
    --project=${PROJECT_ID} --location=${REGION}
  

  Deberías ver tres entradas (una por cada servicio de MCP de Cloud Run). Si la lista está vacía, verifica que se pueda acceder a los servicios de MCP desde la VPC y que Agent Gateway haya completado el registro (lo hace de forma diferida en la primera lista de herramientas proxy).
• Las llamadas a herramientas devuelven 403 PermissionDenied: Vuelve a ejecutar scripts/grant_agent_mcp_egress.sh. La causa más común es olvidar volver a otorgar el permiso después de volver a implementar el agente (el reasoningEngines/ cambia con cada implementación).
• skaffold run falla con el mensaje "permiso denegado en la cuenta de servicio": Falta roles/iam.serviceAccountUser. Vuelve a ejecutar la concesión automática del paso anterior.
• Errores de peering de DNS desde Agent Gateway al LB de MCP: Verifica que agent_gateway_dns_peering_config.target_network coincida exactamente con projects/${PROJECT_ID}/global/networks/${VPC_NAME} y que cada entrada de domains termine con un punto final.
• terraform plan sigue queriendo actualizar las etiquetas de imágenes de Cloud Run, lo que no debería suceder debido a la regla lifecycle { ignore_changes }. Si es así, confirma que no editaste mcp_services[*].image en terraform.tfvars después de skaffold run.

18. Limpia

Terraform no administra el motor de razonamiento (el SDK del ADK lo crea). Bórralo de forma manual:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Destruye todo lo que creó Terraform:

cd terraform
terraform destroy
cd ..

Si creaste la zona del DNS pública solo para este codelab, haz lo siguiente:

gcloud dns managed-zones delete agw-example-com

Por último, borra el bucket de estado de Terraform:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. Felicitaciones

¡Felicitaciones! Implementaste correctamente una administración integral de agentes para un agente del ADK con múltiples herramientas usando Agent Gateway. Al actuar como el plano de control de red centralizado, Agent Gateway te permitió establecer una ruta de salida segura a herramientas privadas, aplicar políticas de IAM detalladas basadas en la identidad a través de Identity-Aware Proxy y depurar las interacciones de contenido con las protecciones integradas de Model Armor.

Qué aprendiste

• Cómo implementar y configurar Agent Gateway como la capa de administración central para el tráfico de salida de Agent-to-Anywhere
• Cómo integrar Agent Registry para el descubrimiento de herramientas dinámicas y administradas en el tiempo de ejecución
• Cómo escribir y aplicar políticas de IAM por herramienta y basadas en condiciones para controlar estrictamente las rutas de ejecución del agente
• Cómo aprovechar las extensiones de servicio de Agent Gateway para aplicar políticas de Model Armor, interceptando y redactando automáticamente el tráfico sensible del agente

Documentos de referencia

• Descripción general de las políticas de gobernanza de agentes
• Documentación de Agent Gateway
• Documentación de la identidad del agente
• Descripción general de Gemini Enterprise Agent Platform