Acheminer le trafic Agent Runtime via Agent Gateway

Cette page explique comment acheminer le trafic d'Agent Runtime via la passerelle d'agent. La passerelle d'agent 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 aient lieu entre des utilisateurs et des agents, entre 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 la passerelle d'agent. Vous pouvez utiliser la passerelle d'agent 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.

  • Créez un projet de test dédié pour essayer ce workflow. Évitez d'utiliser des projets également destinés à d'autres charges de travail critiques.

Limites

  • Pour un projet et une région donnés, il ne peut y avoir qu'une seule instance "Agent vers n'importe quelle destination" (sortie) et une seule instance "Client vers agent" (entrée) de la passerelle d'agent. Tous les agents Agent Runtime du même projet et de la même région qui sont configurés pour utiliser la passerelle d'agent doivent utiliser ces instances de passerelle spécifiques.
  • Le service Security Command Center Agent Engine Threat Detection n'est pas disponible lorsque la passerelle d'agent est activée pour un agent.
  • Vous ne pouvez pas dissocier un agent Runtime d'une ressource de passerelle d'agent. Pour cette raison, assurez-vous d'utiliser un projet de test dédié.

Acheminer le trafic d'Agent Runtime via la passerelle d'agent

Pour acheminer le trafic d'Agent Runtime via la passerelle d'agent, procédez comme suit :

  1. Créez une ressource de passerelle d'agent 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 "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 la passerelle d'agent.

    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 à un LLM, configurez la passerelle pour autoriser cet accès afin d'éviter d'éventuels échecs de déploiement d'Agent Runtime.

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

    Vous devez également vous assurer qu'une identité d'agent est attribuée à l'instance Runtime à l'aide du identity_type paramètre, comme illustré dans cet exemple.

    remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "client_to_agent_config": {"agent_gateway": 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 chemin d'accès complet de la passerelle d'agent que vous avez créée en mode "Agent vers n'importe quelle destination" (sortie). Par exemple, projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID.

    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 chemin d'accès complet de la passerelle d'agent que vous avez créée pour l'entrée.

  3. Enregistrez votre agent auprès de l'instance Agent Registry dans le même projet et la même région que l'agent et la passerelle. Pour en savoir plus, consultez Enregistrer un agent.

Limiter 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 de passerelle d'agent é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.

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 de passerelle d'agent 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 alpha 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ègles 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 alpha 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 de passerelle d'agent 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 alpha 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ègles 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 alpha 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 régir les charges de travail agentiques avec la passerelle d'agent sur Gemini Enterprise Agent Platform.

Guide

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

Guide

Découvrez comment surveiller la passerelle d'agent.