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 con gli agenti, che si verificano tra utenti e agenti, 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 (uscita) per proteggere e gestire tutte le comunicazioni in uscita con il traffico in uscita verso strumenti, modelli, API e altri agenti. Utilizzi il gateway in modalità Client-to-Agent (ingresso) per controllare quali client possono accedere ai tuoi agenti. Il gateway ti consente di scegliere quali policy IAP e modelli 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 alle implementazioni del runtime associate ad Agent Gateway.

Instradare 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 collega le policy di autorizzazione necessarie. Puoi creare un gateway in modalità da agente a ovunque (uscita) o da client ad agente (entrata).

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

    Per istruzioni, vedi Configurare Agent Gateway.

    Assicurati che il gateway sia configurato in modo da soddisfare le esigenze del tuo deployment. Ad esempio, se l'agente richiede l'accesso LLM, configura il gateway per consentire questo accesso per 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 Runtime, esegui i seguenti passaggi per concedere al service agent Runtime l'accesso al progetto del gateway in uscita:

    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.

    2. 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:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

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

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

    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

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

      Se vuoi utilizzare funzionalità della piattaforma mediate da 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. Senza identity_type=AGENT_IDENTITY, effectiveIdentity dell'istanza di runtime torna aaccount di serviziont Vertex AI predefinito e i criteri di governance semantica filtrano silenziosamente l'agente dal selettore di creazione dei criteri.

      Da agente a ovunque 

      remote_agent = client.agent_engines.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 è deployato Agent Gateway
      • REGION: la regione in cui vengono implementati l'agente e il 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.agent_engines.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 vengono distribuiti l'agente e il gateway
      • REGION: la regione in cui vengono implementati l'agente e il gateway
      • 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

      Da agente a ovunque

      Utilizza la seguente richiesta dell'API REST per associare un agente esistente a un gateway Agent-to-Anywhere per l'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 viene 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 vengono implementati l'agente e il 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 dell'API REST per associare un agente esistente a un gateway da client ad agente per l'ingresso.

      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 vengono distribuiti l'agente e il gateway
      • REGION: la regione in cui vengono implementati l'agente e il 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. Registrare l'agente in Agent Registry

    Assicurati che l'agente sia registrato con l'istanza del registro degli agenti nello stesso progetto e nella stessa regione di Agent Gateway.

    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 registro
    • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui è deployato il gateway
    • REGION: la regione in cui vengono implementati l'agente e il gateway
    • RUNTIME_AGENT_DISPLAY_NAME: il nome visualizzato leggibile dell'agente nel registro
    • RUNTIME_AGENT_PROJECT_NUMBER: il numero del progetto in cui viene deployment dell'agente Runtime
    • ENGINE_ID: l'ID risorsa dell'agente

    Per saperne di più, consulta Registrare un agente.

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

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

    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

    Sostituisci quanto segue:

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

    • MEMBER: l'entità dell'identità dell'agente a cui concedere il ruolo. Il formato è in genere: principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

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

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

    • Per abilitare il rilevamento automatico di agent, server MCP ed endpoint, Agent Gateway deve consentire il traffico verso l'endpoint https://agentregistry.googleapis.com/.

    • Se Cloud Trace è abilitato, Agent Gateway deve consentire il traffico verso l'endpoint https://telemetry.googleapis.com/.

      Se le variabili di ambiente GOOGLE_API_USE_CLIENT_CERTIFICATE e GOOGLE_API_USE_MTLS_ENDPOINT sono impostate, assicurati che sia consentito anche il traffico verso https://telemetry.mtls.googleapis.com/.

    • Se Cloud Logging è abilitato, Agent Gateway deve consentire il traffico verso l'endpoint https://logging.googleapis.com/.

      Se le variabili di ambiente GOOGLE_API_USE_CLIENT_CERTIFICATE e GOOGLE_API_USE_MTLS_ENDPOINT sono impostate, assicurati che sia consentito anche il traffico verso https://logging.mtls.googleapis.com/.

    Inoltre, se i tuoi agenti chiamano LLM o utilizzano funzionalità come Sessioni e Memory Bank, devi assicurarti che gli agenti possano comunicare con gli endpoint utilizzati da questi servizi. Ad esempio:

    • 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 accede l'agente. Poiché il gateway corrisponde direttamente ai nomi host, devi assicurarti di registrare tutte le varianti utilizzate dall'SDK agent. 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

    Per scoprire come registrare gli endpoint, consulta Registrare gli endpoint. Devi anche assicurarti che l'agente disponga del ruolo Egressor IAP per questi endpoint. Per istruzioni, consulta Crea una policy di uscita da agente a endpoint.

  7. Verifica la configurazione dell'agente

    Console

    1. Nella console Google Cloud , vai alla pagina Deployment di Agent Platform.

      Vai a Deployment

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

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

    4. Fai clic su Dettagli deployment. Le configurazioni di ingresso e uscita di Agent Gateway sono disponibili nel campo Specifica di deployment.

    gcloud

    Utilizza la seguente richiesta dell'API REST per verificare che l'agente sia ora associato al gateway. Se l'output restituito è null, significa che Runtime non è riuscito a eseguire il binding 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

