Gestire i carichi di lavoro agentici con Agent Gateway su Gemini Enterprise Agent Platform

1. Introduzione

Gemini Enterprise Agent Platform è una piattaforma aperta per creare, scalare, gestire e ottimizzare agenti AI di livello enterprise basati sui tuoi dati.

Agent Runtime fornisce l'ambiente di esecuzione gestito per l'esecuzione di agenti, come quelli creati con Agent Development Kit (ADK) open source, in modo sicuro all'interno di Google Cloud.

Questo codelab esplora come utilizzare questi blocchi di base per controllare un agente avviato da un utente in Gemini Enterprise mentre si connette in modo sicuro agli strumenti interni.

Informazioni su Agent Gateway

Agent Gateway è il componente di rete della suite di governance degli agenti della piattaforma. Funge da punto di ingresso e uscita della rete per tutte le interazioni degli agenti, consentendo agli amministratori della sicurezza di applicare la governance centralizzata senza richiedere agli sviluppatori di gestire primitive di rete complesse.

Facilita due percorsi di accesso regolati principali:

• Da client ad agente (ingresso): protegge le comunicazioni tra client esterni (come Cursor o Gemini CLI) e i tuoi agenti.
• Agente-ovunque (uscita): protegge le comunicazioni tra gli agenti in esecuzione su Google Cloud e server, strumenti o API in esecuzione ovunque.

In questo codelab, ti concentrerai sulla modalità Da agente a ovunque (in uscita).

Per applicare le policy di sicurezza, Agent Gateway si integra perfettamente con il resto dell'ecosistema:

• Agent Registry: una libreria centrale di agenti e strumenti approvati (inclusi i server MCP di terze parti).
• Identità agente: una persona unica e tracciabile per ogni agente, protetta automaticamente con mTLS end-to-end.
• Identity-Aware Proxy (IAP) e IAM: il livello di applicazione predefinito che convalida l'identità dell'agente rispetto alle autorizzazioni IAM granulari prima di consentire le chiamate a strumenti specifici.
• Model Armor: una barriera di protezione per l'AI integrata tramite le Service Extensions per sanificare i contenuti e proteggere da attacchi di prompt injection o fughe di dati.

Modalità di deployment (networking pubblico e privato per Cloud Run)

Per rendere accessibile questo codelab, puoi scegliere tra due percorsi di rete per gli strumenti interni (server MCP) di cui è stato eseguito il deployment su Cloud Run:

1. Predefinito (ingresso pubblico): i server MCP vengono implementati in Cloud Run con nomi host pubblici (ingress=all). Il traffico viene instradato dall'agente agli strumenti tramite URL *.run.app standard. Ciò non richiede domini DNS personalizzati ed è il modo più rapido per apprendere i concetti di governance.
2. Sicura (rete privata): un'architettura facoltativa e completamente privata. I server MCP sono limitati (ingress=internal-and-cloud-load-balancing) ed esposti tramite un bilanciatore del carico delle applicazioni interno con un NEG serverless. Per eseguire il provisioning di un certificato gestito da Google, devi essere proprietario di un dominio DNS pubblico.

Selezionerai il percorso che preferisci durante la configurazione di Terraform.

Per saperne di più sull'ingresso degli endpoint di rete per Cloud Run, leggi la nostra documentazione.

In questo lab proverai a:

• Eseguire il provisioning dello stack di infrastruttura di base utilizzando Terraform
• Crea ed esegui il deployment di strumenti interni come server MCP su Cloud Run
• Esegui il deployment di un agente ADK in Agent Runtime utilizzando l'uscita dell'interfaccia PSC
• Configura le estensioni di servizio Agent Gateway per l'accesso basato sull'identità (IAM) e il controllo dei contenuti (Model Armor)
• Traccia e convalida l'esecuzione sicura end-to-end dell'agente

Che cosa ti serve

• Un browser web come Chrome
• Un progetto Google Cloud con la fatturazione abilitata e accesso Proprietario
• Autorizzazioni IAM a livello di organizzazione (il codelab concede ruoli con ambito organizzativo)
• Un dominio che controlli delegato a Cloud DNS (per il certificato gestito pubblico)
• Familiarità con Terraform, gcloud e il networking di base di Google Cloud

