Integrar o Model Armor ao Gateway de Agente

A Gemini Enterprise Agent Platform é uma plataforma para criar e gerenciar agentes de IA de nível empresarial. O Gateway de Agente serve como um plano de controle que gerencia, protege e controla como os agentes de IA se conectam e interagem no ambiente do Google Cloud e com agentes externos, aplicativos de IA e LLMs. A integração do Model Armor e do Gateway de Agente incorpora os recursos de triagem do Model Armor diretamente aos caminhos de comunicação gerenciados pela Gemini Enterprise Agent Platform. Quando o conteúdo passa pelo Gateway de Agente, ele invoca o Model Armor para aplicar seus modelos de segurança predefinidos. É possível configurar o modelo para bloquear e editar conteúdo que viole as políticas ou apenas inspecionar o conteúdo e registrar as violações detectadas. Isso reduz riscos como injeção de comandos, jailbreaks, exposição a conteúdo nocivo e vazamento de dados sensíveis.

Quando o Model Armor detecta violações da política no conteúdo que passa pelo Gateway de Agente, ele pode ser configurado para registrar esses eventos. É possível conferir essas descobertas na página Model Armor no console do Google Cloud (acesse o Model Armor). Essas descobertas também são exibidas no Security Command Center. Para mais informações, consulte Analisar as descobertas no console doGoogle Cloud .

Ao usar o modo de streaming em tempo real, o Model Armor aceita tokens ilimitados no stream, o que o torna adequado para interações de longa duração e respostas de modelos.

Limitações

Considere as seguintes limitações ao integrar o Model Armor com o Gateway de Agente:

  • Suporte a streaming para agentes: o Model Armor só oferece suporte à sanitização de streaming usando o método streamQuery para agentes criados com o Kit de Desenvolvimento de Agente.
  • Uso de modelos entre projetos: ao usar um modelo do Model Armor em um projeto para limpar solicitações de um serviço, como o Gateway de Agente, em um projeto diferente, a cota de API do Model Armor precisa ser suficiente tanto no projeto que hospeda o modelo quanto no projeto que hospeda o serviço de chamada. Para mais informações, consulte Gerenciar cota.
  • Alinhamento regional: o Model Armor e os serviços com que ele se integra precisam ser implantados na mesma região do Google Cloud . Não é possível fazer chamadas entre regiões para o Model Armor.
  • Compatibilidade com integração de saída: a proteção inline do Model Armor no tráfego de saída é limitada a integrações com servidores MCP, serviços que seguem o formato da OpenAI e A2A pelo Gateway de Agente.
  • Compatibilidade com a integração de entrada: a proteção de entrada inline com o Model Armor só é compatível com agentes criados usando o ADK.
  • Sem suporte a 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.
  • Payloads compatíveis: para uma lista de payloads compatíveis, 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.

Tráfego de entrada e saída

No contexto da integração do Gateway de Agente e do Model Armor, os termos entrada e saída são usados da perspectiva das interações do agente de IA:

  • Tráfego de entrada (cliente para agente): refere-se ao fluxo de comunicação entre um cliente e o agente. O Model Armor pode proteger as solicitações recebidas do cliente para o agente e as respostas enviadas do agente para o cliente.
  • Tráfego de saída (do agente para qualquer lugar): refere-se ao fluxo de comunicação entre o agente e um sistema externo. O Model Armor pode proteger as solicitações de saída do agente para o sistema externo e as respostas de entrada do sistema externo de volta para o agente.

Proteção de entrada do cliente para o agente

Você define os modelos que o Model Armor usa para avaliar:

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

É possível aplicar um único modelo a ambas as direções ou configurar modelos diferentes para cada uma.

