Instradare il traffico di Agent Runtime tramite Agent Gateway

Questa pagina descrive come instradare il traffico di Agent Runtime 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 il deployment degli agenti su Agent Runtime.

• Scopri di più su Agent Gateway. Puoi utilizzare Agent Gateway in modalità Agent-to-Anywhere (traffico in uscita) per proteggere e gestire tutte le comunicazioni in uscita con il traffico in uscita verso strumenti, modelli, API e altri agenti. Utilizza il gateway in modalità Client-to-Agent (traffico in entrata) per controllare quali client possono accedere agli agenti. Il gateway ti consente di scegliere quali policy IAP e modelli di Model Armor devono essere applicati a queste interazioni.

  Una singola istanza di runtime può essere associata contemporaneamente a un gateway Agent-to-Anywhere (in uscita) e a un gateway Client-to-Agent (in entrata).

• Esamina le limitazioni associate ai deployment di runtime associati ad Agent Gateway.

Instrada il traffico di Agent Runtime tramite Agent Gateway

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

1. Crea l'Agent Gateway

   Crea una risorsa Agent Gateway e associa le policy di autorizzazione necessarie. Puoi creare un gateway in modalità Agent-to-Anywhere (traffico in uscita) o Client-to-Agent (traffico in entrata).

   • Per la modalità da client ad agente (traffico in entrata), l'agente e il gateway devono essere creati nello stesso progetto e nella stessa regione.
   • Per la modalità Agent-to-Anywhere (traffico in uscita), il gateway può essere creato in un progetto diverso rispetto all'agente, ma deve essere creato nella stessa regione. Tieni presente che tutte le registrazioni di Agent Registry e le associazioni delle policy IAM associate devono essere create nello stesso progetto dell'Agent Gateway.

   Per istruzioni, vedi Configura Agent Gateway.

   Assicurati che il gateway sia configurato in modo da soddisfare le esigenze del tuo deployment. Ad esempio, se il tuo agente richiede l'accesso LLM, configura il gateway per consentire questo accesso ed evitare potenziali errori di deployment di Agent Runtime.

2. (Facoltativo) Configura l'accesso al gateway in uscita tra progetti

   Se il gateway Agent-to-Anywhere (in uscita) si trova in un progetto diverso da quello dell'agente di runtime, segui questi passaggi per concedere all'agente di servizio di runtime l'accesso al progetto del gateway in uscita:

   gcloud

   1. Crea un ruolo IAM personalizzato nel progetto Agent Gateway:

   gcloud iam roles create ar_agw_cross_project_sa \
       --project=AGENT_GATEWAY_PROJECT_ID \
       --title="Runtime Agent Gateway Cross-Project SA" \
       --description="Custom role for the cross-project service agent to access Agent Gateway" \
       --permissions="networkservices.agentGateways.get,networkservices.operations.get"

   Sostituisci AGENT_GATEWAY_PROJECT_ID con l'ID progetto in cui è stato eseguito il deployment di Agent Gateway.

   1. Assegna il ruolo personalizzato nel progetto gateway al service agent di Agent Runtime del progetto dell'agente:

   gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
       --member="serviceAccount:[e-mail]" \
       --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

   Sostituisci AGENT_RUNTIME_PROJECT_NUMBER con il numero del progetto in cui è stato eseguito il deployment dell'agente di runtime.

   Terraform

   Per concedere l'accesso tra progetti da più progetti di workload di runtime a un progetto Agent Gateway centrale in modo dichiarativo, crea il ruolo IAM personalizzato nel progetto gateway centrale e concedilo all'agente di servizio di runtime di ogni progetto di workload:

   variable "runtime_project_numbers" {
     type        = set(string)
     description = "Project numbers hosting cross-project Agent Runtime workloads"
     default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
   }
   
   resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     role_id     = "ar_agw_cross_project_sa"
     title       = "Runtime Agent Gateway Cross-Project SA"
     description = "Custom role for cross-project service agents to access Agent Gateway"
     permissions = [
       "networkservices.agentGateways.get",
       "networkservices.operations.get",
     ]
   }
   
   resource "google_project_iam_member" "ar_agw_cross_project_binding" {
     for_each = var.runtime_project_numbers
   
     project = "AGENT_GATEWAY_PROJECT_ID"
     role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
     member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.iam.gserviceaccount.com"
   }
   

