Gérer Agent Gateway

Ce document décrit les tâches de maintenance post-déploiement pour les ressources Agent Gateway. Si vous n'avez pas encore créé de passerelle, consultez Configurer Agent Gateway.

Avant de commencer

Avant de gérer les ressources Agent Gateway, vérifiez les conditions préalables suivantes :

Afficher et inspecter les passerelles

Vous pouvez lister les ressources Agent Gateway d'un projet Google Cloudet inspecter la configuration d'une passerelle, les extensions associées et les métadonnées en sortie uniquement.

Console

  1. Dans la console Google Cloud , accédez à la page Passerelles.

    Accéder à la page "Passerelles"

  2. Affichez la liste des passerelles du projet sélectionné.

  3. Cliquez sur le nom d'une passerelle pour ouvrir sa page d'informations :

    • Dans l'onglet Détails, examinez les sections Présentation, Autorisation d'accès, Sécurité de l'IA, Extensions de service et Configuration du VPC.
    • Dans l'onglet Observabilité, examinez les métriques de trafic et de règles de la passerelle. Pour en savoir plus, consultez Surveiller le trafic d'Agent Gateway.

gcloud

  • Répertoriez toutes les passerelles d'une région spécifique :

    gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID

    Remplacez les éléments suivants :

    • LOCATION : région dans laquelle vos passerelles sont déployées, par exemple us-central1.
    • PROJECT_ID : ID du projet Google Cloudqui héberge les passerelles.

  • Inspectez la configuration d'une passerelle spécifique :

    gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Remplacez AGENT_GATEWAY_NAME par le nom de la ressource Agent Gateway.

Paramètres immuables

La plupart des configurations d'Agent Gateway, telles que les instances Agent Registry associées et les règles de sécurité et de gouvernance, peuvent être modifiées sur place, comme décrit dans Mettre à jour une instance Agent Gateway. Cependant, certaines configurations de base sont immuables et nécessitent le déploiement d'une passerelle de remplacement. Consultez le tableau suivant avant de modifier des passerelles :

Paramètre Mutabilité Exigence ou restriction
Nom et région de la passerelle Immuable Pour modifier le nom ou la région, déployez une passerelle de remplacement.

Chemin d'accès contrôlé

(AGENT_TO_ANYWHERE ou CLIENT_TO_AGENT)

 Immuable Configuré lors de la création dans googleManaged.governedAccessPath. Impossible de modifier sur place.

Rattachement de réseau Private Service Connect

(networkAttachment)

 Immuable une fois défini Une fois que vous avez associé un rattachement de réseau à une passerelle, vous ne pouvez plus le modifier ni le supprimer.

Modèle de connectivité de l'agent et appairage Cloud DNS, configuration de confiance TLS et paramètres de sortie VPC associés

 Mutable sous conditions Vous pouvez mettre à jour la configuration de la passerelle pour référencer un autre modèle de connectivité avec de nouveaux paramètres, à condition que le nouveau modèle référence toujours le même networkAttachment.

Remplacer une passerelle pour modifier des paramètres immuables

Si vous devez modifier un paramètre immuable, tel que le rattachement de réseau PSC associé à la passerelle, vous devez déployer une passerelle de remplacement et migrer vos charges de travail vers la nouvelle passerelle :

  1. Créez l'Agent Gateway de remplacement, puis configurez ses règles d'autorisation et de Identity and Access Management (IAM). Pour obtenir des instructions, consultez Configurer Agent Gateway.

  2. Mettez à jour vos charges de travail pour utiliser la passerelle de remplacement :

    • Applications Gemini Enterprise : mettez à jour le nom de la ressource de passerelle dans les paramètres Sécurité > Configuration de l'application. Consultez Acheminer le trafic Gemini Enterprise via Agent Gateway.
    • Agents Agent Runtime : dans un même projet et une même région, tous les agents Agent Runtime doivent être liés à la même passerelle. Les mises à jour directes sur place d'une passerelle à une autre ne sont pas acceptées. Pour migrer vos agents :
      1. Assurez-vous que chaque agent lié achemine 100 % du trafic vers sa dernière révision (trafficConfig.trafficSplitAlwaysLatest).
      2. Dissociez tous les agents du projet et de la région de la passerelle précédente en définissant spec.deploymentSpec.agentGatewayConfig sur {} à l'aide de reasoningEngines.patch, puis attendez que chaque opération de mise à jour se termine.
      3. Appelez reasoningEngines.patch sur chaque agent pour définir spec.deploymentSpec.agentGatewayConfig sur le nom de ressource de la passerelle de remplacement. Pour obtenir des exemples de requêtes, consultez Acheminer le trafic Agent Runtime via Agent Gateway.

  3. Une fois que toutes les charges de travail ont cessé de référencer la passerelle précédente, suivez la procédure décrite dans Supprimer une passerelle d'agent pour supprimer la passerelle précédente.

