Règles extensibles sur Agent Gateway

À mesure que les agents passent de prototypes initiaux à des déploiements d'entreprise, le besoin d'intégrer des contrôles internes, des pipelines de données propriétaires et des règles de sécurité d'entreprise augmente rapidement. Parfois, les décisions d'autorisation complexes ne peuvent pas être facilement exprimées à l'aide des seules stratégies IAM standards.

Pour répondre à ces exigences, Agent Gateway introduit un nouveau framework de règles qui vous permet de prendre en charge l'application des règles avec les services Google, les moteurs d'autorisation personnalisés ou les plates-formes de sécurité tierces, en appliquant les mêmes règles de manière universelle sur vos passerelles. Ce document décrit les principaux cas d'utilisation des risques liés aux agents et explique comment configurer des règles extensibles.

Cas d'utilisation de l'extensibilité des règles pour les risques agentiques

Les contrôles déterministes standards sont souvent insuffisants pour les charges de travail d'IA probabilistes. Les pipelines de services extensibles aident les organisations à injecter une logique avancée adaptée aux risques agentiques uniques :

• Nettoyage du contenu et garde-fous de sécurité : protection contre les injections de prompt, les jailbreaks, les sorties toxiques et la perte d'informations confidentielles (par exemple, à l'aide de Model Armor).
• Protection contre la perte de données (DLP) : surveillance en temps réel des charges utiles et des fragments de flux pour empêcher la fuite de données de code propriétaire ou d'informations permettant d'identifier personnellement l'utilisateur vers des systèmes externes.
• Gouvernance des identités zéro confiance : valider les identifiants et appliquer des contrôles d'accès avant qu'un agent ne soit autorisé à accéder à des backends sensibles ou à des outils externes (par exemple, à l'aide d'IAP).
• Conformité d'entreprise sur mesure : application de règles de masquage des données personnalisées, de traduction de jetons ou de mécanismes de conformité spécifiques aux architectures internes.

Framework pour l'extensibilité des règles sur Agent Gateway

Agent Gateway vous permet d'associer des liaisons d'extension pour déléguer les décisions d'autorisation à des moteurs de stratégies spécialisés, tels que des fournisseurs d'identité, des filtres de sécurité du contenu ou des plates-formes de sécurité tierces personnalisées.

Le framework d'extensibilité des règles fonctionne sur une séparation entre les rôles et les ressources :

• Consommateurs : opérateurs d'Agent Gateway qui souhaitent ajouter des extensions de sécurité et de gouvernance à leurs passerelles avec un minimum d'efforts de configuration.

• Producteurs : équipes de plate-forme internes, services Google propriétaires (comme IAP et Model Armor) et partenaires ISV tiers qui créent et publient des extensions de service pour que d'autres puissent les utiliser.

• ExtensionBinding : ressource créée par le client qui lie un ProducerExtension à un Agent Gateway cible, ainsi que des conditions de correspondance qui déterminent quand l'extension est appelée. Il s'agit de la seule ressource qu'un client doit créer pour commencer à utiliser une extension.

• ProducerExtension: : ressource créée par le producteur qui empaquette un moteur d'autorisation compatible avec ext_proc dans une seule unité gérée. Il encapsule tous les paramètres d'exécution et de connectivité sous-jacents afin que les utilisateurs n'aient pas à configurer les mécanismes de plan de données de bas niveau.

Extensions Google propriétaires intégrées

Les services Google propriétaires, tels que IAP et Model Armor, offrent des fonctionnalités d'extension prépackagées avec un modèle opérationnel simplifié.

• Consommateur : les développeurs d'applications et les opérateurs de sécurité agissent en tant que consommateurs. Pour activer l'authentification zéro confiance ou la protection contre l'injection de prompt, vous devez créer une ressource ExtensionBinding ciblant les URI de point de terminaison de service prédéfinis de Google directement à partir de votre projet client.
• Producteur : Google agit en tant que producteur. Google crée, héberge et gère l'infrastructure de service sous-jacente et les points de terminaison d'extension à l'échelle mondiale (tels que iap.googleapis.com ou modelarmor.us.rep.googleapis.com). Vous n'avez pas besoin de créer ni de gérer une ressource ProducerExtension.

Extensions d'entreprise et de partenaires (2P/3P)

Pour la logique de gouvernance personnalisée, l'extensibilité des règles permet un modèle d'intégration bilatéral flexible entre les équipes d'entreprise et les partenaires de sécurité.

