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 funciona como um plano de controle que gerencia, protege e governa como os agentes de IA se conectam e interagem no Google Cloud ambiente 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 que a Gemini Enterprise Agent Platform gerencia. Quando o conteúdo passa pelo Gateway de Agente, ele invoca o Model Armor para aplicar os modelos de segurança predefinidos. É possível configurar o modelo para bloquear e redigir 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. É possível conferir essas descobertas na página Model Armor no Google Cloud console (Acesse Model Armor). Essas descobertas também aparecem no Security Command Center. Para mais informações, consulte Analisar descobertas no Google Cloud console.

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 de longa duração e respostas de modelos.

Limitações

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

• Suporte a streaming para agentes: o Model Armor só oferece suporte à higienizaçã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 higienizar solicitações de um serviço, como o Gateway de Agente, em um projeto diferente, a cota da 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 Google Cloud região. As chamadas entre regiões para o Model Armor não são aceitas.
• Compatibilidade de 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 OpenAI, e A2A pelo Gateway de Agente.
• Compatibilidade de integração de entrada: a proteção de entrada inline com Model Armor só é aceita para 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. É possível 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 Google Cloud console, consulte 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 do cliente para o agente (entrada) , especifique os modelos do Model Armor que você criou para o tráfego de entrada. Para o gateway do 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 adequados:

   • Do cliente para o agente (entrada): conceda ao Agente de serviço do mecanismo de raciocínio da 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.

     • 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:[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.

   • Do 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:[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 (do cliente para o 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 de volta ao 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 enviadas do agente para o sistema externo e as respostas recebidas do sistema externo de volta ao 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 o agente de IA.
• Respostas enviadas do agente de IA de volta ao cliente.

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

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

Todos os outros ReasoningEngine payloads e ReasoningEngine respostas de erro não são enviados ao Model Armor. Os payloads não ADK (como payloads Langchain) também não são enviados ao Model Armor.

Fluxo de tráfego do cliente para o agente

1. Um cliente envia um comando ao agente. O Gateway de Agente intercepta a solicitação e envia o payload ao 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 examina 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 modelos que o Model Armor usa para avaliar:

• Solicitações enviadas do agente de IA para sistemas externos.
• Respostas recebidas de sistemas externos de volta ao 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 bloqueado, a conexão será encerrada.
3. Se permitido, a solicitação será enviada ao sistema externo.
4. O sistema externo envia uma resposta. O Gateway de Agente intercepta essa resposta recebida.
5. O Model Armor filtra o payload de 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 trace.

Usar um ID de trace

Um ID de trace conecta todos os eventos de uma única solicitação à medida que ela viaja por vários serviços em um sistema distribuído. Isso inclui as aplicaçõ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 no 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 seu próprio ID 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 Google Cloud projeto.
  • 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 pelo Gateway de Agente ao Model Armor e a todos os agentes downstream. Isso é essencial para depurar, entender ações de segurança e monitorar o desempenho. Para mais informações, consulte Conferir períodos de trace do Model Armor spans.

Para conferir os registros de operação de higienização de um ID de trace específico, use a consulta a seguir 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 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, da solicitação inicial à 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.