Traffico in uscita di Agent Gateway da Agent Runtime alla rete VPC

1. Introduzione

Questo codelab esplora la governance del traffico in uscita di Agent Gateway per gli agenti di AI che accedono a endpoint remoti tramite una rete VPC privata. Agent Gateway che opera in modalità di uscita (da agente a ovunque) supporta la connettività privata a una rete VPC utilizzando le interfacce Private Service Connect (PSC). In questo scenario, Agent Runtime utilizza Agent Gateway per accedere a un server HTTP MCP trasmissibile remoto ospitato su Cloud Run utilizzando un endpoint Private Service Connect (PSC) per le API di Google nella rete VPC.

Le app di AI, dai chatbot autonomi ai sistemi autonomi con workflow multi-agente, possono richiamare dinamicamente strumenti esterni. Fornire agli agenti un accesso controllato per eseguire query sui database, recuperare contenuti web ed eseguire azioni è essenziale per agenti sicuri e produttivi. Tuttavia, negli ambienti aziendali, proteggere l'esecuzione degli strumenti dell'agente è una sfida. Se un agente ha accesso diretto alla rete, gli attacchi di prompt injection o le allucinazioni del modello possono indurre l'agente a esfiltrare dati sensibili o a eseguire comandi distruttivi.

Per gestire gli agenti autonomi su larga scala, Agent Gateway fornisce un punto di applicazione centralizzato e zero-trust integrato direttamente nell'architettura di Agent Platform. Anziché fare affidamento su implementazioni personalizzate uniche per ogni applicazione o codice dell'agente, Agent Gateway fornisce routing di rete, governance degli agenti e sicurezza di runtime applicata a livello di piattaforma.

Quando Agent Gateway funziona in modalità di uscita (agent-to-anywhere), funge da proxy per tutte le richieste in uscita dagli agenti configurati per utilizzare il gateway. Ogni richiesta di carico di lavoro dell'agente viene autenticata utilizzando l'identità dell'agente univoca e autorizzata utilizzando le norme di Identity-Aware Proxy (IAP). Le chiamate allo strumento MCP vengono decodificate e ispezionate dinamicamente per l'applicazione delle norme. Gli amministratori della sicurezza possono applicare in modo centralizzato autorizzazioni granulari per garantire che gli agenti possano richiamare solo endpoint e metodi approvati.

Cosa crei

  • Agent Gateway in modalità in uscita (da agente a ovunque)
  • Estensione di autorizzazione Identity-Aware Proxy (IAP)
  • Agente ADK di Agent Runtime con identità dell'agente
  • Server MCP HTTP di Cloud Run in streaming
  • Agent Registry con API di Google ed endpoint MCP personalizzati
  • Criteri di autorizzazione con controllo dell'accesso IAM
  • Risorse di rete VPC, zona Cloud DNS ed endpoint PSC per le API di Google
  • Collegamento di rete PSC per l'uscita di Agent Gateway
  • Regole delle policy firewall Cloud Next Generation Firewall (NGFW)

figure1

Fig. 1 Architettura del codelab

Cosa imparerai

  • Come eseguire il deployment di Agent Gateway in una sequenza di configurazione strutturata
  • Come configurare Agent Gateway con la connettività di rete VPC privata
  • Come eseguire la transizione delle policy di autorizzazione dalla modalità dry run alla modalità di applicazione
  • Come registrare gli endpoint API di Google e i server MCP in Agent Registry
  • Come controllare i log di Agent Gateway per convalidare la governance in uscita
  • Come convalidare il traffico in uscita di Agent Gateway utilizzando i log di Cloud NGFW

Cosa serve

  • Un progetto Google Cloud con la fatturazione abilitata
  • Autorizzazioni IAM per il provisioning di servizi di rete, set di dati BigQuery e risorse di Agent Platform
  • Una shell compatibile con POSIX (bash o zsh) con Google Cloud CLI (componenti gcloud e bq) installata
  • Strumenti a riga di comando: git, curl, jq (processore JSON), Python 3 e uv (gestore pacchetti Python)

