Configurar o Model Armor em um gateway

O Model Armor ajuda a garantir que seus agentes de IA sigam seus padrões de segurança e governança sem que você precise implementar a lógica de filtragem diretamente nos agentes. Ao configurar o Model Armor com o Gateway de Agente, ele aplica as proteções de segurança de conteúdo da sua organização inspecionando todos os comandos e respostas que passam pelo gateway. Esse recurso permite aplicar proteções de segurança de conteúdo de forma consistente em todos os agentes controlados pelo gateway. O Model Armor ajuda a reduzir riscos como injeção de comandos, tentativas de jailbreak, vazamento de informações sensíveis e geração de conteúdo nocivo. Para mais informações, consulte Filtros do Model Armor.

Modelos do Model Armor

Para configurar o Model Armor em um gateway, crie modelos que especifiquem como analisar os comandos e as respostas que seus agentes de IA recebem e retornam. Os modelos fornecem filtros e limites personalizados para várias categorias de segurança. Para mais informações, consulte Modelos do Model Armor.

O Model Armor incorpora recursos de triagem diretamente nos caminhos de comunicação regidos pelo Gateway de Agente. Ao transmitir o conteúdo pelo Model Armor, o gateway aplica seus modelos de segurança de conteúdo. No modelo, é possível configurar o Model Armor para encobrir ou bloquear conteúdo que viole os modelos.

Tráfego de entrada e saída

Por meio do Gateway de Agente, o Model Armor pode ajudar a proteger os seguintes fluxos de tráfego.

Cliente para agente (entrada do agente)

Você define modelos que o Model Armor usa para avaliar as solicitações e respostas no tráfego entre cliente e agente. É possível aplicar um único modelo a ambas as direções ou configurar modelos diferentes para cada uma.

O Model Armor segue os modelos ao analisar o seguinte:

  • Solicitações recebidas do cliente (usuários finais ou aplicativos de chamada) para seu agente de IA
  • Respostas do agente de IA para o cliente

Quando um cliente envia um comando para o agente, o Gateway de Agente intercepta o tráfego e envia o payload para o Model Armor para sanitização. Se o Model Armor emitir um veredito ALLOW, o Gateway de Agente enviará o comando para o agente de IA. Se o Model Armor emitir um veredito BLOCK, o cliente receberá um erro, e o fluxo será encerrado antes de chegar ao agente de IA.

Depois que o agente de IA processa a solicitação e gera uma resposta, o Gateway de Agente intercepta o stream de saída antes que ele chegue ao cliente. O Model Armor avalia a resposta e emite um veredito. Com base no veredito, o Gateway de Agente permite ou bloqueia totalmente a resposta.

Do agente para qualquer lugar (saída do agente)

Você define modelos que o Model Armor usa para avaliar solicitações e respostas no tráfego do Agent-to-Anywhere. É possível aplicar um único modelo a ambas as direções ou configurar modelos diferentes para cada uma.

O Model Armor segue os modelos ao analisar as comunicações entre seu agente de IA e sistemas externos, incluindo:

  • Modelos de linguagem grandes (LLMs) externos
  • Agentes de IA de terceiros
  • Servidores do Protocolo de Contexto de Modelo (MCP, na sigla em inglês)

Quando um agente de IA se comunica com um sistema externo, o Gateway de Agente intercepta o tráfego de saída e chama o Model Armor. O Model Armor avalia o payload de acordo com os modelos de saída que você definiu.

Se os dados de saída violarem suas políticas de segurança, o Model Armor vai emitir um veredito BLOCK. Em seguida, o Gateway de Agente encerra a conexão para evitar que dados nocivos ou sensíveis cheguem ao LLM, à ferramenta ou ao agente de IA externo.

Antes de começar

Ative a API Model Armor, se ainda não estiver ativada.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Funções exigidas

Para receber as permissões necessárias para criar modelos do Model Armor, peça ao administrador para conceder a você o papel do IAM de Administrador do Model Armor (roles/modelarmor.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para saber quais papéis são necessários para trabalhar com o Gateway de Agente, consulte Papéis necessários na documentação do Gateway de Agente.

Para informações sobre payloads compatíveis e incompatíveis que passam pelo gateway, consulte Payloads compatíveis e incompatíveis neste documento.

Configurar o Model Armor em um gateway

Para configurar o Model Armor em um gateway, siga estas etapas:

  1. Ative a API Model Armor no projeto em que você quer criar os modelos do Model Armor.

  2. Crie um ou mais modelos do Model Armor na mesma região em que você planeja adicionar o gateway. É possível usar o mesmo modelo para o tráfego de entrada e saída.

    Anote os nomes dos modelos. Para copiar o nome de um modelo no console doGoogle Cloud , acesse os detalhes do modelo e clique em Copiar para a área de transferência ao lado do nome do modelo.

    Se você criar os modelos do Model Armor em um projeto diferente daquele que contém o agente de IA ou o Gateway de Agente e usar o VPC Service Controls, os dois projetos precisam estar no mesmo perímetro de serviço do VPC Service Controls.

  3. Configure o Gateway de Agente na mesma região em que os modelos do Model Armor estão armazenados. Para o gateway de cliente para agente (entrada), especifique os modelos do Model Armor que você criou para o tráfego de entrada. Para o gateway de agente para qualquer lugar (saída), especifique os modelos do Model Armor que você criou para o tráfego de saída. É possível usar o mesmo modelo para os dois fluxos de tráfego.

  4. Conceda os papéis do IAM necessários aos agentes de serviço apropriados:

    • Cliente para agente (entrada): conceda ao agente de serviço do mecanismo de raciocínio da plataforma de IA os seguintes papéis:

      • O papel de Usuário do Model Armor Callout (roles/modelarmor.calloutUser) no projeto que contém o agente de IA.

      • O papel de Usuário do Model Armor (roles/modelarmor.user) no projeto que contém o modelo do 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

      Substitua:

      • AGENT_RUNTIME_PROJECT_ID: o ID do projeto em que você criou o agente.
      • AGENT_RUNTIME_PROJECT_NUMBER: o número do projeto em que você criou o agente.
      • MODEL_ARMOR_PROJECT_ID: o ID do projeto que contém o modelo do Model Armor.

    • Agente para qualquer lugar (saída): conceda ao agente de serviço das extensões de serviço os seguintes papéis:

      • Os papéis de Usuário do Model Armor Callout (roles/modelarmor.calloutUser) e Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) no projeto que contém o gateway.
      • O papel de Usuário do Model Armor (roles/modelarmor.user) no projeto que contém o modelo do 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

      Substitua:

      • GATEWAY_PROJECT_ID: o ID do projeto em que você criou o gateway.
      • GATEWAY_PROJECT_NUMBER: o número do projeto em que você criou o gateway.
      • MODEL_ARMOR_PROJECT_ID: o ID do projeto que contém o modelo do Model Armor.

      Para instruções, consulte Delegar autorização ao Model Armor.

    Para informações gerais sobre como conceder um papel, consulte Conceder um único papel do IAM.