3. Configura l'agente per instradare il traffico tramite Agent Gateway

   Attenzione: l'associazione dell'agente a un gateway di applicazione forza immediatamente il routing del traffico in uscita, incluse le chiamate alla piattaforma (come l'API Sessions), attraverso il gateway. Se non hai ancora inserito nella lista consentita gli endpoint richiesti (consulta Inserisci nella lista consentita le API essenziali), tutte le chiamate dell'agente non andranno a buon fine e restituiranno un errore 498. Per evitare questo problema, inserisci le API essenziali nella lista consentita prima di eseguire questo passaggio di associazione o assicurati che le policy IAP associate siano in modalità DRY_RUN fino al completamento dell'inserimento nella lista consentita.

   A seconda che tu stia eseguendo il deployment di un nuovo agente o configurando un agente esistente, scegli una delle seguenti opzioni:

   • Per i nuovi agenti che utilizzano l'SDK Python

     Specifica la risorsa gateway durante il deployment dell'agente. Ad esempio, per eseguire il deployment dell'agente su Agent Runtime, utilizza client.runtimes.create per passare l'oggetto local_agent insieme a eventuali configurazioni facoltative.

     Se vuoi utilizzare le funzionalità della piattaforma mediate dal gateway, come Model Armor o norme di governance semantica con questo agente, imposta sia agent_gateway_config sia identity_type=AGENT_IDENTITY nella chiamata di creazione, come mostrato in questo esempio. Il backend applica identity_type = "AGENT_IDENTITY" a livello API ogni volta che viene specificato agent_gateway_config, causando l'errore della convalida del deployment se l'identità dell'istanza di runtime viene omessa o configurata in modo errato.

     Da agente a ovunque

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Sostituisci quanto segue:

     • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment di Agent Gateway
     • REGION: la regione in cui è stato eseguito il deployment dell'agente e del gateway
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: il nome dell'Agent Gateway che hai creato in modalità Da agente a ovunque (in uscita)

     Da client ad agente

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Sostituisci quanto segue:

     • PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment dell'agente e del gateway
     • REGION: la regione in cui è stato eseguito il deployment dell'agente e del gateway
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: il nome dell'Agent Gateway che hai creato in modalità da client ad agente (in entrata)

   • Per i nuovi agenti che utilizzano Terraform

     Quando esegui il provisioning dell'agente con Terraform, utilizza il provider google-beta e configura il blocco agent_gateway_config all'interno della risorsa google_vertex_ai_reasoning_engine. Per maggiori dettagli sulla configurazione di Terraform, consulta Esegui il provisioning degli agenti con Terraform.

     Nota: i deployment che specificano agent_gateway_config devono impostare identity_type = "AGENT_IDENTITY". Senza identity_type = "AGENT_IDENTITY", la convalida delle risorse non va a buon fine.

     Da agente a ovunque

     Utilizza la seguente configurazione Terraform per associare un agente a un gateway Agent-to-Anywhere per il traffico in uscita.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "AGENT_RUNTIME_PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           agent_to_anywhere_config {
             agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
           }
         }
       }
     }
     }

     Sostituisci quanto segue:

     • AGENT_RUNTIME_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment dell'agente
     • REGION: la regione in cui è stato eseguito il deployment dell'agente e del gateway
     • AGENT_DISPLAY_NAME: il nome visualizzato dell'agente
     • AGENT_DESCRIPTION: una descrizione dell'agente
     • REPOSITORY: il repository Artifact Registry contenente l'immagine container
     • IMAGE: il nome dell'immagine container
     • TAG: il tag dell'immagine container
     • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment di Agent Gateway
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: il nome dell'Agent Gateway che hai creato in modalità Da agente a ovunque (in uscita)

     Da client ad agente

     Utilizza la seguente configurazione Terraform per associare un agente a un gateway Client-to-Agent per l'ingress.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           client_to_agent_config {
             agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
           }
         }
       }
     }
     }

     Sostituisci quanto segue:

     • PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment dell'agente e del gateway
     • REGION: la regione in cui è stato eseguito il deployment dell'agente e del gateway
     • AGENT_DISPLAY_NAME: il nome visualizzato dell'agente
     • AGENT_DESCRIPTION: una descrizione dell'agente
     • REPOSITORY: il repository Artifact Registry contenente l'immagine container
     • IMAGE: il nome dell'immagine container
     • TAG: il tag dell'immagine container
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: il nome dell'Agent Gateway che hai creato in modalità da client ad agente (in entrata)

   • Per gli agenti esistenti che utilizzano l'API REST

     Nota: l'aggiornamento di un motore di ragionamento esistente per impostare agentGatewayConfig non ne modifica identity_type. Se il motore è stato creato originariamente senza identity_type=AGENT_IDENTITY, non puoi renderlo idoneo retroattivamente per le norme di governance semantica applicando una patch. Devi rifare il deployment di un nuovo motore di ragionamento con agent_gateway_config e identity_type=AGENT_IDENTITY impostati al momento della creazione dell'agente.

     Da agente a ovunque

     Utilizza la seguente richiesta API REST per associare un agente esistente a un gateway Agent-to-Anywhere per il traffico in uscita.

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

     Sostituisci quanto segue:

     • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment del gateway
     • AGENT_RUNTIME_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment dell'agente
     • REGION: la regione in cui è stato eseguito il deployment dell'agente e del gateway
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: il nome dell'Agent Gateway che hai creato in modalità Da agente a ovunque (in uscita)
     • RESOURCE_ID: l'ID risorsa dell'agente

     Da client ad agente

     Utilizza la seguente richiesta API REST per associare un agente esistente a un gateway client-agente per l'ingress.

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

     Sostituisci quanto segue:

     • PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment dell'agente e del gateway
     • REGION: la regione in cui è stato eseguito il deployment dell'agente e del gateway
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: il nome dell'Agent Gateway che hai creato in Da client ad agente (in entrata)
     • RESOURCE_ID: l'ID risorsa dell'agente