2. Concetti

Sequenza di deployment

Questo codelab segue una sequenza di configurazione strutturata in modo che gli agenti abbiano accesso alle risorse necessarie all'inizializzazione e la connettività possa essere confermata prima di applicare i criteri di accesso applicati.

Questo codelab utilizza la seguente sequenza di deployment:

  1. Avvia in modalità DRY_RUN: assicurati che le richieste dell'agente arrivino correttamente al gateway e lo attraversino (modalità solo controllo).
  2. Registra tutti i servizi:registra tutti i componenti agentici nel registro degli agenti e conferma l'accesso agli strumenti dell'agente. Utilizza Cloud Logging e la dashboard di osservabilità di Agent Gateway per visualizzare le query a Agent Registry.
  3. Crea policy di autorizzazione:crea e applica policy di autorizzazione per consentire il traffico in uscita dagli agenti a server ed endpoint MCP.
  4. Passa alla modalità ENFORCED: aggiorna il criterio di estensione dell'autorizzazione per applicare i criteri e bloccare il traffico in uscita non autorizzato.

figure2

Fig. 2 Sequenza di deployment

Topologia di routing in uscita

L'uscita di Agent Gateway (da agente a ovunque) funge da proxy in uscita centralizzato e Zero Trust per i carichi di lavoro agentici. Quando un agente effettua una richiesta a un'API o a uno strumento esterno, la richiesta in uscita viene intercettata da Agent Gateway e valutata in base alle norme di governance prima di essere indirizzata alla destinazione. In un'architettura di Google Cloud Agent Platform, Agent Gateway fornisce la connettività del piano dati a:

  • Reti private (VPC): traffico in uscita che ha come target API aziendali interne, microservizi, database ospitati all'interno di VPC privati e reti on-premise o cross-cloud raggiungibili tramite connettività ibrida.
  • Reti esterne (internet): traffico in uscita che ha come target servizi web di terze parti, API SaaS o endpoint pubblici.
  • Servizi AI e Agent Platform:traffico in uscita che ha come target API Google Cloud gestite, modelli di base, endpoint MCP di Google (come BigQuery) e servizi di governance della piattaforma (Agent Registry e criteri IAP).

figure3

Fig. 3. Topologia di routing in uscita di Agent Gateway

Questo codelab si concentra sul traffico in uscita da un agente personalizzato su Agent Runtime che ha come target un endpoint PSC per le API di Google di cui è stato eseguito il deployment in una rete VPC. Questa architettura consente l'accesso privato al server MCP ospitato su Cloud Run utilizzando l'allegato di rete PSC per il traffico in uscita di Agent Gateway.

Connettività VPC

L'uscita di Agent Gateway (agent-to-anywhere) è in grado di connettersi a una rete VPC specificando networkConfig: egress: networkAttachment: [URI] nel file di configurazione YAML del deployment. Questa impostazione configura le regole di routing su Agent Gateway per inviare il traffico che si risolve in indirizzi IP privati tramite l'allegato di rete PSC nella rete VPC.

figure4

Fig. 4. Connettività VPC di Agent Gateway

Agent Gateway è in grado di risolvere i nomi host DNS privati utilizzando il peering Cloud DNS a un progetto di destinazione e a una rete VPC specificati. Tutte le zone private elencate nella configurazione dnsPeeringConfig: domains: [NAME] utilizzeranno i record Cloud DNS nel progetto di destinazione. Tutte le altre query DNS utilizzeranno il resolver pubblico Cloud DNS VPC predefinito.

Con questo si conclude la parte sui concetti. Passiamo ora alla sezione Configurazione.

3. Configurazione

Ruoli IAM richiesti

Per creare le risorse in questo Codelab sono necessari i seguenti ruoli:

Categoria

Ruolo IAM richiesto (ID)

Descrizione

Gestione delle API

roles/serviceusage.serviceUsageAdmin

Abilita i servizi API Google Cloud

Networking e gateway

roles/networkservices.admin

