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 de qualité professionnelle. 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 , ainsi qu'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 voies de communication gérées 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 bloquer et expurger le contenu qui ne respecte pas les règles, ou pour inspecter uniquement le contenu et enregistrer les violations détectées. Cela atténue les risques tels que l'injection de prompt, les jailbreaks, l'exposition à des contenus nuisibles et les fuites de données sensibles.

Lorsque Model Armor détecte des violations de règles dans le contenu qui transite par Agent Gateway, il peut être configuré pour enregistrer ces événements. Vous pouvez afficher ces résultats sur la page Model Armor de la Google Cloud console (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 Google Cloud console.

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 l'assainissement en streaming qu'à l'aide de la méthode streamQuery pour les agents créés avec Agent Development Kit.
  • Utilisation de modèles entre projets : lorsque vous utilisez un modèle Model Armor dans un projet pour assainir les requêtes d'un service, tel qu' 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 Google Cloud région. Les appels interrégionaux à Model Armor ne sont pas compatibles.
  • Compatibilité de l'intégration de sortie : la protection intégrée de Model Armor sur le trafic sortant 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 d'entrée : la protection d'entrée 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 templates.

  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 Google Cloud console, 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 où sont stockés les modèles Model Armor. Pour la passerelle Client vers agent (entrée), spécifiez les modèles Model Armor que vous avez créés pour le trafic entrant. Pour la passerelle Agent vers n'importe quelle destination (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.

  4. 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 :

      • Le rôle Utilisateur de Model Armor Callout (roles/modelarmor.calloutUser) dans le projet contenant l'agent IA.

      • Le rôle Utilisateur de 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 à l'agent de service Extensions de service :

      • 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 de 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 savoir comment procéder, 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 IA :

  • Trafic entrant (client vers 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 vers l'agent et les réponses sortantes de l'agent vers le client.
  • Trafic sortant (agent vers n'importe quelle destination) : 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 client vers agent (entrée)

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

  • Les requêtes entrantes du client (utilisateurs finaux ou applications appelantes) vers votre agent IA.
  • Les réponses sortantes de l'agent IA vers le client.

Vous pouvez appliquer un seul modèle dans les deux sens ou configurer des modèles différents pour chacun.

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

Tous les autres ReasoningEngine charges utiles et ReasoningEngine réponses d'erreur ne sont pas envoyés à Model Armor. Les charges utiles non ADK (telles que les charges utiles Langchain) ne sont pas non plus envoyées à Model Armor.

Flux de trafic pour client vers 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 requête. Si elle est bloquée, le client reçoit une erreur.
  3. Si elle est autorisée, la requête atteint l'agent IA.
  4. L'agent IA génère une réponse. Agent Gateway intercepte cette réponse avant qu'elle n'atteigne le client.
  5. Model Armor filtre la réponse, et Agent Gateway l'autorise ou la bloque en fonction du résultat.

Protection agent vers n'importe quelle destination (sortie)

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

  • Les requêtes sortantes de votre agent IA vers des systèmes externes.
  • Les réponses entrantes des systèmes externes vers votre agent IA.

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

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

Flux de trafic pour agent vers n'importe quelle destination

  1. L'agent IA lance une requête vers un système externe. Agent Gateway intercepte le trafic sortant.
  2. Model Armor filtre la charge utile sortante. Si elle est bloquée, la connexion 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. Agent Gateway intercepte cette réponse entrante.
  5. Model Armor filtre 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 en streaming

Pour faciliter le suivi et le débogage des requêtes en streaming, Model Armor utilise un ID de corrélation et un ID de trace.

Utiliser un ID de trace

Un ID de trace connecte 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 délais, chaque ID de délai représentant 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 délai 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 Google Cloud projet.
    • 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 délais de trace de Model Armor spans.

Pour afficher les journaux d'opération d'assainissement d'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 d'assainissement 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.