Políticas extensíveis no Gateway de Agente

À medida que os agentes escalam de protótipos iniciais para implantações empresariais, a necessidade de integrar controles internos, pipelines de dados próprios e políticas de segurança empresariais cresce rapidamente. Às vezes, decisões de autorização complexas não podem ser expressas facilmente usando apenas políticas padrão do IAM.

Para atender a esses requisitos, o Gateway de Agente apresenta um novo framework de políticas que permite oferecer suporte à aplicação com serviços do Google, mecanismos de autorização personalizados ou plataformas de segurança de terceiros, aplicando as mesmas políticas de forma universal em todos os gateways. Este documento descreve os principais casos de uso de risco agêntico e explica como configurar políticas extensíveis.

Casos de uso de extensibilidade de políticas para riscos agênticos

Os controles determinísticos padrão geralmente são insuficientes para cargas de trabalho de IA probabilísticas. Os pipelines de serviço extensíveis ajudam as organizações a injetar lógica avançada adaptada a riscos agênticos específicos:

• Proteções de segurança e sanitização de conteúdo:proteção contra injeções de comandos, jailbreaks, saídas tóxicas e perda de informações confidenciais (por exemplo, usando o Model Armor).
• Prevenção contra perda de dados (DLP): monitoramento em tempo real de payloads e blocos de streaming para evitar o vazamento de dados de código reservado ou PII para sistemas externos.
• Governança de identidade de zero trust:validação de credenciais e aplicação de controles de acesso antes que um agente possa acessar back-ends sensíveis ou ferramentas externas (por exemplo, usando o IAP).
• Compliance empresarial personalizado:aplicação de regras personalizadas de descarte de dados sensíveis, tradução de tokens ou mecanismos de compliance específicos para arquiteturas internas.

Framework para extensibilidade de políticas no Gateway de Agente

O Gateway de Agente permite anexar vinculações de extensão para delegar decisões de autorização a Policy Engines especializados, como provedores de identidade, filtros de segurança de conteúdo ou plataformas de segurança personalizadas de terceiros.

O framework de extensibilidade de políticas opera em uma separação entre papéis e recursos:

• Consumidores:operadores do Gateway de Agente que querem adicionar extensões de segurança e governança aos gateways com o mínimo de esforço de configuração.

• Produtores:equipes de plataforma interna, serviços do Google próprios (como IAP e Model Armor) e parceiros ISV de terceiros que criam e publicam extensões de serviço para consumo de terceiros.

• ExtensionBinding:um recurso criado pelo consumidor que vincula um ProducerExtension a um Gateway de Agente de destino, além de condições de correspondência que determinam quando a extensão é invocada. Esse é o único recurso que um consumidor precisa criar para começar a usar uma extensão.

• ProducerExtension:um recurso criado pelo produtor que empacota um mecanismo de autorização compatível com o ext_proc em uma única unidade gerenciada. Ele encapsula todos os parâmetros de execução e configurações de conectividade subjacentes para que os consumidores não precisem configurar mecânicas de plano de dados de baixo nível.

Extensões próprias integradas do Google

Os serviços próprios do Google, como o IAP e o Model Armor, oferecem recursos de extensão pré-empacotados com um modelo operacional simplificado.

• Consumidor:desenvolvedores de aplicativos e operadores de segurança atuam como consumidores. Para ativar a autenticação de confiança zero ou a proteção contra injeção de comandos, crie um recurso ExtensionBinding que tenha como destino os URIs de endpoint de serviço predefinidos do Google diretamente do seu projeto de consumidor.
• Produtor:o Google atua como produtor. O Google cria, hospeda e gerencia a Service Infrastructure e os endpoints de extensão subjacentes globalmente (como iap.googleapis.com ou modelarmor.us.rep.googleapis.com). Não é necessário criar ou gerenciar um recurso ProducerExtension.

Extensões empresariais e de parceiros (2P/3P)