Provisioning di Agent Gateway

Service Extensions

roles/serviceextensions.admin

Configurare le estensioni di routing

Sicurezza di rete

roles/networksecurity.admin

Deployment dei criteri di autorizzazione

Agent Registry

roles/agentregistry.admin

Host consentiti del catalogo

Vertex AI e agenti

roles/aiplatform.admin

Esegui il deployment dei carichi di lavoro di Agent Runtime

Criteri in uscita

roles/iap.admin

Applica le norme di roles/iap.egressor

Cloud Storage

roles/storage.admin

Gestisci i bucket di staging del deployment

Log e revisione

roles/logging.viewer

Esaminare le tracce e i log di controllo

Cloud Run Developer

roles/run.developer

Esegui il deployment dei servizi Cloud Run

Artifact Registry Reader

roles/artifactregistry.reader

Estrai immagini container

Amministratore rete Compute

roles/compute.networkAdmin

Gestisci le risorse di networking VPC

DNS Administrator

roles/dns.admin

Gestire zone e record Cloud DNS

In alternativa, utilizza un ruolo di base generico come roles/admin o un ruolo legacy come roles/owner.

Accedere al progetto

Questo codelab utilizza un singolo progetto Google Cloud. I passaggi di configurazione utilizzano i comandi della shell Linux e dell'interfaccia a riga di comando gcloud.

Inizia accedendo alla riga di comando del tuo progetto Google Cloud:

Imposta l'ID progetto

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Autentica sessione

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Imposta le variabili di ambiente della shell

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Se esegui un'installazione autogestita di Google Cloud SDK (ovvero al di fuori di Cloud Shell), aggiorna i componenti all'ultima versione.

# update gcloud cli
gcloud components update

Abilitare i servizi API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

Con questo si conclude la parte di configurazione. Passiamo ora alla sezione Rete.

4. Rete

La rete VPC viene implementata utilizzando la modalità personalizzata per creare subnet regolari che supportano l'allegato di rete per Agent Gateway e l'uscita VPC diretta di Cloud Run.

L'endpoint PSC per le API di Google viene implementato utilizzando un singolo /32indirizzo IPv4 interno globale per supportare l'accesso interno privato a Cloud Run. Questo indirizzo IP non è assegnato da alcuna subnet regionale.

Creare reti

Crea una rete VPC globale.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Crea subnet per l'allegato di rete PSC di Agent Gateway e per l'uscita VPC diretta di Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Crea regole firewall

Crea una policy e una regola firewall per consentire tutto il traffico in uscita con la registrazione abilitata. Verrà utilizzato per monitorare il traffico in uscita da Agent Gateway alla rete VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

Crea collegamento di rete PSC

Crea un collegamento di rete PSC configurato per accettare automaticamente le nuove connessioni del produttore.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

Verifica il collegamento di rete PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Crea endpoint PSC

