Acheminer le trafic Agent Runtime via Agent Gateway

Cette page explique comment acheminer le trafic Agent Runtime via Agent Gateway. Agent Gateway est un composant central de mise en réseau et de sécurité de l'écosystème Gemini Enterprise Agent Platform. Elle fournit une connectivité sécurisée et régie pour toutes les interactions agentiques, qu'elles se produisent entre les utilisateurs et les agents, entre les agents et les outils, ou entre les agents eux-mêmes.

Avant de commencer

• Assurez-vous de bien connaître le processus de déploiement d'agents sur Agent Runtime.

• En savoir plus sur Agent Gateway Vous pouvez utiliser Agent Gateway en mode Agent-to-Anywhere (sortie) pour sécuriser et régir toutes les communications sortantes avec le trafic sortant vers des outils, des modèles, des API et d'autres agents. Vous utilisez la passerelle en mode client-agent (entrée) pour contrôler quels clients peuvent accéder à vos agents. La passerelle vous permet de choisir les règles IAP et les modèles Model Armor à appliquer à ces interactions.

  Une même instance d'exécution peut être associée simultanément à une passerelle Agent-to-Anywhere (sortie) et à une passerelle Client-to-Agent (entrée).

• Consultez les limites associées aux déploiements d'exécution associés à Agent Gateway.

Acheminer le trafic Agent Runtime via Agent Gateway

Pour acheminer le trafic Agent Runtime via Agent Gateway, procédez comme suit :

1. Créer Agent Gateway

   Créez une ressource Agent Gateway et associez-y les règles d'autorisation nécessaires. Vous pouvez créer une passerelle en mode Agent-to-Anywhere (sortie) ou Client-to-Agent (entrée).

   • Pour le mode client-agent (entrée), l'agent et la passerelle doivent être créés dans le même projet et la même région.
   • Pour le mode Agent-to-Anywhere (sortie), la passerelle peut être créée dans un projet différent de celui de l'agent, mais elle doit être créée dans la même région. Notez que tous les enregistrements Agent Registry et toutes les liaisons de stratégie IAM associés doivent être créés dans le même projet que l'Agent Gateway.

   Pour obtenir des instructions, consultez Configurer Agent Gateway.

   Assurez-vous que la passerelle est configurée pour répondre aux besoins de votre déploiement. Par exemple, si votre agent nécessite un accès LLM, configurez la passerelle pour autoriser cet accès afin d'éviter d'éventuels échecs de déploiement d'Agent Runtime.

2. Facultatif : Configurer l'accès à la passerelle de sortie entre projets

   Si votre passerelle Agent-to-Anywhere (sortie) se trouve dans un projet différent de celui de votre agent d'exécution, procédez comme suit pour accorder à l'agent de service d'exécution l'accès au projet de passerelle de sortie :

   gcloud

   1. Créez un rôle IAM personnalisé dans le projet Agent Gateway :

   gcloud iam roles create ar_agw_cross_project_sa \
       --project=AGENT_GATEWAY_PROJECT_ID \
       --title="Runtime Agent Gateway Cross-Project SA" \
       --description="Custom role for the cross-project service agent to access Agent Gateway" \
       --permissions="networkservices.agentGateways.get,networkservices.operations.get"

   Remplacez AGENT_GATEWAY_PROJECT_ID par l'ID du projet dans lequel Agent Gateway est déployé.

   1. Attribuez le rôle personnalisé du projet de passerelle à l'agent de service Agent Runtime du projet d'agent :

   gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
       --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
       --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

   Remplacez AGENT_RUNTIME_PROJECT_NUMBER par le numéro du projet dans lequel l'agent d'exécution est déployé.

   Terraform

   Pour accorder un accès multiprojet de manière déclarative à partir de plusieurs projets de charge de travail d'exécution à un projet Agent Gateway central, créez le rôle IAM personnalisé dans le projet de passerelle central et attribuez-le à l'agent de service d'exécution de chaque projet de charge de travail :

   variable "runtime_project_numbers" {
     type        = set(string)
     description = "Project numbers hosting cross-project Agent Runtime workloads"
     default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
   }
   
   resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     role_id     = "ar_agw_cross_project_sa"
     title       = "Runtime Agent Gateway Cross-Project SA"
     description = "Custom role for cross-project service agents to access Agent Gateway"
     permissions = [
       "networkservices.agentGateways.get",
       "networkservices.operations.get",
     ]
   }
   
   resource "google_project_iam_member" "ar_agw_cross_project_binding" {
     for_each = var.runtime_project_numbers
   
     project = "AGENT_GATEWAY_PROJECT_ID"
     role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
     member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com"
   }
   