4. Registra l'agente con Agent Registry

   Assicurati che l'agente sia registrato nell'istanza di Agent Registry nello stesso progetto e nella stessa regione di Agent Gateway.

   gcloud

   gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --location=REGION \
    --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
    --format="value(registryResource)"
   

   Sostituisci quanto segue:

   • RUNTIME_AGENT_SERVICE_NAME: il nome che vuoi assegnare alla voce dell'agente nel registry
   • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment del gateway
   • REGION: la regione in cui viene eseguito il deployment dell'agente e del gateway
   • RUNTIME_AGENT_DISPLAY_NAME: il nome visualizzato leggibile della voce dell'agente nel registry
   • RUNTIME_AGENT_PROJECT_NUMBER: il numero del progetto in cui è stato eseguito il deployment dell'agente di runtime
   • ENGINE_ID: l'ID risorsa dell'agente

   Terraform

   resource "google_agent_registry_service" "runtime_agent_entry" {
     project      = "AGENT_GATEWAY_PROJECT_ID"
     location     = "REGION"
     service_id   = "RUNTIME_AGENT_SERVICE_NAME"
     display_name = "RUNTIME_AGENT_DISPLAY_NAME"
   
     endpoint_spec {
       no_spec {}
     }
   
     interfaces {
       url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
       protocol_binding = "jsonrpc"
     }
   }
   

   Per saperne di più, consulta Registra gli agenti. Per scoprire di più sulla registrazione manuale degli agenti in configurazioni multiprogetto, consulta Registra un agente da un altro progetto.

