Integrar o Model Armor à Gemini Enterprise Agent Platform

Neste documento, descrevemos como configurar o Model Armor para proteger modelos do Gemini na Gemini Enterprise Agent Platform ao filtrar comandos e respostas. Quando integrado à Gemini Enterprise Agent Platform, o Model Armor intercepta comandos antes que eles cheguem aos modelos do Gemini e intercepta respostas antes que seu aplicativo as receba. Com base na sua configuração, a Gemini Enterprise Agent Platform chama o serviço Model Armor, que inspeciona ou bloqueia o tráfego que viola suas políticas definidas, aplicando medidas de segurança como injeção de comando e detecção de jailbreak, filtros de IA responsável e proteção de dados sensíveis. É possível configurar essa integração usando configurações mínimas para proteção para envolvidos no projeto ou modelos para proteção por solicitação.

O Model Armor oferece proteção de comandos e respostas na API Gemini na Vertex AI para o método generateContent. É necessário ativar o Cloud Logging para ver os resultados da higienização de comandos e respostas.

Além de proteger chamadas REST diretas para o serviço da Gemini Enterprise Agent Platform, você também pode usar o Model Armor para proteger outras interfaces que fornecem acesso à API Gemini na Vertex AI, como os SDKs da IA generativa do Google ou os SDKs do Firebase AI Logic.

Limitações

Considere as seguintes limitações ao integrar o Model Armor com a Gemini Enterprise Agent Platform:

  • Quando o Model Armor usa um modelo da Proteção de Dados Sensíveis para verificar comandos ou respostas, ele confere se o conteúdo corresponde aos critérios de filtro definidos no modelo. Se ele encontrar uma correspondência, o Model Armor vai sinalizar que o conteúdo acionou o filtro da Proteção de Dados Sensíveis. Embora a Proteção de Dados Sensíveis desidentifique os dados com base na configuração do modelo, o Model Armor não transmite os dados desidentificados, como conteúdo mascarado, censurado ou com hash, de volta para a Gemini Enterprise Agent Platform para processamento adicional. Em vez disso, se o tipo de aplicação for INSPECT_AND_BLOCK, o Model Armor vai emitir um veredito de bloqueio para garantir que dados sensíveis não sejam processados.
  • Não é possível higienizar comandos e respostas que contêm documentos.
  • Se a Gemini Enterprise Agent Platform encaminhar uma solicitação para uma região em que o modelo especificado do Model Armor não existe, a solicitação vai falhar com um erro Template not found.

  • A Gemini Enterprise Agent Platform pula a etapa de higienização do Model Armor e continua processando a solicitação nas seguintes condições:

    • O Model Armor não está disponível em uma região onde a Gemini Enterprise Agent Platform está presente.
    • O Model Armor está temporariamente inacessível.
    • Ocorrer um erro no Model Armor.

    Todas essas instâncias podem expor comandos ou respostas não verificados porque a solicitação continua sem sanitização de comandos e respostas.

    Embora a integração seja criada para alta disponibilidade durante falhas de conexão, o modo INSPECT_AND_BLOCK ainda vai informar erros de configuração, como problemas de permissão ou cota.

Antes de começar

Configurar como o Model Armor ajuda a proteger a Gemini Enterprise Agent Platform

Você pode configurar como o Model Armor protege a Gemini Enterprise Agent Platform de duas maneiras:

  • Use modelos para proteção por solicitação: essa abordagem oferece controle granular, permitindo que você aplique um modelo específico a cada chamada de API generateContent para modelos do Gemini na Gemini Enterprise Agent Platform.
  • Use configurações mínimas para proteção no nível do projeto: essa abordagem aplica uma proteção básica ao usar configurações mínimas em todas as chamadas da API generateContent para modelos do Gemini na plataforma de agentes do Gemini Enterprise no seu projeto.

Defina o tipo de aplicação para determinar se as violações são apenas inspecionadas ou também bloqueadas.

Configuração por solicitação usando modelos

