Instradare il traffico di Gemini Enterprise tramite Agent Gateway

Questa pagina descrive come instradare il traffico di Gemini Enterprise tramite Agent Gateway. Agent Gateway è un componente centrale di networking e sicurezza dell'ecosistema Gemini Enterprise Agent Platform. Fornisce una connettività sicura e controllata per tutte le interazioni agentiche, che avvengano tra utenti e agenti, tra agenti e strumenti o tra gli agenti stessi.

Prima di iniziare

  • Assicurati di avere familiarità con i concetti di Gemini Enterprise.
  • Scopri di più su Agent Gateway. Tieni presente che Agent Gateway supporta solo Gemini Enterprise in modalità Agent-to-Anywhere (traffico in uscita). Il traffico in entrata non è supportato.
  • Esegui il deployment di un'app Gemini Enterprise (indicata anche come motore). La procedura descritta in questa pagina presuppone che tu abbia già eseguito il deployment di un'app. Per maggiori dettagli, consulta Crea un'app.

Pianifica le mappature delle località e di Agent Registry

Prima di eseguire il deployment di Agent Gateway, scegli la regione in cui eseguire il deployment del gateway e l'Agent Registry in cui registrare le tue risorse. Tieni presente i seguenti requisiti:

  • Mappatura della località: esegui il deployment di Agent Gateway nella regione specifica che corrisponde alla località dell'app Gemini Enterprise per garantire un routing corretto.

  • Mappatura del registry: associa l'Agent Gateway all'istanza Agent Registry regionale nello stesso progetto e nella stessa regione del gateway. Per ulteriori indicazioni sui pattern di deployment, consulta Pianifica il deployment di Agent Gateway.

Tabella: mappature della posizione dell'app Gemini Enterprise e del registro degli agenti
Posizione dell'app Gemini Enterprise Regione Agent Gateway obbligatoria Istanza Agent Registry richiesta per Agent Gateway
global us-central1 us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
us us-central1 us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
eu europe-west1 europe-west1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/europe-west1)

Instrada il traffico di Gemini Enterprise tramite Agent Gateway

Per instradare il traffico di Gemini Enterprise tramite Agent Gateway, segui questi passaggi:

  1. Crea una risorsa Agent Gateway e assicurati di rispettare la regione e il registry selezionati nella sezione precedente. Per le istruzioni, consulta Configura Agent Gateway.

    Verifica la configurazione del gateway. Utilizza l'API Network Services per recuperare la configurazione dell'Agent Gateway e ispezionare le impostazioni.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"

    Ecco un esempio di output per un gateway configurato correttamente:

    {
  "name": "projects/my-ge-project/locations/us-central1/agentGateways/my-egress-gateway",
  "description": "A full configuration for Agent Gateway for Gemini Enterprise egress",
  "googleManaged": {
    "governedAccessPath": "AGENT_TO_ANYWHERE"
  },
  "protocols": [
    "MCP"
  ],
  "registries": [
    "//agentregistry.googleapis.com/projects/my-ge-project/locations/us-central1"
  ]
}

  2. Associa il gateway alla tua app Gemini Enterprise utilizzando l'API UpdateEngine. Tieni presente che il completamento di questo passaggio instrada immediatamente tutto il traffico degli agenti esistente attraverso l'Agent Gateway specificato.

    Console

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

      Gemini Enterprise

    2. Fai clic sul nome dell'app che vuoi associare a un Agent Gateway.

    3. Fai clic su Sicurezza.

    4. Nella scheda Configurazione, in Configurazione di Agent Gateway, inserisci il nome completo della risorsa per il gateway. Utilizza il formato: projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME.

    5. Fai clic su Salva.

    REST

    1. Utilizza la seguente richiesta per aggiornare l'app.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