5. Crea un'associazione di policy IAM da agente a registry

   Esegui questo passaggio nello stesso progetto e nella stessa regione dell'Agent Gateway.

   gcloud

   gcloud iap web add-iam-policy-binding \
    --resource-type=agent-registry \
    --endpoint=AGENT_ENDPOINT_ID \
    --region=REGION \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --member=MEMBER \
    --role=roles/iap.egressor
   

   Terraform

   resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     location    = "REGION"
     endpoint_id = "AGENT_ENDPOINT_ID"
     role        = "roles/iap.egressor"
     member      = "MEMBER"
   }
   

   Sostituisci quanto segue:

   • AGENT_ENDPOINT_ID: l'ID endpoint di servizio dell'agente registrato. Puoi ottenerlo dall'output del passaggio precedente.

   • MEMBER: l'entità dell'identità dell'agente a cui concedere il ruolo. Il formato di un singolo motore di ragionamento è: principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID.

     Se vuoi concedere l'accesso in uscita a tutti gli agenti di un progetto o dell'organizzazione anziché associare singole istanze, puoi associare la policy IAM a un set di entità:

     • Per concedere l'accesso a tutti gli agenti di un progetto: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
     • Per concedere l'accesso a tutti gli agenti dell'organizzazione: principalSet://TRUST_DOMAIN/*

     In queste stringhe di entità, TRUST_DOMAIN è in genere agents.global.org-ORGANIZATION_ID.system.id.goog.

