Configura Agent Gateway

Per centralizzare controllo dell'accesso e proteggere la connettività nei tuoi workflow degli agenti, puoi configurare una risorsa Agent Gateway per gestire il traffico in entrata o in uscita.

Prima di configurare un gateway, consulta i concetti di base e i componenti principali nella panoramica di Agent Gateway.

Autorizzazioni obbligatorie

Per creare e gestire gli Agent Gateway sono necessarie le seguenti autorizzazioni. Puoi ottenere queste autorizzazioni con ruoli personalizzati o utilizzando altri ruoli predefiniti.

API obbligatorie

Abilita le seguenti API minime richieste nel progetto Cloud de Confiance in cui esegui il deployment di Agent Gateway:

• API Compute Engine (compute.googleapis.com): fornisce l'infrastruttura di networking di base, le subnet, il routing e i collegamenti di rete di Private Service Connect (PSC).
• API di sicurezza di rete (networksecurity.googleapis.com): crea e applica policy di autorizzazione (authzPolicies) per il traffico del gateway.
• API Network Services (networkservices.googleapis.com): gestisce le risorse Agent Gateway (agentGateways), i template di connettività (agentConnectivityTemplates) e le estensioni dell'autorizzazione (authzExtensions).
• API Identity and Access Management (iam.googleapis.com): gestisce i service account e le policy di accesso unificato (UAP) IAM per le identità degli agenti.
• API Identity-Aware Proxy (iap.googleapis.com): autentica e verifica il traffico di agenti, endpoint e server.
• API Agent Registry (agentregistry.googleapis.com): registra e gestisce agenti, server MCP ed endpoint degli strumenti regolati dal gateway.

Per abilitare le API minime richieste, esegui questo comando:

gcloud services enable \
    compute.googleapis.com \
    networksecurity.googleapis.com \
    networkservices.googleapis.com \
    iam.googleapis.com \
    iap.googleapis.com \
    agentregistry.googleapis.com \
    --project=PROJECT_ID

Sostituisci PROJECT_ID con l'ID progetto in cui esegui il deployment di Agent Gateway.

A seconda delle funzionalità, degli strumenti di osservabilità e degli Agent Runtime che utilizzi con Agent Gateway, potresti dover abilitare anche le API facoltative:

Pianifica il deployment di Agent Gateway

Utilizza questa sezione per pianificare il deployment di Agent Gateway e comprendere i requisiti dell'architettura di governance. Puoi rivedere questi passaggi quando registri nuove destinazioni, aggiungi nuove policy di controllo dell'accesso o esegui il deployment di altri agenti.

Scegli la modalità di deployment

Agent Gateway supporta due modalità di deployment:

• Da client ad agente (in entrata): protegge le comunicazioni dai client agli agenti in esecuzione su Cloud de Confiance.
• Da agente a qualsiasi destinazione (traffico in uscita): protegge le comunicazioni dagli agenti a target esterni, API pubbliche e server MCP.

Seleziona il runtime, il progetto e la regione di deployment

Agent Gateway gestisce il traffico degli agenti in esecuzione su Gemini Enterprise e Runtime.

• Agent Runtime: Agent Gateway supporta sia la modalità da agente a ovunque (in uscita) sia la modalità da client ad agente (in entrata). In modalità da agente a ovunque, gli agenti possono trovarsi nello stesso progetto del gateway o in un progetto diverso. In modalità client-agente, gli agenti devono trovarsi nello stesso progetto del gateway. In entrambe le modalità, gli agenti devono trovarsi nella stessa regione del gateway.

• Gemini Enterprise: Agent Gateway supporta solo la modalità Da agente a ovunque (in uscita). Con Gemini Enterprise, ogni gateway gestisce le interazioni degli agenti solo nell'ambito del progetto e della regione in cui è stato eseguito il deployment.

Per gestire gli agenti in Gemini Enterprise e Runtime, puoi utilizzare una singola istanza di Agent Gateway. In alternativa, puoi anche eseguire il deployment di istanze Agent Gateway indipendenti per Gemini Enterprise e Runtime.

Pattern di deployment di esempio

Ecco alcuni esempi di pattern di deployment da prendere in considerazione:

Governance tra progetti per gli agenti di runtime

In questo pattern di deployment, esegui il deployment di un Agent Gateway Agent-to-Anywhere (in uscita) in un progetto di governance dedicato. Il deployment degli agenti di runtime viene eseguito in progetti separati nella stessa regione del gateway e possono appartenere a qualsiasi cartella della tua organizzazione.