-d '{
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
    }
  }
}' \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name"

      Sostituisci quanto segue:

      • PROJECT_ID: l'ID progetto
      • AGENT_GATEWAY_REGION: la regione dell'Agent Gateway.
      • AGENT_GATEWAY_NAME: il nome dell'Agent Gateway.
      • ENDPOINT_LOCATION: il prefisso multiregionale per l'endpoint API che corrisponde a GE_APP_LOCATION. Specifica global, us o eu. Ad esempio, le app eu utilizzano eu-discoveryengine.googleapis.com. Per le app global, è supportato anche discoveryengine.googleapis.com senza prefisso.
      • PROJECT_NUMBER: il numero del progetto.
      • GE_APP_LOCATION: la posizione dell'app Gemini Enterprise. Specifica global, us o eu.
      • GE_APP_ID: l'ID dell'app Gemini Enterprise.

    2. Per verificare la configurazione dell'app, utilizza il comando seguente per recuperare la configurazione e ispezionare le impostazioni:

      curl -s -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID" \
| jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'

      Sostituisci quanto segue:

      • PROJECT_ID: l'ID progetto
      • ENDPOINT_LOCATION: il prefisso multiregionale per l'endpoint API che corrisponde a GE_APP_LOCATION. Specifica global, us o eu.
      • PROJECT_NUMBER: il numero del progetto.
      • GE_APP_LOCATION: la posizione dell'app Gemini Enterprise. Specifica global, us o eu.
      • GE_APP_ID: l'ID dell'app Gemini Enterprise.

      Ecco un esempio di output per un'app configurata correttamente:

      {
"name": "projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID",
"displayName": "GE_APP_ID",
"agentGatewaySetting": {
  "defaultEgressAgentGateway": {
    "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
  }
}
}

  3. Anche se la governance del traffico in uscita è ora abilitata per la tua app Gemini Enterprise, l'app non sa automaticamente con quali risorse esterne nel registro degli agenti può interagire.

    Devi importare esplicitamente gli agenti, gli endpoint e i server MCP scelti nella tua app Gemini Enterprise. La risorsa importata deve essere indicata utilizzando il nome esatto della risorsa basato sul registry. Per istruzioni, consulta le guide seguenti:

  4. Per verificare che il traffico in uscita funzioni correttamente, segui questi passaggi:

    1. Apri l'applicazione web Gemini Enterprise.
    2. Invia una query progettata per attivare uno strumento esterno (ad esempio, "Forniscimi un elenco di problemi recenti da GitHub").
    3. Monitora l'esecuzione per assicurarti che la risposta venga recuperata correttamente. Dietro le quinte, l'agente Gemini Enterprise pacchettizza la richiesta, la instrada tramite l'Agent Gateway (che applica le policy di autorizzazione configurate) e recupera la risposta dalla destinazione.

Limita l'associazione di Gemini Enterprise agli Agent Gateway approvati

Puoi creare vincoli delle policy dell'organizzazione personalizzati per limitare la possibilità per un'app Gemini Enterprise di eseguire il binding a uno o tutti gli Agent Gateway.

Crea vincoli personalizzati delle policy dell'organizzazione

Questo esempio crea un vincolo personalizzato che blocca tutti i binding tra le app Gemini Enterprise e gli Agent Gateway.

Da agente a ovunque

  1. Per definire un vincolo personalizzato per la modalità Da agente a ovunque (traffico in uscita), crea un file denominato constraint-agent-gateway-egress.yaml.

    L'esempio seguente mostra come applicare un isolamento di rete rigoroso non consentendo alcuna associazione. Il campo condition specifica che l'operazione viene negata se viene specificata una risorsa Agent Gateway (il campo è presente e non vuoto).

    name: organizations/ORGANIZATION_ID/customConstraints/custom.disallowGeminiEnterpriseAgentGatewayBinding
resource_types:
    


      

    • discoveryengine.googleapis.com/Engine
condition: >-
has(resource.agentGatewaySetting.defaultEgressAgentGateway.name) &&
resource.agentGatewaySetting.defaultEgressAgentGateway.name != ''
actionType: DENY
displayName: "Disallow all Agent Gateway Bindings for Discovery Engines"
description: "To enforce strict network isolation, Discovery Engines are not permitted to bind to any Agent Gateway."

    2. Sostituisci quanto segue:

    • ORGANIZATION_ID: ID organizzazione.
    • PROJECT_ID: il tuo ID progetto.
    • REGION: la regione in cui è stato creato il gateway.
    • AGENT_GATEWAY_NAME: il nome del gateway.

  2. Applica il vincolo personalizzato.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Sostituisci EGRESS_CONSTRAINT_PATH con il percorso completo del file del vincolo personalizzato creato nel passaggio precedente.

  3. Crea la policy dell'organizzazione per applicare il vincolo. Per definire la policy dell'organizzazione, crea un file YAML della policy denominato policy-agent-gateway-egress.yaml. In questo esempio applichiamo questo vincolo a livello di progetto, ma puoi impostarlo anche a livello di organizzazione o cartella.

    name: projects/PROJECT_ID/policies/custom.disallowGeminiEnterpriseAgentGatewayBinding
spec:
rules:
    


      

    • enforce: true

    4. Sostituisci PROJECT_ID con l'ID progetto.

  4. Applica la policy dell'organizzazione.

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    Sostituisci EGRESS_POLICY_PATH con il percorso completo del file YAML della policy dell'organizzazione creato nel passaggio precedente. L'applicazione della policy può richiedere fino a 15 minuti.

Per saperne di più su come utilizzare i vincoli delle policy dell'organizzazione personalizzate, consulta Crea vincoli personalizzati.

Passaggi successivi

Codelab

Scopri come gestire i workload degli agenti con Agent Gateway su Gemini Enterprise Agent Platform.

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.

Risoluzione dei problemi

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