Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Traffico in uscita da Agent Gateway da Agent Runtime a Google MCP

1. Introduzione

Questo codelab esplora la governance del traffico in uscita di Agent Gateway per gli agenti AI che accedono ai server Model Context Protocol (MCP) di Google Cloud remoti.

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 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
Agent Registry con endpoint API e MCP di Google
Criteri di autorizzazione con controllo dell'accesso IAM
Set di dati BigQuery su cui eseguire query utilizzando MCP

Fig. 1 Architettura del codelab

Cosa imparerai

Come eseguire il deployment di Agent Gateway in una sequenza di configurazione strutturata
Come eseguire la transizione delle policy di autorizzazione dalla modalità dry run alla modalità di applicazione forzata
Come registrare gli endpoint API di Google e i server MCP nel registry dell'agente
Come controllare i log di Agent Gateway per convalidare la governance in uscita

Cosa serve

Un progetto cloud 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

Quando esegui il deployment di Agent Gateway con controlli di governance, è importante seguire una sequenza di configurazione strutturata in modo che gli agenti abbiano accesso alle risorse necessarie durante l'inizializzazione e le richieste di rete vadano a buon fine.

Questo codelab utilizza la seguente sequenza di deployment:

Avvia in modalità di prova:se un runtime dell'agente è configurato per instradare le chiamate in uscita al gateway prima che venga eseguito il provisioning completo del gateway, l'inizializzazione del workload non andrà a buon fine. La configurazione dell'estensione di autorizzazione del gateway in modalità DRY_RUN garantisce che, quando il traffico dell'agente arriva al gateway, non vengano eliminate richieste.
Registra tutti i servizi:tutti gli agenti, i server MCP e gli endpoint che utilizzano Agent Gateway devono essere registrati in Agent Registry. Le richieste vengono rifiutate per qualsiasi origine o destinazione non registrata. Gli agenti di cui è stato eseguito il deployment su Agent Runtime e sui server Google MCP vengono registrati automaticamente. Qualsiasi endpoint API di Google o server MCP personalizzato deve essere registrato manualmente.
Applica le policy di autorizzazione:le policy di autorizzazione vengono utilizzate per consentire agli agenti registrati di accedere ai componenti agentic concedendo il ruolo roles/iap.egressor all'entità identità dell'agente e associandolo alla risorsa di registro di destinazione. Valuta il comportamento dell'agente utilizzando la modalità dry run, quindi definisci le policy per consentire il traffico in uscita scelto tramite il gateway. Una volta implementate le policy, passa alla modalità ENFORCED per consentire al gateway di applicare attivamente le policy di governance.

Fig. 2 Sequenza di deployment

Topologia di routing in uscita

I gateway in genere gestiscono il traffico in entrata (ingress) ai servizi di backend. Agent Gateway, che opera in modalità di uscita (da agente a ovunque), funge da proxy di uscita centralizzato e Zero Trust per i carichi di lavoro agentici.

Quando un'app AI o un carico di lavoro basato su agenti tenta di richiamare un'API o 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:

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 Cloud gestite, foundation model, endpoint MCP di Google (come BigQuery) e servizi di governance della piattaforma (Agent Registry e criteri IAP).

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

Questo Codelab si concentra sul traffico in uscita da un agente personalizzato in Agent Runtime che ha come target l'endpoint del server MCP remoto di Google per BigQuery.

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`	Esegui il provisioning di Agent Gateway
Service Extensions	`roles/serviceextensions.admin`	Configurare le estensioni di routing
Sicurezza di rete	`roles/networksecurity.admin`	Esegui il deployment delle policy 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`
BigQuery	`roles/bigquery.admin`	Configurare gli schemi e testare i set di dati
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

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 cloud di Google. 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:

Cloud Shell all'indirizzo shell.cloud.google.com o
Un terminale locale con l'interfaccia a riga di comando gcloud installata

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)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

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 \
  discoveryengine.googleapis.com

Con questo si conclude la parte di configurazione… passiamo ora alla sezione Gateway.

4. Gateway

Prima di applicare i controlli dell'accesso, implementa Agent Gateway e configura la relativa 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.

Agent Gateway utilizza un registro regionale per supportare le risorse di Agent Runtime regionali.

Crea gateway

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. Autorizzazione

