Gestisci Agent Gateway

Questo documento descrive le attività di manutenzione post-deployment per le risorse Agent Gateway. Se non hai ancora creato un gateway, consulta Configura Agent Gateway.

Prima di iniziare

Prima di gestire le risorse di Agent Gateway, verifica i seguenti prerequisiti:

Visualizza e ispeziona i gateway

Puoi elencare le risorse di Agent Gateway in un progetto Google Cloude ispezionare la configurazione di un gateway, le estensioni collegate e i metadati di solo output.

Console

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

    Vai a Gateway

  2. Visualizza l'elenco dei gateway nel progetto selezionato.

  3. Fai clic sul nome di un gateway per aprire la relativa pagina dei dettagli:

    • Nella scheda Dettagli, esamina le sezioni Panoramica, Autorizzazione di accesso, AI Security, Estensioni di servizio e Configurazione VPC.
    • Nella scheda Osservabilità, esamina le metriche relative al traffico e alle policy del gateway. Per saperne di più, consulta Monitora il traffico di Agent Gateway.

gcloud

  • Elenca tutti i gateway in una regione specifica:

    gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID

    Sostituisci quanto segue:

    • LOCATION: la regione in cui viene eseguito il deployment dei gateway, ad esempio us-central1.
    • PROJECT_ID: l'ID del progetto Google Cloudche ospita i gateway.

  • Esamina la configurazione di un gateway specifico:

    gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Sostituisci AGENT_GATEWAY_NAME con il nome della risorsa Agent Gateway.

Impostazioni immutabili

La maggior parte delle configurazioni di Agent Gateway, come le istanze di Agent Registry associate e le policy di sicurezza e governance, può essere modificata in loco come descritto in Aggiorna un Agent Gateway. Tuttavia, alcune configurazioni di base sono immutabili e richiedono il deployment di un gateway sostitutivo. Prima di modificare i gateway, consulta la tabella seguente:

Impostazione Mutabilità Requisito o limitazione
Nome e regione del gateway Immutabile Per modificare il nome o la regione, esegui il deployment di un gateway sostitutivo.

Percorso di accesso regolato

(AGENT_TO_ANYWHERE o CLIENT_TO_AGENT)

 Immutabile Configurato al momento della creazione in googleManaged.governedAccessPath. Non può essere modificato in loco.

Collegamento di rete Private Service Connect

(networkAttachment)

 Immutabile dopo l'impostazione Una volta associato un collegamento di rete a un gateway, non è possibile modificarlo o rimuoverlo.

Modello di connettività dell'agente e peering Cloud DNS, configurazione del trust TLS e impostazioni di traffico in uscita VPC associati

 Modificabile in modo condizionale Puoi aggiornare la configurazione del gateway in modo che faccia riferimento a un modello di connettività diverso con nuove impostazioni, purché il nuovo modello faccia ancora riferimento allo stesso networkAttachment.

Sostituisci un gateway per modificare le impostazioni immutabili

Se devi modificare un'impostazione immutabile, ad esempio il collegamento di rete PSC associato al gateway, devi eseguire il deployment di un gateway sostitutivo ed eseguire la migrazione dei workload al nuovo gateway:

  1. Crea l'Agent Gateway sostitutivo e configura le relative policy di Identity and Access Management (IAM) e di autorizzazione. Per istruzioni, consulta Configura Agent Gateway.

  2. Aggiorna i workload per utilizzare il gateway sostitutivo:

    • App Gemini Enterprise: aggiorna il nome della risorsa gateway nelle impostazioni Sicurezza > Configurazione dell'app. Consulta Instrada il traffico di Gemini Enterprise tramite Agent Gateway.
    • Agenti Agent Runtime: all'interno di un singolo progetto e di una singola regione, tutti gli agenti Agent Runtime devono essere associati allo stesso gateway. Gli aggiornamenti in loco diretti da un gateway a un altro non sono supportati. Per eseguire la migrazione degli agenti:
      1. Assicurati che ogni agente associato indirizzi il 100% del traffico alla sua ultima revisione (trafficConfig.trafficSplitAlwaysLatest).
      2. Scollega tutti gli agenti nel progetto e nella regione dal gateway precedente impostando spec.deploymentSpec.agentGatewayConfig su {} utilizzando reasoningEngines.patch, quindi attendi il completamento di ogni operazione di aggiornamento.
      3. Chiama reasoningEngines.patch su ogni agente per impostare spec.deploymentSpec.agentGatewayConfig sul nome della risorsa del gateway sostitutivo. Per esempi di richieste, consulta Instrada il traffico di Agent Runtime tramite Agent Gateway.

  3. Dopo che tutti i workload hanno smesso di fare riferimento al gateway precedente, segui i passaggi descritti in Elimina un Agent Gateway per eliminare il gateway precedente.