Com os modelos, é possível configurar como o Model Armor examina comandos e respostas e definir configurações de filtro de segurança. Primeiro, crie modelos e depois use-os com o método generateContent do Gemini. Para mais informações sobre modelos, consulte Criar e gerenciar modelos do Model Armor.

Depois de configurar o modelo do Model Armor, transmita o ID do modelo como um parâmetro ao fazer uma chamada para a API Gemini usando o método generateContent. A Gemini Enterprise Agent Platform encaminha a solicitação para o Model Armor para processamento.

Para aplicar modelos específicos a uma chamada generateContent individual, inclua o objeto modelArmorConfig na solicitação.

  • promptTemplateName: o nome do recurso do modelo do Model Armor para higienizar o comando.
  • responseTemplateName: o nome do recurso do modelo do Model Armor para higienizar a resposta.

O exemplo de código a seguir mostra a solicitação para o método generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "[YOUR PROMPT HERE]"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "model_armor_config": {
        "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
        }
}'

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: o Google Cloud local do endpoint do Gemini. Os locais aceitos são europe-west1, europe-west2, europe-west3, asia-southeast1 e asia-south1.
  • TEMPLATE_ID: ID do modelo do Model Armor.

O exemplo de código a seguir mostra a resposta do método generateContent.

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Definir o tipo de aplicação para modelos

Para configurar como o Model Armor lida com as detecções, defina o tipo de aplicação.

O exemplo a seguir mostra a configuração do modelo do Model Armor com o tipo de aplicação Inspect only.

export TEMPLATE_CONFIG='{
   "filter_config": {
    "rai_settings": {
     "rai_filters": [{
       "filter_type": "HATE_SPEECH",
       "confidence_level": "MEDIUM_AND_ABOVE"
      }, {
      "filter_type": "HARASSMENT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }, {
      "filter_type": "DANGEROUS",
      "confidence_level": "MEDIUM_AND_ABOVE"
    },{
      "filter_type": "SEXUALLY_EXPLICIT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }]
  },
  "pi_and_jailbreak_filter_settings": {
    "filter_enforcement": "ENABLED",
    "confidence_level": "LOW_AND_ABOVE"
  },
  "malicious_uri_filter_settings": {
    "filter_enforcement": "ENABLED"
  }
 },
 "template_metadata": {
    "enforcement_type": "INSPECT_ONLY",
    "multi_language_detection": {
      "enable_multi_language_detection": true
    }
  }
}'

curl -X POST \
    -d "$TEMPLATE_CONFIG"  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

Substitua:

  • PROJECT_ID: o ID do projeto a que o modelo pertence.
  • TEMPLATE_ID: o ID do modelo a ser criado.
  • LOCATION: o local do modelo.

Configuração para envolvidos no projeto usando as configurações mínimas

As configurações mínimas definem uma proteção básica que se aplica a todas as chamadas da Gemini Enterprise Agent Platform generateContent em um projeto, mesmo que o parâmetro modelArmorConfig seja omitido da solicitação de API. Consulte Definir configurações mínimas para saber como fazer isso.

Para ativar a integração do Model Armor e da Gemini Enterprise Agent Platform, defina as configurações mínimas apenas no nível do projeto usando a API ou o console Google Cloud .

Para configurar as configurações mínimas com a integração da Gemini Enterprise Agent Platform, execute o comando a seguir:

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

Esse comando ativa o modo de aplicação INSPECT_ONLY por padrão. Para mudar o modo para INSPECT_AND_BLOCK, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

Para remover a plataforma do agente do Gemini Enterprise dos serviços integrados, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

Para remover todos os serviços integrados configurados das configurações mínimas, execute o seguinte comando:

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

Substitua PROJECT_ID pelo ID do projeto das configurações mínimas.

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Substitua PROJECT_ID pelo ID do projeto que contém as configurações mínimas.

Depois de configurar as configurações mínimas para ativar a limpeza da Gemini Enterprise Agent Platform, o Model Armor limpa todas as chamadas de API generateContent para os endpoints do Gemini do projeto usando as configurações de filtro especificadas.

O exemplo de código a seguir mostra como usar o método generateContent.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: o Google Cloud local do endpoint do Gemini. Para locais compatíveis, consulte Locais da API Model Armor.

O exemplo de código a seguir mostra a resposta do método generateContent.

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated
  Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection
  and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Definir o tipo de aplicação para as configurações mínimas

Para configurar como o Model Armor lida com as detecções, defina o tipo de aplicação como INSPECT ou INSPECT_AND_BLOCK. O exemplo a seguir mostra a configuração de restrições mínimas com o tipo de aplicação INSPECT_AND_BLOCK.

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Substitua:

  • PROJECT_ID: o ID do projeto para as configurações mínimas.
  • LOCATION: o local das configurações mínimas.

Testar a aplicação inline com uma chamada de API

Teste a integração para chamar o método generateContent da API Gemini Enterprise Agent Platform. Usar um comando projetado para violar as configurações mínimas configuradas.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": ""
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
}
}'