Opcional: verificação de validação do modelo pré-implantação

Antes de implantar os modelos em um gateway, é possível executar uma verificação pré-implantação para confirmar se a configuração do modelo está aplicando as políticas de segurança corretamente.

Para validar o modelo, consulte o método sanitizeUserPrompt diretamente usando um conjunto de comandos de teste. Para mais informações sobre como executar essa verificação pré-implantação e uma lista de comandos de teste verificados, consulte Testar um modelo do Model Armor.

Encobrir dados sensíveis de solicitações e respostas

É possível instruir o Model Armor a ocultar dados sensíveis, como números ID nacional e de telefone, de payloads. Para usar esse recurso, siga estas etapas:

Se você usar o tipo de restrição INSPECT_AND_BLOCK, uma das seguintes situações vai ocorrer:

  • Se um payload violar apenas o detector da Proteção de Dados Sensíveis, o Model Armor vai encobrir o payload de acordo com as configurações avançadas da Proteção de Dados Sensíveis e o modelo de desidentificação.

  • Se um payload violar vários detectores, o Model Armor não vai realizar a ocultação, mas bloqueará todo o payload.

Se você usar o tipo de aplicação INSPECT_ONLY em vez de INSPECT_AND_BLOCK, o Model Armor não vai encobrir o payload.

Independentemente do tipo de restrição (INSPECT_ONLY ou INSPECT_AND_BLOCK), os registros do Model Armor são encobertos de acordo com as configurações avançadas da Proteção de Dados Sensíveis e o modelo de desidentificação.

Para uma lista completa de detectores do Model Armor (também chamados de filtros), consulte Filtros do Model Armor.

Payloads compatíveis e incompatíveis

Nesta seção, listamos os tipos de payloads que o Model Armor limpa.

Tráfego do cliente para o agente (entrada)

Para o tráfego de cliente para agente (entrada) usando o protocolo ADK, o Model Armor limpa apenas as solicitações e respostas reasoningEngines.streamQuery para agentes que foram criados usando o Kit de Desenvolvimento de Agente (ADK) e estão em execução no Vertex AI Agent Engine.

Todos os outros payloads ReasoningEngine e respostas de erro ReasoningEngine não são enviados ao Model Armor. Os payloads que não são do ADK (como os do Langchain) também não são enviados ao Model Armor.

Tráfego do agente para qualquer lugar (saída)

Para o tráfego de agente para qualquer lugar (saída), os payloads a seguir são compatíveis.

Payloads A2A

O Model Armor limpa apenas os seguintes payloads do protocolo A2A v1:

O Model Armor permite os seguintes payloads de A2A sem limpeza:

Payloads do MCP

O Model Armor higieniza apenas os seguintes payloads do MCP:

  • Solicitação e resposta de tools/call
  • Solicitação e resposta de prompts/get
  • Erros de execução da ferramenta MCP (alvo de injeção de comandos por autores de ferramentas MCP mal-intencionadas)

O Model Armor permite os seguintes payloads sem sanitização:

  • tools/list
  • resources/*
  • notifications/*
  • HTTP/SSE transmissível para MCP
  • Erros de protocolo MCP (por exemplo, todos os erros que não são de execução de ferramenta)

Payloads de LLM externos

O Model Armor limpa apenas os seguintes payloads do protocolo da API OpenAI (saída), que inclui modelos GPT no openai.com, bem como qualquer outro modelo por meio de servidores LLM compatíveis com a API OpenAI (como vLLM). Os payloads que não estão listados aqui são permitidos sem limpeza.

Triagem de documentos

A limpeza de comandos e respostas que contêm documentos ou uploads de arquivos (como PDFs) não é compatível com essa integração. Para analisar documentos, chame a API REST do Model Armor diretamente. Para mais informações, consulte Análise de documentos na documentação do Model Armor.

Cotas e limites do sistema

A cota é consumida no projeto em que os modelos do Model Armor estão. Se o gateway estiver em um projeto diferente, a cota de ExternalProcessor também será consumida no projeto do gateway.

Para mais informações sobre as cotas que se aplicam quando você usa o Model Armor com outros serviços, consulte Gerenciar cotas.

Para informações gerais sobre as cotas e os limites do sistema do Model Armor, incluindo o tamanho de entrada e os limites de tokens, consulte Cotas e limites do sistema na documentação do Model Armor.

A seguir