Crea una prenotazione di indirizzi IP per l'endpoint PSC globale. L'indirizzo utilizzato qui non può provenire da una subnet esistente né sovrapporsi a essa.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Crea un endpoint PSC per le API di Google utilizzando il bundle all-apis, che include Cloud Run (run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

Verifica l'endpoint PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

Crea zona DNS e record

Crea una zona gestita privata di Cloud DNS per il dominio run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Crea un record DNS jolly A per *.run.app. che punta all'indirizzo IP dell'endpoint PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Crea una policy Cloud DNS per abilitare il logging delle query DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Crea Cloud NAT

Crea un Cloud Router e Cloud NAT per supportare il traffico in uscita VPC diretto di Cloud Run per il server MCP per raggiungere i dati meteo esterni tramite la rete VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

Con questo si conclude la parte relativa alla rete. Passiamo ora alla sezione Gateway.

5. Gateway

Prima di applicare i controlli dell'accesso, implementa Agent Gateway e configura l'estensione di autorizzazione in modalità DRY_RUN. In questo modo, le chiamate agli strumenti in uscita vengono eseguite correttamente durante la registrazione dei risultati della valutazione a fini di audit.

In questo caso, Agent Gateway utilizza un registry regionale per supportare le risorse di runtime dell'agente regionali e specifica i campi networkConfig per il collegamento di rete PSC della rete VPC e la configurazione del peering DNS.

Crea gateway

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

Verifica gateway

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Verifica che esista un endpoint di connessione accettato.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

Con questo si conclude la parte relativa al gateway. Passiamo ora alla sezione Autorizzazione.

6. Autorizzazione

L'estensione di autorizzazione del gateway dell'agente per Identity-Aware Proxy (IAP) è un tipo di estensione di servizio utilizzata per delegare le decisioni di autorizzazione per tutte le comunicazioni della piattaforma dell'agente.

  1. Flusso di delega:quando un agente tenta di richiamare un endpoint esterno o un server MCP, indirizza la richiesta ad Agent Gateway. Anziché valutare l'accesso localmente, il gateway utilizza l'estensione di autorizzazione per inviare un callout al servizio di valutazione IAP. IAP valuta l'identità dell'agente (basata su SPIFFE) in base alla policy IAM della risorsa di destinazione in Agent Registry. IAP restituisce una decisione ALLOW o DENY al gateway, che inoltra il traffico o lo blocca con un codice di stato HTTP 403 Forbidden.
  2. Modalità di applicazione:in modalità DRY_RUN, IAP valuta le richieste e registra le decisioni in Cloud Logging senza bloccare il traffico. In modalità ENFORCE, qualsiasi richiesta da un agente non autorizzato o a una destinazione non registrata viene immediatamente bloccata.
  3. Livello di binding:l'estensione del servizio è connessa ad Agent Gateway utilizzando una policy di autorizzazione configurata con il profilo REQUEST_AUTHZ.

Estensione autorizzazione

Un'estensione di autorizzazione specifica il servizio del fornitore di sicurezza con le impostazioni di connettività e altri parametri che definiscono il funzionamento e l'integrazione del servizio con Agent Gateway.

Crea estensione di autorizzazione

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

Importa estensione di autorizzazione

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

Verifica l'estensione di autorizzazione

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Norme relative alle autorizzazioni

Una policy di autorizzazione associa il fornitore di sicurezza (IAP) alla risorsa gateway di destinazione e specifica il profilo di intercettazione (REQUEST_AUTHZ).

Crea policy di autorizzazione

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

Associa la policy di autorizzazione

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Verifica la policy di autorizzazione

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Con questo si conclude la parte relativa all'autorizzazione. Passiamo ora alla sezione Codebase.

7. Codebase

Il codice di registrazione dell'agente, del server MCP e dell'endpoint utilizzato per questo codelab viene gestito in un repository GitHub di Google Cloud remoto. I seguenti passaggi cloneranno il repository localmente, copieranno i file necessari nella struttura della directory di lavoro corrente e poi puliranno i file temporanei.

Viene creato un bucket di gestione temporanea dell'archiviazione per consentire ad Agent Runtime di caricare, compilare ed eseguire il deployment del codice dell'applicazione dell'agente pacchettizzato e dei relativi artefatti di dipendenza.

Recuperare artefatti remoti

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

Crea bucket di staging

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

Con questo si conclude la parte del codebase. Passiamo ora alla sezione Registro.

8. Registro

Agent Registry è un inventario centralizzato di tutti gli agenti, i server MCP e gli endpoint (API) nell'ecosistema dell'AI. È anche un catalogo che può essere utilizzato per elencare, cercare e scoprire altri strumenti e servizi registrati da utilizzare per le applicazioni di AI. Agent Gateway utilizza il modello di dati del registro come framework di governance per applicare il controllo dell'accesso in uscita. Le concessioni di ruoli IAM per gli agenti chiamanti dell'entità vengono controllate in base al criterio associato alla risorsa del registro.

Per eseguire il bootstrap dell'ambiente e supportare l'agente utilizzando vari servizi e API di Google, crea un unico servizio di endpoint del registro che raggruppi le interfacce API di base necessarie per questo lab. In questo modo sarà più facile gestire le norme di governance per i set di strumenti comuni che la maggior parte degli agenti utilizzerà.

Registra endpoint

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Verificare la registrazione dell'endpoint

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

Con questo si conclude la parte relativa al registro. Passiamo ora alla sezione Server MCP.

9. Server MCP

Concedi autorizzazioni IAM per il deployment

Concedi le autorizzazioni al service account Compute predefinito per supportare il deployment dei servizi Cloud Run dal codice sorgente.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Verifica le autorizzazioni IAM

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Esegui il deployment del server MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

Concedi autorizzazioni IAM per l'ingresso

Associa policy per l'accesso utente

Concedi le autorizzazioni all'account utente (self) per richiamare il server MCP ospitato di Cloud Run. Questo è necessario per eseguire lo script di generazione di toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

Verifica le autorizzazioni IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Crea un account di servizio personalizzato per la chiamata MCP

Crea un service account personalizzato per richiamare il server MCP ospitato da Cloud Run. Questo service account verrà utilizzato dall'agente per recuperare un token ID OIDC firmato da Google valido per accedere a Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Policy di binding per il service account

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

Verifica le autorizzazioni IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Concedi autorizzazioni IAM per l'autenticazione

Concedi i ruoli di rappresentazione del service account al service account Compute predefinito. In questo modo, l'agente, in esecuzione con le credenziali predefinite dell'applicazione (ADC), potrà generare token ID OIDC firmati da Google per conto del service account invoker personalizzato per autenticare le chiamate a Cloud Run.

Associa criteri per l'autenticazione

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

Verifica le autorizzazioni IAM

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Crea MCP toolspec

Quando registri manualmente un server MCP, devi includere un file di specifica dello strumento. Un file toolspec.json elenca tutti gli strumenti resi disponibili dal server MCP e consente ad altri utenti di scoprirli una volta registrati.

Lo script test_mcp.py, incluso nel codebase mcp-weather/, genera un file toolspec.json connettendosi al server MCP di destinazione (tramite SSE o HTTP) e chiamando list_tools() per recuperare tutti gli strumenti disponibili esposti dal server.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Un'occhiata all'output toolspec generato mostra gli attributi MCP che Agent Gateway può utilizzare per la valutazione e l'applicazione delle policy in uscita.

Verifica MCP toolspec

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Aggiorna l'ingresso Cloud Run

Modifica l'impostazione di ingresso per il servizio Cloud Run in modo che accetti solo le richieste in entrata dalla rete VPC. In questo modo si impedisce l'accesso pubblico diretto all'endpoint MCP e si consente l'accesso solo alle risorse interne. Il traffico destinato all'endpoint PSC per le API di Google nella rete VPC verrà considerato in entrata interno e consentito.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Verifica l'ingresso di Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

Registra server MCP

Ora, con l'toolspec a portata di mano, registra il server MCP con l'Agent Registry regionale.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

Verificare la registrazione MCP

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

Con questo si conclude la sezione del server MCP. Passiamo ora alla sezione dell'agente ADK.

10. Agente ADK

L'agente ADK agent-weather di cui è stato eseguito il deployment in Agent Runtime è configurato con le seguenti impostazioni nello script di deployment per l'integrazione con Agent Platform:

  • "identity_type": types.IdentityType.AGENT_IDENTITY per eseguire il provisioning di un'identità principale basata su SPIFFE univoca per l'agente
  • "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } per indirizzare tutto il traffico in uscita avviato dall'agente al gateway dell'agente per la valutazione e l'applicazione delle norme

L'agente è configurato anche per utilizzare il server MCP passando l'URL e il service account per recuperare il token ID OIDC.

Esegui il deployment dell'agente

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Verifica il deployment

Recupera i parametri vitali del deployment

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Verifica la voce del registro

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

Verifica la configurazione del gateway

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Concedi autorizzazioni IAM per l'autenticazione

Quando un agente è configurato per utilizzare Agent Identity, riceve un token (formato JWT-SVID) dal servizio token di sicurezza (STS) federato firmato da sts.googleapis.com (il provider di identità SPIFFE).

Tuttavia, il controllo dell'invoker IAM di Cloud Run integrato considera attendibili e può verificare solo i token ID OIDC standard firmati dall'emittente OIDC principale di Google (accounts.google.com).

Pertanto, un service account personalizzato viene utilizzato per scambiare il token STS federato (JWT-SVID) ottenuto dall'identità dell'agente con un token Google (OIDC) standard ottenuto utilizzando la rappresentazione del service account in fase di runtime.

Crea le associazioni di ruoli necessarie per il service account personalizzato.

Associa criteri per l'autenticazione (furto d'identità)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