6. Inserisci nella lista consentita le API essenziali per le operazioni di runtime

   A questo punto, il traffico dell'agente viene indirizzato tramite l'Agent Gateway. Tuttavia, Agent Gateway adotta una policy di negazione predefinita. Per abilitare alcune funzioni di Agent Platform, devi assicurarti che l'agente possa comunicare con i seguenti endpoint:

   La corrispondenza del nome host in Agent Gateway è esatta. I caratteri jolly, come *.googleapis.com, o le forme di prefisso non sono supportati. Devi registrare ogni variante di nome host standard, regionale e sicuro (mTLS) che l'SDK dell'agente o l'applicazione client risolve.

   Per abilitare determinate funzioni di Agent Platform e garantire l'inizializzazione e la telemetria corrette, devi consentire il traffico verso i seguenti endpoint nel registro degli agenti:

   Endpoint della piattaforma essenziali

   La tabella seguente elenca gli endpoint della piattaforma essenziali richiesti dagli agenti per le operazioni standard, il tracciamento, il logging e la risoluzione dei metadati:

   Nome servizio	Nome host standard	Nome host mTLS	Varianti regionali e di altro tipo
   Agent Registry	agentregistry.googleapis.com	—	—
   Cloud Logging	logging.googleapis.com	logging.mtls.googleapis.com	—
   Cloud Trace / telemetria	telemetry.googleapis.com	telemetry.mtls.googleapis.com	—
   API Trace	cloudtrace.googleapis.com	cloudtrace.mtls.googleapis.com	—
   Cloud Monitoring	monitoring.googleapis.com	monitoring.mtls.googleapis.com	—
   Secret Manager	secretmanager.googleapis.com	secretmanager.mtls.googleapis.com	—
   Resource Manager	cloudresourcemanager.googleapis.com	cloudresourcemanager.mtls.googleapis.com	—
   Credenziali IAM	iamcredentials.googleapis.com	iamcredentials.mtls.googleapis.com	—
   Agent Platform (aiplatform)	aiplatform.googleapis.com	aiplatform.mtls.googleapis.com	REGION-aiplatform.googleapis.com REGION-aiplatform.mtls.googleapis.com aiplatform.REGION.rep.googleapis.com

   Endpoint specifici per le funzionalità

   Inoltre, se i tuoi agenti utilizzano funzionalità come Sessioni o Agent Platform Memory Bank, devi assicurarti che possano comunicare con gli endpoint specifici utilizzati da questi servizi:

   • Per le sessioni: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
   • Per Memory Bank: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

   Per motivi di sicurezza, ti consigliamo di registrare e inserire nella lista consentita solo gli URI specifici a cui l'agente accede. Poiché il gateway corrisponde direttamente ai nomi host, devi assicurarti di registrare tutte le varianti utilizzate dall'SDK dell'agente. Ad esempio, a seconda della versione dell'SDK, della configurazione del client regionale o dell'utilizzo di mTLS, un'API di Google può essere risolta tramite i seguenti nomi host degli endpoint:

   • https://REGION-aiplatform.googleapis.com
   • https://REGION-aiplatform.mtls.googleapis.com
   • https://aiplatform.REGION.rep.googleapis.com
   Attenzione: anche se puoi registrare un URI di base (ad esempio https://REGION-aiplatform.googleapis.com/) per comodità, questa operazione fornisce una policy di accesso ampia che consente all'agente di accedere a qualsiasi servizio in quel dominio. Tieni presente che, anche se registri un URI di base, devi comunque registrare tutte le sue varianti regionali e mTLS.

   Per scoprire come registrare gli endpoint, consulta Registra gli endpoint. Se hai una configurazione con più progetti, puoi registrare più endpoint API di Google principali in un unico servizio Agent Registry. Per saperne di più, consulta Registra un endpoint API di Google composito. Devi inoltre assicurarti che l'agente disponga dell'autorizzazione iap.resources.egressViaIAP per questi endpoint. Per istruzioni, consulta Crea una policy in uscita da agente a endpoint.

7. Verifica la configurazione dell'agente

   Console

   1. Nella console Google Cloud , vai alla pagina Deployment della piattaforma agente.
      

      Vai a Deployment

   2. Fai clic sul nome dell'agente di cui hai eseguito il deployment.

   3. Fai clic su Configurazione del servizio. Viene visualizzato il riquadro Osservabilità per l'agente.

   4. Fai clic su Dettagli deployment. Le configurazioni di traffico in entrata e in uscita di Agent Gateway sono disponibili nel campo Deployment spec.

   gcloud

   Utilizza la seguente richiesta API REST per verificare che l'agente sia ora associato al gateway. Se l'output restituito è null, significa che il runtime non è riuscito ad associarsi al gateway.

   curl -s -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
     | jq '.spec.deploymentSpec.agentGatewayConfig'

   Sostituisci quanto segue:

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

Configura gli agenti container personalizzati (BYOC) per Agent Gateway

Se vuoi instradare il traffico in uscita tramite un Agent Gateway Agent-to-Anywhere (in uscita) per un agente di cui è stato eseguito il deployment con un'immagine container personalizzata (Bring Your Own Container / BYOC), devi inserire il certificato dell'autorità di certificazione radice (CA) del gateway nell'archivio di attendibilità dell'immagine container personalizzata.

Poiché Agent Gateway esegue la decrittografia e l'ispezione TLS sulle comunicazioni degli agenti in uscita, i deployment degli agenti non BYOC (basati sull'origine) inseriscono automaticamente il certificato della CA durante la creazione dell'immagine. Per le immagini container personalizzate, devi recuperare esplicitamente il certificato CA del gateway, installarlo nell'archivio di attendibilità CA di sistema all'interno di Dockerfile e impostare le variabili di ambiente del bundle di certificati richieste dagli SDK Python, dalle librerie client HTTP e da gRPC.

Per configurare un'immagine container BYOC per il traffico in uscita di Agent Gateway, segui questi passaggi:

1. Recupera i certificati radice dalla risorsa Agent Gateway.

   Esporta la stringa PEM del certificato radice della CA direttamente dal campo agentGatewayCard.rootCertificates della risorsa Agent Gateway:

   export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
      --location=REGION \
      --project=PROJECT_ID \
      --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

   In alternativa, puoi utilizzare l'API REST per recuperare la risorsa gateway:

   curl -s -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
      | jq -r '.agentGatewayCard.rootCertificates[]'

   Sostituisci quanto segue:

   • AGENT_GATEWAY_NAME: il nome dell'Agent Gateway in uscita
   • REGION: la regione in cui è stato eseguito il deployment del gateway
   • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment del gateway