Para Custom Governance, a extensibilidade de políticas permite um modelo de integração flexível de dois lados entre equipes corporativas e parceiros de segurança.

• Produtor:as equipes internas de engenharia de plataforma (2P) ou os fornecedores de segurança de ISV terceirizados (3P) atuam como produtores. O produtor cria um serviço gRPC compatível com o protocolo ext_proc do Envoy, o hospeda em um projeto de produtor dedicado (como um serviço do Cloud Run por trás de um balanceador de carga de aplicativo), o expõe usando um anexo de serviço do Private Service Connect (PSC) e publica um recurso ProducerExtension.

• Consumidor:os desenvolvedores de aplicativos e os administradores de segurança em projetos de consumidor atuam como consumidores. Depois que o produtor conceder acesso usando o PSC, os consumidores vão criar um ExtensionBinding no projeto deles que faz referência ao URI de recurso ProducerExtension específico para aplicar controles personalizados (como políticas de governança semântica ou regras de firewall de terceiros) nas cargas de trabalho.

Padrões de implantação

As vinculações de extensão são compatíveis com padrões de implantação flexíveis para aplicar uma governança consistente em todos os caminhos de tráfego, garantindo que as políticas de governança atuem de maneira idêntica, independentemente de onde os agentes sejam implantados. A API ExtensionBinding se aplica de maneira uniforme a todos os modelos de implantação do Gateway de Agente.

Caminhos de interceptação de tráfego de ponta a ponta

É possível aplicar vinculações de extensão para interceptar o tráfego nos seguintes caminhos de comunicação no seu ecossistema de agentes:

• Usuário → Agente (entrada): intercepta solicitações recebidas de usuários finais ou aplicativos cliente direcionados ao Gateway de Agente para aplicar a autenticação de usuários, a governança de identidade ou a limpeza de injeção de comandos.
• Agente → Ferramenta / MCP (saída): intercepta chamadas de saída de agentes para servidores do Protocolo de Contexto de Modelo (MCP) ou APIs externas para validar permissões e limpar entradas de ferramentas.
• Agente → Modelo de LLM (saída): verifica os comandos antes que eles cheguem aos modelos de fundação e filtra as respostas do modelo para evitar a perda de dados ou saídas tóxicas.

• Agente → Agente (saída A2A): controla a comunicação entre agentes e aplica limites de política quando agentes autônomos colaboram entre projetos.

Do cliente para o agente

Do agente para qualquer lugar

Consumidores: vincular extensões aos Gateways de Agente

Os consumidores (como desenvolvedores de aplicativos ou operadores de segurança) anexam a lógica de governança e segurança aos Gateways de Agente criando um ExtensionBinding. Esse recurso vincula a carga de trabalho de destino a uma extensão e declara condições de correspondência para definir exatamente quando a extensão deve ser invocada (por exemplo, interceptando o tráfego destinado a ferramentas externas específicas ou servidores MCP). É possível especificar condições de correspondência diretamente inline (como mostrado nos exemplos desta seção) ou em um arquivo YAML separado.

Dependendo do provedor da extensão, o consumo segue um de dois caminhos:

Configuração do consumidor próprio

Para serviços do Google, como o IAP ou o Model Armor, o Google gerencia a infraestrutura de back-end e o registro globalmente. Como consumidor, você não precisa segmentar um URI de recurso ProducerExtension específico. É possível vincular diretamente esses serviços às suas cargas de trabalho transmitindo as strings de endpoint predefinidas (por exemplo, iap.googleapis.com ou modelarmor.us.rep.googleapis.com) como o destino no ExtensionBinding.

Vincular uma extensão do IAP a um Gateway de Agente

O exemplo a seguir demonstra um recurso ExtensionBinding que vincula um serviço do Google próprio (IAP) a um Gateway de Agente em um projeto de consumidor. Com base no campo matchConditions especificado, essa extensão é invocada quando o tráfego é enviado para um servidor MCP.

