Acheminer le trafic Agent Runtime via Agent Gateway

Cette page explique comment acheminer le trafic Agent Runtime via Agent Gateway. La passerelle d'agent est un composant réseau et de sécurité central de l'écosystème Gemini Enterprise Agent Platform. Il 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 la procédure de déploiement d'agents sur Agent Runtime.

  • En savoir plus sur la passerelle d'agent 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 les outils, les modèles, les API et les autres agents. Vous utilisez la passerelle en mode Client-to-Agent (entrée) pour contrôler les clients qui 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 Runtime peut se lier simultanément à une passerelle Agent-to-Anywhere (sortie) et à une passerelle Client-to-Agent (entrée).

  • Consultez les limites associées aux déploiements de l'environnement 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 la passerelle d'agent

    Créez une ressource Agent Gateway et associez 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-to-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 toutes les inscriptions au registre d'agents et les liaisons de règles IAM associées doivent être créées 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 au LLM, configurez la passerelle pour autoriser cet accès afin d'éviter d'éventuels échecs de déploiement de l'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 votre agent Runtime, procédez comme suit pour accorder à l'agent de service Runtime l'accès au projet de passerelle de sortie :

    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 la passerelle d'agent est déployée.

    2. Attribuez le rôle personnalisé dans le 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.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 Runtime est déployé.

  3. Configurer votre agent pour qu'il achemine le trafic via la passerelle d'agent

    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

      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.agent_engines.create pour transmettre l'objet local_agent avec les configurations facultatives.

      Si vous souhaitez utiliser des fonctionnalités de plate-forme avec passerelle, telles que Model Armor ou les Règles de gouvernance sémantique, avec cet agent, définissez agent_gateway_config et identity_type=AGENT_IDENTITY dans l'appel de création, comme indiqué dans cet exemple. Sans identity_type=AGENT_IDENTITY, le effectiveIdentity de l'instance de notebook Runtime revient au compte de service Vertex AI par défaut, et les règles de gouvernance sémantique filtrent silencieusement l'agent du sélecteur de création de règles.

      Agent vers n'importe quelle destination 

      remote_agent = client.agent_engines.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éée en mode Agent-to-Anywhere (sortie)

      Client vers agent 

      remote_agent = client.agent_engines.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 agents existants

      Agent vers n'importe quelle destination

      Utilisez la requête d'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éée en mode Agent-to-Anywhere (sortie)
      • RESOURCE_ID : ID de ressource de l'agent

      Client vers agent

      Utilisez la requête d'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éée 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 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 de l'entrée de l'agent dans le registre, dans un format lisible
    • RUNTIME_AGENT_PROJECT_NUMBER : numéro du projet dans lequel l'agent Runtime est déployé
    • ENGINE_ID : ID de ressource de l'agent

    Pour en savoir plus, consultez Enregistrer un agent.

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

    Remplacez les éléments suivants :

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

    • MEMBER : compte principal de l'identité de l'agent auquel attribuer le rôle. Le format est généralement le suivant : principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

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

    À ce stade, le trafic de vos agents est désormais dirigé vers l'Agent Gateway. Toutefois, Agent Gateway adopte une stratégie 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 :

    • Pour activer la découverte automatique des agents, des serveurs MCP et des points de terminaison, l'Agent Gateway doit autoriser le trafic vers le point de terminaison https://agentregistry.googleapis.com/.

    • Si Cloud Trace est activé, Agent Gateway doit autoriser le trafic vers le point de terminaison https://telemetry.googleapis.com/.

      Si les variables d'environnement GOOGLE_API_USE_CLIENT_CERTIFICATE et GOOGLE_API_USE_MTLS_ENDPOINT sont définies, assurez-vous que le trafic vers https://telemetry.mtls.googleapis.com/ est également autorisé.

    • Si Cloud Logging est activé, Agent Gateway doit autoriser le trafic vers le point de terminaison https://logging.googleapis.com/.

      Si les variables d'environnement GOOGLE_API_USE_CLIENT_CERTIFICATE et GOOGLE_API_USE_MTLS_ENDPOINT sont définies, assurez-vous que le trafic vers https://logging.mtls.googleapis.com/ est également autorisé.

    De plus, si vos agents appellent des LLM ou utilisent des fonctionnalités telles que Sessions et Memory Bank, vous devez vous assurer qu'ils peuvent communiquer avec les points de terminaison utilisés par ces services. Exemple :

    • 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 fait correspondre directement 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 régionale du client 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. Vous devez également vous assurer que l'agent dispose du rôle "IAP Egressor" pour ces points de terminaison. Pour obtenir des instructions, consultez Créer une stratégie de sortie d'agent vers point de terminaison.

  7. Vérifier la configuration de l'agent

    Console

    1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

      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 Informations sur le déploiement. Les configurations d'entrée et de sortie de la passerelle d'agent sont disponibles dans le champ Spécification de déploiement.

    gcloud

    Utilisez la requête d'API REST suivante pour vérifier que l'agent est désormais associé à la passerelle. Si la sortie renvoyée est null, cela signifie que le runtime n'a pas réussi à 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 la passerelle d'agent