Mettre à jour une passerelle d'agent

Vous pouvez mettre à jour certaines configurations d'Agent Gateway directement dans la console Google Cloud ou en utilisant la gcloud CLI pour exporter la configuration de la passerelle vers un fichier YAML, apporter vos modifications et réimporter le fichier.

Mettre à jour Agent Registry

Vous pouvez mettre à jour le registre d'agents associé dans la consoleGoogle Cloud ou la gcloud CLI. Votre passerelle doit référencer le registre régional unique correspondant à la région de la passerelle. Si la passerelle est associée à une application Gemini Enterprise, elle doit conserver un seul registre correspondant à l'emplacement de cette application.

Console

  1. Dans la console Google Cloud , accédez à la page Passerelles.

    Accéder à la page "Passerelles"

  2. Cliquez sur le nom de la passerelle que vous souhaitez mettre à jour.

  3. Dans l'onglet Détails, dans la section Présentation, cliquez sur Modifier les registres.

  4. Sélectionnez le registre d'agents régional correspondant à la région dans laquelle votre passerelle est déployée, puis cliquez sur Enregistrer.

gcloud

Exportez la configuration de la passerelle vers agent-gateway.yaml à l'aide de gcloud network-services agent-gateways export, modifiez registries, description ou labels (en supprimant les champs de sortie uniquement tels que createTime, updateTime, agentGatewayCard et selfLink), puis réimportez le fichier à l'aide de gcloud network-services agent-gateways import, comme indiqué dans Mettre à jour le modèle de connectivité de la passerelle.

Mettre à jour le modèle de connectivité

Vous pouvez mettre à jour le modèle de connectivité d'une ressource Agent Gateway à l'aide de la gcloud CLI.

