Configura Model Armor su un gateway

Model Armor ti aiuta a garantire che i tuoi agenti AI rispettino i tuoi standard di sicurezza e governance senza richiedere l'implementazione della logica di filtro direttamente all'interno degli agenti. Quando configuri Model Armor con Agent Gateway, Model Armor applica i guardrail di sicurezza dei contenuti della tua organizzazione ispezionando tutti i prompt e le risposte che passano attraverso il gateway. Questa funzionalità ti consente di applicare in modo coerente i guardrail di sicurezza dei contenuti a tutti gli agenti regolati dal gateway. Model Armor ti aiuta a mitigare rischi come prompt injection, tentativi di jailbreak, fuga di informazioni sensibili e generazione di contenuti dannosi. Per saperne di più, consulta Filtri di Model Armor.

Template di Model Armor

Per configurare Model Armor su un gateway, crea template che specificano come filtrare i prompt e le risposte che i tuoi agenti AI ricevono e restituiscono. I template forniscono filtri e soglie personalizzati per più categorie di sicurezza. Per saperne di più, consulta Template di Model Armor.

Model Armor incorpora le funzionalità di screening direttamente nei percorsi di comunicazione regolati da Agent Gateway. Passando i contenuti tramite Model Armor, il gateway applica i tuoi template di sicurezza dei contenuti. Nel template, puoi configurare Model Armor in modo che oscuri o blocchi i contenuti che violano i tuoi template.

Traffico in entrata e in uscita

Tramite Agent Gateway, Model Armor può contribuire a proteggere i seguenti flussi di traffico.

Da client ad agente (agente in entrata)

Definisci i template che Model Armor utilizza per valutare sia le richieste sia le risposte all'interno del traffico da client ad agente. Puoi applicare un singolo modello a entrambe le direzioni o configurare modelli diversi per ciascuna.

Model Armor segue i template durante l'esame di quanto segue:

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

Quando un client invia un prompt all'agente, Agent Gateway intercetta il traffico e invia il payload a Model Armor per la sanitizzazione. Se Model Armor emette un verdetto ALLOW, Agent Gateway invia il prompt all'agente AI. Se Model Armor emette un verdetto BLOCK, il client riceve un errore e il flusso termina prima di raggiungere l'agente AI.

Dopo che l'agente AI ha elaborato la richiesta e generato una risposta, Agent Gateway intercetta lo stream in uscita prima che raggiunga il client. Model Armor valuta la risposta ed emette un verdetto. In base alla decisione, Agent Gateway consente o blocca completamente la risposta.

Da agente a ovunque (agente in uscita)

Definisci i template che Model Armor utilizza per valutare le richieste e le risposte nel traffico da agente a ovunque. Puoi applicare un singolo modello a entrambe le direzioni o configurare modelli diversi per ciascuna.

Model Armor segue i template durante lo screening delle comunicazioni tra l'agente AI e i sistemi esterni, tra cui:

  • Modelli linguistici di grandi dimensioni (LLM) esterni
  • Agenti AI di terze parti
  • Server Model Context Protocol (MCP)

Quando un agente AI comunica con un sistema esterno, Agent Gateway intercetta il traffico in uscita e chiama Model Armor. Model Armor valuta il payload in base ai template di uscita che hai impostato.

Se i dati in uscita violano le tue policy di sicurezza, Model Armor emette un verdetto BLOCK. Agent Gateway termina quindi la connessione per impedire che dati dannosi o sensibili raggiungano l'LLM, lo strumento o l'agente AI esterno.

Prima di iniziare

Abilita l'API Model Armor, se non è già abilitata.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare i template Model Armor, chiedi all'amministratore di concederti il ruolo IAM Model Armor Admin (roles/modelarmor.admin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per i ruoli necessari per lavorare con Agent Gateway, consulta Ruoli richiesti nella documentazione di Agent Gateway.

Per informazioni sui payload supportati e non supportati che passano attraverso il gateway, 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.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 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.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 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.

(Facoltativo) Controllo di convalida del modello pre-deployment

Prima di eseguire il deployment dei template in un gateway, puoi eseguire un controllo pre-deployment per verificare che la configurazione del template applichi correttamente le policy di sicurezza.

Puoi convalidare il template eseguendo una query direttamente sul metodo sanitizeUserPrompt utilizzando un insieme di prompt di test. Per saperne di più su come eseguire questo controllo pre-deployment e per un elenco di prompt di test verificati, consulta Testa un template Model Armor.

Oscura i dati sensibili nelle richieste e nelle risposte

Puoi istruire Model Armor a oscurare i dati sensibili, come i numeri del documento di identità e i numeri di telefono, dai payload. Per utilizzare questa funzionalità, segui questi passaggi:

Se utilizzi il tipo di applicazione INSPECT_AND_BLOCK, si verifica una delle seguenti condizioni:

  • Se un payload viola solo il rilevatore di Sensitive Data Protection, Model Armor lo oscura in base alle impostazioni avanzate di Sensitive Data Protection e al template di anonimizzazione.

  • Se un payload viola più rilevatori, Model Armor non esegue l'oscuramento, ma blocca l'intero payload.

Se utilizzi il tipo di applicazione INSPECT_ONLY anziché INSPECT_AND_BLOCK, Model Armor non oscura il payload.

Indipendentemente dal tipo di applicazione (INSPECT_ONLY o INSPECT_AND_BLOCK), i log di Model Armor vengono oscurati in base alle impostazioni avanzate di Sensitive Data Protection e al template di anonimizzazione.

Per un elenco completo dei rilevatori di Model Armor (chiamati anche filtri), consulta Filtri di Model Armor.

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 Vertex AI Agent Engine.

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.

Controllo dei documenti

La sanitizzazione di prompt e risposte che contengono documenti o caricamenti di file (come PDF) non è supportata in questa integrazione. Per controllare i documenti, chiama direttamente l'API REST Model Armor. Per saperne di più, consulta Screening dei documenti nella documentazione di Model Armor.

Quote e limiti di sistema

La quota viene consumata nel progetto in cui si trovano i template di Model Armor. Se il gateway si trova in un progetto diverso, la quota ExternalProcessor viene utilizzata anche nel progetto del gateway.

Per saperne di più sulle quote che si applicano quando utilizzi Model Armor con altri servizi, consulta Gestisci le quote.

Per informazioni generali sulle quote e sui limiti di sistema di Model Armor, inclusi i limiti di dimensioni e token di input, consulta Quote e limiti di sistema nella documentazione di Model Armor.

Passaggi successivi