• Producteur : les équipes internes d'ingénierie de plate-forme (2P) ou les fournisseurs de sécurité ISV tiers (3P) agissent en tant que producteurs. Le producteur crée un service gRPC compatible avec le protocole ext_proc d'Envoy, l'héberge dans un projet de producteur dédié (par exemple, un service Cloud Run derrière un équilibreur de charge d'application), l'expose à l'aide d'un rattachement de service Private Service Connect (PSC) et publie une ressource ProducerExtension.

• Client : les développeurs d'applications et les administrateurs de sécurité des projets clients agissent en tant que clients. Une fois que le producteur leur a accordé l'accès à l'aide de PSC, les consommateurs créent un ExtensionBinding dans leur projet en référençant l'URI de ressource ProducerExtension spécifique pour appliquer des contrôles personnalisés (tels que des règles de gouvernance sémantique ou des règles de pare-feu tierces) à leurs charges de travail.

Schémas de déploiement

Les liaisons d'extension sont compatibles avec des modèles de déploiement flexibles pour appliquer une gouvernance cohérente sur tous les chemins de trafic, afin de s'assurer que vos règles de gouvernance agissent de manière identique, quel que soit l'endroit où vos agents sont déployés. L'API ExtensionBinding s'applique de manière uniforme à tous les modèles de déploiement d'Agent Gateway.

Chemins d'interception du trafic de bout en bout

Vous pouvez appliquer des liaisons d'extension pour intercepter le trafic sur les chemins de communication suivants dans votre écosystème d'agents :

• Utilisateur → Agent (Ingress) : intercepte les requêtes entrantes des utilisateurs finaux ou des applications clientes ciblant Agent Gateway pour appliquer l'authentification des utilisateurs, la gouvernance des identités ou le nettoyage des injections de prompts.
• Agent → Outil / MCP (sortie) : intercepte les appels sortants des agents vers les serveurs MCP (Model Context Protocol) ou les API externes pour valider les autorisations et nettoyer les entrées des outils.
• Agent → Modèle LLM (sortie) : analyse les requêtes avant qu'elles n'atteignent les modèles de fondation et filtre les réponses des modèles pour éviter la perte de données ou les sorties toxiques.

• Agent → Agent (sortie A2A) : contrôle la communication entre les agents et applique les limites des règles lorsque des agents autonomes collaborent entre différents projets.

Client vers agent

Agent vers n'importe quelle destination

Consommateurs : lier des extensions à des passerelles d'agent

Les consommateurs (tels que les développeurs d'applications ou les opérateurs de sécurité) associent une logique de gouvernance et de sécurité à leurs Agent Gateways en créant un ExtensionBinding. Cette ressource lie la charge de travail cible à une extension et déclare des conditions de correspondance pour définir précisément quand l'extension doit être appelée (par exemple, en interceptant le trafic destiné à des outils externes ou des serveurs MCP spécifiques). Vous pouvez spécifier des conditions de correspondance directement de manière intégrée (comme indiqué dans les exemples de cette section) ou dans un fichier YAML distinct.

Selon le fournisseur de l'extension, la consommation suit l'un des deux chemins suivants :

Configuration du client 1P

Pour les services Google tels que IAP (IAP) ou Model Armor, Google gère l'infrastructure de backend et l'enregistrement à l'échelle mondiale. En tant que consommateur, vous n'avez pas besoin de cibler un URI de ressource ProducerExtension spécifique. Vous pouvez lier directement ces services à vos charges de travail en transmettant leurs chaînes de point de terminaison prédéfinies (par exemple, iap.googleapis.com ou modelarmor.us.rep.googleapis.com) en tant que cible dans votre ExtensionBinding.

Lier une extension IAP à une passerelle Agent Gateway

L'exemple suivant illustre une ressource ExtensionBinding qui lie un service Google propriétaire (IAP) à une Agent Gateway dans un projet client. En fonction du champ matchConditions spécifié, cette extension est appelée lorsque du trafic est envoyé à un serveur MCP.

1. Créez un fichier YAML avec la configuration suivante :

   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"
   

   Remplacez les éléments suivants :

   • EXTENSION_BINDING_NAME : nom de la ressource de liaison d'extension.
   • PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
   • LOCATION : emplacement de la passerelle et de la liaison d'extension.
   • AGENT_GATEWAY_NAME : nom de l'Agent Gateway cible.

2. Importez la configuration de liaison de l'extension :

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

   Remplacez EXTENSION_BINDING_FILE_PATH par le chemin d'accès au fichier de configuration YAML.

Associer une extension Model Armor à une passerelle d'agent

Pour protéger vos agents contre l'injection de prompt, les contenus toxiques et les fuites de données sensibles, vous pouvez lier Model Armor directement à votre charge de travail. En fonction du champ matchConditions spécifié, cette extension est appelée lorsque du trafic est envoyé à un serveur MCP.

1. Créez un fichier YAML avec la configuration suivante :

   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"
     }]'
   

   Remplacez les éléments suivants :

   • EXTENSION_BINDING_NAME : nom de la ressource de liaison d'extension.
   • PROJECT_ID : ID de votre projet Cloud de Confiance .
   • LOCATION : emplacement des ressources.
   • AGENT_GATEWAY_NAME : nom de l'Agent Gateway cible.
   • TEMPLATE_PROJECT_ID : ID du projet dans lequel se trouvent vos modèles Model Armor.
   • REQUEST_TEMPLATE_ID : ID du modèle Model Armor utilisé pour évaluer les requêtes.
   • RESPONSE_TEMPLATE_ID : ID du modèle Model Armor utilisé pour évaluer les réponses.