3. Configurer votre agent pour acheminer le trafic via Agent Gateway

   Selon que vous déployez un nouvel agent ou que vous configurez un agent existant, choisissez l'une des options suivantes :

   • Pour les nouveaux agents utilisant le SDK Python

     Spécifiez la ressource de passerelle lors du déploiement de votre agent. Par exemple, pour déployer l'agent sur Agent Runtime, utilisez client.runtimes.create pour transmettre l'objet local_agent ainsi que les configurations facultatives.

     Si vous souhaitez utiliser des fonctionnalités de plate-forme gérées par une passerelle, telles que Model Armor ou les règles de gouvernance sémantique avec cet agent, définissez à la fois agent_gateway_config et identity_type=AGENT_IDENTITY dans l'appel de création, comme illustré dans cet exemple. Le backend applique identity_type = "AGENT_IDENTITY" au niveau de l'API chaque fois que agent_gateway_config est spécifié, ce qui entraîne l'échec de la validation du déploiement si l'identité de l'instance d'exécution est omise ou mal configurée.

     Agent vers n'importe quelle destination

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Remplacez les éléments suivants :

     • AGENT_GATEWAY_PROJECT_ID : ID du projet dans lequel Agent Gateway est déployé
     • REGION : région dans laquelle l'agent et la passerelle sont déployés
     • AGENT_GATEWAY_TO_ANYWHERE_NAME : nom de l'Agent Gateway que vous avez créé en mode Agent vers n'importe quelle destination (sortie)

     Client vers agent

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Remplacez les éléments suivants :

     • PROJECT_ID : ID du projet dans lequel l'agent et la passerelle sont déployés
     • REGION : région dans laquelle l'agent et la passerelle sont déployés
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME : nom de l'Agent Gateway que vous avez créé en mode client vers agent (entrée)

   • Pour les nouveaux agents utilisant Terraform

     Lorsque vous provisionnez votre agent avec Terraform, utilisez le fournisseur google-beta et configurez le bloc agent_gateway_config dans la ressource google_vertex_ai_reasoning_engine. Pour en savoir plus sur la configuration de Terraform, consultez Provisionner des agents avec Terraform.

     Agent vers n'importe quelle destination

     Utilisez la configuration Terraform suivante pour associer un agent à une passerelle Agent-to-Anywhere pour la sortie.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "AGENT_RUNTIME_PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           agent_to_anywhere_config {
             agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
           }
         }
       }
     }
     }

     Remplacez les éléments suivants :

     • AGENT_RUNTIME_PROJECT_ID : ID du projet dans lequel l'agent est déployé
     • REGION : région où l'agent et la passerelle sont déployés.
     • AGENT_DISPLAY_NAME : nom à afficher de votre agent
     • AGENT_DESCRIPTION : description de votre agent
     • REPOSITORY : dépôt Artifact Registry contenant votre image de conteneur
     • IMAGE : nom de l'image de conteneur
     • TAG : tag de l'image de conteneur
     • AGENT_GATEWAY_PROJECT_ID : ID du projet dans lequel Agent Gateway est déployé
     • AGENT_GATEWAY_TO_ANYWHERE_NAME : nom de l'Agent Gateway que vous avez créé en mode Agent vers n'importe quelle destination (sortie)

     Client vers agent

     Utilisez la configuration Terraform suivante pour associer un agent à une passerelle client-agent pour l'entrée.

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           client_to_agent_config {
             agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
           }
         }
       }
     }
     }

     Remplacez les éléments suivants :

     • PROJECT_ID : ID du projet dans lequel l'agent et la passerelle sont déployés
     • REGION : région où l'agent et la passerelle sont déployés
     • AGENT_DISPLAY_NAME : nom à afficher de votre agent
     • AGENT_DESCRIPTION : description de votre agent
     • REPOSITORY : dépôt Artifact Registry contenant votre image de conteneur
     • IMAGE : nom de l'image de conteneur
     • TAG : tag de l'image de conteneur
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME : nom de l'Agent Gateway que vous avez créé en mode client vers agent (entrée)

   • Pour les agents existants utilisant l'API REST

     Agent vers n'importe quelle destination

     Utilisez la requête API REST suivante pour associer un agent existant à une passerelle Agent-to-Anywhere pour la sortie.

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

     Remplacez les éléments suivants :

     • AGENT_GATEWAY_PROJECT_ID : ID du projet dans lequel la passerelle est déployée
     • AGENT_RUNTIME_PROJECT_ID : ID du projet dans lequel l'agent est déployé
     • REGION : région dans laquelle l'agent et la passerelle sont déployés
     • AGENT_GATEWAY_TO_ANYWHERE_NAME : nom de l'Agent Gateway que vous avez créé en mode Agent vers n'importe quelle destination (sortie)
     • RESOURCE_ID : ID de ressource de l'agent

     Client vers agent

     Utilisez la requête API REST suivante pour associer un agent existant à une passerelle client-agent pour l'entrée.

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

     Remplacez les éléments suivants :

     • PROJECT_ID : ID du projet dans lequel l'agent et la passerelle sont déployés
     • REGION : région dans laquelle l'agent et la passerelle sont déployés
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME : nom de l'Agent Gateway que vous avez créé dans "Client vers agent (entrée)"
     • RESOURCE_ID : ID de ressource de l'agent.

