Configura Agent Gateway

Per centralizzare controllo dell'accesso e proteggere la connettività nei tuoi flussi di lavoro 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.

Autorizzazioni obbligatorie

  • agentregistry.agents.list
  • agentregistry.endpoints.list
  • agentregistry.mcpServers.list
  • compute.networkAttachments.create
  • compute.networkAttachments.delete
  • compute.networkAttachments.get
  • compute.networkAttachments.list
  • compute.networkAttachments.update
  • compute.regionOperations.get
  • compute.regions.list
  • modelarmor.templates.list
  • networksecurity.authzPolicies.create
  • networksecurity.authzPolicies.delete
  • networksecurity.authzPolicies.get
  • networksecurity.authzPolicies.list
  • networksecurity.operations.get
  • networkservices.agentConnectivityTemplates.create
  • networkservices.agentConnectivityTemplates.delete
  • networkservices.agentConnectivityTemplates.get
  • networkservices.agentConnectivityTemplates.list
  • networkservices.agentConnectivityTemplates.update
  • networkservices.agentGateways.create
  • networkservices.agentGateways.createPolicyBinding
  • networkservices.agentGateways.delete
  • networkservices.agentGateways.deletePolicyBinding
  • networkservices.agentGateways.get
  • networkservices.agentGateways.list
  • networkservices.agentGateways.searchPolicyBindings
  • networkservices.agentGateways.update
  • networkservices.agentGateways.updatePolicyBinding
  • networkservices.agentGateways.use
  • networkservices.authzExtensions.create
  • networkservices.authzExtensions.delete
  • networkservices.authzExtensions.get
  • networkservices.authzExtensions.list
  • networkservices.authzExtensions.update
  • networkservices.authzExtensions.use
  • networkservices.operations.get
  • certificatemanager.trustconfigs.create
  • certificatemanager.trustconfigs.get
  • certificatemanager.trustconfigs.list
  • certificatemanager.trustconfigs.use

API obbligatorie

Abilita le seguenti API minime richieste nel progetto Google Cloud 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 API facoltative:

API facoltative per funzionalità

  • Connettività VPC privata e TLS:
    • API Cloud DNS (dns.googleapis.com): richiesta solo se configuri la connettività VPC con il peering DNS Cloud per la risoluzione dei domini privati.
    • API Certificate Manager (certificatemanager.googleapis.com): obbligatoria solo se configuri trust anchor TLS personalizzati (TrustConfig) quando ti connetti a backend privati che utilizzano CA private o certificati autofirmati.
  • Sicurezza dell'AI e filtro dei contenuti:
    • API Model Armor (modelarmor.googleapis.com): richiesta solo se attivi i guardrail di Model Armor per ispezionare e filtrare prompt injection, contenuti tossici e dati sensibili.
  • Osservabilità e controllo:
    • API Cloud Logging (logging.googleapis.com): acquisisce i log di accesso al gateway, i log di controllo della sicurezza e gli eventi di valutazione delle policy in modalità dry run.
    • API Cloud Monitoring (monitoring.googleapis.com): monitora l'integrità, la latenza, il throughput e i tassi di errore del gateway e configura gli avvisi operativi.
    • API Observability (observability.googleapis.com): fornisce dashboard operative e di osservabilità unificate per l'attività di agenti e gateway.
    • API Telemetry (telemetry.googleapis.com): raccoglie e trasmette in streaming la telemetria di runtime e le metriche sul rendimento tra i componenti della piattaforma.
    • API Cloud Trace (cloudtrace.googleapis.com): fornisce il tracciamento distribuito per ispezionare le richieste multi-hop tra agenti e backend.
  • Runtime degli agenti e governance semantica:
    • API Agent Platform (aiplatform.googleapis.com): obbligatoria nei progetti che ospitano agenti Agent Runtime o utilizzano norme di governance semantica.
    • API Discovery Engine (discoveryengine.googleapis.com): obbligatoria nei progetti che ospitano app e agenti Gemini Enterprise.
    • API Agent Identity (agentidentity.googleapis.com): obbligatoria solo se gestisci le credenziali in uscita con il gestore di autenticazione di Agent Identity o se visualizzi i provider di autenticazione di Agent Identity nella console Google Cloud .

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#39;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 Google Cloud.
  • 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 proveniente dagli 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à da client ad 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 un'unica 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 attraverso un unico Agent Gateway.

