Instradare il traffico di Agent Runtime tramite Agent Gateway

Anteprima privata - Agent Gateway

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Questa funzionalità offre capacità di governance e sicurezza per gli agenti AI, pertanto si applicano i Termini specifici dei servizi "Servizi di AI agentica". Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Per richiedere l'accesso per utilizzare Agent Gateway con Agent Runtime, consulta la pagina di richiesta di accesso.

Questa pagina descrive come instradare il traffico di Agent Runtime tramite Agent Gateway. Agent Gateway è un componente centrale di rete 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.

• Crea un progetto di test dedicato per provare questo flusso di lavoro. Evita di utilizzare progetti destinati anche ad altri carichi di lavoro critici.

Limitazioni

• Per un determinato progetto e una determinata regione, può esistere una sola istanza Agent-to-Anywhere (in uscita) e una sola istanza Client-to-Agent (in entrata) di Agent Gateway. Tutti gli agenti Agent Runtime all'interno dello stesso progetto e della stessa regione configurati per utilizzare Agent Gateway devono utilizzare queste istanze gateway specifiche.
• Il servizio di rilevamento delle minacce del motore dell'agente di Security Command Center non è disponibile quando Agent Gateway è abilitato per un agente.
• Non puoi scollegare un agente Runtime da una risorsa Agent Gateway. Per questo motivo, assicurati di utilizzare un progetto di test dedicato.

Instradare il traffico di Agent Runtime tramite Agent Gateway

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

1. Crea una risorsa del gateway dell'agente e collega le policy di autorizzazione in base alle esigenze. Puoi creare un gateway in modalità Agent-to-Anywhere (in uscita) o Client-to-Agent (in entrata). Tieni presente che l'agente e il gateway devono essere creati nello stesso progetto e nella stessa regione. 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. 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.

   Devi anche assicurarti che all'istanza Runtime sia assegnata un'identità agente utilizzando il parametro identity_type, come mostrato in questo esempio.

   remote_agent = client.agent_engines.create(
     agent=local_agent,
     config={
         "agent_gateway_config": {
           "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_NAME},
           # "client_to_agent_config": {"agent_gateway": 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 AGENT_GATEWAY_TO_ANYWHERE_NAME con il percorso completo del gateway dell'agente che hai creato in modalità Agent-to-Anywhere (in uscita). Ad esempio, projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID.

   Se hai creato un gateway in modalità da client ad agente (ingresso), utilizza il campo client_to_agent_config e sostituisci AGENT_GATEWAY_CLIENT_TO_AGENT_NAME con il percorso completo del gateway agente che hai creato per l'ingresso.

3. Registra l'agente con l'istanza del registro degli agenti nello stesso progetto e nella stessa regione dell'agente e del gateway. Per saperne di più, consulta Registrare un agente.

Limitare Agent Runtime ai gateway dell'agente approvati

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

Nota: i Controlli di servizio VPC non sono supportati con Agent Gateway. Tuttavia, se i Controlli di servizio VPC vengono applicati al progetto, queste policy dell'organizzazione sono necessarie per garantire che gli agenti utilizzino solo i percorsi di uscita approvati, impedendo l'esfiltrazione di dati tramite gateway non autorizzati.

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 alpha 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 alpha 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à Client-to-Agent (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 alpha 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 alpha 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.

Passaggi successivi

Codelab

Codelab: Govern agentic workloads with Agent Platform

Scopri come gestire i carichi di lavoro agentici con Agent Gateway sulla piattaforma agentica Gemini Enterprise.

Guida

Delegare l'autorizzazione per il gateway dell'agente

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

Guida

Monitor Agent Gateway

Scopri come monitorare Agent Gateway.