Si vous souhaitez acheminer le trafic sortant via une passerelle d'agent 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 truststore de l'image de conteneur personnalisée.

Étant donné qu'Agent Gateway effectue le déchiffrement et l'inspection TLS sur les communications sortantes des agents, 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 à l'intérieur de votre Dockerfile et définir les variables d'environnement du bundle de certificats requises par les SDK Python, les bibliothèques de clients 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 à partir du 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 passerelle d'agent 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 faire 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 les noms de votre dépôt Artifact Registry et 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 demande de déploiement (à l'aide de agent_gateway_config sous spec.deploymentSpec ou à l'aide des appels de déploiement du SDK).

Restreindre Agent Runtime aux passerelles d'agent approuvées

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 qu'à destination et en provenance d'une liste de passerelles préapprouvée.

Agent vers n'importe quelle destination

  1. Pour définir une contrainte personnalisée pour le mode Agent-to-Anywhere (sortie), créez un fichier nommé constraint-agent-gateway-egress.yaml.

    Dans l'exemple suivant, le champ condition spécifie que l'opération n'est autorisée que si une ressource Agent Gateway est spécifiée (champ présent et non vide) et si la passerelle spécifiée figure dans la liste préapprouvée.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Remplacez les éléments suivants :

    • ORGANIZATION_ID : votre ID d'organisation.
    • AGENT_PROJECT_ID : ID de votre projet.
    • REGION : région dans laquelle la passerelle a été créée.
    • AGENT_GATEWAY_ID : ID de votre passerelle.

  2. Appliquez la contrainte personnalisée.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Remplacez EGRESS_CONSTRAINT_PATH par le chemin d'accès complet au fichier de contrainte personnalisée créé à l'étape précédente.

  3. Créez la règle d'administration pour appliquer la contrainte. Pour définir la règle d'administration, créez un fichier YAML de règle nommé policy-agent-gateway-egress.yaml. Dans cet exemple, nous appliquons cette contrainte au niveau d'un projet, mais vous pouvez également la définir au niveau de l'organisation ou d'un dossier.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Remplacez AGENT_PROJECT_ID par l'ID du projet.

  4. Appliquez la règle d'administration.

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    Remplacez EGRESS_POLICY_PATH par le chemin d'accès complet au fichier YAML de la règle d'administration créé à l'étape précédente. L'application de la règle peut prendre jusqu'à 15 minutes.

Client vers agent

  1. Pour définir une contrainte personnalisée pour le mode Client-to-Agent (entrée), créez un fichier nommé constraint-agent-gateway-ingress.yaml.

    Dans l'exemple suivant, le champ condition spécifie que l'opération n'est autorisée que si une ressource Agent Gateway est spécifiée (champ présent et non vide) et si la passerelle spécifiée figure dans la liste préapprouvée.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Remplacez les éléments suivants :

    • ORGANIZATION_ID : votre ID d'organisation.
    • AGENT_PROJECT_ID : ID de votre projet.
    • REGION : région dans laquelle la passerelle a été créée.
    • AGENT_GATEWAY_ID : ID de votre passerelle.

  2. Appliquez la contrainte personnalisée.

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Remplacez INGRESS_CONSTRAINT_PATH par le chemin d'accès complet au fichier de contrainte personnalisée créé à l'étape précédente.

  3. Créez la règle d'administration pour appliquer la contrainte. Pour définir la règle d'administration, créez un fichier YAML de règle nommé policy-agent-gateway-ingress.yaml. Dans cet exemple, nous appliquons cette contrainte au niveau d'un projet, mais vous pouvez également la définir au niveau de l'organisation ou d'un dossier.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Remplacez AGENT_PROJECT_ID par l'ID du projet.

  4. Appliquez la règle d'administration.

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    Remplacez INGRESS_POLICY_PATH par le chemin d'accès complet au fichier YAML de la règle d'administration créé à l'étape précédente. L'application de la règle peut prendre jusqu'à 15 minutes.

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 multi-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 la passerelle d'agent doivent se trouver dans le même projet.
    • Vous devez utiliser l'API REST ou gcloud pour configurer la gouvernance de bout en bout entre les projets. La console Google Cloud Google Cloud ne permet pas de créer des liaisons de stratégie IAM ni des entrées du Registre d'agents interprojets.

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

  • Bien qu'un même projet et une même 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 associés aux mêmes instances Agent Gateway spécifiques de sortie et d'entrée.

    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 ni agent-B pour utiliser egress-gateway-Y.

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

  • Le service Security Command Center Agent Engine Threat Detection 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 (telles que 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.

  • VPC Service Controls n'est pas compatible avec Agent Gateway.

  • Agent Gateway n'est pas compatible avec les agents Agent Runtime qui utilisent des révisions. Vous ne pourrez pas utiliser les fonctionnalités liées au versionnement, telles que la configuration de la répartition du trafic et les requêtes par révision, si une passerelle Agent Gateway est associée à la configuration d'un agent.

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

Étapes suivantes

Atelier de programmation

Découvrez comment régir les charges de travail agentiques avec Agent Gateway sur Gemini Enterprise Agent Platform.

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 la passerelle d'agent.

Dépannage

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