gcloud

  1. Créez un AgentConnectivityTemplate avec vos paramètres de connectivité mis à jour, en vous assurant qu'il utilise le même networkAttachment que la passerelle existante. Pour obtenir des instructions détaillées sur la syntaxe et la configuration des modèles, consultez Configurer Agent Gateway avec la connectivité VPC.

  2. Exportez la configuration de la passerelle existante dans un fichier YAML :

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

    Remplacez les éléments suivants :

    • AGENT_GATEWAY_NAME : nom de la passerelle à mettre à jour.
    • LOCATION : région dans laquelle la passerelle est déployée.
    • PROJECT_ID : ID du projet dans lequel la passerelle est déployée.

  3. Dans le fichier agent-gateway.yaml exporté, conservez vos champs protocols, registries, description et labels existants, supprimez les champs en sortie uniquement (createTime, updateTime, agentGatewayCard, selfLink) et mettez à jour agentConnectivityTemplate pour référencer le nouveau modèle :

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME

    Remplacez les éléments suivants :

    • PROJECT_NUMBER : numéro de projet numérique dans lequel la passerelle est déployée (agentConnectivityTemplate nécessite le numéro de projet plutôt que l'ID du projet).
    • LOCATION : région de la passerelle.
    • AGENT_GATEWAY_NAME : nom de la passerelle.
    • NEW_TEMPLATE_NAME : nom du modèle de connectivité de remplacement.

  4. Réimportez le fichier YAML mis à jour pour appliquer vos modifications :

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Facultatif : supprimez l'ancien modèle de connectivité une fois la mise à jour de la passerelle terminée :

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

Modifier les paramètres IAP ou les modèles Model Armor

Vous pouvez modifier les paramètres d'application d'IAP et les modèles Model Armor en mettant à jour les extensions d'autorisation associées à votre passerelle.

Console

  1. Dans la console Google Cloud , accédez à la page Passerelles.

    Accéder à la page "Passerelles"

  2. Cliquez sur le nom de la passerelle que vous souhaitez mettre à jour.

  3. Dans l'onglet Détails, mettez à jour vos extensions de sécurité associées :

    • Modifier le mode d'application d'IAP : dans la section Autorisation d'accès, à côté de Autorisation d'accès, cliquez sur Modifier l'autorisation d'accès. Sélectionnez Audit uniquement (mode dry run) ou Appliquer les règles, puis cliquez sur Enregistrer.

    • Modifier les modèles Model Armor : dans la section Sécurité de l'IA, cliquez sur Modifier le modèle pour les requêtes à côté de Modèle pour les requêtes ou sur Modifier le modèle pour les réponses à côté de Modèle pour les réponses. Sélectionnez le modèle de remplacement, puis cliquez sur Enregistrer.

gcloud

  1. Répertoriez les extensions d'autorisation dans la région de la passerelle pour identifier le nom de l'extension :

    gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID

    Remplacez LOCATION par la région de la passerelle et PROJECT_ID par l'ID de votre projet.

  2. Inspectez la configuration actuelle de l'extension :

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

    Remplacez AUTHZ_EXTENSION_NAME par le nom de votre ressource IAP ou Model Armor AuthzExtension.

  3. Enregistrez la spécification d'extension mise à jour dans authz-extension.yaml, en omettant les champs de sortie uniquement tels que createTime et updateTime :

    • Pour une extension IAP : incluez iamEnforcementMode: "DRY_RUN" pour le mode d'audit uniquement, ou supprimez iamEnforcementMode pour appliquer les règles :

      name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies

    • Pour une extension Model Armor : mettez à jour request_template_id et response_template_id dans metadata.model_armor_settings :

      name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'

      Remplacez les éléments suivants :

      • AUTHZ_EXTENSION_NAME : nom de votre ressource Model Armor AuthzExtension.
      • LOCATION : région de la passerelle.
      • MODEL_ARMOR_PROJECT_ID : ID du projet qui héberge vos modèles Model Armor.
      • REQUEST_TEMPLATE_ID et RESPONSE_TEMPLATE_ID : ID de vos modèles de requête et de réponse.

      Assurez-vous que le compte de service de la passerelle (agentGatewayCard.serviceExtensionsServiceAccount) dispose de l'autorisation roles/modelarmor.user sur tout projet de modèle nouvellement référencé, ainsi que des autorisations roles/modelarmor.calloutUser et roles/serviceusage.serviceUsageConsumer sur le projet de passerelle (voir Autorisation de délégation).

  4. Importez le fichier YAML de l'extension mis à jour :

    gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
 --source="authz-extension.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

Pour associer de nouvelles règles d'autorisation ou modifier les règles de correspondance du trafic sur un AuthzPolicy existant, consultez Déléguer l'autorisation.

Dissocier des charges de travail d'une passerelle d'agent

Avant de pouvoir supprimer une Agent Gateway, vous devez dissocier chaque application Gemini Enterprise et chaque agent Agent Runtime qui fait référence à la passerelle.

Dissocier une application Gemini Enterprise

Vous pouvez dissocier une passerelle d'agent d'une application Gemini Enterprise dans la console Google Cloud  :

  1. Dans la console Google Cloud , accédez à la page Gemini Enterprise.

    Accéder à Gemini Enterprise

  2. Cliquez sur le nom de l'application associée à la passerelle.

  3. Cliquez sur Sécurité.

  4. Dans l'onglet Configuration, sous Configuration de l'Agent Gateway, effacez le champ Nom de la ressource de l'Agent Gateway.

  5. Cliquez sur Enregistrer.

La dissociation d'une passerelle Agent Gateway arrête le routage du trafic sortant de l'application via la passerelle. Les agents et les serveurs MCP (Model Context Protocol) importés restent enregistrés dans Agent Registry, mais l'application ne peut pas y accéder tant que vous n'avez pas associé à nouveau une passerelle. Notez que la nouvelle passerelle doit référencer le même registre d'agents.

Dissocier un agent Agent Runtime

La console Google Cloud et la gcloud CLI ne permettent pas de modifier les liaisons de passerelle Agent Runtime. Pour dissocier une passerelle d'agent d'un agent Agent Runtime déployé tout en maintenant l'agent en cours d'exécution, vous pouvez appeler la méthode d'API REST reasoningEngines.patch pour effacer spec.deploymentSpec.agentGatewayConfig :

  1. Assurez-vous que l'agent achemine tout le trafic vers la dernière révision (trafficConfig.trafficSplitAlwaysLatest défini sur true, ou aucune répartition manuelle de trafficConfig configurée). L'effacement ou la modification d'une liaison de passerelle échoue si une répartition manuelle du trafic de révision est active et archive de manière irréversible toutes les révisions précédentes. Pour en savoir plus, consultez Agent Gateway et révisions.

  2. Envoyez une requête PATCH au moteur de raisonnement avec updateMask=spec.deploymentSpec.agentGatewayConfig et un objet agentGatewayConfig vide ({}) :

    curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
   "spec": {
     "deploymentSpec": {
       "agentGatewayConfig": {}
     }
   }
 }' \
 "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

    Remplacez les éléments suivants :

    • REGION : région dans laquelle l'agent est déployé.
    • PROJECT_ID : ID du projet dans lequel l'agent est déployé.
    • RESOURCE_ID : ID de ressource de l'agent.

Supprimer une passerelle d'agent

