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 exigir que você implemente a lógica de filtragem diretamente nos agentes. Quando você configura o Model Armor com o Gateway de Agente, o Model Armor aplica as proteções de segurança de conteúdo da sua organização inspecionando todos os comandos e respostas que passam pelo gateway. Com esse recurso, você pode aplicar restrições de segurança de conteúdo de maneira consistente em todos os agentes gerenciados 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 prejudicial. 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 proteção e segurança. Para mais informações, consulte Modelos do Model Armor.

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

Tráfego de entrada e saída

Com o 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 solicitações e respostas no tráfego de cliente para agente. É possível aplicar um único modelo às duas 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 enviadas do agente de IA para o cliente

Quando um cliente envia um comando ao agente, o Gateway de Agente intercepta o tráfego e envia o payload para o Model Armor para higienização. Se o Model Armor emitir um veredito de ALLOW, o gateway de agentes vai 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 fluxo de saída antes que ele chegue ao cliente. O Model Armor avalia a resposta e emite um veredito. Com base no veredicto, o Gateway de Agente permite ou bloqueia totalmente a resposta.

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 às duas 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 a carga útil de acordo com os modelos de saída definidos.

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 impedir que dados sensíveis ou prejudiciais cheguem ao LLM, à ferramenta ou ao agente de IA externo.

Antes de começar

Ative a API Model Armor, se ela 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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o 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 obrigató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 consoleCloud de Confiance , confira os detalhes do modelo e clique em Copiar para a área de transferência ao lado do nome do modelo.

  3. Configure o Gateway de Agente na mesma região em que os modelos do Model Armor estão armazenados. Para o gateway cliente-agente (entrada), especifique os modelos do Model Armor que você criou para o tráfego de entrada. Para o gateway de saída do agente para qualquer lugar, 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 adequados:

    • Cliente para agente (entrada): conceda ao agente de serviço do AI Platform Reasoning Engine Service Agent os seguintes papéis:

      • A função de usuário do Model Armor Callout (roles/modelarmor.calloutUser) no projeto que contém o agente de IA.

      • A função 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.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

      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.
      • A função 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.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

      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, você pode executar uma verificação pré-implantação para verificar se a configuração do modelo está aplicando as políticas de segurança corretamente.

Para validar seu 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 Validar a configuração do modelo.

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

Você pode instruir o Model Armor a encobrir dados sensíveis, como números ID nacional e números de telefone, de payloads. Para usar esse recurso, siga estas etapas:

Se você usar o tipo de aplicaçã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 fazer a redação. Ele vai bloquear o payload inteiro.

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.

Independente do tipo de aplicação (INSPECT_ONLY ou INSPECT_AND_BLOCK), os registros do Model Armor são encobridos 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

Esta seção lista os tipos de payloads que o Model Armor higieniza.

Tráfego do cliente para o agente (entrada)

Para tráfego de cliente para agente (entrada) usando o protocolo ADK, o Model Armor higieniza apenas solicitações e respostas reasoningEngines.streamQuery para agentes criados com o Kit de Desenvolvimento de Agente (ADK) e 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. Payloads que não são do ADK (como os do Langchain) também não são enviados para o Model Armor.

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

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

Payloads A2A

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

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

Payloads do MCP

O Model Armor higieniza apenas os seguintes payloads da MCP:

O Model Armor permite os seguintes payloads sem limpeza:

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

Payloads de LLM externos

O Model Armor higieniza apenas os seguintes payloads do protocolo da API OpenAI (saída), que inclui modelos GPT no openai.com e outros modelos por servidores LLM compatíveis com a API OpenAI (como vLLM). Os payloads não listados aqui são permitidos sem higienização.

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 Triagem 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 localizados. 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 aplicadas ao usar o Model Armor com outros serviços, consulte Gerenciar cotas.

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

A seguir