Verifica le autorizzazioni IAM

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Concedi autorizzazioni IAM per il runtime

La concessione delle autorizzazioni IAM per il runtime consente all'agente di accedere ai servizi AI Platform e ad altre API e altri servizi Google di base utilizzando la sua identità principale dell'agente basata su SPIFFE. Questi criteri vengono applicati utilizzando IAM a livello di risorsa.

Crea le associazioni di ruoli necessarie per l'identità dell'agente.

Associare policy per l'accesso degli agenti

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Verifica le autorizzazioni IAM

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Con questo si conclude la parte relativa all'agente ADK. Passiamo ora alla sezione Norme.

11. Norme

Le policy di autorizzazione per la governance degli agenti consentono di instradare il traffico da un agente AI tramite Agent Gateway fino alla destinazione finale della risorsa (ad es. un endpoint server MCP privato per il recupero dei dati). Una volta che il traffico raggiunge la destinazione, le autorizzazioni regolari a livello di servizio o applicazione autorizzano l'accesso ai dati.

La concessione di ruoli IAM per l'uscita del gateway dell'agente abilita le policy di accesso che consentono all'identità dell'entità agente di accedere alle risorse di destinazione registrate tramite il gateway dell'agente. Le policy vengono applicate a livello di gateway dell'agente e convalidate utilizzando le policy IAM di Identity-Aware Proxy (IAP).

