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 filtraggio direttamente all'interno degli agenti. Quando configuri Model Armor con Agent Gateway, Model Armor applica i controlli 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 limiti di sicurezza dei contenuti in tutti gli agenti regolati dal gateway. Model Armor ti aiuta a mitigare i rischi come prompt injection, tentativi di jailbreak, fuga di informazioni sensibili e generazione di contenuti dannosi. Per saperne di più, consulta Filtri Model Armor.

Modelli Model Armor

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

Model Armor incorpora funzionalità di screening direttamente nei percorsi di comunicazione regolati da Agent Gateway. Passando i contenuti tramite Model Armor, il gateway applica i modelli di sicurezza dei contenuti. Nel modello, puoi configurare Model Armor per oscurare o bloccare i contenuti che violano i tuoi modelli.

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 modelli che Model Armor utilizza per valutare sia le richieste che le risposte nel traffico da client ad agente. Puoi applicare un singolo modello a entrambe le direzioni o configurare modelli diversi per ciascuna.

Model Armor segue i modelli quando esamina quanto segue:

  • Richieste in arrivo dal client (utenti finali o applicazioni di chiamata) al tuo agente AI
  • Risposte in uscita dell'agente AI al cliente

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

Dopo che l'agente AI elabora la richiesta e genera una risposta, Agent Gateway intercetta il flusso in uscita prima che raggiunga il client. Model Armor valuta la risposta ed emette un verdetto. In base al verdetto, Agent Gateway consente o blocca completamente la risposta.

Da agente a ovunque (agente in uscita)

Definisci i modelli che Model Armor utilizza per valutare le richieste e le risposte nel traffico Agent-to-Anywhere. Puoi applicare un singolo modello a entrambe le direzioni o configurare modelli diversi per ciascuna.

Model Armor segue i modelli 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 modelli in uscita che hai impostato.

Se i dati in uscita violano le tue norme 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 disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare modelli Model Armor, chiedi all'amministratore di concederti il ruolo IAM Model Armor Admin (roles/modelarmor.admin) sul 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 utilizzare Agent Gateway, consulta la sezione Ruoli richiesti nella documentazione di Agent Gateway.

Per informazioni sui payload supportati e non supportati che passano attraverso il gateway, vedi Payload supportati e non supportati in questo documento.

Configura 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 che in uscita.

    Prendi nota dei nomi dei modelli. Per copiare il nome di un modello nella consoleCloud de Confiance , 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 di Model Armor. Per il gateway Client-to-Agent (in entrata), specifica i modelli Model Armor che hai creato per il traffico in entrata. Per il gateway Agent-to-Anywhere (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 agent appropriati:

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

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

      • Il ruolo Utente Model Armor (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.s3ns-system.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.s3ns-system.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 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 modello Model Armor.
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.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.s3ns-system.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.s3ns-system.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, vedi Delegare 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 modelli su un gateway, puoi eseguire un controllo pre-deployment per verificare che la configurazione del modello applichi correttamente i criteri di sicurezza.

Puoi convalidare il modello eseguendo query sul metodo sanitizeUserPrompt direttamente utilizzando un insieme di prompt di test. Per ulteriori informazioni su come eseguire questo controllo pre-deployment e un elenco di prompt di test verificati, consulta Convalida la configurazione del modello.

Oscuramento dei dati sensibili da richieste e risposte

Puoi chiedere a Model Armor di oscurare i dati sensibili, ad esempio numeri di documenti di identità e 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 situazioni:

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

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

Se utilizzi il tipo di applicazione INSPECT_ONLY anziché INSPECT_AND_BLOCK, Model Armor non redige 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 modello di anonimizzazione.

Per un elenco completo dei rilevatori Model Armor (chiamati anche filtri), consulta Filtri 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 da client ad agente (ingresso) che utilizza il protocollo ADK, Model Armor pulisce solo reasoningEngines.streamQuery richieste e risposte 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 pulisce solo i seguenti payload del protocollo A2A v1:

Model Armor consente i seguenti payload A2A senza sanitizzazione:

Payload MCP

Model Armor esegue la sanitizzazione solo dei seguenti payload MCP:

Model Armor consente i seguenti payload senza sanificazione:

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

Payload LLM esterni

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

Controllo dei documenti

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

Quote e limiti di sistema

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

Per ulteriori informazioni sulle quote che si applicano quando utilizzi Model Armor con altri servizi, consulta Gestire le quote.

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

Passaggi successivi