Intégrer Model Armor à Agent Gateway

Gemini Enterprise Agent Platform est une plate-forme permettant de créer et de gérer des agents IA professionnels. Agent Gateway sert de plan de contrôle qui gère, sécurise et régit la façon dont les agents d'IA se connectent et interagissent dans l'environnement Google Cloud , ainsi qu'avec les agents, les applications d'IA et les LLM externes. L'intégration de Model Armor et d'Agent Gateway permet d'intégrer les capacités de filtrage de Model Armor directement dans les canaux de communication gérés par Gemini Enterprise Agent Platform. Lorsque le contenu transite 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 enregistre les cas de non-respect détectés. Cela permet d'atténuer les risques liés aux injections de prompt, aux jailbreaks, à l'exposition à des contenus nuisibles et aux fuites de données sensibles.

Lorsque Model Armor détecte des cas de non-respect des règles dans le contenu transitant par la passerelle d'agent, il peut être configuré pour consigner ces événements. Vous pouvez consulter 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é du streaming pour les agents : Model Armor n'est compatible avec la désinfection du streaming qu'à l'aide de la méthode streamQuery pour les agents créés avec Agent Development Kit.
  • Utilisation de modèles interprojets : lorsque vous utilisez un modèle Model Armor dans un projet pour assainir 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 suivant le format OpenAI et A2A via Agent Gateway.
  • Compatibilité de l'intégration Ingress : la protection Ingress intégrée avec Model Armor n'est compatible qu'avec les agents créés à l'aide d'ADK.

Configurer Model Armor sur une passerelle

Pour configurer Model Armor sur une passerelle, procédez comme suit :

  1. Activez l'API Model Armor dans le projet dans lequel vous souhaitez créer les modèles Model Armor.

  2. Créez un ou plusieurs modèles Model Armor dans la même région 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 console Google Cloud , affichez les détails du modèle, puis cliquez sur  Copier dans le presse-papiers à côté du nom du modèle.

  3. Configurez Agent Gateway dans la même région que celle où sont stockés les modèles Model Armor. Pour la passerelle Client-to-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 de sortie. Vous pouvez utiliser le même modèle pour les deux flux de trafic.

  4. Attribuez les rôles IAM requis aux comptes de service appropriés :

    • Client vers agent (entrée) : attribuez les rôles suivants au compte de service Agent de service AI Platform Reasoning Engine :

      • Le rôle Utilisateur de Model Armor Callout (roles/modelarmor.calloutUser) dans le projet contenant l'agent d'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.iam.gserviceaccount.com \
    --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.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Remplacez 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 quelle destination (sortie) : attribuez les rôles suivants au compte de service Agent Gateway :

      • Les rôles Utilisateur de Model Armor Callout (roles/modelarmor.calloutUser) et Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer) dans le projet contenant 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.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Remplacez 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.

    Pour obtenir des informations générales sur l'attribution d'un rôle, consultez Attribuer un seul rôle IAM.

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 d'IA :

  • Trafic entrant (du client vers l'agent) : fait référence au flux de communication entre un client et l'agent. Model Armor peut protéger à la fois les requêtes entrantes du client à l'agent et les réponses sortantes de l'agent au client.
  • Trafic de sortie (de l'agent vers n'importe où) : fait référence au 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 du trafic entrant du client vers l'agent

Vous définissez les modèles que Model Armor utilise pour évaluer les éléments suivants :

  • Requêtes entrantes du client (utilisateurs finaux ou applications appelantes) à votre agent d'IA.
  • Réponses sortantes de l'agent d'IA au client.

Vous pouvez appliquer un seul modèle aux deux directions ou configurer des modèles différents pour chacune d'elles.

Pour le trafic client vers agent (entrée) utilisant le protocole ADK, Model Armor n'assainit que les requêtes et les réponses reasoningEngines.streamQuery pour les agents créés à l'aide d'Agent Development Kit (ADK) et exécutés sur Agent Runtime.

Toutes les autres charges utiles ReasoningEngine et les 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.

Flux du trafic de client à agent

  1. Un client envoie un prompt à l'agent. Agent Gateway intercepte la requête et envoie la charge utile à Model Armor.
  2. Model Armor filtre la demande. Si l'accès est bloqué, le client reçoit un message d'erreur.
  3. Si elle est autorisée, la requête est transmise à l'agent d'IA.
  4. L'agent d'IA génère une réponse. L'Agent Gateway intercepte cette réponse avant qu'elle n'atteigne le client.
  5. 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 les modèles que Model Armor utilise pour évaluer les éléments suivants :

  • Requêtes sortantes de votre agent d'IA vers des systèmes externes.
  • Réponses entrantes provenant de systèmes externes et renvoyées à votre agent d'IA.

Cette protection s'applique aux communications avec les systèmes suivants :

  • LLM externes et agents d'IA tiers
  • Serveurs MCP (Model Context Protocol)
  • Autres agents IA

Flux de trafic pour Agent-to-Anywhere

  1. L'agent d'IA envoie une requête à un système externe. Agent Gateway intercepte le trafic sortant.
  2. Model Armor filtre la charge utile sortante. Si la connexion est bloquée, elle est interrompue.
  3. Si elle est autorisée, la requête est envoyée au système externe.
  4. Le système externe renvoie une réponse. La passerelle d'agent intercepte cette réponse entrante.
  5. Model Armor analyse la charge utile de la réponse, et l'Agent Gateway l'autorise ou la bloque.

Pour en savoir plus, consultez Configurer Model Armor sur une passerelle.

Suivre et déboguer les demandes 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 relie tous les événements d'une même requête lorsqu'elle transite par plusieurs services d'un système distribué. Cela inclut les mesures de sécurité appliquées par Model Armor dans le chemin de requête de la ressource Agent Gateway.

Chaque trace contient un ou plusieurs spans, où chaque ID de span représente une opération ou une unité de travail spécifique dans la trace. Les journaux générés lors de l'exécution d'une requête sont associés à l'ID de portée spécifique de l'opération effectuant 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 corréler les journaux et les traces de bout en bout, de l'appelant à Model Armor en passant par Agent Gateway et tous les agents en aval. 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 spans de trace Model Armor.

Pour afficher les journaux des opérations de désinfection 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 relie toutes les entrées de journal dans Cloud Logging qui se rapportent à une même session de désinfection du flux, 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.