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 governa como os agentes de IA se conectam e interagem no ambiente 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 nos 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 encobrir conteúdo que viola 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. Você pode conferir essas descobertas na página Model Armor no console do Google Cloud (Acessar o Model Armor). Essas descobertas também aparecem no Security Command Center. Para mais informações, consulte Analisar descobertas no console doGoogle Cloud .

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

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 à limpeza 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 outro projeto, a cota de API do Model Armor precisa ser suficiente no projeto que hospeda o modelo e 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 . As chamadas entre regiões para o Model Armor não são compatíveis.
• Compatibilidade da 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 do Ingress: a proteção inline do Ingress com o Model Armor só é compatível com agentes criados usando o ADK.

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. Você pode usar o mesmo modelo para tráfego de entrada e saída.

   Anote os nomes dos modelos. Para copiar o nome de um modelo no consoleGoogle Cloud , 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 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 às contas de serviço adequadas:

   • Cliente para agente (entrada): conceda à conta de serviço do agente de serviço do mecanismo de raciocínio do AI Platform 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.

     • 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:[e-mail] \
         --role=roles/modelarmor.calloutUser
     gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
         --member=serviceAccount:[e-mail] \
         --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 à conta de serviço do Agent Gateway os seguintes papéis:

     • Os papéis 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:[e-mail] \
         --role=roles/modelarmor.calloutUser
     gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
         --member=serviceAccount:[e-mail] \
         --role=roles/serviceusage.serviceUsageConsumer
     gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
         --member=serviceAccount:[e-mail] \
         --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 na 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 tanto as solicitações recebidas do cliente para o agente quanto as respostas enviadas do agente para o cliente.
• Tráfego de saída (agente para qualquer lugar): refere-se ao fluxo de comunicação entre o agente e um sistema externo. O Model Armor pode proteger tanto as solicitações enviadas do agente para o sistema externo quanto as respostas recebidas do sistema externo de volta para o agente.

Proteção do cliente para o agente (entrada)

Você define 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 para o cliente.

É possível aplicar um único modelo às duas direções ou configurar modelos diferentes para cada uma.

Para o tráfego de cliente para agente (entrada) usando o protocolo ADK, o Model Armor higieniza apenas solicitações e respostas reasoningEngines.streamQuery de agentes criados com o Kit de Desenvolvimento de Agente (ADK) e em execução no Agent Runtime.

Todos os outros payloads de 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.

Fluxo de tráfego de cliente para agente

1. Um cliente envia um comando ao 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, o pedido 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 examina a resposta, e o Gateway de Agente a permite ou bloqueia com base no veredito.

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

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

• Solicitações enviadas do seu agente de IA para sistemas externos.
• Respostas recebidas de sistemas externos para seu 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 do 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 será encerrada.
3. Se permitido, o pedido será enviado ao sistema externo.
4. O sistema externo envia uma resposta. 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.

Acompanhar 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 rastreamento.

Usar um ID de rastreamento

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 imposições de segurança que o Model Armor aplica no caminho de solicitação do recurso do Gateway de Agente.

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

Um ID de rastreamento é 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 rastreamento 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 rastreamento 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 seu mecanismo de raciocínio.

Usar um ID de rastreamento é o método recomendado para correlacionar registros e rastreamentos de ponta a ponta do chamador pelo gateway de agente até o Model Armor e qualquer agente downstream. Isso é essencial para depurar, entender ações de segurança e monitorar o desempenho. Para mais informações, consulte Visualizar intervalos de rastreamento do Model Armor.

Para conferir os registros de operações 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 do rastreamento da sua 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 higienizaçã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.