4. Enregistrer l'agent dans Agent Registry

   Assurez-vous que l'agent est enregistré auprès de l'instance Agent Registry dans le même projet et la même région que l'Agent Gateway.

   gcloud

   gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --location=REGION \
    --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
    --format="value(registryResource)"
   

   Remplacez les éléments suivants :

   • RUNTIME_AGENT_SERVICE_NAME : nom que vous souhaitez attribuer à l'entrée de votre agent dans le registre
   • AGENT_GATEWAY_PROJECT_ID : ID du projet dans lequel la passerelle est déployée
   • REGION : région où l'agent et la passerelle sont déployés
   • RUNTIME_AGENT_DISPLAY_NAME : nom à afficher lisible par l'humain de l'entrée de l'agent dans le registre
   • RUNTIME_AGENT_PROJECT_NUMBER : numéro du projet dans lequel l'agent d'exécution est déployé.
   • ENGINE_ID : ID de ressource de l'agent

   Terraform

   resource "google_agent_registry_service" "runtime_agent_entry" {
     project      = "AGENT_GATEWAY_PROJECT_ID"
     location     = "REGION"
     service_id   = "RUNTIME_AGENT_SERVICE_NAME"
     display_name = "RUNTIME_AGENT_DISPLAY_NAME"
   
     endpoint_spec {
       no_spec {}
     }
   
     interfaces {
       url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
       protocol_binding = "jsonrpc"
     }
   }
   

   Pour en savoir plus, consultez Enregistrer des agents. Pour en savoir plus sur l'enregistrement manuel d'agents dans des configurations multiprojets, consultez Enregistrer un agent à partir d'un autre projet.

5. Créer une liaison de stratégie IAM entre l'agent et le registre

   Effectuez cette étape dans le même projet et la même région que l'Agent Gateway.

   gcloud

   gcloud iap web add-iam-policy-binding \
    --resource-type=agent-registry \
    --endpoint=AGENT_ENDPOINT_ID \
    --region=REGION \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --member=MEMBER \
    --role=roles/iap.egressor
   

   Terraform

   resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     location    = "REGION"
     endpoint_id = "AGENT_ENDPOINT_ID"
     role        = "roles/iap.egressor"
     member      = "MEMBER"
   }
   

   Remplacez les éléments suivants :

   • AGENT_ENDPOINT_ID : ID du point de terminaison de service de l'agent enregistré. Vous l'obtenez à partir du résultat de l'étape précédente.

   • MEMBER : compte principal de l'agent auquel attribuer le rôle. Le format d'un moteur de raisonnement individuel est le suivant : principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID.

     Si vous souhaitez accorder un accès en sortie à tous les agents d'un projet ou de l'organisation plutôt que de lier des instances individuelles, vous pouvez lier la stratégie IAM à un ensemble de comptes principaux :

     • Pour accorder l'accès à tous les agents d'un projet : principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
     • Pour accorder l'accès à tous les agents de l'organisation : principalSet://TRUST_DOMAIN/*

     Dans ces chaînes de comptes principaux, TRUST_DOMAIN est généralement agents.global.org-ORGANIZATION_ID.system.id.goog.