2. Importez la configuration de liaison de l'extension :

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

   Remplacez EXTENSION_BINDING_FILE_PATH par le chemin d'accès au fichier de configuration YAML.

Configuration du client 2P/3P

En tant que consommateur d'une extension de service créée par une autre équipe interne (2P) ou un fournisseur tiers externe (3P), vous devez vous assurer que votre projet consommateur a explicitement été autorisé à utiliser le service. L'accès est contrôlé par le producteur à l'aide de sa configuration de rattachement de service Private Service Connect. Une fois l'accès accordé, liez la charge de travail en référençant l'URI de ressource ProducerExtension spécifique fourni par le producteur dans votre ExtensionBinding.

Associer des moteurs d'autorisation personnalisés

L'exemple suivant illustre une ressource ExtensionBinding qui lie une extension personnalisée d'un projet de producteur 2P/3P à une Agent Gateway dans un projet de consommateur. En fonction du champ matchConditions spécifié, cette extension est appelée lorsque du trafic est envoyé à un agent.

1. Créez un fichier YAML avec la configuration suivante :

   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"
   

   Remplacez les éléments suivants :

   • EXTENSION_BINDING_NAME : nom de la ressource de liaison d'extension.
   • CONSUMER_PROJECT_ID : ID du projet client hébergeant Agent Gateway.
   • LOCATION : emplacement des ressources.
   • AGENT_GATEWAY_NAME : nom de l'Agent Gateway cible.
   • PRODUCER_PROJECT_ID : ID du projet producteur hébergeant l'instance ProducerExtension.
   • PRODUCER_EXTENSION_NAME : nom de la ressource ProducerExtension.

2. Importez la configuration de liaison de l'extension :

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

   Remplacez EXTENSION_BINDING_FILE_PATH par le chemin d'accès au fichier de configuration YAML.

Points d'association de liaison d'extension

Les liaisons d'extension peuvent être configurées à différents niveaux de la hiérarchie de vos ressources en fonction de vos exigences de gouvernance :

• Niveau Agent Gateway : associez des règles directement à une ressource Agent Gateway pour régir l'ensemble du trafic transitant par la passerelle.
• Au niveau du projet : créez des ExtensionBindings qui s'appliquent de manière globale à toutes les ressources d'un type donné dans un projet, ce qui simplifie la gestion pour les administrateurs d'entreprise qui appliquent la conformité à l'échelle du projet.

Associer une extension Model Armor à toutes les Agent Gateways d'un projet

1. Créez un fichier YAML avec la configuration suivante :

   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"
     }]'
   

   Remplacez les éléments suivants :

   • EXTENSION_BINDING_NAME : nom de la ressource de liaison d'extension.
   • PROJECT_NUMBER : numéro de votre projetCloud de Confiance .
   • TEMPLATE_PROJECT_ID : ID du projet dans lequel se trouvent vos modèles Model Armor.
   • LOCATION : emplacement des ressources.
   • REQUEST_TEMPLATE_ID : ID du modèle Model Armor utilisé pour évaluer les requêtes.
   • RESPONSE_TEMPLATE_ID : ID du modèle Model Armor utilisé pour évaluer les réponses.

2. Importez la configuration de liaison de l'extension :

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

   Remplacez EXTENSION_BINDING_FILE_PATH par le chemin d'accès au fichier de configuration YAML.

Pour les requêtes correspondant à une charge de travail spécifique, les liaisons d'extension au niveau du projet et au niveau de la ressource sont exécutées. Si la même extension est configurée à la fois au niveau de la ressource et au niveau du projet, elle sera appelée deux fois.