Topologia del codelab

In questo codelab, eseguirai il deployment di un agente di valutazione dei mutui end-to-end che comunica in modo sicuro con tre strumenti interni.

Inizierai con il provisioning della rete di base, inclusa una rete VPC e un bilanciatore del carico delle applicazioni interno configurato come gateway dell'agente. Dopodiché, eseguirai il deployment di tre server Model Context Protocol (MCP) su Cloud Run. Questi fungono da strumenti proprietari interni:

• Gestione dei documenti (legacy-dms)
• Email aziendale (corporate-email)
• Verifica del reddito (income-verification)

Con gli strumenti a disposizione, eseguirai il deployment di un assistente per i mutui (mortgage-agent) creato con ADK in Agent Runtime. Configurerai questo agente in modo che utilizzi un'interfaccia PSC per l'uscita privata e abiliterai l'individuazione degli strumenti di runtime tramite il registro degli agenti.

Per proteggere il flusso, configurerai Agent Gateway con due estensioni di servizio. Innanzitutto, un'estensione REQUEST_AUTHZ verificherà l'identità dell'agente in base ai criteri IAM per strumento, assicurandosi che l'agente acceda solo agli strumenti autorizzati. In secondo luogo, un'estensione CONTENT_AUTHZ che utilizza Model Armor esaminerà i prompt e le risposte dell'agente.

Infine, registrerai l'agente in Gemini Enterprise, attiverai un'attività di valutazione del rischio ipotecario come utente finale e verificherai l'esecuzione sicura e controllata utilizzando Cloud Trace.

Questo codelab è destinato a ingegneri di piattaforme e sicurezza di tutti i livelli. La compilazione dovrebbe richiedere circa 100 minuti.

2. Prima di iniziare

Crea un progetto e autenticati

Crea un nuovo progetto GCP (o riutilizzane uno) con la fatturazione abilitata, poi autentica Cloud Shell o la tua macchina locale:

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

Abilita le API di bootstrap

Il modulo di base di Terraform abilita circa 30 API alla prima applicazione, ma è necessario un piccolo set di bootstrap per terraform init e il bucket di stato GCS:

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

Installa gli strumenti richiesti

Installa la toolchain. In Cloud Shell la maggior parte di questi sono già presenti; su una workstation:

# 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

Sono necessari anche Terraform >= 1.12.2, Python 3.12+ e Google Cloud SDK (gcloud).

Imposta le variabili di ambiente

Il resto del codelab presuppone che questi siano esportati nella shell.

Se stai seguendo il percorso di rete sicuro facoltativo, definisci DOMAIN_NAME (ad es. agw.example.com); altrimenti, puoi 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" 

Verifica che tutte le variabili siano state compilate correttamente. Dovresti visualizzare tre valori restituiti.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Se l'ID organizzazione non viene compilato automaticamente, puoi trovarlo e impostarlo manualmente.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Clona il repository

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

Un rapido tour dei contenuti della directory demo:

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 il bucket di stato Terraform e la configurazione del backend

Crea un bucket GCS per contenere lo stato remoto, quindi copia il modello di backend:

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

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

Modifica terraform/backend.conf con i tuoi valori:

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

terraform/backend.conf viene ignorato da Git. Ogni utente mantiene la propria copia.

5. (Facoltativo) Crea una zona Cloud DNS pubblica

Ignora questo passaggio se utilizzi il percorso predefinito. Se vuoi utilizzare la configurazione più semplice con gli URL Cloud Run pubblici, vai direttamente al passaggio successivo.

Per impostazione predefinita, per questo lab Cloud Run ha la configurazione di Ingress impostata su all e il registro agent registra ogni server MCP al relativo URL *.run.app pubblico, senza richiedere DNS, certificati o bilanciatori del carico aggiuntivi. Se vuoi passare al networking privato (Cloud Run con ingress = internal-and-cloud-load-balancing dietro un bilanciamento del carico delle applicazioni interno), ti serve anche una zona DNS pubblica di Cloud in modo che Certificate Manager possa convalidare il certificato del bilanciamento del carico.

Flusso di alto livello del networking privato

Per utilizzare l'approccio di networking privato:

