Integrare Model Armor con Agent Gateway

Gemini Enterprise Agent Platform è una piattaforma per la creazione e la gestione di agenti AI di livello enterprise. Agent Gateway funge da control plane che gestisce, protegge e governa il modo in cui gli agenti AI si connettono e interagiscono all'interno dell'ambiente Google Cloud e con agenti esterni, applicazioni AI e LLM. L'integrazione di Model Armor e Agent Gateway incorpora le funzionalità di screening di Model Armor direttamente nei percorsi di comunicazione gestiti da Gemini Enterprise Agent Platform. Quando i contenuti passano attraverso Agent Gateway, viene richiamato Model Armor per applicare i modelli di sicurezza predefiniti. Puoi configurare il template in modo da bloccare e oscurare i contenuti che violano le norme o solo per ispezionare i contenuti e registrare eventuali violazioni rilevate. In questo modo si riducono i rischi come prompt injection, jailbreak, esposizione a contenuti dannosi e fuga di dati sensibili.

Quando Model Armor rileva violazioni delle policy nei contenuti che passano attraverso Agent Gateway, può essere configurato per registrare questi eventi. Puoi visualizzare questi risultati nella pagina Model Armor nella console Google Cloud (Vai a Model Armor). Questi risultati vengono visualizzati anche in Security Command Center. Per saperne di più, consulta Esamina i risultati nella consoleGoogle Cloud .

Quando utilizzi la modalità di streaming in tempo reale, Model Armor supporta token illimitati nello stream, il che lo rende adatto per interazioni e risposte del modello di lunga durata.

Limitazioni

Tieni presenti le seguenti limitazioni durante l'integrazione di Model Armor con Agent Gateway:

  • Supporto dello streaming per gli agenti: Model Armor supporta la sanitizzazione dello streaming solo utilizzando il metodo streamQuery per gli agenti creati con l'Agent Development Kit.
  • Utilizzo dei template tra progetti: quando utilizzi un template di Model Armor in un progetto per sanitizzare le richieste per un servizio, come Agent Gateway, in un progetto diverso, la quota API per Model Armor deve essere sufficiente sia nel progetto che ospita il template sia nel progetto che ospita il servizio chiamante. Per ulteriori informazioni, consulta Gestisci la quota.
  • Allineamento regionale: il deployment di Model Armor e dei servizi con cui si integra deve essere eseguito nella stessa regione Google Cloud . Le chiamate tra regioni a Model Armor non sono supportate.
  • Compatibilità dell'integrazione in uscita: la protezione inline di Model Armor sul traffico in uscita è limitata alle integrazioni con i server MCP, i servizi che seguono il formato OpenAI e l'A2A tramite Agent Gateway.
  • Compatibilità con l'integrazione di Ingress: la protezione in entrata in linea con Model Armor è supportata solo per gli agenti creati utilizzando ADK.
  • Nessun supporto per i documenti: la sanitizzazione di prompt e risposte che contengono documenti o caricamenti di file (come i PDF) non è supportata in questa integrazione. Per eseguire lo screening dei documenti, chiama direttamente l'API REST Model Armor.
  • Payload supportati: per un elenco dei payload supportati, consulta Payload supportati e non supportati in questo documento.

Configura Model Armor su un gateway