2. Aggiorna il tuo Dockerfile in modo che consideri attendibile il certificato CA.

   Aggiungi l'argomento di build AGENT_GATEWAY_ROOT_CERTIFICATES al tuo Dockerfile. I comandi di build suddividono i certificati in file separati, li installano utilizzando update-ca-certificates e impostano le variabili di ambiente in modo che OpenSSL, le librerie client HTTP Python (requests, httpx) e gRPC riconoscano la CA personalizzata:

   Nota: l'esempio seguente presuppone un'immagine container basata su Debian o Ubuntu. Se utilizzi una distribuzione Linux diversa (ad esempio RHEL, CentOS o Alpine), i comandi per aggiornare l'archivio CA (ad esempio update-ca-certificates rispetto a update-ca-trust), le directory per i file dei certificati e i percorsi del bundle di certificati di sistema potrebbero essere diversi. Modifica questi comandi e percorsi in base alla documentazione della tua distribuzione.

   # Install root certificates under root user
   USER root
   
   ARG AGENT_GATEWAY_ROOT_CERTIFICATES
   RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
        echo "Installing Agent Gateway root certificates..."; \
        printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
        update-ca-certificates; \
      fi
   
   # Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
   ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   
   # Switch back to application execution user
   USER 1000

3. Crea l'immagine container utilizzando Cloud Build.

   Crea un file cloudbuild.yaml per passare la stringa del certificato radice a Cloud Build utilizzando le sostituzioni:

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args:
     - 'build'
     - '--build-arg'
     - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
     - '-t'
     - '$_IMAGE_URI'
     - '.'
   
   images:
   - '$_IMAGE_URI'
   

   Invia la build dell'immagine container a Cloud Build:

   export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"
   
   gcloud builds submit \
      --project=PROJECT_ID \
      --region=REGION \
      --config=cloudbuild.yaml \
      --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
      .
   

   Sostituisci REPOSITORY_NAME e IMAGE_NAME con i nomi del repository Artifact Registry e dell'immagine.