1. Crie um arquivo YAML com a seguinte configuração:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "iap.googleapis.com"
   

   Substitua:

   • EXTENSION_BINDING_NAME: o nome do recurso de vinculação da extensão.
   • PROJECT_ID: o ID do projeto Cloud de Confiance by S3NS .
   • LOCATION: o local do gateway e da vinculação de extensão.
   • AGENT_GATEWAY_NAME: o nome do Gateway de Agente de destino.

2. Importe a configuração de vinculação da extensão:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Substitua EXTENSION_BINDING_FILE_PATH pelo caminho para o arquivo de configuração YAML.

Vincular uma extensão do Model Armor a um Gateway de Agente

Para proteger seus agentes contra injeção de comandos, conteúdo tóxico e vazamento de dados sensíveis, vincule o Model Armor diretamente à sua carga de trabalho. Com base no campo matchConditions especificado, essa extensão é invocada quando o tráfego é enviado para um servidor MCP.

1. Crie um arquivo YAML com a seguinte configuração:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "modelarmor.us.rep.googleapis.com"
   failOpen: true
   producerMetadata:
     model_armor_settings: '[{
       "request_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
       "response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
     }]'
   

   Substitua:

   • EXTENSION_BINDING_NAME: o nome do recurso de vinculação da extensão.
   • PROJECT_ID: o ID do projeto Cloud de Confiance .
   • LOCATION: o local dos recursos.
   • AGENT_GATEWAY_NAME: o nome do Gateway de Agente de destino.
   • TEMPLATE_PROJECT_ID: o ID do projeto em que os modelos do Model Armor estão localizados.
   • REQUEST_TEMPLATE_ID: o ID do modelo do Model Armor usado para avaliar as solicitações.
   • RESPONSE_TEMPLATE_ID: o ID do modelo do Model Armor usado para avaliar as respostas.

2. Importe a configuração de vinculação da extensão:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Substitua EXTENSION_BINDING_FILE_PATH pelo caminho para o arquivo de configuração YAML.

Configuração do consumidor próprio/de terceiros

Como consumidor de uma extensão de serviço criada por outra equipe interna (2P) ou fornecedor terceirizado externo (3P), sua responsabilidade é garantir que o projeto do consumidor tenha recebido explicitamente acesso para usar o serviço. O acesso é controlado pelo produtor usando a configuração do anexo de serviço do Private Service Connect. Depois de receber acesso, vincule a carga de trabalho referenciando o URI de recurso ProducerExtension específico fornecido pelo produtor no ExtensionBinding.

Vincular mecanismos de autorização personalizados

O exemplo a seguir demonstra um recurso ExtensionBinding que vincula uma extensão personalizada de um projeto de produtor 2P/3P a um Gateway de Agente em um projeto de consumidor. Com base no campo matchConditions especificado, essa extensão é invocada quando o tráfego é enviado para um agente.

1. Crie um arquivo YAML com a seguinte configuração:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/CONSUMER_PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:agent"
   producerExtension: "projects/PRODUCER_PROJECT_ID/locations/LOCATION/producerExtensions/PRODUCER_EXTENSION_NAME"
   

   Substitua:

   • EXTENSION_BINDING_NAME: o nome do recurso de vinculação da extensão.
   • CONSUMER_PROJECT_ID: o ID do projeto do consumidor que hospeda o Gateway de Agente.
   • LOCATION: o local dos recursos.
   • AGENT_GATEWAY_NAME: o nome do Gateway de Agente de destino.
   • PRODUCER_PROJECT_ID: o ID do projeto do produtor que hospeda o ProducerExtension.
   • PRODUCER_EXTENSION_NAME: o nome do recurso ProducerExtension.

2. Importe a configuração de vinculação da extensão:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Substitua EXTENSION_BINDING_FILE_PATH pelo caminho para o arquivo de configuração YAML.