Per configurare Model Armor su un gateway, segui questi passaggi:

  1. Abilita l'API Model Armor nel progetto in cui vuoi creare i template di Model Armor.

  2. Crea uno o più template Model Armor nella stessa regione in cui prevedi di aggiungere il gateway. Puoi utilizzare lo stesso template per il traffico in entrata e in uscita.

    Prendi nota dei nomi dei template. Per copiare il nome di un template nella consoleGoogle Cloud , visualizza i dettagli del template e fai clic su Copia negli appunti accanto al nome del template.

    Se crei i template di Model Armor in un progetto diverso da quello che contiene l'agente AI o l'Agent Gateway e utilizzi i Controlli di servizio VPC, entrambi i progetti devono trovarsi nello stesso perimetro di servizio dei Controlli di servizio VPC.

  3. Configura Agent Gateway nella stessa regione in cui sono archiviati i template di Model Armor. Per il gateway client-agente (in entrata), specifica i template Model Armor che hai creato per il traffico in entrata. Per il gateway Agent-to-Anywhere (traffico in uscita), specifica i template di Model Armor che hai creato per il traffico in uscita. Puoi utilizzare lo stesso modello per entrambi i flussi di traffico.

  4. Concedi i ruoli IAM richiesti agli agenti di servizio appropriati:

    • Da client ad agente (ingress): concedi al service agent AI Platform Reasoning Engine Service Agent i seguenti ruoli:

      • Il ruolo Model Armor Callout User (roles/modelarmor.calloutUser) nel progetto che contiene l'agente AI.

      • Il ruolo Utente Model Armor (roles/modelarmor.user) nel progetto che contiene il template Model Armor.

      gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re. \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re. \
    --role=roles/modelarmor.user

      Sostituisci quanto segue:

      • AGENT_RUNTIME_PROJECT_ID: l'ID progetto in cui hai creato l'agente.
      • AGENT_RUNTIME_PROJECT_NUMBER: il numero del progetto in cui hai creato l'agente.
      • MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il template di Model Armor.

    • Da agente a ovunque (in uscita): concedi al service agent Service Extensions i seguenti ruoli:

      • I ruoli Model Armor Callout User (roles/modelarmor.calloutUser) e Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) nel progetto che contiene il gateway.
      • Il ruolo Utente Model Armor (roles/modelarmor.user) nel progetto che contiene il template Model Armor.
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --role=roles/modelarmor.user

      Sostituisci quanto segue:

      • GATEWAY_PROJECT_ID: l'ID progetto in cui hai creato il gateway.
      • GATEWAY_PROJECT_NUMBER: il numero del progetto in cui hai creato il gateway.
      • MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il template di Model Armor.

      Per istruzioni, consulta Delega l'autorizzazione a Model Armor.

    Per informazioni generali su come concedere un ruolo, consulta Concedi un singolo ruolo IAM.

Traffico in entrata e in uscita

