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 piano di controllo che gestisce, protegge e governa il modo in cui gli agenti AI si connettono e interagiscono all'interno dell' Google Cloud ambiente 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 modello in modo da bloccare e oscurare i contenuti che violano le norme o solo per ispezionare i contenuti e registrare le 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 norme nei contenuti che passano attraverso Agent Gateway, può essere configurato per registrare questi eventi. Puoi visualizzare questi risultati nella pagina Model Armor della Google Cloud console (vai a Model Armor). Questi risultati vengono visualizzati anche in Security Command Center. Per saperne di più, consulta Esaminare i risultati nella Google Cloud console.

Quando si utilizza 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 a lunga esecuzione.

Limitazioni

Tieni presente le seguenti limitazioni quando integri Model Armor con Agent Gateway:

  • Supporto dello streaming per gli agenti: Model Armor supporta la sanificazione dello streaming solo utilizzando il metodo streamQuery per gli agenti creati con Agent Development Kit.
  • Utilizzo di modelli tra progetti: quando utilizzi un modello Model Armor in un progetto per sanificare le richieste di un servizio, come Agent Gateway, in un progetto diverso, la quota API per Model Armor deve essere sufficiente sia nel progetto che ospita il modello sia nel progetto che ospita il servizio chiamante. Per saperne di più, consulta Gestire le quote.
  • Allineamento regionale: Model Armor e i servizi con cui si integra devono essere sottoposti a deployment nella stessa Google Cloud regione. Le chiamate tra regioni a Model Armor non sono supportate.
  • Compatibilità dell'integrazione in uscita: la protezione in linea di Model Armor sul traffico in uscita è limitata alle integrazioni con i server MCP, ai servizi che seguono il formatoOpenAIe ad A2A tramite Agent Gateway.
  • Compatibilità dell'integrazione in entrata: la protezione in linea in entrata con Model Armor è supportata solo per gli agenti creati utilizzando ADK.

Configurare Model Armor su un gateway

Per configurare Model Armor su un gateway:

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

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

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

  3. Configura Agent Gateway nella stessa regione in cui sono archiviati i modelli Model Armor. Per il gateway Da client ad agente (in entrata), specifica i modelli Model Armor che hai creato per il traffico in entrata. Per il gateway Da agente a ovunque (in uscita) , specifica i modelli 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 ai service account appropriati:

    • Da client ad agente (in entrata): concedi al service agent del motore di ragionamento di AI Platform i seguenti ruoli:

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

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

      gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --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.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Sostituisci quanto segue:

      • AGENT_RUNTIME_PROJECT_ID: l'ID progetto del 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 modello Model Armor.

    • Da agente a ovunque (in uscita): concedi al service account Agent Gateway 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 Model Armor User (roles/modelarmor.user) nel progetto che contiene il modello Model Armor.
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Sostituisci quanto segue:

      • GATEWAY_PROJECT_ID: l'ID progetto del 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 modello Model Armor.

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

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

Traffico in entrata e in uscita

Nel contesto dell'integrazione di Agent Gateway e Model Armor, i termini in entrata e in uscita 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 (da agente a ovunque): 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 modelli che Model Armor utilizza per valutare:

  • Richieste in entrata 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.

Per il traffico da client ad agente (in entrata) che utilizza il protocollo ADK, Model Armor sanifica solo reasoningEngines.streamQuery richieste e risposte per gli agenti creati utilizzando Agent Development Kit (ADK) ed eseguiti su Agent Runtime.

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

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 bloccata, 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 filtra la risposta e Agent Gateway la consente o la blocca in base al verdetto.

Protezione da agente a ovunque (in uscita)

Definisci i modelli che Model Armor utilizza per valutare:

  • Richieste in uscita dal tuo agente AI a sistemi esterni.
  • Risposte in entrata da sistemi esterni al tuo agente AI.

Questa protezione si applica alle comunicazioni con i sistemi, tra cui:

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

Flusso di traffico 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 filtra il payload in uscita. Se bloccata, la connessione viene terminata.
  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 di risposta e Agent Gateway consente o blocca l'accesso all'agente.

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

Monitorare ed eseguire il debug delle richieste di streaming

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

Utilizzare un ID traccia

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

Ogni traccia contiene uno o più intervalli, dove 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 intervallo 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 attraverso il sistema.

  • Fornito dall'utente: puoi sostituire l'ID traccia generato dal sistema fornendo il tuo utilizzando l'intestazione HTTP traceparent nelle 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 Google Cloud progetto.
    • REASONING_ENGINE_ID: l'ID del motore di ragionamento.

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

Per visualizzare i log delle operazioni di sanificazione 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 tua richiesta.

Utilizzare un ID di correlazione

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