4. Esegui il deployment dell'agente containerizzato.

   Specifica l'URI dell'immagine container creata insieme alla configurazione di Agent Gateway nella richiesta di deployment (utilizzando agent_gateway_config in spec.deploymentSpec o le chiamate di deployment dell'SDK).

Limita l'Agent Runtime agli Agent Gateway approvati

Puoi creare vincoli delle policy dell'organizzazione personalizzati per definire l'insieme di risorse Agent Gateway idonee che possono essere utilizzate durante il deployment degli agenti.

Crea vincoli personalizzati delle policy dell'organizzazione

Questo esempio crea vincoli personalizzati che consentono il traffico solo da e verso un elenco di gateway pre-approvati.

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.

   Nell'esempio seguente, il campo condition specifica che l'operazione è consentita solo se viene specificata una risorsa Agent Gateway (il campo è presente e non vuoto) e se il gateway specificato è nell'elenco pre-approvato.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
     'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
     'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   Sostituisci quanto segue:

   • ORGANIZATION_ID: ID organizzazione.
   • AGENT_PROJECT_ID: il tuo ID progetto.
   • REGION: la regione in cui è stato creato il gateway.
   • AGENT_GATEWAY_ID: l'ID 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/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Sostituisci AGENT_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.

Da client ad agente

1. Per definire un vincolo personalizzato per la modalità da client ad agente (traffico in entrata), crea un file denominato constraint-agent-gateway-ingress.yaml.

   Nell'esempio seguente, il campo condition specifica che l'operazione è consentita solo se viene specificata una risorsa Agent Gateway (il campo è presente e non vuoto) e se il gateway specificato è nell'elenco pre-approvato.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
     'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
     'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   Sostituisci quanto segue:

   • ORGANIZATION_ID: ID organizzazione.
   • AGENT_PROJECT_ID: il tuo ID progetto.
   • REGION: la regione in cui è stato creato il gateway.
   • AGENT_GATEWAY_ID: l'ID del gateway.

2. Applica il vincolo personalizzato.

   gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
   

   Sostituisci INGRESS_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-ingress.yaml. In questo esempio applichiamo questo vincolo a livello di progetto, ma puoi impostarlo anche a livello di organizzazione o cartella.

   name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Sostituisci AGENT_PROJECT_ID con l'ID progetto.

4. Applica la policy dell'organizzazione.

   gcloud org-policies set-policy INGRESS_POLICY_PATH
   

   Sostituisci INGRESS_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.

Limitazioni

• La governance tra progetti presenta le seguenti limitazioni:

  • Le associazioni tra progetti tra agenti e gateway sono supportate solo in modalità da agente a ovunque (traffico in uscita). In modalità client-agente (traffico in entrata), l'agente e l'Agent Gateway devono trovarsi nello stesso progetto.
  • Devi utilizzare l'API REST o gcloud per configurare la governance end-to-end tra progetti. La console Google Cloud Google Cloud non supporta la creazione di associazioni di policy IAM tra progetti o di voci del registry degli agenti.

• Un Agent Gateway non può essere associato ai motori di ragionamento di runtime creati prima del 29 aprile 2026.

• Sebbene un singolo progetto e una singola regione possano ospitare più istanze di Agent Gateway da agente ad agente (in uscita) e da client ad agente (in entrata), tutti gli agenti Agent Runtime di cui è stato eseguito il deployment nello stesso progetto e nella stessa regione devono essere associati alle stesse istanze di Agent Gateway in uscita e in entrata specifiche.

  Ad esempio, se un progetto e una regione contengono egress-gateway-X e egress-gateway-Y, tutti gli agenti in quel progetto e in quella regione devono essere configurati per utilizzare lo stesso gateway per il traffico in uscita. In altre parole, tutti gli agenti utilizzano egress-gateway-X o tutti gli agenti utilizzano egress-gateway-Y. Non puoi configurare agent-A per utilizzare egress-gateway-X e agent-B per utilizzare egress-gateway-Y.

  La stessa regola di associazione si applica anche ai gateway in entrata all'interno di un progetto e di una regione.

• Il servizio Threat Detection di Security Command Center Agent Engine non è disponibile quando Agent Gateway è abilitato per un agente.

• In modalità Client-to-Agent (ingress), Agent Gateway può gestire solo i metodi query e streamQuery di Agent Runtime. Per proteggere altri metodi non supportati (come asyncQuery), puoi applicare i template di Model Armor direttamente dalla tua applicazione o dal tuo agente. Consulta Sanitizza prompt e risposte o questo codelab sulla creazione di un sistema di agenti sicuro con Model Armor.

• La modifica di un'associazione di Agent Gateway su un agente di runtime archivia ogni revisione preesistente dell'agente. L'archiviazione è irreversibile. Consulta Agent Gateway e revisioni.

  Nota: le modifiche alle associazioni sono consentite solo quando tutto il traffico è sull'ultima revisione, ovvero se traffic_config.traffic_split_always_latest è impostato o traffic_config non è impostato.

  Per aggiornare un agente senza modificare l'ID del motore di ragionamento o interrompere le associazioni delle policy, aggiorna l'istanza dell'agente in loco come descritto in Aggiornamento di un'istanza di Agent Runtime.

Passaggi successivi

Codelab

Codelab: gestisci i workload degli agenti con Agent Platform

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

Guida

Delega l'autorizzazione per Agent Gateway

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

Guida

Monitora Agent Gateway

Scopri come monitorare Agent Gateway.

Risoluzione dei problemi

Risolvi i problemi di Agent Gateway

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