6. Ajouter les API essentielles à la liste d'autorisation pour les opérations d'exécution

   À ce stade, le trafic de votre agent est désormais dirigé via Agent Gateway. Cependant, Agent Gateway adopte une règle de refus par défaut. Pour activer certaines fonctions d'Agent Platform, vous devez vous assurer que l'agent peut communiquer avec les points de terminaison suivants :

   La correspondance du nom d'hôte dans Agent Gateway est exacte. Les caractères génériques, tels que *.googleapis.com, ou les formes de préfixe ne sont pas acceptés. Vous devez enregistrer chaque variante de nom d'hôte standard, régional et sécurisé (mTLS) vers laquelle votre SDK d'agent ou votre application cliente effectue la résolution.

   Pour activer certaines fonctions d'Agent Platform et assurer l'initialisation et la télémétrie, vous devez autoriser le trafic vers les points de terminaison suivants dans le registre d'agents :

   Points de terminaison essentiels de la plate-forme

   Le tableau suivant liste les points de terminaison de plate-forme essentiels dont vos agents ont besoin pour les opérations standards, le traçage, la journalisation et la résolution des métadonnées :

   Nom du service	Nom d'hôte standard	Nom d'hôte mTLS	Variantes régionales et autres
   Registre des agents	agentregistry.googleapis.com	—	—
   Cloud Logging	logging.googleapis.com	logging.mtls.googleapis.com	—
   Cloud Trace / Télémétrie	telemetry.googleapis.com	telemetry.mtls.googleapis.com	—
   API Trace	cloudtrace.googleapis.com	cloudtrace.mtls.googleapis.com	—
   Cloud Monitoring	monitoring.googleapis.com	monitoring.mtls.googleapis.com	—
   Secret Manager	secretmanager.googleapis.com	secretmanager.mtls.googleapis.com	—
   Resource Manager	cloudresourcemanager.googleapis.com	cloudresourcemanager.mtls.googleapis.com	—
   Identifiants IAM	iamcredentials.googleapis.com	iamcredentials.mtls.googleapis.com	—
   Agent Platform (aiplatform)	aiplatform.googleapis.com	aiplatform.mtls.googleapis.com	REGION-aiplatform.googleapis.com REGION-aiplatform.mtls.googleapis.com aiplatform.REGION.rep.googleapis.com

   Points de terminaison spécifiques à une fonctionnalité

   De plus, si vos agents utilisent des fonctionnalités telles que les sessions ou Memory Bank, vous devez vous assurer qu'ils peuvent communiquer avec les points de terminaison spécifiques utilisés par ces services :

   • Pour les sessions : https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
   • Pour Memory Bank : https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

   Pour des raisons de sécurité, nous vous recommandons d'enregistrer et d'ajouter à la liste d'autorisation uniquement les URI spécifiques auxquels l'agent accède. Étant donné que la passerelle met directement en correspondance les noms d'hôte, vous devez vous assurer d'enregistrer toutes les variantes utilisées par le SDK de l'agent. Par exemple, selon la version du SDK, la configuration du client régional ou l'utilisation de mTLS, une API Google peut être résolue via les noms d'hôte de point de terminaison suivants :

   • https://REGION-aiplatform.googleapis.com
   • https://REGION-aiplatform.mtls.googleapis.com
   • https://aiplatform.REGION.rep.googleapis.com

   Pour savoir comment enregistrer des points de terminaison, consultez Enregistrer des points de terminaison. Si vous disposez d'une configuration multiprojet, vous pouvez enregistrer plusieurs points de terminaison de l'API Google de base dans un seul service Agent Registry. Pour en savoir plus, consultez Enregistrer un point de terminaison composite des API Google. Vous devez également vous assurer que l'agent dispose de l'autorisation iap.resources.egressViaIAP pour ces points de terminaison. Pour obtenir des instructions, consultez Créer une règle de sortie agent-point de terminaison.