Fluxo de tráfego de cliente para agente

  1. Um cliente envia um comando para o agente. O Gateway de Agente intercepta a solicitação e envia o payload para o Model Armor.
  2. O Model Armor examina a solicitação. Se bloqueado, o cliente recebe um erro.
  3. Se permitido, a solicitação chega ao agente de IA.
  4. O agente de IA gera uma resposta. O Gateway de Agente intercepta essa resposta antes que ela chegue ao cliente.
  5. O Model Armor analisa a resposta, e o Gateway de Agente a permite ou bloqueia com base no veredito.

Proteção do agente para qualquer lugar (saída)

Você define os modelos que o Model Armor usa para avaliar:

  • Solicitações de saída do seu agente de IA para sistemas externos.
  • Respostas recebidas de sistemas externos de volta para o agente de IA.

Essa proteção se aplica a comunicações com sistemas, incluindo:

  • LLMs externos e agentes de IA de terceiros
  • Servidores do Protocolo de Contexto de Modelo (MCP, na sigla em inglês)
  • Outros agentes de IA

Fluxo de tráfego para o agente para qualquer lugar

  1. O agente de IA inicia uma solicitação para um sistema externo. O Gateway de Agente intercepta o tráfego de saída.
  2. O Model Armor examina o payload de saída. Se bloqueada, a conexão é encerrada.
  3. Se permitido, a solicitação é enviada ao sistema externo.
  4. O sistema externo envia uma resposta de volta. O Gateway de Agente intercepta essa resposta recebida.
  5. O Model Armor examina o payload da resposta, e o Gateway de Agente permite que ele chegue ao agente ou o bloqueia.

Para mais informações, consulte Configurar o Model Armor em um gateway.

Rastrear e depurar solicitações de streaming

Para facilitar o rastreamento e a depuração de solicitações de streaming, o Model Armor usa um ID de correlação e um ID de trace.

Usar um ID de trace

Um ID de trace conecta todos os eventos de uma única solicitação à medida que ela passa por vários serviços em um sistema distribuído. Isso inclui as restrições de segurança que o Model Armor aplica no caminho de solicitação do recurso do Gateway de Agente.

Cada trace contém um ou mais períodos, em que cada ID de período representa uma operação ou unidade de trabalho específica dentro do trace. Os registros gerados durante a execução de uma solicitação são associados ao ID de período específico da operação que realiza o trabalho.

Um ID de trace é processado de duas maneiras:

  • Automático: quando o Google Cloud Observability está ativado, o Gateway de Agente gera automaticamente um ID de trace e o propaga pelo sistema.

  • Fornecido pelo usuário: é possível substituir o ID de trace gerado pelo sistema fornecendo o seu próprio usando o cabeçalho HTTP traceparent nas solicitações.

    O exemplo de código a seguir mostra como transmitir um ID de trace personalizado em uma solicitação para o método streamQuery:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-98adffecc8dd095968a06c44216190f6-5b565a8342378cd7-01" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:streamQuery?alt=sse"

    Substitua:

    • LOCATION: a região em que o mecanismo de raciocínio está localizado.
    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • REASONING_ENGINE_ID: o ID do mecanismo de raciocínio.

O uso de um ID de trace é o método recomendado para correlacionar registros e traces de ponta a ponta, do autor da chamada ao Model Armor e a todos os agentes downstream, passando pelo Gateway de Agente. Isso é essencial para depurar, entender ações de segurança e monitorar o desempenho. Para mais informações, consulte Ver períodos de trace do Model Armor.

Para ver os registros de operação de limpeza de um ID de trace específico, use a seguinte consulta na Análise de registros:

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID

Substitua TRACE_ID pelo ID de trace da solicitação.

Usar um ID de correlação

Um ID de correlação vincula todas as entradas de registro no Cloud Logging que pertencem a uma única sessão de sanitização de streaming, desde a solicitação inicial até a resposta final. É um identificador interno usado principalmente nos registros do Model Armor, especificamente para sessões de streaming de entrada. Para mais informações, consulte Correlacionar registros e eventos relacionados.

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 Agent Runtime.

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.