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à Agent-to-Anywhere (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à Client-to-Agent (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.
Crea un progetto di test dedicato project 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 (uscita) e una sola istanza Client-to-Agent (entrata) di Agent Gateway. Tutti gli agenti di 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 di Agent Engine di Security Command Center non è disponibile quando Agent Gateway è abilitato per un agente.
Non puoi annullare l'associazione di un agente di runtime a una risorsa Agent Gateway. Per questo motivo, assicurati di utilizzare un progetto di test dedicato.

Autorizzazioni obbligatorie

Devi concedere all'agente di servizio del motore di ragionamento l'autorizzazione a utilizzare la risorsa Agent Gateway che creerai.

Se non esiste già, crea l'account di servizio. In genere, l'account di servizio del motore di ragionamento viene creato automaticamente quando utilizzi per la prima volta il motore di ragionamento.
```
gcloud beta services identity create --service=aiplatform.googleapis.com --project=AGENT_PROJECT_ID
```
Sostituisci AGENT_PROJECT_ID con l'ID progetto del progetto in cui intendi eseguire il deployment dell'agente.
Per utilizzare il gateway, devi disporre delle seguenti autorizzazioni:
- networkservices.agentGateways.get
- networkservices.agentGateways.use
- networkservices.operations.get
Crea un ruolo personalizzato con tutte queste autorizzazioni e poi concedi il ruolo all'account di servizio del motore di ragionamento.
```
gcloud alpha iam roles create AGENT_GATEWAY_ROLE_ID \
  --project=AGENT_PROJECT_ID \
  --title="Custom Agent Gateway access role" \
  --description="Custom role for Agent Gateway" \
  --permissions="networkservices.operations.get,networkservices.agentGateways.get,networkservices.agentGateways.use"
```
Sostituisci quanto segue:
- AGENT_GATEWAY_ROLE_ID: l'ID del ruolo personalizzato.
- AGENT_PROJECT_ID: l'ID progetto del progetto in cui intendi eseguire il deployment dell'agente.
Assegna il ruolo all'account di servizio di Agent Runtime.
```
gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
    --member="serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
    --role="projects/AGENT_PROJECT_ID/roles/AGENT_GATEWAY_ROLE_ID"
```
Sostituisci quanto segue:
- AGENT_PROJECT_ID: l'ID progetto del progetto in cui intendi eseguire il deployment dell'agente.
- AGENT_PROJECT_NUMBER: il numero di progetto del progetto in cui intendi eseguire il deployment dell'agente.
- AGENT_GATEWAY_ROLE_ID: l'ID del ruolo personalizzato che hai creato.

Inoltre, se intendi utilizzare i modelli Model Armor per l'autorizzazione dei contenuti, devi concedere le seguenti autorizzazioni sia al service agent del motore di ragionamento sia all'account di servizio di Agent Gateway:

gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
    --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
 gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
     --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
     --role=roles/modelarmor.calloutUser
 gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
     --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
     --role=roles/modelarmor.user

Sostituisci quanto segue:

AGENT_PROJECT_ID: l'ID progetto del progetto in cui intendi eseguire il deployment dell'agente.
AGENT_PROJECT_NUMBER: il numero di progetto del progetto in cui intendi eseguire il deployment dell'agente.
MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto in cui vengono creati i modelli Model Armor.

Instradare il traffico di Agent Runtime tramite Agent Gateway

Per instradare il traffico di Agent Runtime tramite Agent Gateway:

Crea una risorsa Agent Gateway 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, 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 a LLM, configura il gateway per consentire questo accesso per evitare potenziali errori di deployment di Agent Runtime.

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

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 di Agent Gateway 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à Client-to-Agent (entrata), utilizza il campo client_to_agent_config e sostituisci AGENT_GATEWAY_CLIENT_TO_AGENT_NAME con il percorso completo di Agent Gateway creato per l'entrata.

Registra l'agente con l'istanza di Agent Registry nello stesso progetto e nella stessa regione dell'agente e del gateway. Per ulteriori informazioni, 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.

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.

Agent-to-Anywhere

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

Client-to-Agent

Per definire un vincolo personalizzato per la modalità Client-to-Agent (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 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.
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 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 personalizzati delle policy dell'organizzazione, consulta Creare vincoli personalizzati.

Passaggi successivi

Monitorare il traffico tramite 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

Autorizzazioni obbligatorie

Instradare il traffico di Agent Runtime tramite Agent Gateway

Limitare Agent Runtime ai gateway dell'agente approvati

Crea vincoli personalizzati delle policy dell'organizzazione

Agent-to-Anywhere

Client-to-Agent

Passaggi successivi

Instradare il traffico di Agent Runtime tramite Agent Gateway