Gemini Enterprise Agent Platform est une plate-forme permettant de créer et de gérer des agents IA de niveau entreprise. Agent Gateway sert de plan de contrôle qui gère, sécurise et régit la façon dont les agents IA se connectent et interagissent dans l'environnement Google Cloud et avec les agents externes, les applications d'IA et les LLM. L'intégration de Model Armor et d'Agent Gateway intègre les fonctionnalités de filtrage de Model Armor directement dans les canaux de communication gérés par Gemini Enterprise Agent Platform. Lorsque le contenu passe par Agent Gateway, il appelle Model Armor pour appliquer vos modèles de sécurité prédéfinis. Vous pouvez configurer votre modèle pour qu'il bloque et masque le contenu qui ne respecte pas les règles, ou pour qu'il inspecte uniquement le contenu et consigne les cas de non-respect détectés. Cela permet d'atténuer les risques tels que l'injection de prompt, le jailbreaking, l'exposition à des contenus nuisibles et les fuites de données sensibles.
Lorsque Model Armor détecte des cas de non-respect des règles dans le contenu transitant par Agent Gateway, il peut être configuré pour consigner ces événements. Vous pouvez afficher ces résultats sur la page Model Armor de la console Google Cloud (Accéder à Model Armor). Ces résultats sont également affichés dans Security Command Center. Pour en savoir plus, consultez Examiner les résultats dans la consoleGoogle Cloud .
Lorsque vous utilisez le mode de streaming en temps réel, Model Armor accepte un nombre illimité de jetons dans le flux, ce qui le rend adapté aux interactions et aux réponses de modèle de longue durée.
Limites
Tenez compte des limites suivantes lorsque vous intégrez Model Armor à Agent Gateway :
- Compatibilité avec le streaming pour les agents : Model Armor n'est compatible qu'avec l'assainissement en streaming à l'aide de la méthode
streamQuerypour les agents créés avec l'Agent Development Kit. - Utilisation de modèles interprojets : lorsque vous utilisez un modèle Model Armor dans un projet pour nettoyer les requêtes d'un service, comme Agent Gateway, dans un autre projet, le quota d'API pour Model Armor doit être suffisant à la fois dans le projet hébergeant le modèle et dans le projet hébergeant le service appelant. Pour en savoir plus, consultez Gérer les quotas.
- Alignement régional : Model Armor et les services avec lesquels il s'intègre doivent être déployés dans la même région Google Cloud . Les appels interrégionaux à Model Armor ne sont pas acceptés.
- Compatibilité de l'intégration de sortie : la protection intégrée de Model Armor sur le trafic de sortie est limitée aux intégrations avec les serveurs MCP, les services au format OpenAI et A2A via Agent Gateway.
- Compatibilité de l'intégration d'Ingress : la protection Ingress intégrée avec Model Armor n'est compatible qu'avec les agents créés à l'aide d'ADK.
- Pas de compatibilité avec les documents : l'assainissement des requêtes et des réponses contenant des documents ou des importations de fichiers (comme des PDF) n'est pas possible dans cette intégration. Pour filtrer des documents, appelez directement l'API REST Model Armor.
- Charges utiles compatibles : pour obtenir la liste des charges utiles compatibles, consultez la section Charges utiles compatibles et non compatibles de ce document.
Configurer Model Armor sur une passerelle
Pour configurer Model Armor sur une passerelle, procédez comme suit :
- Activez l'API Model Armor dans le projet où vous souhaitez créer les modèles Model Armor.
Créez un ou plusieurs modèles Model Armor dans la même région que celle où vous prévoyez d'ajouter la passerelle. Vous pouvez utiliser le même modèle pour le trafic entrant et sortant.
Notez les noms des modèles. Pour copier le nom d'un modèle dans la consoleGoogle Cloud , affichez les détails du modèle, puis cliquez sur Copier dans le presse-papiers à côté du nom du modèle.
Si vous créez les modèles Model Armor dans un projet différent de celui qui contient l'agent IA ou Agent Gateway et que vous utilisez VPC Service Controls, les deux projets doivent se trouver dans le même périmètre de service VPC Service Controls.
Configurez Agent Gateway dans la même région que celle où sont stockés les modèles Model Armor. Pour la passerelle client-agent (entrée), spécifiez les modèles Model Armor que vous avez créés pour le trafic entrant. Pour la passerelle Agent-to-Anywhere (sortie), spécifiez les modèles Model Armor que vous avez créés pour le trafic sortant. Vous pouvez utiliser le même modèle pour les deux flux de trafic.
Attribuez les rôles IAM requis aux agents de service appropriés :
Client vers agent (entrée) : attribuez les rôles suivants à l'agent de service Agent de service du moteur de raisonnement AI Platform :
Rôle Utilisateur de Model Armor Callout (
roles/modelarmor.calloutUser) dans le projet contenant l'agent IA.Le rôle Utilisateur Model Armor (
roles/modelarmor.user) dans le projet contenant le modèle Model Armor.
gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \ --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re. \ --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. \ --role=roles/modelarmor.userRemplacez les éléments suivants :
AGENT_RUNTIME_PROJECT_ID: ID du projet dans lequel vous avez créé l'agent.AGENT_RUNTIME_PROJECT_NUMBER: numéro du projet dans lequel vous avez créé l'agent.MODEL_ARMOR_PROJECT_ID: ID du projet contenant le modèle Model Armor.
Agent vers n'importe où (sortie) : attribuez à l'agent de service Service Extensions les rôles suivants :
- Les rôles Utilisateur de Model Armor Callout (
roles/modelarmor.calloutUser) et Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer) dans le projet qui contient la passerelle. - Le rôle Utilisateur Model Armor (
roles/modelarmor.user) dans le projet contenant le modèle Model Armor.
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \ --role=roles/modelarmor.calloutUser gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \ --role=roles/serviceusage.serviceUsageConsumer gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \ --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \ --role=roles/modelarmor.userRemplacez les éléments suivants :
GATEWAY_PROJECT_ID: ID du projet dans lequel vous avez créé la passerelle.GATEWAY_PROJECT_NUMBER: numéro du projet dans lequel vous avez créé la passerelle.MODEL_ARMOR_PROJECT_ID: ID du projet contenant le modèle Model Armor.
Pour obtenir des instructions, consultez Déléguer l'autorisation à Model Armor.
- Les rôles Utilisateur de Model Armor Callout (
Pour obtenir des informations générales sur l'attribution d'un rôle, consultez Attribuer un rôle IAM unique.
Trafic Ingress et sortant
Dans le contexte de l'intégration d'Agent Gateway et de Model Armor, les termes entrée et sortie sont utilisés du point de vue des interactions de l'agent IA :
- Trafic entrant (client vers agent) : désigne le flux de communication entre un client et l'agent. Model Armor peut protéger à la fois les requêtes entrantes du client vers l'agent et les réponses sortantes de l'agent vers le client.
- Trafic de sortie (agent vers n'importe où) : désigne le flux de communication entre l'agent et un système externe. Model Armor peut protéger à la fois les requêtes sortantes de l'agent vers le système externe et les réponses entrantes du système externe vers l'agent.
Protection client vers agent (entrée)
Vous définissez des modèles que Model Armor utilise pour évaluer :
- Requêtes entrantes du client (utilisateurs finaux ou applications appelantes) vers votre agent IA.
- Réponses sortantes de l'agent IA vers le client.
Vous pouvez appliquer un seul modèle aux deux directions ou configurer des modèles différents pour chacune d'elles.
Flux de trafic du client vers l'agent
- Un client envoie un prompt à l'agent. Agent Gateway intercepte la requête et envoie la charge utile à Model Armor.
- Model Armor filtre la requête. Si elle est bloquée, le client reçoit une erreur.
- Si elle est autorisée, la requête atteint l'agent IA.
- L'agent IA génère une réponse. Agent Gateway intercepte cette réponse avant qu'elle n'atteigne le client.
- Model Armor analyse la réponse, et Agent Gateway l'autorise ou la bloque en fonction du verdict.
Protection agent vers n'importe quelle destination (sortie)
Vous définissez des modèles que Model Armor utilise pour évaluer :
- Requêtes sortantes de votre agent IA vers des systèmes externes.
- Réponses entrantes des systèmes externes vers votre agent IA.
Cette protection s'applique aux communications avec les systèmes, y compris :
- LLM externes et agents IA tiers
- Serveurs MCP (Model Context Protocol)
- Autres agents IA
Flux de trafic pour l'agent vers n'importe quelle destination
- L'agent IA envoie une requête à un système externe. Agent Gateway intercepte le trafic sortant.
- Model Armor filtre la charge utile sortante. Si elle est bloquée, la connexion est interrompue.
- Si elle est autorisée, la requête est envoyée au système externe.
- Le système externe renvoie une réponse. Agent Gateway intercepte cette réponse entrante.
- Model Armor analyse la charge utile de la réponse, et Agent Gateway l'autorise à atteindre l'agent ou la bloque.
Pour en savoir plus, consultez Configurer Model Armor sur une passerelle.
Suivre et déboguer les requêtes de streaming
Pour faciliter le suivi et le débogage des requêtes de streaming, Model Armor utilise un ID de corrélation et un ID de trace.
Utiliser un ID de trace
Un ID de trace associe tous les événements d'une même requête lorsqu'elle transite par plusieurs services dans un système distribué. Cela inclut les mesures de sécurité que Model Armor applique dans le chemin de requête de la ressource Agent Gateway.
Chaque trace contient un ou plusieurs segments, où chaque ID de segment représente une opération ou une unité de travail spécifique au sein de la trace. Les journaux générés lors de l'exécution d'une requête sont associés à l'ID de segment spécifique de l'opération qui effectue le travail.
Un ID de trace est géré de deux manières :
- Automatique : lorsque Google Cloud Observability est activé, Agent Gateway génère automatiquement un ID de trace et le propage dans le système.
Fourni par l'utilisateur : vous pouvez remplacer l'ID de trace généré par le système en fournissant le vôtre à l'aide de l'en-tête HTTP traceparent dans vos requêtes.
L'exemple de code suivant montre comment transmettre un ID de trace personnalisé dans une requête à la méthode
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"Remplacez les éléments suivants :
LOCATION: région où se trouve le moteur de raisonnement.PROJECT_ID: ID de votre projet Google Cloud .REASONING_ENGINE_ID: ID de votre moteur de raisonnement.
L'utilisation d'un ID de trace est la méthode recommandée pour mettre en corrélation les journaux et les traces de bout en bout, de l'appelant à Model Armor et aux agents en aval, en passant par Agent Gateway. Cela est essentiel pour le débogage, la compréhension des actions de sécurité et la surveillance des performances. Pour en savoir plus, consultez Afficher les segments de trace Model Armor.
Pour afficher les journaux des opérations de nettoyage pour un ID de trace spécifique, utilisez la requête suivante dans l'explorateur de journaux :
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID
Remplacez TRACE_ID par l'ID de trace de votre requête.
Utiliser un ID de corrélation
Un ID de corrélation associe toutes les entrées de journal dans Cloud Logging qui se rapportent à une même session de nettoyage en streaming, de la requête initiale à la réponse finale. Il s'agit d'un identifiant interne principalement utilisé dans les journaux Model Armor, en particulier pour les sessions de streaming d'entrée. Pour en savoir plus, consultez Corréler les journaux et les événements associés.
Charges utiles compatibles et non compatibles
Cette section liste les types de charges utiles que Model Armor nettoie.
Trafic client vers agent (entrée)
Pour le trafic client-agent (entrée) utilisant le protocole ADK, Model Armor ne nettoie que les requêtes et les réponses reasoningEngines.streamQuery pour les agents créés à l'aide d'Agent Development Kit (ADK) et s'exécutant sur Agent Runtime.
Toutes les autres charges utiles ReasoningEngine et réponses d'erreur ReasoningEngine ne sont pas envoyées à Model Armor. Les charges utiles non ADK (telles que les charges utiles Langchain) ne sont pas non plus envoyées à Model Armor.
Trafic agent vers n'importe quelle destination (sortie)
Pour le trafic Agent-to-Anywhere (sortie), les charges utiles suivantes sont acceptées.
Charges utiles A2A
Model Armor ne nettoie que les charges utiles suivantes du protocole A2A v1 :
- Opérations SendMessage
- Fiche d'agent
- Obtenir les opérations de la carte d'agent étendue
- Liaisons de protocole JSON-RPC
- Liaisons de protocole HTTP+JSON/REST
Model Armor autorise les charges utiles A2A suivantes sans nettoyage :
- Charges utiles des versions d'A2A antérieures à la v1
SendStreamingMessageGetTaskListTasksCancelTaskSubscribeToTask- Méthodes CRUD sur
TaskPushNotificationConfig - Charges utiles utilisant la liaison de protocole gRPC A2A (protobuf sur le réseau)
- Charges utiles d'erreur A2A
Charges utiles MCP
Model Armor ne nettoie que les charges utiles MCP suivantes :
- Requête et réponse
tools/call - Requête et réponse
prompts/get - Erreurs d'exécution de l'outil MCP (cible d'injection de prompt par des auteurs d'outils MCP malveillants)
Model Armor autorise les charges utiles suivantes sans nettoyage :
tools/listresources/*notifications/*- HTTP/SSE diffusable pour MCP
- Erreurs de protocole MCP (par exemple, toutes les erreurs autres que les erreurs d'exécution d'outils)
Charges utiles LLM externes
Model Armor ne nettoie que les charges utiles suivantes du protocole de l'API OpenAI (sortie), qui inclut les modèles GPT sur openai.com ainsi que tous les autres modèles via des serveurs LLM compatibles avec l'API OpenAI (comme vLLM).
Les charges utiles qui ne sont pas listées ici sont autorisées sans nettoyage.
- Complétions de chat : Create, Delete, Get, List et Update (variantes sans streaming uniquement)
- Obtenir des messages de chat
- Réponses : Create, Get et Delete (variantes sans streaming uniquement)
- Erreurs de l'API OpenAI (y compris la variante de vLLM)
- Anciennes complétions
- Anciens assistants : créer, supprimer, lister, modifier et récupérer
- Anciens messages : créer, supprimer, lister, modifier et récupérer
- Anciens fils de discussion : créer, supprimer, modifier et récupérer
- Embeddings : créer