L'estensione di autorizzazione di Agent Gateway per Identity-Aware Proxy (IAP) è un tipo di Service Extension utilizzata per delegare le decisioni di autorizzazione per tutte le comunicazioni di Agent Platform.

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 nel registry degli agenti. IAP restituisce una decisione ALLOW o DENY al gateway, che inoltra il traffico o lo blocca con un codice di stato HTTP 403 Forbidden.
Modalità di applicazione forzata: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.
Livello di binding:l'estensione del servizio è connessa ad Agent Gateway utilizzando una policy di autorizzazione configurata con il profilo REQUEST_AUTHZ.

Estensione autorizzazione

Crea un'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

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

# show authz extension details (verify extension state)
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

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

# show authz policy details (verify dry run mode)
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.

6. Codebase

Il codice dell'agente, il set di dati BigQuery e lo script di registrazione utilizzati per questo Codelab vengono gestiti in un repository GitHub di Google Cloud remoto. I passaggi seguenti cloneranno il repository localmente, copieranno i file necessari nella struttura della directory di lavoro corrente e poi puliranno i file temporanei non necessari.

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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Crea set di dati BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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.

7. 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. La modalità di uscita (agent-to-anywhere) di Agent Gateway utilizza il modello dei dati del registry 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 gli agenti utilizzando vari servizi e API di Google, viene utilizzato uno script per registrare rapidamente un insieme comune di endpoint API utilizzando nomi host e località di endpoints/googleapis.txt.

Registra endpoint

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Verifica gli endpoint

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

Con questo si conclude la parte del registro. Passiamo ora alla sezione Runtime.

8. Runtime

L'agente agent-dj ADK 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 univoca basata su SPIFFE per l'agente
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } per indirizzare tutto il traffico in uscita avviato dall'agente all'Agent Gateway per la valutazione e l'applicazione delle norme

Esegui il deployment dell'agente

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Verifica la voce del registro

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

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Verifica la configurazione del gateway

# verify agent gateway routing specification
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 ruoli IAM dell'agente per le risorse

Le concessioni di ruoli IAM per le risorse consentono all'identità principale dell'agente di accedere a BigQuery, agli strumenti MCP (per le API di Google) e ad altri servizi della piattaforma AI richiesti. Questi criteri vengono applicati utilizzando IAM a livello di risorsa.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# 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 i ruoli IAM dell'agente per le risorse

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

Con questo si conclude la parte relativa al runtime. Passiamo ora alla sezione Norme.

9. Norme

I criteri di autorizzazione per la governance degli agenti consentono il traffico da un agente AI tramite Agent Gateway e fino alla destinazione (ad es. l'endpoint del server MCP di Google Cloud per BigQuery). Una volta che il traffico raggiunge la destinazione, le normali autorizzazioni IAM autorizzano l'accesso ai dati (e sono state attivate nella sezione precedente).

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

Concedi ruoli IAM dell'agente per l'uscita del gateway dell'agente

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'insieme di entità che concede l'autorizzazione a tutte le identità degli agenti Agent Runtime nel progetto.

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, il criterio IAM è associato al livello registry, che applica l'autorizzazione a tutte le risorse secondarie.

Configura il criterio IAM del registro regionale IAP

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

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

10. Controlla

L'estensione di autorizzazione dell'Agent Gateway funziona in modalità DRY_RUN. Le richieste in uscita vengono osservate e registrate, ma non bloccate.

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-dj
Seleziona la scheda Playground.

In alternativa, esegui l'echo di questo comando del terminale e fai clic sul link per passare all'area giochi 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…

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

Verifica che le query restituiscano risposte valide (ad es. "Sono presenti 12 DJ nel file").

Analizzare gli audit log

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

# query gateway logs for dry run
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
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. Applica

L'agente è riuscito a effettuare richieste tramite il gateway in modalità DRY_RUN. Esegui la transizione dell'estensione di autorizzazione IAP dell'Agent Gateway alla modalità ENFORCE aggiornando la policy di autorizzazione.

Aggiornamento dell'estensione 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

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

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

Aggiorna 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

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

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

Invia un'altra query di test…

What DJ Fishfry's credit card number?

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

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

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

12. Esegui la pulizia

# delete agent
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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "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 storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
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}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. Conclusione

Complimenti! Hai eseguito il deployment e gestito correttamente le comunicazioni in uscita per un agente che accede agli strumenti utilizzando Agent Gateway.

cosmopup

Cosmopup pensa che i codelab siano il massimo!

Quali sono i passaggi successivi?

Consulta la documentazione di Gemini Enterprise Agent Platform per funzionalità avanzate e tutorial.
Configura i guardrail di Model Armor su Agent Gateway per una maggiore sicurezza dell'AI
Esplora le policy di governance semantica per applicare le regole aziendali e la conformità per le query in linguaggio naturale

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

Grazie.