Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

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 raggiunge in modo sicuro gli 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 (uscita).

Controllo dell'accesso con Agent Gateway

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 monitorabile 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 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 i tuoi strumenti interni (server MCP) di cui è stato eseguito il deployment su Cloud Run:

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.
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 del servizio Agent Gateway per l'accesso basato sull'identità (IAM) e il controllo dei contenuti (Model Armor)
Traccia e convalida l'esecuzione end-to-end sicura 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 organizzazione)
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

Architettura end-to-end: da Gemini Enterprise ad Agent Runtime, ad Agent Gateway e ai server MCP su Cloud Run

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 Agent Gateway. Successivamente, 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 attiverai 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 di credito ipotecario come utente finale e verificherai l'esecuzione sicura e controllata utilizzando Cloud Trace.

Questo codelab è destinato agli ingegneri di piattaforma e di 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, quindi 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.

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"

5. (Facoltativo) Crea una zona Cloud DNS pubblica

Per impostazione predefinita, per questo lab Cloud Run ha la configurazione Ingress impostata su all e il registry degli agenti registra ogni server MCP al relativo URL pubblico *.run.app. Non sono necessari 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 Cloud DNS pubblica in modo che Certificate Manager possa convalidare il certificato del bilanciatore del carico.

Flusso di alto livello del networking privato

Flusso di alto livello dell'opzione di networking privato

Per utilizzare l'approccio di networking privato:

Crea la zona Cloud DNS pubblica. 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 né della zona pubblica né di quella privata.

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:admin@example.com"]

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

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 dell'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"

7. Esegui il deployment dell'infrastruttura con Terraform

Inizializza, rivedi e applica:

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

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 dell'Agent Gateway), 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 è attiva 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, ecc.) più i tre server MCP (registrati per impostazione predefinita su *.run.app/mcp; su ./mcp quando è attiva 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 di Agent Gateway per mcp.. (aggiunto automaticamente)

8. Esamina gli endpoint del registro degli agenti

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