Ecco un esempio di deployment:

  • L'app Gemini Enterprise viene distribuita 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 dell'Agent Gateway viene eseguito nella stessa regione (us-central1).
  • L'istanza di Agent Registry us-central1 è associata ad Agent Gateway. Devi registrare gli agenti e le destinazioni in questa istanza di Agent Registry.
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 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 nell'istanza di Agent Registry regionale associata 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 di Agent Registry e registrare le risorse gestite dal gateway.

  1. Identifica l'istanza di Agent Registry regionale da utilizzare. Ogni Agent Gateway è associato a un singolo registry regionale (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION) nello stesso progetto e nella stessa regione in cui è stato eseguito il deployment del gateway:

    • Agent Runtime: fai riferimento al registry regionale nello stesso progetto e nella stessa regione in cui è stato eseguito il deployment di Agent Gateway. Registra gli agenti tra progetti nel registry regionale del progetto di governance centrale che ospita il gateway.
    • Gemini Enterprise: fai riferimento al registry regionale nello stesso progetto e nella stessa regione di Agent Gateway (us-central1 per le app global e us o europe-west1 per le app eu). Per maggiori dettagli, vedi Pianifica le mappature delle località e del registry degli agenti.

    Assicurati che l'istanza del registry regionale associata all'Agent Gateway sia quella in cui sono registrati gli agenti, gli endpoint e i server MCP.

  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 destinazioni in Agent Registry perché ti consente di applicare le 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. Assicurati che tutte le regole a livello di registry corrispondano all'istanza di Agent Registry regionale configurata per il tuo Agent Gateway.

    Le destinazioni in un progetto diverso da quello del gateway devono essere registrate in 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 guide seguenti:

Configura le policy di controllo dell'accesso

Ogni Agent Gateway Agent-to-Anywhere richiede una policy di autorizzazione collegata (AuthzPolicy). Senza una policy di autorizzazione collegata, un Agent Gateway Agent-to-Anywhere adotta una policy di negazione predefinita e blocca tutto il traffico in uscita.

I deployment di Agent Gateway da client ad agente non adottano una policy di negazione predefinita. Per questi gateway, il collegamento di una policy di autorizzazione CONTENT_AUTHZ, come Model Armor o una policy di governance semantica, è facoltativo e le richieste in entrata passano se non è collegata alcuna policy di autorizzazione.

IAM (solo modalità Da agente a ovunque)

Configura una policy di accesso utente IAM che assegni l'autorizzazione iap.resources.egressViaIAP all'entità dell'identità dell'agente per ciascuna delle risorse di destinazione o degli endpoint non registrati chiamati dall'agente. Tieni presente che Agent Gateway blocca tutto il traffico in uscita, a meno che un criterio di accesso utente IAM non autorizzi esplicitamente l'accesso dell'agente.

Puoi associare un criterio di accesso utente IAM in uno dei seguenti ambiti:

  • Un progetto: tutte le istanze di Agent Gateway nel progetto applicano la policy.
  • Un'istanza di Agent Gateway: solo l'istanza di Agent Gateway specifica applica la policy.