1. Crea la zona DNS pubblica di Cloud. Certificate Manager convalida il certificato gestito regionale scrivendo i CNAME al suo interno:

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

La zona privata corrispondente per mcp.${DOMAIN_NAME} (utilizzata dal bilanciamento del carico interno MCP e dal peering DNS da Agent Runtime) viene creata automaticamente da Terraform, quindi non devi crearla manualmente. Con il networking privato disattivato, non viene eseguito il provisioning della zona pubblica o privata.

Per una descrizione più dettagliata del pattern DNS split horizon pubblico e privato utilizzato in questa demo (configurazione della zona gestita, peering DNS tra VPC, flusso di convalida dei certificati), consulta la guida alla configurazione DNS.

6. Configura le variabili Terraform

Copia il file tfvars di esempio e modificalo:

cp terraform/example.tfvars terraform/terraform.tfvars

Esistono due percorsi demo, protetti da enable_cloud_run_private_networking.

Percorso predefinito: Cloud Run con ingresso pubblico

**La configurazione più semplice.**Per il percorso predefinito devi modificare solo tre valori in terraform.tfvars. Tutte le altre variabili nel file hanno già un valore predefinito adatto alla demo.

# 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"

Configureremo IAP in modalità di solo controllo dry run per testare il criterio di autorizzazione IAP senza applicarlo. Una volta convalidata l'implementazione, aggiorneremo la modalità di applicazione forzata su "APPLICATA".

Networking privato (facoltativo)

Imposta enable_cloud_run_private_networking = true e aggiungi le variabili riportate di seguito per eseguire il provisioning dello stack sicuro completo:

• Bilanciatore del carico delle applicazioni interno
• Certificato gestito da Google
• Cloud Run con ingress = internal-and-cloud-load-balancing
• Peering DNS del gateway dell'agente.

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"

Le immagini di Cloud Run riportate sopra puntano a un segnaposto Google. È intenzionale: Terraform crea i servizi Cloud Run con lifecycle { ignore_changes = [template[0].containers[0].image] }, quindi le successive invocazioni di skaffold run sostituiscono l'immagine senza che Terraform si opponga.

agent_gateway_subnet_cidr deve essere almeno /28, RFC 1918 e non deve sovrapporsi a 10.0.0.0/24, 10.0.1.0/24 o 10.0.2.0/24. Questi intervalli sono riservati all'uscita del gateway dell'agente.

Il bilanciatore del carico interno MCP gestisce TLS per *.mcp.${DOMAIN_NAME} utilizzando lo stesso certificato regionale gestito da Google. Non impostare mcp_internal_dns_zone.domain su un suffisso non instradabile come mcp-server.internal. mentre enable_agent_gateway = true E enable_cloud_run_private_networking = true.

Agent Gateway al momento non convalida il certificato di riserva autofirmato. La configurazione Terraform lo applica con un blocco check in fase di pianificazione (ignorato quando il networking privato è disattivato, poiché non esiste alcun certificato LB da convalidare).

7. Esegui il deployment dell'infrastruttura con Terraform

Inizializza, rivedi e applica:

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

terraform apply esegue il provisioning di circa 40 risorse nel percorso predefinito e richiede 8-10 minuti in un nuovo progetto (circa 60 risorse / 15-20 minuti quando enable_cloud_run_private_networking = true). Crea:

• Fondamenta del progetto (API, identità di servizio, quote)
• VPC, subnet (principale, solo proxy, PSC, interfaccia PSC, colocation del gateway dell'agente), Cloud NAT, regole firewall
• Repository Artifact Registry per le immagini Cloud Run
• Tre servizi Cloud Run + SA di runtime per servizio (traffico in entrata = all per impostazione predefinita; internal-and-cloud-load-balancing quando è attivata la rete privata)
• Template Model Armor + IAM
• Agent Gateway, collegamento di rete PSC-I, estensioni IAP e Model Armor, entrambe le policy di autorizzazione e la concessione roles/iap.egressor a livello di progetto
• Endpoint del registry dell'agente (Vertex AI, IAP, Discovery Engine, ...) più i tre server MCP (registrati per impostazione predefinita su *.run.app/mcp; su ./mcp quando è attivata la rete privata)

Solo quando enable_cloud_run_private_networking = true:

• Bilanciatore del carico delle applicazioni regionale interno con NEG serverless (routing con maschera URL) + record A DNS privati
• Zona DNS privata MCP (mcp..) collegata al VPC
• Modulo della zona DNS pubblica (autorizzazioni DNS di Certificate Manager) + certificato regionale gestito da Google
• Zona DNS dell'interfaccia PSC (orfana quando non ci sono nomi host privati da risolvere, quindi è anche controllata dal flag principale)
• Peering DNS del gateway dell'agente per mcp.. (aggiunto automaticamente)

8. Esamina gli endpoint del registro degli agenti

Solo per riferimento. I comandi in questa sezione sono già stati eseguiti per te dal modulo agent-registry-endpoints di Terraform. Vengono mostrati in modo che tu possa vedere esattamente come appare la registrazione di un endpoint rilevabile da MCP.

Agent Registry è un catalogo di servizi per progetto (API di Google e i tuoi server MCP) che un agente rileva in fase di runtime. L'agente ipotecario lo legge all'avvio e associa gli strumenti in modo dinamico. Nessun URL MCP è incorporato nel codice dell'agente o nel relativo comando di deployment.

Endpoint

Cosa ha eseguito Terraform per tuo conto: per ogni API Google in agent_registry_google_apis, ha registrato cinque varianti (globale, globale mTLS, regionale, regionale mTLS, regionale REP). Ad esempio, per 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"

Server MCP

Terraform registra anche i tre server MCP per te. Per registrare altri server MCP, puoi seguire i passaggi della documentazione.

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 gli endpoint e i server MCP registrati.

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)"

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

9. Rivedi la configurazione di Agent Gateway

Solo per riferimento. Terraform ha già importato questo gateway dell'agente. Il codice YAML riportato di seguito è l'equivalente letterale di terraform/modules/agent-gateway/main.tf.

Agent Gateway è un piano di governance gestito da Google tra Agent Runtime e i tuoi strumenti. In modalità AGENT_TO_ANYWHERE è associato al registry degli agenti del progetto e il traffico in uscita avviene tramite un'interfaccia PSC di proprietà del cliente, in modo da poter raggiungere i server MCP privati nel tuo VPC.

Se importassi questo gateway manualmente, il codice YAML sarebbe simile al seguente:

# 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 il gateway creato da Terraform:

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

L'attuale terraform-provider-google-beta non espone ancora network_config.dns_peering_config. Terraform lo applica tramite un PATCH post-apply su networkservices.googleapis.com/v1beta1. Lo vedrai in terraform_data.dns_peering nel modulo.

10. Esamina l'autorizzazione IAP e Model Armor

Solo per riferimento. Terraform ha già creato entrambe le estensioni e entrambe le policy. I comandi riportati di seguito provengono direttamente da terraform/modules/agent-gateway/main.tf.

Agent Gateway delega l'autorizzazione alle estensioni di servizio. La demo copre due profili di norme:

• REQUEST_AUTHZ: valutato una volta per richiesta nella fase delle intestazioni. Utilizzato qui per chiamare IAP, che verifica se l'identità dell'agente chiamante dispone di roles/iap.egressor sul server MCP di destinazione.
• CONTENT_AUTHZ: trasmette gli eventi del corpo all'estensione per la sanificazione dei contenuti. Utilizzato qui per chiamare Model Armor, che esegue lo screening di prompt injection, jailbreak, violazioni RAI e (facoltativamente) PII tramite Sensitive Data Protection (SDP).

Estensione IAP REQUEST_AUTHZ

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}

Associalo al gateway dell'agente con un criterio 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"
        ]
      }
    }
  }'

Estensione CONTENT_AUTHZ di Model Armor

L'metadata.model_armor_settings dell'estensione contiene gli ID dei modelli di richiesta e risposta che Model Armor utilizza per valutare ogni callout:

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"
        ]
      }
    }
  }'

Modelli DLP personalizzati

sdpSettings.basicConfig di Model Armor utilizza un elenco di infoType integrato. Per un controllo più preciso (infoType personalizzati, mascheramento parziale, sostituzione surrogata, oscuramento in base alla probabilità), indirizza Model Armor ai tuoi modelli inspect e de-identify di Cloud DLP tramite sdpSettings.advancedConfig.