Pontos de anexo de vinculação de extensão

As vinculações de extensão podem ser configuradas em diferentes níveis da hierarquia de recursos, dependendo dos requisitos de governança:

• Nível do Gateway de Agente:anexe políticas diretamente a um recurso do Gateway de Agente para controlar todo o tráfego que passa por ele.
• Nível do projeto:crie ExtensionBindings que se aplicam globalmente a todos os recursos de um determinado tipo em um projeto, simplificando o gerenciamento para administradores corporativos que aplicam a conformidade em todo o projeto.

Vincular uma extensão do Model Armor a todos os Gateways de Agente em um projeto

1. Crie um arquivo YAML com a seguinte configuração:

   name: EXTENSION_BINDING_NAME
   target:
     scope:
       parent: "projects/PROJECT_NUMBER"
       resourceTypes: "AGENT_GATEWAY"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "modelarmor.us.rep.googleapis.com"
   failOpen: true
   producerMetadata:
     model_armor_settings: '[{
       "request_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
       "response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
     }]'
   

   Substitua:

   • EXTENSION_BINDING_NAME: o nome do recurso de vinculação da extensão.
   • PROJECT_NUMBER: o número do projeto do Cloud de Confiance .
   • TEMPLATE_PROJECT_ID: o ID do projeto em que os modelos do Model Armor estão localizados.
   • LOCATION: o local dos recursos.
   • REQUEST_TEMPLATE_ID: o ID do modelo do Model Armor usado para avaliar as solicitações.
   • RESPONSE_TEMPLATE_ID: o ID do modelo do Model Armor usado para avaliar as respostas.

2. Importe a configuração de vinculação da extensão:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Substitua EXTENSION_BINDING_FILE_PATH pelo caminho para o arquivo de configuração YAML.

Para solicitações que correspondem a uma carga de trabalho específica, as vinculações de extensão para envolvidos no projeto e no nível do recurso são executadas. Se a mesma extensão estiver configurada no nível do recurso e do projeto, ela será invocada duas vezes.

Condições de correspondência para invocar extensões

As condições de correspondência determinam quando a extensão é invocada. É possível especificar condições de correspondência diretamente inline (como mostrado nos exemplos anteriores nesta página) ou em um arquivo YAML.

Nesta seção, apresentamos exemplos de configurações de arquivos YAML para situações comuns com base no fluxo de tráfego, nos URNs de recursos de destino ou nos hosts de destino:

• Saída para servidores de ferramentas do MCP (agente → ferramenta): intercepta o tráfego enviado de um agente para servidores de ferramentas remotos do Protocolo de Contexto de Modelo (MCP):

  # Invoke extension for all agent traffic to remote MCP servers
  - to:
      destination:
        resources:
        - prefix: "urn:mcp"
  

• Tráfego de entrada (usuário → agente): intercepta solicitações recebidas de usuários finais ou aplicativos clientes direcionados a agentes controlados pelo Gateway de Agente (por exemplo, para aplicar a autenticação do usuário final ou a limpeza de injeção de comandos na entrada):

  # Invoke extension on incoming user requests targeting agents
  - to:
      destination:
        resources:
        - prefix: "urn:agent"
  

• Saída para modelos de LLM (agente → modelo de LLM): intercepta solicitações enviadas de agentes para modelos de LLM de fundação ou servidores de modelos, correspondendo ao host de destino:

  # Invoke extension on traffic sent to a specific model server
  - to:
      destination:
        hosts:
        - exact: "myexamplemodelserver.com"
  

Produtores: criar e publicar extensões

Como produtor personalizado (2P ou 3P), hospede sua implementação de extensão de serviço baseada em ext_proc atrás de um anexo do Private Service Connect. Quando o anexo estiver pronto, crie um recurso ProducerExtension especificando a fase de processamento da solicitação em que a extensão opera, a autoridade a ser usada e o URI do anexo do PSC para o serviço ext_proc:

gcloud beta service-extensions producer-extensions create PRODUCER_EXTENSION_NAME \
  --phase authz \
  --extension-settings=service=projects/PRODUCER_PROJECT_ID/regions/REGION/serviceAttachments/PSC_ATTACHMENT_NAME,authority="example.provider.net"

Substitua:

• PRODUCER_EXTENSION_NAME: o nome do recurso ProducerExtension.
• PRODUCER_PROJECT_ID: o ID do projeto do produtor.
• REGION: a região do anexo de serviço do Private Service Connect.
• PSC_ATTACHMENT_NAME: o nome do anexo de serviço do Private Service Connect.

Hospedar extensões personalizadas no Cloud Run

Para produtores que querem executar o serviço gRPC personalizado do ext_proc sem gerenciar clusters ou VMs dedicados, o Cloud Run é uma alternativa ideal sem servidor.

Para publicar sua extensão sem servidor como um ProducerExtension, exponha-a usando o Private Service Connect (PSC). Como os recursos ProducerExtension exigem um URI de anexo de serviço do PSC, e os anexos de serviço têm como destino regras de encaminhamento de balanceador de carga em vez de serviços do Cloud Run diretamente, coloque um balanceador de carga de aplicativo (usando um back-end de NEG sem servidor) na frente do serviço do Cloud Run.

Este é o fluxo de trabalho de implantação de alto nível para hospedar sua extensão no Cloud Run:

1. Implante sua extensão no Cloud Run:hospede sua extensão gRPC personalizada do ext_proc como um serviço conteinerizado no Cloud Run.

2. Criar um NEG sem servidor:implante um grupo de endpoints de rede (NEG) sem servidor que aponte para a extensão em execução no Cloud Run.

3. Configurar um balanceador de carga com o back-end de NEG sem servidor:configure um balanceador de carga de aplicativo regional na rede VPC, com o NEG sem servidor como back-end.

4. Publique seu serviço com o PSC:crie um anexo de serviço do Private Service Connect que aponte diretamente para a regra de encaminhamento do balanceador de carga. Isso gera um URI de anexo de serviço exclusivo (por exemplo, projects/.../regions/.../serviceAttachments/...).

5. Crie sua extensão de produtor:use esse URI gerado para instanciar o recurso ProducerExtension.

6. Vincular cargas de trabalho do consumidor:agora os consumidores podem vincular os gateways à sua extensão referenciando o URI do recurso ProducerExtension.

Apêndice: metadados contextuais para extensões personalizadas

Para ajudar suas extensões personalizadas a tomar decisões de autorização e processamento com reconhecimento de contexto,os planos de dados do Cloud de Confiance transmitem o contexto de ciclo de vida e de recursos diretamente para os servidores do ext_proc.

Essas informações são agrupadas como metadados não tipados no campo metadata_context do ext_proc gRPC ProcessingRequest. Esses metadados residem no namespace com.google.serviceextensions.invocation_info e usam o formato padrão google.protobuf.Struct.

É possível decodificar ou converter esses metadados em JSON para processamento downstream. Confira um exemplo de formato JSON para uma solicitação direcionada a um Gateway de Agente com tráfego vinculado a um servidor MCP:

{
 "binding_selector" : {
   "target" : "//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME",
   "project_number" : PROJECT_NUMBER,
   "to_resource": "urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID"
 }
}

O esquema do JSON é o seguinte:

message ServiceExtensionsInvocationInfo {
  message ExtensionBindingSelector {
    // The target (gateway ID, etc) in fully qualified name format.
    // For example:
    // "//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    string target = 1;
    // Project number associated with the target.
    uint64 project_number = 2;
    // The destination resource within the Agent Registry that traffic is directed to.
    string to_resource = 3;
  }
  ExtensionBindingSelector binding_selector = 1;
}