Integrar com a plataforma de agentes do Gemini Enterprise

O Model Armor pode ser integrado diretamente à plataforma de agentes do Gemini Enterprise usando configurações mínimas ou usando modelos. O Model Armor é integrado à plataforma de agentes do Gemini Enterprise para analisar as solicitações enviadas e as respostas recebidas dos modelos do Gemini. Ele inspeciona ou bloqueia o tráfego que viola as configurações mínimas.

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 ter visibilidade dos resultados da higienização de comandos e respostas.

Além de proteger chamadas REST diretas para o serviço da plataforma de agentes do Gemini Enterprise, também é possível usar o Model Armor para proteger outras interfaces que fornecem acesso à API Gemini na Vertex AI, como os SDKs de IA generativa do Google ou os SDKs de lógica de IA do Firebase.

Antes de começar

Conceda a permissão de usuário do Model Armor à conta de serviço da plataforma de agentes do Gemini Enterprise.

gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com' --role='roles/modelarmor.user'

Substitua:

  • PROJECT_ID: o ID do Google Cloud projeto.
  • PROJECT_NUMBER: o número do seu Google Cloud projeto.

Definir configurações mínimas

Use as configurações mínimas para definir os limites básicos de detecção para modelos do Model Armor. Essas configurações verificam se todos os modelos novos e modificados atendem aos requisitos de configurações mínimas.

Para ativar a integração do Model Armor e da plataforma de agentes do Gemini Enterprise, você pode definir as configurações mínimas apenas no nível do projeto usando a API ou o Google Cloud console.

Para configurar as configurações mínimas, consulte Definir as configurações mínimas.

Para configurar as configurações mínimas com a integração da plataforma de agentes do Gemini Enterprise, execute o seguinte comando:

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 de agentes 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, use 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 para as 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 higienização da plataforma de agentes do Gemini Enterprise, o Model Armor higieniza 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 '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Substitua:

  • PROJECT_ID: o ID do Google Cloud projeto.
  • 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 configurações mínimas

Para configurar como o Model Armor processa as detecções, defina o tipo de aplicação. O exemplo a seguir mostra a configuração de configuraçõ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 pelo ID do projeto que contém as configurações mínimas.

Configurar modelos do Model Armor

O Model Armor também pode ser integrado à plataforma de agentes do Gemini Enterprise usando modelos do Model Armor. Os modelos permitem configurar como o Model Armor verifica comandos e respostas e definem configurações de filtro de segurança.

Primeiro, crie modelos e, em seguida, 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 plataforma de agentes do Gemini Enterprise vai encaminhar a solicitação para o Model Armor para processamento.

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.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "PROMPT"
            }
        ]
    }
]
, "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 Google Cloud ID do projeto.
  • LOCATION: o Google Cloud local do endpoint do Gemini. Os locais compatíveis são us-central1, us-east4, us-west1 e europe-west4.
  • PROMPT: o comando de texto.
  • 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.5-flash",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Precedência de configuração

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

  1. Modelos do Model Armor: qualquer configuração fornecida explicitamente na configuração definida na 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 sobreposiçã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 plataforma de agentes do Gemini Enterprise: os filtros de segurança padrão integrados à plataforma de agentes do Gemini Enterprise têm a menor precedência. Eles são aplicados apenas se nenhum modelo específico do Model Armor ou configurações mínimas forem definidos.

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), aproveitando os recursos de segurança inerentes da plataforma de agentes do Gemini Enterprise como uma linha de base.

Considerações

Considere o seguinte ao integrar o Model Armor à plataforma de agentes do Gemini Enterprise:

  • A redação de Proteção de Dados Sensíveis para o modelo de desidentificação não é compatível.
  • A higienização de comandos e respostas que contêm documentos não é compatível.

  • A plataforma de agentes do Gemini Enterprise ignora 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 em que a plataforma de agentes do Gemini Enterprise está presente.
    • O Model Armor está temporariamente inacessível.
    • Ocorreu um erro no Model Armor.

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

    Embora a integração seja projetada para manter o serviço em execução mesmo que a conexão falhe, o modo INSPECT_AND_BLOCK ainda mostra erros de configuração, como problemas de permissão ou cota.