Se a integração estiver funcionando conforme o esperado, a API vai retornar uma resposta com o campo blockReason definido como MODEL_ARMOR quando o Model Armor identificar a solicitação como uma violação.

Confira um exemplo de resposta:

    {
    "promptFeedback": {
      "blockReason": "MODEL_ARMOR",
      "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings..."
    },
    "usageMetadata": { "trafficType": "ON_DEMAND" },
    "modelVersion": "gemini-2.5-flash"
    }

Regras de interação e precedência

Ao usar o Model Armor com a Gemini Enterprise Agent Platform, é possível definir configurações de segurança em vários níveis. Nesses casos, a Model Armor e a Gemini Enterprise Agent Platform seguem uma ordem de precedência específica:

  1. Model Armor templates: qualquer configuração fornecida explicitamente na configuração da solicitação de API tem a maior precedência. Essas configurações substituem qualquer outra configuração conflitante para essa solicitação específica.

  2. Configurações mínimas do Model Armor: se nenhuma configuração de substituição for fornecida na solicitação de API, as configurações mínimas do Model Armor serão aplicadas.

  3. Filtros de segurança da Gemini Enterprise Agent Platform: os filtros de segurança padrão integrados à plataforma têm a menor precedência. Elas só se aplicam se você não definir modelos ou configurações mínimas do Model Armor específicos.

Essa abordagem hierárquica oferece uma combinação de padrões mínimos amplos em toda a organização (usando configurações mínimas) e controle por solicitação (usando modelos), sem deixar de usar os recursos de segurança inerentes da Gemini Enterprise Agent Platform como base.

O comportamento do Model Armor e dos recursos de segurança da Gemini Enterprise Agent Platform depende de como você fornece a configuração.

O modelo está configurado? Os filtros de segurança da Gemini Enterprise Agent Platform estão configurados? As configurações mínimas estão definidas? Comportamento
Sim Sim Qualquer Você vai receber um erro. Não é possível especificar a configuração do modelo e os filtros de segurança da Gemini Enterprise Agent Platform na mesma solicitação.
Sim Não Qualquer O Model Armor é executado usando os modelos especificados em modelArmorConfig. Os filtros de segurança da Gemini Enterprise Agent Platform são ignorados. Os modelos de solicitação substituem as configurações mínimas.
Não Sim Sim Ambos são executados. O Model Armor faz verificações usando a política de configuração mínima, e a Gemini Enterprise Agent Platform avalia os filtros de segurança. O resultado mais restritivo é aplicado.
Não Não Sim Execuções do Model Armor usando a política de configuração de valor mínimo ativa.
Não Sim Não Somente os filtros de segurança da Gemini Enterprise Agent Platform são avaliados. O Model Armor não é chamado.
Não Não Não Não são aplicados filtros de segurança por solicitação do Model Armor nem da Gemini Enterprise Agent Platform. Somente os comportamentos do modelo de referência estão ativos.