Conditions de correspondance pour appeler des extensions

Les conditions de correspondance déterminent quand votre extension est appelée. Vous pouvez spécifier des conditions de correspondance directement de manière intégrée (comme indiqué dans les exemples précédents sur cette page) ou dans un fichier YAML.

Cette section fournit des exemples de configurations de fichiers YAML pour des situations courantes basées sur le flux de trafic, les URN des ressources cibles ou les hôtes de destination :

• Sortie vers les serveurs d'outils MCP (agent → outil) : intercepte le trafic envoyé d'un agent vers des serveurs d'outils MCP (Model Context Protocol) distants :

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

• Trafic entrant (utilisateur → agent) : intercepte les requêtes entrantes des utilisateurs finaux ou des applications clientes ciblant les agents régis par Agent Gateway (par exemple, pour appliquer l'authentification des utilisateurs finaux ou le nettoyage des injections de prompt à l'entrée) :

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

• Sortie vers les modèles LLM (agent → modèle LLM) : intercepte les requêtes envoyées par les agents aux modèles LLM de fondation ou aux serveurs de modèles en fonction de l'hôte de destination :

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

Producteurs : créer et publier des extensions

En tant que producteur personnalisé (2P ou 3P), hébergez votre implémentation d'extension de service basée sur ext_proc derrière un rattachement Private Service Connect. Une fois votre rattachement prêt, créez une ressource ProducerExtension en spécifiant la phase de traitement de la requête au cours de laquelle votre extension fonctionne, l'autorité à utiliser et l'URI du rattachement PSC pour votre service 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"

Remplacez les éléments suivants :

• PRODUCER_EXTENSION_NAME : nom de la ressource ProducerExtension.
• PRODUCER_PROJECT_ID : ID du projet du producteur.
• REGION : région du rattachement de service Private Service Connect.
• PSC_ATTACHMENT_NAME : nom du rattachement de service Private Service Connect.

Héberger des extensions personnalisées sur Cloud Run

Pour les producteurs qui souhaitent exécuter leur service gRPC ext_proc personnalisé sans gérer de clusters ni de VM dédiés, Cloud Run est une alternative sans serveur idéale.

Pour publier votre extension sans serveur en tant que ProducerExtension, exposez-la à l'aide de Private Service Connect (PSC). Étant donné que les ressources ProducerExtension nécessitent un URI de rattachement de service PSC et que les rattachements de service ciblent les règles de transfert de l'équilibreur de charge plutôt que les services Cloud Run directement, placez un équilibreur de charge d'application (à l'aide d'un backend NEG sans serveur) devant votre service Cloud Run.

Voici le workflow de déploiement général pour héberger votre extension sur Cloud Run :

1. Déployez votre extension sur Cloud Run : hébergez votre extension gRPC ext_proc personnalisée en tant que service conteneurisé sur Cloud Run.

2. Créer un NEG sans serveur : déployez un groupe de points de terminaison du réseau (NEG) sans serveur qui pointe vers l'extension exécutée sur Cloud Run.

3. Configurer un équilibreur de charge avec le backend du NEG sans serveur : configurez un équilibreur de charge d'application régional dans votre réseau VPC, avec le NEG sans serveur comme backend.

4. Publiez votre service avec PSC : créez un rattachement de service Private Service Connect pointant directement vers la règle de transfert de l'équilibreur de charge. Un URI de rattachement de service unique est alors généré (par exemple, projects/.../regions/.../serviceAttachments/...).

5. Créer votre extension de producteur : utilisez cet URI généré pour instancier votre ressource ProducerExtension.

6. Lier les charges de travail des clients : les clients peuvent désormais lier leurs passerelles à votre extension en référençant l'URI de la ressource ProducerExtension.

Annexe : Métadonnées contextuelles pour les extensions personnalisées

Pour aider vos extensions personnalisées à prendre des décisions d'autorisation et de traitement en fonction du contexte,les plans de données Cloud de Confiance transmettent le contexte du cycle de vie et des ressources directement aux serveursext_proc.

Ces informations sont regroupées en tant que métadonnées non typées dans le champ metadata_context du ProcessingRequest gRPC ext_proc. Ces métadonnées se trouvent dans l'espace de noms com.google.serviceextensions.invocation_info et utilisent le format google.protobuf.Struct standard.

Vous pouvez décoder ou convertir ces métadonnées au format JSON pour un traitement en aval. Voici un exemple de format JSON pour une requête ciblant une Agent Gateway avec du trafic destiné à un serveur 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"
 }
}

Le schéma du fichier JSON est le suivant :

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;
}