Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 rete e sicurezza dell'ecosistema di Gemini Enterprise Agent Platform. Fornisce una connettività sicura e controllata per tutte le interazioni agentiche, che si verifichino 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à Da agente a ovunque (in uscita) per proteggere e controllare tutte le comunicazioni in uscita con il traffico in uscita verso strumenti, modelli, API e altri agenti. Utilizza il gateway in modalità Da client ad agente (in entrata) 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 Da agente a ovunque (in uscita) e a un gateway Da client ad agente (in entrata).

Limitazioni

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 a ovunque (in uscita) e Da client ad agente (in entrata), tutti gli agenti di Agent Runtime di cui è stato eseguito il deployment nello stesso progetto e nella 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 il traffico in 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 associazione si applica anche ai gateway in entrata all'interno di un progetto e di una regione.
Il servizio di rilevamento delle minacce di Agent Engine di Security Command Center non è disponibile quando Agent Gateway è abilitato per un agente.
In modalità Da client ad agente (in entrata), Agent Gateway può controllare 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 dall'applicazione o dall'agente. Consulta Sanificare prompt e risposte o questo codelab sulla creazione di un sistema di agenti sicuro con Model Armor.

Instradare il traffico di Agent Runtime tramite Agent Gateway

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

Crea una risorsa Agent Gateway e collega le policy di autorizzazione in base alle esigenze. Puoi creare un gateway in modalità Da agente a ovunque (in uscita) o Da client ad agente (in entrata). Tieni presente che l'agente e il gateway devono essere creati nello stesso progetto e nella stessa regione. Per istruzioni, consulta Configurare Agent Gateway.

Assicurati che il gateway sia configurato in modo da soddisfare le esigenze del 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.

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

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 trasmettere l'oggetto local_agent insieme a eventuali configurazioni facoltative.

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

remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "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 AGENT_GATEWAY_TO_ANYWHERE_NAME con il nome dell'Agent Gateway creato in modalità Da agente a ovunque (in uscita).

Se hai creato un gateway in modalità Da client ad agente (in entrata), utilizza invece il campo client_to_agent_config e sostituisci AGENT_GATEWAY_CLIENT_TO_AGENT_NAME con il nome dell'Agent Gateway creato per il traffico 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 Da agente a ovunque 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/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto
REGION: la regione in cui è stato eseguito il deployment dell'agente
AGENT_GATEWAY_TO_ANYWHERE_NAME: il nome dell'Agent Gateway 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 il traffico in entrata.

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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto
REGION: la regione in cui è stato eseguito il deployment dell'agente
AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: il nome dell'Agent Gateway creato in modalità Da client ad agente (in entrata)
RESOURCE_ID: l'ID risorsa dell'agente

Registrati con l'istanza del registro degli agenti nello stesso progetto e nella stessa regione dell'agente e del gateway.
```
gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"
```
Sostituisci quanto segue:
- SERVICE_NAME: il nome che vuoi assegnare alla risorsa, ad esempio allow-aiplatform-region-eu3.
- PROJECT_ID: l'ID progetto.
- REGION: la regione del registro.
- DISPLAY_NAME: il nome leggibile dell'endpoint.
Per saperne di più, consulta Registrare un agente.
Crea un'associazione di policy IAM da agente a registro per l'agente.
```
gcloud iap web add-iam-policy-binding \
  --resource-type=agent-registry \
  --endpoint=ENDPOINT_ID \
  --region=REGION \
  --project=PROJECT_ID \
  --member=MEMBER \
  --role=roles/iap.egressor
```
Sostituisci quanto segue:
- ENDPOINT_ID: l'ID endpoint del servizio dell'agente registrato. Lo ottieni dall'output del passaggio precedente.
- MEMBER: l'entità 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.
  
  Nota: se vuoi associare tutti gli agenti di un progetto a un registro (inclusi tutti gli agenti di Runtime, gli agenti di Gemini Enterprise e tutti gli altri agenti creati in futuro), puoi associare la policy IAM a principal://TRUST_DOMAIN/attribute.container/projects/PROJECT_ID.
A questo punto, il traffico dell'agente verrà indirizzato tramite Agent Gateway. Tuttavia, Agent Gateway adotta una policy di negazione predefinita. Per abilitare determinate funzioni di Agent Platform, devi assicurarti che l'agente possa comunicare con i seguenti endpoint:
- 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 gli agenti chiamano LLM o utilizzano funzionalità come Sessioni e Memory Bank, devi assicurarti che 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 dell'agente. Ad esempio, a seconda della versione dell'SDK, della configurazione del client regionale o dell'utilizzo di mTLS, un'API 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: sebbene tu possa 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 sotto quel dominio. Tieni presente che, anche se registri un URI di base, devi comunque registrarne tutte le varianti regionali e mTLS.

Per scoprire come registrare gli endpoint, consulta Registrare gli endpoint. Devi anche assicurarti che l'agente abbia il ruolo di Egressor IAP per questi endpoint. Per istruzioni, consulta Creare una policy di uscita da agente a endpoint policy.
Verifica la configurazione dell'agente.
Console
1. Nella Google Cloud console 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 del deployment. Le configurazioni in entrata e in uscita di Agent Gateway sono disponibili nel campo Specifica del 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 ad associarsi al gateway.
curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \ | jq '.spec.deploymentSpec.agentGatewayConfig'
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto
- REGION: la regione in cui è stato eseguito il deployment dell'agente
- RESOURCE_ID: l'ID risorsa dell'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.

Creare 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

Per definire un vincolo personalizzato per la modalità Da agente a ovunque (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 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: l'ID progetto.
REGION: la regione in cui è stato creato il gateway.
AGENT_GATEWAY_ID: l'ID gateway.

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

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

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: l'ID progetto.
REGION: la regione in cui è stato creato il gateway.
AGENT_GATEWAY_ID: l'ID gateway.

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.
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.
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 personalizzati delle policy dell'organizzazione, consulta Creare vincoli personalizzati.

Passaggi successivi

Codelab

Instradare il traffico di Agent Runtime tramite Agent Gateway

Prima di iniziare

Limitazioni

Instradare il traffico di Agent Runtime tramite Agent Gateway

Da agente a ovunque

Da client ad agente

Console

gcloud

Limitare Agent Runtime ai gateway dell'agente approvati

Creare vincoli personalizzati delle policy dell'organizzazione

Da agente a ovunque

Da client ad agente

Passaggi successivi

Codelab: controllare i carichi di lavoro agentici con Agent Platform

Delegare l'autorizzazione per Agent Gateway

Monitorare Agent Gateway

Risolvere i problemi relativi ad Agent Gateway

Instradare il traffico di Agent Runtime tramite Agent Gateway Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Limitazioni

Instradare il traffico di Agent Runtime tramite Agent Gateway

Da agente a ovunque

Da client ad agente

Console

gcloud

Limitare Agent Runtime ai gateway dell'agente approvati

Creare vincoli personalizzati delle policy dell'organizzazione

Da agente a ovunque

Da client ad agente

Passaggi successivi

Codelab: controllare i carichi di lavoro agentici con Agent Platform

Delegare l'autorizzazione per Agent Gateway

Monitorare Agent Gateway

Risolvere i problemi relativi ad Agent Gateway

Instradare il traffico di Agent Runtime tramite Agent Gateway