Nel contesto dell'integrazione di Agent Gateway e Model Armor, i termini ingress ed egress vengono utilizzati dal punto di vista delle interazioni dell'agente AI:

  • Traffico in entrata (da client ad agente): si riferisce al flusso di comunicazione tra un client e l'agente. Model Armor può proteggere sia le richieste in entrata dal client all'agente sia le risposte in uscita dall'agente al client.
  • Traffico in uscita (dall'agente a qualsiasi destinazione): si riferisce al flusso di comunicazione tra l'agente e un sistema esterno. Model Armor può proteggere sia le richieste in uscita dall'agente al sistema esterno sia le risposte in entrata dal sistema esterno all'agente.

Protezione da client ad agente (in entrata)

Definisci i template che Model Armor utilizza per valutare:

  • Richieste in arrivo dal client (utenti finali o applicazioni chiamanti) al tuo agente AI.
  • Risposte in uscita dall'agente AI al client.

Puoi applicare un singolo modello a entrambe le direzioni o configurare modelli diversi per ciascuna.

Flusso di traffico da client ad agente

  1. Un client invia un prompt all'agente. Agent Gateway intercetta la richiesta e invia il payload a Model Armor.
  2. Model Armor filtra la richiesta. Se bloccato, il client riceve un errore.
  3. Se consentita, la richiesta raggiunge l'agente AI.
  4. L'agente AI genera una risposta. Agent Gateway intercetta questa risposta prima che raggiunga il client.
  5. Model Armor esamina la risposta e Agent Gateway la consente o la blocca in base al verdetto.

Protezione da agente a ovunque (in uscita)

Definisci i template che Model Armor utilizza per valutare:

  • Richieste in uscita dall'agente AI a sistemi esterni.
  • Risposte in entrata dai sistemi esterni all'agente AI.

Questa protezione si applica alle comunicazioni con sistemi tra cui:

  • LLM esterni e agenti AI di terze parti
  • Server Model Context Protocol (MCP)
  • Altri agenti AI

Flusso di traffico per Da agente a ovunque

  1. L'agente AI avvia una richiesta a un sistema esterno. Agent Gateway intercetta il traffico in uscita.
  2. Model Armor esamina il payload in uscita. Se viene bloccata, la connessione viene interrotta.
  3. Se consentita, la richiesta viene inviata al sistema esterno.
  4. Il sistema esterno invia una risposta. Agent Gateway intercetta questa risposta in entrata.
  5. Model Armor filtra il payload della risposta e Agent Gateway lo consente o lo blocca.

Per saperne di più, consulta Configura Model Armor su un gateway.

Monitora ed esegui il debug delle richieste di streaming

Per facilitare il monitoraggio e il debug delle richieste di streaming, Model Armor utilizza un ID correlazione e un ID traccia.

Utilizza un ID traccia

Un ID traccia collega tutti gli eventi per una singola richiesta mentre attraversa più servizi in un sistema distribuito. Sono incluse le applicazioni delle misure di sicurezza che Model Armor applica all'interno del percorso della richiesta della risorsa Agent Gateway.

Ogni traccia contiene uno o più intervalli, in cui ogni ID intervallo rappresenta un'operazione o un'unità di lavoro specifica all'interno della traccia. I log generati durante l'esecuzione di una richiesta sono associati all'ID span specifico dell'operazione che esegue il lavoro.

Un ID traccia viene gestito in due modi:

  • Automatico: quando Google Cloud Observability è abilitato, Agent Gateway genera automaticamente un ID traccia e lo propaga nel sistema.

  • Fornito dall'utente: puoi eseguire l'override dell'ID traccia generato dal sistema fornendo il tuo ID utilizzando l'intestazione HTTP traceparent nelle tue richieste.

    Il seguente esempio di codice mostra come passare un ID traccia personalizzato in una richiesta al metodo streamQuery:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-98adffecc8dd095968a06c44216190f6-5b565a8342378cd7-01" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:streamQuery?alt=sse"

    Sostituisci quanto segue:

    • LOCATION: la regione in cui si trova il motore di ragionamento.
    • PROJECT_ID: l'ID del tuo progetto Google Cloud .
    • REASONING_ENGINE_ID: l'ID del tuo motore di ragionamento.

L'utilizzo di un ID traccia è il metodo consigliato per correlare log e tracce end-to-end dal chiamante tramite Agent Gateway a Model Armor e a eventuali agenti downstream. Questo è essenziale per il debug, la comprensione delle azioni di sicurezza e il monitoraggio delle prestazioni. Per saperne di più, consulta Visualizza gli intervalli di traccia di Model Armor.

Per visualizzare i log delle operazioni di sanitizzazione per un ID traccia specifico, utilizza la seguente query in Esplora log:

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID

Sostituisci TRACE_ID con l'ID traccia della richiesta.

Utilizza un ID correlazione

Un ID correlazione collega tutte le voci di log in Cloud Logging relative a una singola sessione di sanificazione in streaming, dalla richiesta iniziale alla risposta finale. Si tratta di un identificatore interno utilizzato principalmente nei log di Model Armor, in particolare per le sessioni di flussi in entrata. Per saperne di più, consulta Correlare i log e gli eventi correlati.

Payload supportati e non supportati

Questa sezione elenca i tipi di payload che Model Armor sanitizza.

Traffico da client ad agente (in entrata)

Per il traffico client-agente (in entrata) che utilizza il protocollo ADK, Model Armor esegue la sanitizzazione solo delle richieste e delle risposte reasoningEngines.streamQuery per gli agenti creati utilizzando Agent Development Kit (ADK) e in esecuzione su Agent Runtime.

Tutti gli altri payload ReasoningEngine e le risposte di errore ReasoningEngine non vengono inviati a Model Armor. Anche i payload non ADK (come i payload Langchain) non vengono inviati a Model Armor.

Traffico da agente a ovunque (in uscita)

Per il traffico da agente a qualsiasi destinazione (in uscita), sono supportati i seguenti payload.

Payload A2A

Model Armor esegue la sanitizzazione solo dei seguenti payload del protocollo A2A v1:

Model Armor consente i seguenti payload A2A senza sanitizzazione:

Payload MCP

Model Armor sanitizza solo i seguenti payload MCP:

Model Armor consente i seguenti payload senza sanitizzazione:

  • tools/list
  • resources/*
  • notifications/*
  • HTTP/SSE trasmissibile in streaming per MCP
  • Errori del protocollo MCP (ad esempio, tutti gli errori diversi da quelli di esecuzione dello strumento)

Payload LLM esterni

Model Armor esegue la sanitizzazione solo dei seguenti payload del protocollo API OpenAI (traffico in uscita), che include i modelli GPT su openai.com e qualsiasi altro modello tramite server LLM compatibili con l'API OpenAI (come vLLM). I payload non elencati qui sono consentiti senza sanitizzazione.