Aggiorna un Agent Gateway

Puoi aggiornare alcune configurazioni di Agent Gateway direttamente nella console Google Cloud o utilizzando gcloud CLI per esportare la configurazione del gateway in un file YAML, apportare le modifiche e reimportare il file.

Aggiorna Agent Registry

Puoi aggiornare il registry degli agenti associato nella consoleGoogle Cloud o in gcloud CLI. Il gateway deve fare riferimento al singolo registry regionale corrispondente alla regione del gateway. Se il gateway è collegato a un'app Gemini Enterprise, deve mantenere un singolo registry corrispondente alla località dell'app.

Console

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

    Vai a Gateway

  2. Fai clic sul nome del gateway da aggiornare.

  3. Nella scheda Dettagli, nella sezione Panoramica, fai clic su Modifica registri.

  4. Seleziona il registro degli agenti regionale corrispondente alla regione in cui è stato eseguito il deployment del gateway, quindi fai clic su Salva.

gcloud

Esporta la configurazione del gateway in agent-gateway.yaml utilizzando gcloud network-services agent-gateways export, modifica registries, description o labels (rimuovendo i campi di solo output come createTime, updateTime, agentGatewayCard e selfLink) e importa nuovamente il file utilizzando gcloud network-services agent-gateways import come mostrato in Aggiorna il template di connettività del gateway.

Aggiorna il template di connettività

Puoi aggiornare il template di connettività di una risorsa Agent Gateway utilizzando gcloud CLI.