7. Vérifier la configuration de l'agent

   Console

   1. Dans la console Cloud de Confiance , accédez à la page Déploiements d'Agent Platform.
      

      Accéder à la page "Déploiements"

   2. Cliquez sur le nom de l'agent que vous avez déployé.

   3. Cliquez sur Configuration du service. Le volet Observabilité de l'agent s'ouvre.

   4. Cliquez sur Détails du déploiement. Les configurations d'entrée et de sortie d'Agent Gateway sont disponibles dans le champ Spécification du déploiement.

   gcloud

   Utilisez la requête API REST suivante pour vérifier que l'agent est désormais associé à la passerelle. Si le résultat renvoyé est null, cela signifie que l'environnement d'exécution n'a pas pu se lier à la passerelle.

   curl -s -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
     | jq '.spec.deploymentSpec.agentGatewayConfig'

   Remplacez les éléments suivants :

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

Configurer des agents de conteneur personnalisé (BYOC) pour Agent Gateway

Si vous souhaitez acheminer le trafic sortant via une Agent Gateway Agent-to-Anywhere (sortie) pour un agent déployé avec une image de conteneur personnalisée (Bring Your Own Container / BYOC), vous devez intégrer le certificat de l'autorité de certification (CA) racine de la passerelle dans le magasin de confiance de l'image de conteneur personnalisée.

Étant donné qu'Agent Gateway effectue le déchiffrement et l'inspection TLS sur les communications sortantes de l'agent, les déploiements d'agents non BYOC (basés sur la source) injectent automatiquement le certificat de l'autorité de certification lors de la création de l'image. Pour les images de conteneurs personnalisées, vous devez récupérer explicitement le certificat CA de la passerelle, l'installer dans le magasin de confiance CA du système dans votre Dockerfile et définir les variables d'environnement du bundle de certificats requises par les SDK Python, les bibliothèques clientes HTTP et gRPC.

Pour configurer une image de conteneur BYOC pour la sortie Agent Gateway, procédez comme suit :

1. Récupérez les certificats racine à partir de la ressource Agent Gateway.

   Exportez la chaîne PEM du certificat racine de l'autorité de certification directement depuis le champ agentGatewayCard.rootCertificates de votre ressource Agent Gateway :

   export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
      --location=REGION \
      --project=PROJECT_ID \
      --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

   Vous pouvez également utiliser l'API REST pour récupérer la ressource de passerelle :

   curl -s -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
      | jq -r '.agentGatewayCard.rootCertificates[]'

   Remplacez les éléments suivants :

   • AGENT_GATEWAY_NAME : nom de votre Agent Gateway de sortie
   • REGION : région où la passerelle est déployée
   • AGENT_GATEWAY_PROJECT_ID : ID du projet dans lequel la passerelle est déployée

2. Mettez à jour votre Dockerfile pour qu'il fasse confiance au certificat CA.

   Ajoutez l'argument de compilation AGENT_GATEWAY_ROOT_CERTIFICATES à votre Dockerfile. Les commandes de compilation divisent les certificats en fichiers distincts, les installent à l'aide de update-ca-certificates et définissent des variables d'environnement afin qu'OpenSSL, les bibliothèques clientes HTTP Python (requests, httpx) et gRPC reconnaissent l'autorité de certification personnalisée :

   # Install root certificates under root user
   USER root
   
   ARG AGENT_GATEWAY_ROOT_CERTIFICATES
   RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
        echo "Installing Agent Gateway root certificates..."; \
        printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
        update-ca-certificates; \
      fi
   
   # Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
   ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
   
   # Switch back to application execution user
   USER 1000