Concedi ruoli IAM per l'uscita di Agent Gateway

Agent Gateway controlla le richieste in entrata per convalidare che l'identità dell'agente chiamante disponga dell'autorizzazione iap.webServiceVersions.egressViaIAP (concessa dal ruolo roles/iap.egressor) sulla risorsa di destinazione.

La concessione di roles/iap.egressor all'identità dell'agente o al set di entità di Agent Runtime sulla risorsa di destinazione selezionata consente questo traffico in uscita. In questo codelab, il ruolo viene applicato all'entità agente, che concede l'autorizzazione all'identità dell'agente Agent Runtime specifica.

I criteri IAM sono associati alle risorse di destinazione come definito nel modello dei dati del registro agenti. La risorsa iap_web/agentRegistry rappresenta un livello "a livello di registro" nella gerarchia IAM. Dove agentRegistry funge da genitore per le singole risorse secondarie per agents, mcpServers e endpoints. In questo codelab, la policy IAM è associata ai livelli mcpServer ed endpoint, il che applica l'autorizzazione alle risorse secondarie specifiche.

Configura il criterio dell'agente per il server MCP

Crea una policy per l'agente sul server MCP

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

NOTA: etag: deve restituire il valore predefinito ACAB poiché non sono ancora state definite norme.

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

Associa la policy per l'agente al server MCP

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

Verifica le autorizzazioni IAM

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

Con questo si conclude la parte relativa alle norme. Passiamo ora alla sezione Audit.

12. Controlla

L'estensione di autorizzazione di Agent Gateway funziona in modalità DRY_RUN. Le richieste in uscita vengono osservate e registrate, ma non bloccate. L'analisi dei log prima di passare alla modalità ENFORCED confermerà quali criteri devono essere configurati per consentire il traffico previsto.

Testare le query dell'agente