Crea un modello di ispezione che contrassegni i numeri di previdenza sociale statunitensi con una probabilità pari o superiore a POSSIBLE:

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 un modello di anonimizzazione che sostituisca ogni risultato con il token del tipo di informazioni (ad es. [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": {} }
          }]
        }
      }
    }
  }'

Poi, punta la configurazione della risposta di un modello Model Armor alla coppia tramite sdpSettings.advancedConfig (è qui che il modulo model_armor di Terraform imposterebbe advanced_config se lo hai configurato):

{
  "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"
      }
    }
  }
}

L'estensione Model Armor CONTENT_AUTHZ riportata sopra rileverà automaticamente questi modelli di configurazione avanzata la prossima volta che valuterà una risposta, senza necessità di modificare l'estensione. Assicurati che l'agente di servizio Model Armor (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) disponga di roles/dlp.user e roles/dlp.reader sul progetto (il modulo model-armor di Terraform concede già questi ruoli).

IAM egressor IAP (solo per server MCP)

Terraform non crea un'associazione roles/iap.egressor a livello di progetto nel registro dell'agente IAP implicito. L'associazione IAP REQUEST_AUTHZ effettivamente valutata è per server MCP e per motore di ragionamento, concessa dopo il deployment dell'agente e dopo che conosci l'ID agente. Il passaggio "Concedi l'uscita per server MCP all'agente" esegue scripts/grant_agent_mcp_egress.sh.

11. Crea ed esegui il deployment dei server MCP su Cloud Run