Per convalidare la configurazione senza bloccare il traffico, ti consigliamo di eseguire inizialmente il deployment di IAP in modalità dry run. Per le istruzioni, consulta Crea UAP IAM.

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:

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 eseguendo il deployment delle norme di governance semantica in modalità dry run, in modo da poter convalidare la configurazione senza bloccare il traffico. Per maggiori dettagli, consulta 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à Da agente a ovunque (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.

Console Google Cloud

  1. Nella console Google Cloud , vai alla pagina Agent Gateway.

    Vai a Gateway

  2. Fai clic su Aggiungi gateway.
  3. Inserisci un Nome.
  4. Nell'elenco Regione, seleziona una regione.
  5. In Modalità di deployment, verifica che sia selezionata l'opzione Gestito da Google.
  6. In Registri degli agenti, seleziona il registro regionale corrispondente alla regione di Agent Gateway. Per indicazioni, consulta Pianifica il deployment di Agent Gateway.
  7. Nell'elenco Percorso di accesso regolato, seleziona Da agente a ovunque (agente in uscita).
  8. Nella sezione Autorizzazione di accesso, scegli come viene gestito il traffico da IAP:

    • Per eseguire il deployment del gateway in modalità dry run, in cui il gateway consente tutto il traffico e genera solo audit log, seleziona Solo controllo (che imposta iamEnforcementMode: "DRY_RUN" sull'estensione dell'autorizzazione). Le policy IAM non vengono applicate da IAP in modalità dry run. Una volta acquisita sicurezza, puoi disattivare la modalità dry run per applicare le policy IAM.
    • Per bloccare le richieste che non hanno una policy IAM Allow esplicita, seleziona Applica policy (che scrive iamEnforcementMode: "ENFORCED" sull'estensione dell'autorizzazione durante la creazione di un gateway o rimuove iamEnforcementMode durante l'aggiornamento di un gateway esistente). Questa opzione è consigliata per gli ambienti di produzione.
    • In Modello di policy, seleziona Policy Unified Access Policies.
  9. (Facoltativo) Nella sezione Sicurezza AI, configura ulteriori misure di sicurezza:

    1. Per proteggere le interazioni dei modelli di AI con Model Armor, attiva Abilita Model Armor.
    2. Seleziona un template dall'elenco che si applica alle richieste in entrata al gateway.
    3. Per utilizzare un template diverso per le risposte, deseleziona Utilizza lo stesso template per richieste e risposte e seleziona un template dall'elenco.

  10. Fai clic su Aggiungi gateway.

gcloud

Puoi definire gli Agent Gateway in modo dichiarativo utilizzando YAML.

  1. Definisci la risorsa e salva la configurazione in un file YAML. Per questo esempio, utilizziamo my-agent-gateway-egress.yaml.

    name: AGENT_GATEWAY_NAME
    protocols:
      - MCP
    googleManaged:
      governedAccessPath: AGENT_TO_ANYWHERE
    registries:
      - AGENT_REGISTRY_PATH
    

    Sostituisci quanto segue:

    • AGENT_GATEWAY_NAME: il nome della risorsa Agent Gateway.
    • AGENT_REGISTRY_PATH: il percorso dell'istanza di Agent Registry regionale nello stesso progetto e nella stessa regione del gateway, formattato come //agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION. Per indicazioni, consulta Pianifica il deployment di Agent Gateway.
  2. Esegui questo comando per creare una risorsa Agent Gateway basata sulla specifica YAML:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
     --source="my-agent-gateway-egress.yaml" \
     --location=LOCATION
    

    Sostituisci LOCATION con la località in cui vuoi creare la risorsa Agent Gateway. Ad esempio, us-central1.

    Tieni presente che per Gemini Enterprise devi eseguire il deployment di Agent Gateway in una regione corrispondente alla località della tua app. Per le mappature delle località richieste, consulta Instrada il traffico di Gemini Enterprise tramite Agent Gateway.

  3. Crea e associa una policy di autorizzazione (AuthzPolicy) per applicare policy di controllo dell'accesso e governance centralizzate al traffico che passa attraverso l'Agent Gateway. Senza una policy di autorizzazione allegata, un Agent Gateway Agent-to-Anywhere adotta una policy di negazione predefinita e blocca tutto il traffico in uscita. I passaggi seguenti mostrano come configurare una policy di autorizzazione che utilizza IAP.

    1. Configura un'estensione dell'autorizzazione che rimanda a IAP. Definisci l'estensione in un file YAML, ad esempio iap-request-authz-extension.yaml. Utilizza i valori di esempio forniti:

      cat >iap-request-authz-extension.yaml <<EOF
      name: AUTHORIZATION_EXTENSION_NAME
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      

      Se vuoi eseguire il deployment dell'estensione in modalità dry run solo controllo per testare la policy di autorizzazione senza applicarla, puoi specificare il campo iamEnforcementMode all'interno del blocco metadata. In questo modo puoi verificare la policy e ridurre al minimo il rischio di interruzione del traffico a causa di errori di configurazione:

      cat >iap-request-authz-extension.yaml <<EOF
      name: AUTHORIZATION_EXTENSION_NAME
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        iamEnforcementMode: "DRY_RUN"
      EOF
      

      Rimuovi il campo iamEnforcementMode: "DRY_RUN" dal blocco metadata quando vuoi iniziare ad applicare le policy. Per istruzioni su come controllare le violazioni in modalità dry run nei controlli prima di attivare l'applicazione, consulta Controlla le violazioni delle policy in modalità dry run nei controlli.

    2. Importa il file di configurazione YAML in un'estensione dell'autorizzazione.

      gcloud beta service-extensions authz-extensions import AUTHORIZATION_EXTENSION_NAME \
        --source=iap-request-authz-extension.yaml \
        --location=LOCATION
      

      Sostituisci AUTHORIZATION_EXTENSION_NAME con il nome dell'estensione dell'autorizzazione, ad esempio my-iap-request-authz-ext.

    3. Definisci una policy di autorizzazione in un file YAML, ad esempio iap-request-authz-policy.yaml, per associare l'estensione al gateway:

      cat >iap-request-authz-policy.yaml <<EOF
      name: AUTHORIZATION_POLICY_NAME
      target:
        resources:
          - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: REQUEST_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
            - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHORIZATION_EXTENSION_NAME"
      EOF
      

      Sostituisci quanto segue:

      • AUTHORIZATION_POLICY_NAME: il nome della policy di autorizzazione, ad esempio my-iap-request-authz-policy
      • PROJECT_ID: l'ID progetto
    4. Importa il file di configurazione YAML in una policy di autorizzazione.

      gcloud network-security authz-policies import AUTHORIZATION_POLICY_NAME \
        --source=iap-request-authz-policy.yaml \
        --location=LOCATION
      
  4. (Facoltativo) Se vuoi configurare le protezioni di Model Armor per proteggere il tuo deployment da attacchi di prompt injection e fughe di dati sensibili, consulta Delega l'autorizzazione a Model Armor.

Terraform

Per eseguire il provisioning di un Agent Gateway Agent-to-Anywhere (in uscita) e della relativa estensione dell'autorizzazione IAP e della policy in modo dichiarativo in un progetto di governance centrale utilizzando il provider google, completa i seguenti passaggi.

  1. Crea la risorsa google_network_services_agent_gateway e associa l'istanza di Agent Registry regionale:

    resource "google_network_services_agent_gateway" "egress_gateway" {
      project   = "PROJECT_ID"
      location  = "LOCATION"
      name      = "AGENT_GATEWAY_NAME"
      protocols = ["MCP"]
    
      google_managed {
        governed_access_path = "AGENT_TO_ANYWHERE"
      }
    
      registries = [
        "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION",
      ]
    }
    
  2. Configura IAP google_network_services_authz_extension e collegalo al gateway con un google_network_security_authz_policy:

    resource "google_network_services_authz_extension" "iap_request_authz_ext" {
      project   = "PROJECT_ID"
      location  = "LOCATION"
      name      = "my-iap-request-authz-ext"
      service   = "iap.googleapis.com"
      timeout   = "1s"
      fail_open = false
    
      metadata = {
        iapPolicyVersion = "V2"
        # Uncomment the following line to deploy in dry-run (audit-only) mode:
        # iamEnforcementMode = "DRY_RUN"
      }
    }
    
    resource "google_network_security_authz_policy" "iap_request_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-iap-request-authz-policy"
      policy_profile = "REQUEST_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          google_network_services_agent_gateway.egress_gateway.id
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.iap_request_authz_ext.id
          ]
        }
      }
    }
    
  1. Dopo aver creato un Agent Gateway, questo funge da punto di connessione principale per il routing del traffico degli agenti all'interno del progetto e della regione scelti. Ora puoi utilizzare questo endpoint per stabilire canali di comunicazione sicuri, crittografati 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.