Configurare agenti di 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 incorporare il certificato dell'autorità di certificazione radice 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 l'uscita di Agent Gateway, svolgi i seguenti passaggi:

  1. Recupera i certificati radice dalla risorsa Agent Gateway.

    Esporta la stringa PEM del certificato radice 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 del gateway dell'agente di uscita
    • REGION: la regione in cui viene eseguito il deployment del gateway
    • AGENT_GATEWAY_PROJECT_ID: l'ID progetto in cui viene eseguito il deployment del gateway

  2. Aggiorna il tuo Dockerfile per considerare attendibile il certificato CA.

    Aggiungi l'argomento di build AGENT_GATEWAY_ROOT_CERTIFICATES al tuo Dockerfile. I comandi di compilazione dividono 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:

    # 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 trasmettere 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 e dell'immagine di Artifact Registry.

  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 utilizzando le chiamate di deployment dell'SDK).

Limita Agent Runtime ai gateway dell'agente approvati

Puoi creare vincoli personalizzati delle policy dell'organizzazione per definire il set 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 preapprovati.

Da agente a ovunque

  1. Per definire un vincolo personalizzato per la modalità Agent-to-Anywhere (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 si trova nell'elenco preapprovato.

    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: l'ID organizzazione.
    • AGENT_PROJECT_ID: il tuo ID progetto.
    • REGION: la regione in cui è stato creato il gateway.
    • AGENT_GATEWAY_ID: il tuo ID 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 (ingresso), 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 si trova nell'elenco preapprovato.

    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: l'ID organizzazione.
    • AGENT_PROJECT_ID: il tuo ID progetto.
    • REGION: la regione in cui è stato creato il gateway.
    • AGENT_GATEWAY_ID: il tuo ID 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 Creare vincoli personalizzati.

Limitazioni

  • La governance tra progetti presenta le seguenti limitazioni:

    • Le associazioni tra progetti tra agenti e gateway sono supportate solo in modalità Agente-ovunque (uscita). In modalità da client ad agente (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 criteri IAM tra progetti o voci del registro agenti.

  • Un gateway dell'agente non può essere associato a motori di ragionamento di runtime creati prima del 29 aprile 2026.

  • Anche se un singolo progetto e una singola regione possono ospitare più istanze di Agent Gateway (in uscita) da agente a ovunque e (in entrata) da client ad agente, tutti gli agenti Agent Runtime di cui è stato eseguito il deployment all'interno dello stesso progetto e della stessa regione devono essere associati alle stesse istanze specifiche di Agent Gateway in uscita e in entrata.

    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 l'uscita. ovvero 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.

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

  • Il servizio di rilevamento delle minacce del motore dell'agente di Security Command Center non è disponibile quando Agent Gateway è abilitato per un agente.

  • In modalità da client ad agente (ingresso), Agent Gateway può gestire solo i metodi query e streamQuery di Agent Runtime. Per proteggere altri metodi non supportati (ad esempio asyncQuery), puoi applicare i modelli Model Armor direttamente dalla tua applicazione o dal tuo agente. Consulta Sanitizzazione dei prompt e delle risposte o questo codelab sulla creazione di un sistema di agenti sicuro con Model Armor.

  • I Controlli di servizio VPC non sono supportati con Agent Gateway.

  • Agent Gateway non è supportato per gli agenti Agent Runtime che utilizzano le revisioni. Non potrai utilizzare le funzionalità correlate al controllo delle versioni, come la configurazione della suddivisione del traffico e le query per revisione, se un Agent Gateway è collegato alla configurazione di un agente.

    Per aggiornare un agente senza modificarne l'ID del motore di ragionamento o interrompere i binding delle policy, aggiorna l'istanza dell'agente sul posto come descritto in Aggiornamento di un'istanza di Agent Runtime.

Passaggi successivi

Codelab

Scopri come gestire i carichi di lavoro agentici 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.