3. Générez l'image de conteneur à l'aide de Cloud Build.

   Créez un fichier cloudbuild.yaml pour transmettre la chaîne du certificat racine à Cloud Build à l'aide de substitutions :

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args:
     - 'build'
     - '--build-arg'
     - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
     - '-t'
     - '$_IMAGE_URI'
     - '.'
   
   images:
   - '$_IMAGE_URI'
   

   Envoyez la compilation de l'image de conteneur à Cloud Build :

   export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"
   
   gcloud builds submit \
      --project=PROJECT_ID \
      --region=REGION \
      --config=cloudbuild.yaml \
      --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
      .
   

   Remplacez REPOSITORY_NAME et IMAGE_NAME par le nom de votre dépôt Artifact Registry et le nom de votre image.

4. Déployez votre agent conteneurisé.

   Spécifiez l'URI de l'image de conteneur compilée ainsi que la configuration de votre Agent Gateway dans votre requête de déploiement (à l'aide de agent_gateway_config sous spec.deploymentSpec ou d'appels de déploiement du SDK).

Limiter Agent Runtime aux Agent Gateways approuvés

Vous pouvez créer des contraintes de règles d'administration personnalisées pour définir l'ensemble des ressources Agent Gateway éligibles pouvant être utilisées lors du déploiement d'agents.

Créer des contraintes personnalisées liées aux règles d'administration

Cet exemple crée des contraintes personnalisées qui n'autorisent le trafic que vers et depuis une liste de passerelles préapprouvées.

Pour en savoir plus sur l'utilisation des contraintes de règles d'administration personnalisées, consultez Créer des contraintes personnalisées.

Limites

• La gouvernance inter-projets présente les limites suivantes :

  • Les liaisons inter-projets entre les agents et les passerelles ne sont compatibles qu'en mode Agent-to-Anywhere (sortie). En mode client-agent (entrée), l'agent et l'Agent Gateway doivent se trouver dans le même projet.
  • Vous devez utiliser l'API REST ou gcloud pour configurer la gouvernance multiprojet de bout en bout. La console Cloud de Confiance Cloud de Confiance ne permet pas de créer des liaisons de stratégie IAM multiprojets ni des entrées de registre d'agents.

• Une passerelle d'agent ne peut pas être liée à des moteurs de raisonnement d'exécution créés avant le 29 avril 2026.

• Bien qu'un seul projet et une seule région puissent héberger plusieurs instances Agent Gateway Agent-to-Anywhere (sortie) et Client-to-Agent (entrée), tous les agents Agent Runtime déployés dans ce même projet et cette même région doivent être liés aux mêmes instances Agent Gateway de sortie et d'entrée spécifiques.

  Par exemple, si un projet et une région contiennent egress-gateway-X et egress-gateway-Y, tous les agents de ce projet et de cette région doivent être configurés pour utiliser la même passerelle pour la sortie. Autrement dit, soit tous les agents utilisent egress-gateway-X, soit tous les agents utilisent egress-gateway-Y. Vous ne pouvez pas configurer agent-A pour utiliser egress-gateway-X et agent-B pour utiliser egress-gateway-Y.

  Cette même règle de liaison s'applique également aux passerelles d'entrée d'un projet et d'une région.

• Le service de détection des menaces du moteur d'agent Security Command Center n'est pas disponible lorsque Agent Gateway est activé pour un agent.

• En mode client-agent (entrée), Agent Gateway ne peut régir que les méthodes query et streamQuery d'Agent Runtime. Pour protéger d'autres méthodes non compatibles (comme asyncQuery), vous pouvez appliquer des modèles Model Armor directement depuis votre application ou votre agent. Consultez Nettoyer les requêtes et les réponses ou cet atelier de programmation sur la création d'un système d'agents sécurisé avec Model Armor.

• La modification d'une liaison Agent Gateway sur un agent d'exécution archive chaque révision préexistante de l'agent. L'archivage est irréversible. Consultez Agent Gateway et révisions.

  Pour mettre à jour un agent sans modifier l'ID de son moteur de raisonnement ni rompre les liaisons de stratégie, mettez à jour votre instance d'agent sur place, comme décrit dans Mettre à jour une instance Agent Runtime.

Étapes suivantes