Per configurare la governance del traffico in uscita tra progetti, configura le seguenti risorse:

Nel progetto di governance centrale:

• Crea l'Agent Gateway. Assicurati che il gateway sia associato a un'istanza di Agent Registry.
• Registra gli agenti tra progetti insieme a tutti gli strumenti, i server o gli endpoint con il registry degli agenti collegato al gateway.
• Concedi le autorizzazioni IAM tra progetti all'agente di servizio di runtime di ogni progetto in cui si trovano gli agenti, in modo che gli agenti di questi progetti possano associarsi al gateway nel progetto di governance. Per un esempio, consulta Instrada il traffico di runtime tramite Agent Gateway.
• Configura le policy IAP, i confini di accesso delle entità e le Workload Identity compatibili con SPIFFE per gestire e proteggere il traffico in uscita verso gli endpoint autorizzati.
• Crea i template Model Armor che vuoi utilizzare per l'egress.
• Se vuoi eseguire il traffico in uscita verso una rete VPC, puoi creare il collegamento di rete PSC, i trust anchor TLS personalizzati (tlsConfig) per le CA private e la configurazione del peering DNS nel progetto di governance.

In Progetti di Agent Runtime:

• Esegui il deployment degli agenti e associali al gateway centrale nel progetto di governance.

Tieni presente che la governance tra progetti è supportata solo per il runtime con gateway Agent-to-Anywhere (in uscita); Gemini Enterprise non è supportato.

Governance condivisa per gli agenti Gemini Enterprise e Runtime

In questo pattern di deployment, tutto il traffico proveniente dalle app Gemini Enterprise e dagli agenti di runtime viene instradato tramite un unico Agent Gateway.

Ecco un esempio di deployment:

• L'app Gemini Enterprise viene implementata come deployment global.
• Il deployment degli agenti di runtime viene eseguito all'interno di una singola regione (us-central1) che corrisponde al deployment di Gemini Enterprise.
• Il deployment di Agent Gateway viene eseguito nella stessa regione (us-central1).
• Sia le istanze di Agent Registry global sia quelle di us-central1 possono essere associate ad Agent Gateway. Gli agenti e le destinazioni devono essere registrati con le istanze di Agent Registry associate al gateway.

Governance indipendente per gli agenti Gemini Enterprise e Runtime

In questo pattern di deployment, ogni regione ha un Agent Gateway dedicato per monitorare e gestire il traffico degli agenti, garantendo l'isolamento regionale:

• L'app Gemini Enterprise viene implementata come deployment globale o multiregionale (in global, us o eu).
• Gli agenti di runtime vengono distribuiti in ogni regione in cui sono necessari.
• Il deployment delle istanze di Agent Gateway viene eseguito in ogni regione in cui si trovano gli agenti e le app.
• Devi registrare gli agenti e le destinazioni nelle istanze di Agent Registry associate a ogni gateway.

Configura l'identità dell'agente

Ogni agente gestito da Agent Gateway richiede un'identità agente univoca (un ID SPIFFE). Poiché le policy di accesso IAM dipendono da questa Workload Identity, il traffico proveniente da agenti non identificati viene bloccato per impostazione predefinita.

Puoi eseguire il provisioning di un'identità agente quando esegui il deployment di un agente in Runtime o lo assegni ai workload degli agenti esistenti. Per istruzioni dettagliate, consulta Utilizza l'identità dell'agente con il runtime.

Registra gli agenti e le risorse di destinazione

Per abilitare la comunicazione sicura, devi identificare l'istanza del registry degli agenti e registrare le risorse che verranno gestite dal gateway.

1. Identifica le istanze di Agent Registry che utilizzerai. Un Agent Gateway può essere associato a un massimo di due registry (un registry globale e un registry regionale o multiregionale):

   • Gli agenti Agent Runtime sono risorse regionali e in genere vengono registrati in registri regionali corrispondenti alla regione di deployment. Tieni presente che gli agenti tra progetti devono essere registrati nel registry associato al progetto di governance centrale in cui è stato eseguito il deployment di Agent Gateway.
   • Gli agenti Gemini Enterprise sono risorse globali o multiregionali e sono registrati in registri globali o multiregionali (come global, us o eu).

   Assicurati che le istanze del registry associate ad Agent Gateway siano quelle in cui sono registrati gli agenti, gli endpoint e i server.