Agent Gateway applique un suivi strict des références pour éviter les règles de sécurité orphelines et les chemins de trafic d'agent rompus. La suppression d'une passerelle échoue et le bouton Supprimer de la console Google Cloud reste indisponible si l'une des conditions suivantes s'applique :

  • Un ou plusieurs agents Agent Runtime ou applications Gemini Enterprise font toujours référence à la passerelle.
  • Tout AuthzPolicy (pour IAP, Model Armor ou un fournisseur personnalisé) ou TelemetryPolicy cible toujours la passerelle.
  • Une opération de mise à jour de la configuration du VPC est toujours en cours sur la passerelle.

Suivez les étapes ci-dessous dans l'ordre pour supprimer une Agent Gateway et nettoyer les ressources associées :

Console

  1. Assurez-vous qu'aucune application Gemini Enterprise ni aucun agent Agent Runtime ne font référence à la passerelle. Suivez les instructions de la section Dissocier des charges de travail d'une Agent Gateway.

  2. Dans la console Google Cloud , accédez à la page Passerelles.

    Accéder à la page "Passerelles"

  3. Cliquez sur le nom de la passerelle que vous souhaitez supprimer.

  4. Dans l'onglet Détails, supprimez toutes les associations de règles ciblant la passerelle :

    • Si la section Autorisation d'accès s'affiche, cliquez sur Supprimer, puis confirmez la suppression. Cette action supprime à la fois l'AuthzPolicy IAP et son AuthzExtension.
    • Si la section AI Security s'affiche, cliquez sur Supprimer, puis confirmez la suppression. Cette action supprime à la fois le AuthzPolicy Model Armor et son AuthzExtension.
    • Consultez le tableau Extensions de service. Si des ressources AuthzPolicy personnalisées restent associées, utilisez l'onglet gcloud de cette procédure pour les supprimer avant de continuer.

  5. Une fois toutes les associations de règles supprimées et qu'aucune mise à jour de VPC n'est en cours, cliquez sur Supprimer, puis confirmez la suppression.

  6. Vérifiez que la passerelle n'apparaît plus dans la liste Passerelles de votre projet.

  7. Facultatif : Nettoyez les ressources de connectivité inutilisées si aucune autre passerelle ne les utilise. Utilisez l'onglet gcloud pour supprimer le AgentConnectivityTemplate et supprimer le rattachement de réseau.

gcloud

  1. Assurez-vous qu'aucune application Gemini Enterprise ni aucun agent Agent Runtime ne font référence à la passerelle. Suivez les instructions de la section Dissocier des charges de travail d'une Agent Gateway.

  2. Supprimez les règles d'autorisation et les extensions d'autorisation :

    1. Répertoriez les règles d'autorisation dans la région de la passerelle pour trouver celles dont le champ target.resources fait référence à votre passerelle, et notez les authzExtensions référencés :

      gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"

      Remplacez LOCATION par la région de la passerelle et PROJECT_ID par l'ID de votre projet.

    2. Supprimez chaque AuthzPolicy qui cible la passerelle :

      gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      Remplacez AUTHZ_POLICY_NAME par l'ID de chaque règle d'autorisation ciblant la passerelle (par exemple, AGENT_GATEWAY_NAME-iap-authzpolicy ou AGENT_GATEWAY_NAME-aisecurity-authzpolicy pour les règles créées dans la console).

    3. Facultatif : Après avoir supprimé les ressources AuthzPolicy de référence, supprimez toutes les ressources AuthzExtension qui ne sont utilisées par aucune autre règle :

      gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      Remplacez AUTHZ_EXTENSION_NAME par l'ID de l'extension d'autorisation inutilisée.

  3. Supprimez l'Agent Gateway :

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Remplacez AGENT_GATEWAY_NAME par le nom de la passerelle à supprimer.

  4. Vérifiez que la passerelle n'apparaît plus dans la liste des passerelles régionales :

    gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Facultatif : Vous ne pouvez pas supprimer un AgentConnectivityTemplate tant qu'une Agent Gateway y fait référence. Après avoir supprimé la passerelle, supprimez les modèles de connectivité inutilisés :

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Remplacez CONNECTIVITY_TEMPLATE_NAME par le nom du modèle de connectivité inutilisé. Si vous n'avez plus besoin du rattachement de réseau Private Service Connect sous-jacent, des zones DNS privées Cloud DNS ou des ressources TrustConfig de Certificate Manager, consultez Supprimer des rattachements de réseau.

Étapes suivantes

Guide

Découvrez comment déléguer l'autorisation pour Agent Gateway à IAP, Model Armor ou à votre propre service d'autorisation personnalisé.

Guide

Découvrez comment surveiller Agent Gateway.

Guide

Découvrez comment configurer une Agent Gateway.

Dépannage

Découvrez comment résoudre les problèmes de connectivité d'Agent Gateway.