Successivamente, scopri 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.

Console Google Cloud

  1. Nella console Google Cloud , vai alla pagina Agent Gateway.

    Vai a Gateway

  2. Fai clic su Aggiungi gateway.
  3. Inserisci un Nome.
  4. Nell'elenco Regione, seleziona una regione.
  5. In Modalità di deployment, verifica che sia selezionata l'opzione Gestito da Google.
  6. Lascia invariata l'impostazione Agent registry. Il registry non viene utilizzato per l'ingress.
  7. Dall'elenco Percorso di accesso regolato, seleziona Da client ad agente (traffico in entrata).
  8. (Facoltativo) Nella sezione AI Security, configura ulteriori misure di sicurezza:

    1. Per proteggere le interazioni dei modelli di AI con Model Armor, attiva Abilita Model Armor.

    2. Seleziona un template dall'elenco che si applica alle richieste in entrata al gateway.

    3. Per utilizzare un template diverso per le risposte, deseleziona Utilizza lo stesso template per richieste e risposte e seleziona un template dall'elenco.

  9. Fai clic su Aggiungi gateway.

gcloud

Puoi definire gli Agent Gateway in modo dichiarativo utilizzando YAML.

  1. Definisci la risorsa e salva la configurazione in un file YAML. Per questo esempio, utilizziamo my-agent-gateway-ingress.yaml.

    name: AGENT_GATEWAY_NAME
    protocols:
      - MCP
    googleManaged:
      governedAccessPath: CLIENT_TO_AGENT
    

    Sostituisci AGENT_GATEWAY_NAME con un nome per la risorsa Agent Gateway.

  2. Esegui questo comando per creare una risorsa Agent Gateway in base alla specifica YAML:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
     --source="my-agent-gateway-ingress.yaml" \
     --location=LOCATION
    

    Sostituisci LOCATION con la località in cui vuoi creare la risorsa Agent Gateway. Ad esempio, us-central1.

Terraform

Per eseguire il provisioning di una risorsa Agent Gateway da client ad agente (in entrata) in modo dichiarativo utilizzando il provider google:

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 l'instradamento 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:

Passaggi successivi

Guida

Scopri come instradare il traffico di Agent Runtime tramite Agent Gateway per una connettività sicura e controllata.

Guida

Scopri come delegare l'autorizzazione per Agent Gateway a IAP, Model Armor o al tuo servizio di autorizzazione personalizzato.

Guida

Scopri come visualizzare, aggiornare, dissociare ed eliminare le risorse Agent Gateway.

Guida

Scopri come monitorare Agent Gateway.

Risoluzione dei problemi

Scopri come risolvere i problemi di connettività di Agent Gateway.

Guida

Scopri come instradare il traffico di Gemini Enterprise tramite Agent Gateway.