Apri una finestra del browser nell'interfaccia utente della console Google Cloud e vai a:

  • Agent Platform → Agenti → Deployment → agent-weather
  • Seleziona la scheda Playground.

In alternativa, esegui l'echo di questo comando del terminale e fai clic sul link per passare al playground dell'agente:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Invia alcune query di test…

  • What is the weather like in London?
  • How warm is it in New York?

Verifica che le query restituiscano risposte valide.

Analizzare gli audit log

Visualizza i log e ispeziona le valutazioni delle policy dry run.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Configura la policy dell'agente per gli endpoint

Poiché le API di Google principali per agent-weather sono state registrate in un servizio endpoint collettivo nel registro (gapi.core.services), è necessaria una sola policy per concedere le autorizzazioni di uscita dell'agente per l'accesso all'endpoint.

Crea una policy per l'agente e l'endpoint

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Associa la policy per l'agente all'endpoint

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

Verifica le autorizzazioni IAM

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

Con questo si conclude la parte relativa al controllo. Passiamo ora alla sezione Applica.

13. Applica

L'agente è riuscito a effettuare richieste tramite il gateway in modalità DRY_RUN. I log di accesso e gli endpoint sono stati analizzati per creare un insieme di policy di governance che consentano il traffico in uscita necessario dall'agente. Ora esegui la transizione dell'estensione di autorizzazione IAP di Agent Gateway alla modalità ENFORCE aggiornando il criterio di autorizzazione.

Aggiornamento dell'estensione autorizzazione

Crea estensione di autorizzazione

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

Importa estensione di autorizzazione

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

Verifica l'estensione di autorizzazione

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Aggiorna policy di autorizzazione

Crea policy di autorizzazione

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

Associa la policy di autorizzazione

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Verifica la policy di autorizzazione

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Verifica applicazione

Torna all'area giochi dell'agente nell'interfaccia utente della console.

  • Fai clic sul pulsante "+ Nuova sessione" per creare una nuova sessione di chat.

Invia un'altra query di test…

  • What is the current temperature in Los Angeles?

Osserva che le richieste dell'agente al modello di base Gemini (${REGION}-aiplatform.googleapis.com/...) e all'endpoint del server MCP (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) vengono trasmesse con codici di stato HTTP 200 OK.

Analizzare i log del gateway

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Controlla che non siano presenti richieste bloccate. Cerca eventuali tentativi di uscita negati con codici di stato HTTP 403 Forbidden nei log di controllo del gateway.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Visualizza i log MCP di Agent Gateway e osserva come viene ispezionato il payload dell'applicazione MCP (JSON-RPC) per esporre i metadati del protocollo, inclusi gli strumenti in esecuzione.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Analizzare i log firewall

Visualizza i log per la priorità della regola dei criteri firewall di rete 1001.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Prendi nota della visualizzazione a livello di rete dei diversi percorsi del traffico:

  • Agent Gateway che comunica con le risorse di rete VPC interne utilizzando subnet-${REGION}-agw
  • Il server MCP ospitato su Cloud Run che effettua chiamate ad API meteo esterne utilizzando subnet-${REGION}-crun
TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

Analizzare i log DNS

Visualizza i log delle query DNS per le richieste risolte dalla zona DNS privata (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Tieni presente che le ricerche DNS per il servizio Cloud Run (mcp-weather...run.app) hanno origine dalla rete VPC utilizzando il peering DNS e vengono risolte correttamente nell'endpoint PSC interno per le API di Google (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

Con questo si conclude la parte relativa all'applicazione... passiamo ora alla sezione Pulizia.

14. Esegui la pulizia 

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

Con questo si conclude la parte di pulizia. Passiamo ora alla conclusione.

15. Conclusione

Complimenti! Hai eseguito correttamente il deployment di Agent Gateway e hai regolato il traffico in uscita dell'agente AI.

cosmopup

Cosmopup pensa che i codelab siano il massimo!

Quali sono i passaggi successivi?

Non esitare a inviare commenti, domande o correzioni utilizzando questo modulo di feedback.

Grazie.