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. Il fournit une connectivité sécurisée et régie pour toutes les interactions agentiques, qu'elles aient lieu entre des utilisateurs et des agents, des agents et des outils, ou entre des agents eux-mêmes.

Avant de commencer

  • Assurez-vous de savoir comment déployer des agents sur Agent Runtime.

  • Découvrez Agent Gateway. Vous pouvez utiliser Agent Gateway en mode Agent vers n'importe quelle destination (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 vers 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 seule instance Runtime peut être liée simultanément à une passerelle Agent vers n'importe quelle destination (sortie) et à une passerelle Client vers agent (entrée).

Limites

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

  • Bien qu'un seul projet et une seule région puissent héberger plusieurs instances de passerelle d'agent Agent vers n'importe quelle destination (sortie) et Client vers 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 spécifiques de passerelle d'agent 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, tous les agents utilisent egress-gateway-X ou tous les agents utilisent egress-gateway-Y. Vous ne pouvez pas configurer agent-A pour qu'il utilise egress-gateway-X et agent-B pour qu'il utilise 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 Agent Engine de Security Command Center n'est pas disponible lorsque Agent Gateway est activé pour un agent.

  • En mode Client vers 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 à partir de votre application ou de votre agent. Consultez Assainir 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.

Acheminer le trafic Agent Runtime via Agent Gateway

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

  1. 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 vers n'importe quelle destination (sortie) ou en mode Client vers agent (entrée). Notez que l'agent et la passerelle doivent être créés dans le même projet et la même région. 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. Configurez votre agent pour qu'il achemine le trafic via Agent Gateway.

    • 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 ainsi que toutes les configurations facultatives.

      Si vous souhaitez utiliser des fonctionnalités de plate-forme gérées par la 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 illustré dans cet exemple. Sans identity_type=AGENT_IDENTITY, effectiveIdentity de l'instance 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.

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "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 AGENT_GATEWAY_TO_ANYWHERE_NAME par le nom de l'Agent Gateway que vous avez créé en mode Agent vers n'importe quelle destination (sortie).

      Si vous avez créé une passerelle en mode Client vers agent (entrée), utilisez plutôt le champ client_to_agent_config et remplacez AGENT_GATEWAY_CLIENT_TO_AGENT_NAME par le nom de l'Agent Gateway que vous avez créé pour l'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 vers n'importe quelle destination 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/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Remplacez les éléments suivants :

      • PROJECT_ID : ID du projet
      • REGION : région dans laquelle l'agent 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)
      • RESOURCE_ID : l'ID deressource de l'agent

      Client vers agent

      Utilisez la requête d'API REST suivante pour associer un agent existant à une passerelle Client vers 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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Remplacez les éléments suivants :

      • PROJECT_ID : ID du projet
      • REGION : région dans laquelle l'agent est déployé
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: nom de l'Agent Gateway que vous avez créé en mode Client vers agent (entrée)
      • RESOURCE_ID : l'ID de ressource de l'agent

  3. Enregistrez-vous auprès de l'instance Agent Registry dans le même projet et la même région que l'agent et la passerelle.

    gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"

    Remplacez les éléments suivants :

    • SERVICE_NAME: nom que vous souhaitez attribuer à votre ressource, par exemple allow-aiplatform-region-eu3.
    • PROJECT_ID : ID du projet.
    • REGION : région du registre.
    • DISPLAY_NAME: nom lisible du point de terminaison.

    Pour en savoir plus, consultez Enregistrer un agent.

  4. Créez une liaison de stratégie IAM entre l'agent et le registre pour l'agent.

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

    Remplacez les éléments suivants :

    • ENDPOINT_ID: ID du point de terminaison de service de l'agent enregistré. Vous l'obtenez à partir de la sortie de l'étape précédente.

    • MEMBER: compte principal d'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.

  5. À ce stade, le trafic de votre agent sera désormais acheminé via 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 :

    • 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 les 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'autoriser uniquement les URI spécifiques auxquels l'agent accède. Étant donné que la passerelle correspond directement aux 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 l'authentification 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 règle de sortie d'agent vers un point de terminaison.

  6. Vérifiez la configuration de votre agent.

    Console

    1. Dans la Google Cloud console, 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 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 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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

    Remplacez les éléments suivants :

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

Restreindre Agent Runtime aux passerelles d'agent approuvées

Vous pouvez créer des contraintes personnalisées liées aux règles d'administration pour définir l'ensemble des ressources Agent Gateway éligibles qui peuvent ê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ée.

Agent vers n'importe quelle destination

  1. Pour définir une contrainte personnalisée pour le mode Agent vers n'importe quelle destination (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 (le champ est 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 : ID de votre 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 de votre 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 vers 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 (le champ est 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 : ID de votre 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 de votre 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 personnalisées liées aux règles d'administration, consultez Créer des contraintes personnalisées.

Étape suivante

Atelier de programmation

Découvrez comment gérer 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 Agent Gateway.

Résolution des problèmes

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