I file cloudrun/*.yaml.tmpl e skaffold.yaml.tmpl fanno riferimento a ${PROJECT_ID}, ${REGION} e ${MCP_INGRESS} (l'annotazione di ingresso di Cloud Run). Origine MCP_INGRESS da un output Terraform in modo che i manifest sottoposti a rendering rimangano sincronizzati con enable_cloud_run_private_networking, quindi esegui il rendering con envsubst:

Esporta la configurazione di Cloud Run Ingress.

• all
• internal-and-cloud-load-balancing (quando si utilizza l'approccio di rete privata)

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

Ogni servizio Cloud Run viene eseguito come service account di runtime per servizio creato da Terraform (ad es. mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Per eseguire il deployment come questi service account, devi disporre di roles/iam.serviceAccountUser:

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

Crea con Cloud Build ed esegui il deployment con Skaffold:

skaffold run

Skaffold crea tre immagini (legacy-dms, corporate-email, income-verification-api) nel repository Artifact Registry e aggiorna ogni servizio Cloud Run in modo che punti al nuovo digest.

Verifica:

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

Dovresti vedere tutti e tre i servizi con lo stato ACTIVE.

12. Esegui il deployment dell'agente per i mutui in Agent Runtime

Installa le dipendenze dell'agente ed esegui il deployment:

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

L'agente rileva gli strumenti MCP in fase di runtime elencando mcpServers in Agent Registry in projects/${PROJECT_ID}/locations/${REGION}.

Al termine dello script, copia reasoningEngines/ stampato nella shell:

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

13. Concedi l'uscita per agente per server MCP

L'estensione IAP REQUEST_AUTHZ autorizza ogni chiamata di strumenti controllando roles/iap.egressor dell'agente sul server MCP specifico o sull'endpoint che sta chiamando. Consulta Creare una policy in uscita da agente a server MCP.

Lo script (scripts/grant_agent_mcp_egress.sh) enumera i server MCP nel registro agent in projects/${PROJECT_ID}/locations/${REGION} e unisce un'associazione roles/iap.egressor per l'entità agente nei criteri IAM di ogni server (rispecchiando la semantica di gcloud add-iam-policy-binding).

Caso d'uso 1: concessione incondizionata con ambito limitato a server MCP specifici

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

Caso d'uso 2: concessione condizionale (CEL) limitata a un server MCP specifico

Per limitare l'agente a un sottoinsieme di strumenti su un singolo server MCP, associa una condizione IAM. L'Agent Gateway pubblica gli attributi per strumento che IAP REQUEST_AUTHZ espone a CEL, tra cui:

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

Limita l'agente agli strumenti di sola lettura su 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"

Dopo l'esecuzione, gli strumenti di scrittura su corporate-email restituiscono 403 PermissionDenied da IAP REQUEST_AUTHZ; gli strumenti di sola lettura continuano a funzionare.

Verifica i binding

Vai alla scheda Norme e vedrai l'elenco delle norme create in base agli endpoint e ai server MCP.

Altri casi d'uso:

Concessione incondizionata su ogni server MCP, limitata a un agente

Esegui questo comando dopo ogni nuovo deployment dell'agente. Senza filtro e senza condizione, l'agente denominato ottiene roles/iap.egressor su ogni server MCP nel registro:

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

14. Testare l'agente nella console Agent Platform

La console Agent Platform viene fornita con un ambiente di prova che ti consente di chattare direttamente con l'agente di cui è stato eseguito il deployment. È il modo più rapido per eseguire test di fumo delle chiamate di strumenti e ispezionare le tracce prima di collegare l'agente a Gemini Enterprise.

1. Apri la pagina Deployment della piattaforma dell'agente nella console Google Cloud.
2. Utilizza il campo Filtra se devi restringere l'elenco dei runtime, quindi fai clic sul runtime mortgage-agent.
3. Apri la scheda Playground.
4. Digita un prompt per chattare con l'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?

Dovrebbe restituire una risposta dallo strumento di gestione dei documenti e dallo strumento di verifica del reddito. Inoltre, i numeri di previdenza sociale devono essere oscurati in questa risposta. 5. Digita una domanda aggiuntiva:

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

L'agente deve identificare di non avere accesso allo strumento send_email e rispondere di conseguenza.

Poiché l'agente è stato implementato con l'instrumentazione OpenTelemetry, il Playground espone quattro visualizzazioni del riquadro laterale tra cui puoi passare mentre l'agente risponde:

• Traccia: tracce complete della conversazione, inclusi gli intervalli Agent Gateway, IAP REQUEST_AUTHZ e Model Armor CONTENT_AUTHZ
• Evento: un grafico degli strumenti richiamati e dei dettagli dell'evento per il turno corrente
• Stato: lo stato della sessione dell'agente e gli input/output dello strumento
• Sessioni: ogni sessione che hai avviato rispetto a questo runtime

Playground ignora completamente l'autenticazione di Gemini Enterprise, il che lo rende il modo più rapido per verificare che l'estensione IAP REQUEST_AUTHZ conceda correttamente le chiamate di strumenti. Se uno strumento restituisce 403 qui, esegui di nuovo scripts/grant_agent_mcp_egress.sh prima di eseguire il debug più in dettaglio.

15. Applica l'autorizzazione IAP

Ora che abbiamo convalidato il deployment, possiamo aggiornare la modalità di applicazione forzata di IAP a null per applicare le norme. Apri terraform.tfvars e aggiorna la modalità da DRY_RUN a null.

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

Applica la modifica.

terraform apply

Torna al Playground e riprova la conversazione.

1. Apri la pagina Deployment della piattaforma dell'agente nella console Google Cloud.
2. Utilizza il campo Filtra se devi restringere l'elenco dei runtime, quindi fai clic sul runtime mortgage-agent.
3. Apri la scheda Playground.
4. Digita un prompt per chattare con l'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?

Dovrebbe restituire una risposta dallo strumento di gestione dei documenti e dallo strumento di verifica del reddito. Inoltre, i numeri di previdenza sociale devono essere oscurati in questa risposta. 5. Digita una domanda aggiuntiva:

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

Se tutto è stato configurato correttamente, l'agente dovrebbe rispondere che non può inviare l'email a causa delle norme di autorizzazione.

16. Configurazione e test di Gemini Enterprise

Configurare Gemini Enterprise

Segui la guida introduttiva a Gemini Enterprise.

Registra il nostro agente ADK con Gemini Enterprise

Per registrare il nostro agente in Gemini Enterprise, segui i passaggi descritti qui.

1. Nella console Google Cloud, vai alla pagina Gemini Enterprise.
2. Seleziona l'app Gemini Enterprise in cui è registrato l'agente.
3. Apri l'URL mostrato nella sezione La tua app web Gemini Enterprise è pronta.
4. Seleziona la scheda Agente dal menu a sinistra per aprire la Galleria degli agenti.
5. Seleziona Agente assistente per i mutui e inizia a chattare.

Prova gli stessi prompt di Agent Runtime Playground:

Prompt iniziale:

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?

Domanda aggiuntiva:

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

Se torni alla sezione Deployment dell'agente nella console, seleziona il deployment dell'agente e vai alla scheda Tracce. Ora vedrai l'agente Gemini Assistant nello span che mostra la chiamata originata da Gemini Enterprise.

17. Risoluzione dei problemi e correzioni comuni

• terraform apply non riesce sul gateway dell'agente con il messaggio"resource is being created and therefore can not be updated": il progetto tenant del gateway impiega circa 30 secondi per stabilizzarsi prima che le policy di autorizzazione possano essere associate. Il modulo time_sleep.wait_for_gateway gestisce questa operazione; esegui di nuovo terraform apply.
• L'agente segnala "Nessun server MCP trovato" o si avvia solo con gli strumenti di utilità: conferma enable_agent_registry_endpoints = true in terraform.tfvars, poi:

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

  Dovresti vedere tre voci (una per ogni servizio Cloud Run MCP). Se l'elenco è vuoto, verifica che i servizi MCP siano raggiungibili dall'interno del VPC e che Agent Gateway abbia compilato il registry (lo fa in modo differito al primo elenco di strumenti proxy).
• Le chiamate agli strumenti restituiscono 403 PermissionDenied: esegui di nuovo scripts/grant_agent_mcp_egress.sh. La causa più comune è la mancata concessione di nuovo dopo il redeployment dell'agente (reasoningEngines/ cambia a ogni deployment).
• skaffold run non riesce con "autorizzazione negata per il service account": manca roles/iam.serviceAccountUser. Esegui di nuovo la concessione automatica nel passaggio precedente.
• Errori di peering DNS da Agent Gateway a MCP LB: verifica che agent_gateway_dns_peering_config.target_network corrisponda esattamente a projects/${PROJECT_ID}/global/networks/${VPC_NAME} e che ogni voce domains termini con un punto finale.
• terraform plan continua a voler aggiornare i tag delle immagini Cloud Run. Questo non dovrebbe accadere a causa della regola lifecycle { ignore_changes }. In caso affermativo, conferma di non aver modificato mcp_services[*].image in terraform.tfvars dopo il giorno skaffold run.

18. Esegui la pulizia

Il motore di ragionamento non è gestito da Terraform (viene creato dall'SDK ADK). Eliminalo manualmente:

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

Elimina tutto ciò che è stato creato da Terraform:

cd terraform
terraform destroy
cd ..

Se hai creato la zona DNS pubblica solo per questo codelab:

gcloud dns managed-zones delete agw-example-com

Infine, elimina il bucket di stato di Terraform:

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

19. Complimenti

Complimenti! Hai implementato correttamente la governance completa degli agenti per un agente ADK multi-strumento utilizzando Agent Gateway. Fungendo da control plane di rete centralizzato, Agent Gateway ti ha consentito di stabilire un percorso di uscita sicuro verso strumenti privati, applicare policy IAM granulari basate sull'identità tramite Identity-Aware Proxy e sanificare le interazioni con i contenuti utilizzando le protezioni integrate di Model Armor.

Cosa hai imparato

• Come eseguire il deployment e configurare Agent Gateway come livello di governance centrale per il traffico in uscita da Agent-to-Anywhere.
• Come integrare Agent Registry per il rilevamento di strumenti di runtime dinamici e controllati.
• Come scrivere e applicare criteri IAM basati su condizioni e per strumento per controllare rigorosamente i percorsi di esecuzione degli agenti.
• Come sfruttare le estensioni del servizio Agent Gateway per applicare le policy di Model Armor, intercettando e oscurando automaticamente il traffico sensibile dell'agente.

Documenti di riferimento

• Panoramica delle norme di governance degli agenti
• Documentazione del gateway dell'agente
• Documentazione sull'identità dell'agente
• Panoramica della piattaforma agentica Gemini Enterprise