2. Registra i tuoi agenti con Agent Registry. Se non hai ancora creato l'agente, devi completare questo passaggio in un secondo momento. Per istruzioni, consulta Registra gli agenti.

3. Consigliato: identifica e registra tutti gli strumenti, i server MCP e gli endpoint API che i tuoi agenti chiameranno (incluse le API della piattaforma essenziali). L'accesso dell'agente alle destinazioni richiede sempre una policy di accesso IAM che conceda l'autorizzazione iap.resources.egressViaIAP all'identità dell'agente. Ti consigliamo di registrare le risorse in Agent Registry in modo da poter applicare policy granulari per risorsa e controlli a livello di strumento. Per le destinazioni non registrate, devi concedere questa autorizzazione all'agente configurando le policy per gli endpoint non registrati.

   Le destinazioni in un progetto diverso dal gateway devono essere registrate con Agent Registry nel progetto del gateway. Queste destinazioni sono valide solo per gli agenti di runtime in modalità Agent-to-Anywhere.

   Per istruzioni, consulta le seguenti guide:

   • Registra i server MCP
   • Registra gli endpoint

Configura le policy di controllo dell'accesso

Ogni Agent Gateway richiede una policy di autorizzazione associata.

IAM (solo modalità Da agente a ovunque)

Configura una policy IAM che assegni l'autorizzazione iap.resources.egressViaIAP all'entità dell'identità dell'agente per ciascuna delle risorse di destinazione registrate in Agent Registry.

Per impostazione predefinita, Agent Gateway blocca tutto il traffico, a meno che una policy di accesso IAM non autorizzi esplicitamente l'accesso dell'agente alle risorse di destinazione concedendo l'autorizzazione iap.resources.egressViaIAP all'identità dell'agente.

Ti consigliamo di registrare le destinazioni in Agent Registry perché ti consente di applicare l'ambito delle policy a risorse specifiche e di applicare controlli granulari degli strumenti. Se le destinazioni non sono registrate in Agent Registry, devi concedere l'autorizzazione iap.resources.egressViaIAP all'agente configurando una policy per gli endpoint non registrati.

Poiché i registry possono essere globali, multiregionali o regionali, assicurati che qualsiasi associazione a livello di registry corrisponda all'istanza (o alle istanze) del registry configurata per il tuo Agent Gateway.

Per le istruzioni, vedi Crea policy degli agenti IAM.

Per convalidare la configurazione senza bloccare il traffico, ti consigliamo di eseguire inizialmente il deployment di IAP in modalità dry run.

Model Armor

(Facoltativo) Se il tuo deployment richiede la protezione da attacchi di prompt injection, jailbreak, contenuti tossici o fughe di dati sensibili, devi pianificare l'integrazione dei guardrail di Model Armor e creare modelli con i filtri di sicurezza necessari.

Per saperne di più, consulta i seguenti documenti:

• Configura Model Armor su un gateway
• Delega l'autorizzazione utilizzando Service Extensions

Norme di governance semantica

(Facoltativo) Puoi scegliere di aggiungere controlli sensibili al contesto basati sul linguaggio naturale ai tuoi agenti per attivare protezioni contro combinazioni dannose di strumenti.

Ti consigliamo di iniziare implementando le norme di governance semantica in modalità dry run, in modo da poter convalidare la configurazione senza bloccare il traffico. Per maggiori dettagli, vedi Configura le policy di governance semantica.

Motori di autorizzazione personalizzati

(Facoltativo) Se vuoi delegare l'autorizzazione a motori di autorizzazione personalizzati o sistemi di terze parti utilizzando Service Extensions, devi assicurarti che i motori di autorizzazione personalizzati siano disponibili durante il deployment del gateway.

Model Armor, le norme di governance semantica e qualsiasi altro motore di autorizzazione personalizzato possono essere attivati durante la configurazione iniziale di Agent Gateway o collegati dopo il deployment come aggiornamento incrementale delle policy di sicurezza.

Configura Agent Gateway in modalità Da agente a ovunque (in uscita)

Quando configuri Agent Gateway in modalità Agent-to-Anywhere (traffico in uscita), puoi configurare il modo in cui il traffico regolamentato raggiunge gli endpoint e gli strumenti di destinazione. A seconda dei requisiti di networking e sicurezza, scegli tra le seguenti opzioni di deployment:

• Traffico in uscita verso internet: il gateway instrada in modo sicuro il traffico degli agenti verso endpoint e API accessibili pubblicamente su internet. Per configurare un Agent Gateway con traffico in uscita verso internet, puoi utilizzare le istruzioni riportate in questa pagina.

• Traffico in uscita dalla rete VPC: il gateway instrada il traffico degli agenti privatamente in una rete VPC utilizzando i collegamenti di rete di Private Service Connect. Puoi scegliere di instradare tutto il traffico attraverso la rete VPC (ALL_TRAFFIC) o solo il traffico destinato a intervalli di indirizzi IP privati (PRIVATE_RANGES_ONLY).

  Per configurare un Agent Gateway con traffico VPC in uscita, devi seguire le istruzioni riportate in Configura la connettività VPC per Agent Gateway.

Segui questi passaggi per creare una risorsa Agent Gateway per le comunicazioni Agent-to-Anywhere.

1. Una volta creato, un Agent Gateway funge da punto di connessione principale per il routing del traffico degli agenti all'interno del progetto e della regione scelta. Ora puoi utilizzare questo endpoint per stabilire canali di comunicazione sicuri, criptati e autenticati tra gli agenti e le loro destinazioni (strumenti, altri agenti o altri endpoint).

   Rivedi la sezione Pianifica il deployment di Agent Gateway in questa pagina e assicurati che i tuoi agenti siano registrati in Agent Registry e che al tuo agente sia stata concessa l'autorizzazione iap.resources.egressViaIAP per tutte le destinazioni a cui sta tentando di connettersi. Se riscontri problemi di connettività, consulta Risolvi i problemi di connettività di Agent Gateway.

Scopri poi come eseguire il deployment degli agenti e instradare il traffico tramite Agent Gateway.

Configura Agent Gateway in modalità da client ad agente (ingress)

Questa sezione mostra come configurare un Agent Gateway per le comunicazioni da client ad agente.

Per creare una risorsa Agent Gateway, segui questi passaggi.

resource "google_network_services_agent_gateway" "ingress_gateway" {
  project   = "PROJECT_ID"
  location  = "LOCATION"
  name      = "AGENT_GATEWAY_NAME"
  protocols = ["MCP"]

  google_managed {
    governed_access_path = "CLIENT_TO_AGENT"
  }
}

Una volta creato, un Agent Gateway funge da punto di connessione principale per il routing del traffico agli agenti nel tuo progetto e nella regione scelta.

Successivamente, scopri come eseguire il deployment degli agenti e instradare il traffico tramite Agent Gateway.

Esegui il deployment degli agenti e instrada il traffico tramite Agent Gateway

Per eseguire il deployment di un agente Agent Runtime che instrada il traffico tramite Agent Gateway, consulta Instrada il traffico tramite Agent Gateway.

Per eseguire il deployment di un agente Gemini Enterprise che instrada il traffico tramite Agent Gateway, consulta Instrada il traffico di Gemini Enterprise tramite Agent Gateway.

Codelab

Per dimostrazioni end-to-end su come configurare e utilizzare Agent Gateway, consulta i seguenti codelab:

• Gestisci i workload degli agenti con Agent Platform: scopri come eseguire il deployment di un agente ADK gestito su Agent Runtime.
• Traffico in uscita da Agent Gateway da Agent Runtime ai server MCP di Google Cloud: scopri come configurare Agent Gateway in modalità Agent-to-Anywhere per gestire le chiamate agentiche degli agenti ADK ai server MCP di Google Cloud.
• Traffico in uscita di Agent Gateway da Agent Runtime a server MCP esterni: scopri come configurare Agent Gateway in modalità Agent-to-Anywhere per gestire le chiamate agentiche degli agenti ADK ai server MCP esterni.
• Traffico in uscita da Agent Gateway da Agent Runtime alla rete VPC: scopri come configurare Agent Gateway in modalità Agent-to-Anywhere per gestire le chiamate agentiche degli agenti ADK alle destinazioni in una rete VPC.
• Governance di Agent Gateway per gli agenti Agent Runtime tra progetti: scopri come configurare Agent Gateway in modalità Agent-to-Anywhere per gestire gli agenti Agent Runtime tra progetti.
• Traffico in uscita privato di Agent Gateway da Gemini Enterprise: scopri come configurare la governance del traffico in uscita privato di Agent Gateway per Gemini Enterprise.

Passaggi successivi