gcloud

  1. Crea un nuovo AgentConnectivityTemplate con le impostazioni di connettività aggiornate, assicurandoti che utilizzi lo stesso networkAttachment del gateway esistente. Per istruzioni dettagliate sulla sintassi e sulla configurazione dei template, consulta Configura Agent Gateway con connettività VPC.

  2. Esporta la configurazione del gateway esistente in un file YAML:

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

    Sostituisci quanto segue:

    • AGENT_GATEWAY_NAME: il nome del gateway da aggiornare.
    • LOCATION: la regione in cui è stato eseguito il deployment del gateway.
    • PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment del gateway.

  3. Nel file agent-gateway.yaml esportato, mantieni intatti i campi protocols, registries, description e labels esistenti, rimuovi i campi di solo output (createTime, updateTime, agentGatewayCard, selfLink) e aggiorna agentConnectivityTemplate in modo che faccia riferimento al nuovo template:

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero di progetto numerico in cui viene eseguito il deployment del gateway (agentConnectivityTemplate richiede il numero di progetto anziché l'ID progetto).
    • LOCATION: la regione del gateway.
    • AGENT_GATEWAY_NAME: il nome del gateway.
    • NEW_TEMPLATE_NAME: il nome del template di connettività sostitutivo.

  4. Importa di nuovo il file YAML aggiornato per applicare le modifiche:

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

  5. (Facoltativo) Elimina il template di connettività precedente al termine dell'aggiornamento del gateway:

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

Modifica le impostazioni IAP o i template Model Armor

Puoi modificare le impostazioni di applicazione di IAP e i template di Model Armor aggiornando le estensioni dell'autorizzazione collegate al gateway.

Console

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

    Vai a Gateway

  2. Fai clic sul nome del gateway da aggiornare.

  3. Nella scheda Dettagli, aggiorna le estensioni di sicurezza collegate:

    • Modifica la modalità di applicazione forzata di IAP: nella sezione Autorizzazione di accesso, accanto ad Autorizzazione di accesso, fai clic su Modifica autorizzazione di accesso. Seleziona Solo controllo (modalità dry run) o Applica policy, quindi fai clic su Salva.

    • Modifica i template di Model Armor: nella sezione AI Security, fai clic su Modifica template per le richieste accanto a Template per le richieste o su Modifica template per le risposte accanto a Template per le risposte. Seleziona il modello sostitutivo e poi fai clic su Salva.

gcloud

  1. Elenca le estensioni dell'autorizzazione nella regione del gateway per identificare il nome dell'estensione:

    gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID

    Sostituisci LOCATION con la regione del gateway e PROJECT_ID con l'ID progetto.

  2. Esamina la configurazione attuale dell'estensione:

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

    Sostituisci AUTHZ_EXTENSION_NAME con il nome della tua risorsa IAP o Model Armor AuthzExtension.

  3. Salva la specifica dell'estensione aggiornata in authz-extension.yaml, omettendo i campi di solo output come createTime e updateTime:

    • Per un'estensione IAP: includi iamEnforcementMode: "DRY_RUN" per la modalità di solo controllo o rimuovi iamEnforcementMode per applicare le policy:

      name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies

    • Per un'estensione Model Armor: aggiorna request_template_id e response_template_id in metadata.model_armor_settings:

      name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'

      Sostituisci quanto segue:

      • AUTHZ_EXTENSION_NAME: il nome della tua risorsa Model Armor AuthzExtension.
      • LOCATION: la regione del gateway.
      • MODEL_ARMOR_PROJECT_ID: l'ID progetto che ospita i template di Model Armor.
      • REQUEST_TEMPLATE_ID e RESPONSE_TEMPLATE_ID: gli ID dei template di richiesta e risposta.

      Assicurati che il account di servizio del gateway (agentGatewayCard.serviceExtensionsServiceAccount) disponga di roles/modelarmor.user su qualsiasi progetto di template appena referenziato, nonché di roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer sul progetto del gateway (vedi Delega l'autorizzazione).

  4. Importa il file YAML dell'estensione aggiornato:

    gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
 --source="authz-extension.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

Per collegare nuove policy di autorizzazione o modificare le regole di corrispondenza del traffico su un AuthzPolicy esistente, consulta Delega l'autorizzazione.

Disassocia i workload da un Agent Gateway

Prima di poter eliminare un Agent Gateway, devi annullare l'associazione di ogni app Gemini Enterprise e di ogni agente Agent Runtime che fa riferimento al gateway.

Disassociare un'app Gemini Enterprise

Puoi scollegare un Agent Gateway da un'app Gemini Enterprise nella console Google Cloud :

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Vai a Gemini Enterprise

  2. Fai clic sul nome dell'app associata al gateway.

  3. Fai clic su Sicurezza.

  4. Nella scheda Configurazione, in Configurazione di Agent Gateway, cancella il campo Nome risorsa Agent Gateway.

  5. Fai clic su Salva.

La disassociazione di un Agent Gateway interrompe il routing del traffico in uscita dell'app tramite il gateway. Gli agenti e i server Model Context Protocol (MCP) importati rimangono registrati in Agent Registry, ma l'app non può accedervi finché non colleghi nuovamente un gateway. Tieni presente che il nuovo gateway deve fare riferimento allo stesso Agent Registry.

Disassocia un agente Agent Runtime

La console Google Cloud e gcloud CLI non supportano la modifica delle associazioni del gateway di Agent Runtime. Per disassociare un Agent Gateway da un agente Agent Runtime di cui è stato eseguito il deployment mantenendo l'agente in esecuzione, puoi chiamare il metodo dell'API REST reasoningEngines.patch per cancellare spec.deploymentSpec.agentGatewayConfig:

  1. Assicurati che l'agente indirizzi tutto il traffico all'ultima revisione (trafficConfig.trafficSplitAlwaysLatest impostato su true o nessuna suddivisione manuale di trafficConfig configurata). La cancellazione o la modifica di un'associazione del gateway non va a buon fine se è attiva una suddivisione del traffico della revisione manuale e archivia in modo irreversibile tutte le revisioni precedenti. Per maggiori dettagli, consulta Agent Gateway e revisioni.

  2. Invia una richiesta PATCH al motore di ragionamento con updateMask=spec.deploymentSpec.agentGatewayConfig e un oggetto agentGatewayConfig vuoto ({}):

    curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
   "spec": {
     "deploymentSpec": {
       "agentGatewayConfig": {}
     }
   }
 }' \
 "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

    Sostituisci quanto segue:

    • REGION: la regione in cui è stato eseguito il deployment dell'agente.
    • PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment dell'agente.
    • RESOURCE_ID: l'ID risorsa dell'agente.

Elimina un Agent Gateway

Agent Gateway applica un monitoraggio rigoroso dei riferimenti per evitare policy di sicurezza orfane e percorsi di traffico degli agenti interrotti. L'eliminazione di un gateway non va a buon fine e il pulsante Elimina nella console Google Cloud rimane non disponibile se si verifica una delle seguenti condizioni:

  • Uno o più agenti Agent Runtime o app Gemini Enterprise fanno ancora riferimento al gateway.
  • Qualsiasi AuthzPolicy (per IAP, Model Armor o un provider personalizzato) o TelemetryPolicy ha ancora come target il gateway.
  • Un'operazione di aggiornamento della configurazione VPC è ancora in esecuzione sul gateway.

Completa i seguenti passaggi in sequenza per eliminare un Agent Gateway e ripulire le risorse associate:

Console

  1. Assicurati che nessuna app Gemini Enterprise o agente Agent Runtime faccia riferimento al gateway. Segui le istruzioni riportate in Scollega i workload da un Agent Gateway.

  2. Nella console Google Cloud , vai alla pagina Gateway.

    Vai a Gateway

  3. Fai clic sul nome del gateway che vuoi eliminare.

  4. Nella scheda Dettagli, rimuovi tutte le associazioni di policy che hanno come target il gateway:

    • Se viene visualizzata la sezione Autorizzazione di accesso, fai clic su Rimuovi, quindi conferma l'eliminazione. Questa azione elimina sia l'IAP AuthzPolicy sia il relativo AuthzExtension.
    • Se viene visualizzata la sezione AI Security, fai clic su Rimuovi e poi conferma l'eliminazione. Questa azione elimina sia Model Armor AuthzPolicy sia il relativo AuthzExtension.
    • Controlla la tabella Service Extensions. Se rimangono collegate risorse AuthzPolicy personalizzate, utilizza la scheda gcloud in questa procedura per eliminarle prima di continuare.

  5. Dopo aver rimosso tutte le associazioni delle policy e quando non è in corso alcun aggiornamento del VPC, fai clic su Elimina e conferma l'eliminazione.

  6. Verifica che il gateway non venga più visualizzato nell'elenco Gateway del tuo progetto.

  7. (Facoltativo) Esegui la pulizia delle risorse di connettività inutilizzate se non vengono utilizzate da altri gateway. Utilizza la scheda gcloud per eliminare AgentConnectivityTemplate ed elimina il collegamento di rete.

gcloud

  1. Assicurati che nessuna app Gemini Enterprise o agente Agent Runtime faccia riferimento al gateway. Segui le istruzioni riportate in Scollega i workload da un Agent Gateway.

  2. Rimuovi le policy di autorizzazione e le estensioni dell'autorizzazione:

    1. Elenca le policy di autorizzazione nella regione del gateway per trovare quelle il cui campo target.resources fa riferimento al tuo gateway e prendi nota di eventuali authzExtensions a cui viene fatto riferimento:

      gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"

      Sostituisci LOCATION con la regione del gateway e PROJECT_ID con l'ID progetto.

    2. Elimina ogni AuthzPolicy che ha come target il gateway:

      gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      Sostituisci AUTHZ_POLICY_NAME con l'ID di ogni policy di autorizzazione che ha come target il gateway (ad esempio, AGENT_GATEWAY_NAME-iap-authzpolicy o AGENT_GATEWAY_NAME-aisecurity-authzpolicy per le policy create dalla console).

    3. (Facoltativo) Dopo aver eliminato le risorse AuthzPolicy di riferimento, elimina tutte le risorse AuthzExtension non utilizzate da altre policy:

      gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      Sostituisci AUTHZ_EXTENSION_NAME con l'ID dell'estensione dell'autorizzazione inutilizzata.

  3. Elimina l'Agent Gateway:

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Sostituisci AGENT_GATEWAY_NAME con il nome del gateway da eliminare.

  4. Verifica che il gateway non venga più visualizzato nell'elenco dei gateway regionali:

    gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

  5. (Facoltativo) Non puoi eliminare un AgentConnectivityTemplate mentre è presente un riferimento da parte di un Agent Gateway. Dopo aver eliminato il gateway, elimina i template di connettività inutilizzati:

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Sostituisci CONNECTIVITY_TEMPLATE_NAME con il nome del template di connettività non utilizzato. Se non hai più bisogno del collegamento di rete Private Service Connect, delle zone DNS private di Cloud DNS o delle risorse TrustConfig di Certificate Manager sottostanti, consulta Elimina i collegamenti di rete.

Passaggi successivi

Guida

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

Guida

Scopri come monitorare Agent Gateway.

Guida

Scopri come configurare un Agent Gateway.

Risoluzione dei problemi

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