Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Gouverner les charges de travail agentiques avec Agent Gateway sur Gemini Enterprise Agent Platform

1. Introduction

Gemini Enterprise Agent Platform est une plate-forme ouverte qui permet de créer, de faire évoluer, de gérer et d'optimiser des agents IA de niveau entreprise ancrés dans vos données.

Agent Runtime fournit l'environnement d'exécution géré pour exécuter des agents, tels que ceux créés avec l'Agent Development Kit (ADK) Open Source, de manière sécurisée dans Google Cloud.

Cet atelier de programmation explique comment utiliser ces blocs de construction de base pour contrôler un agent initié par un utilisateur dans Gemini Enterprise lorsqu'il accède de manière sécurisée à des outils internes.

À propos d'Agent Gateway

Agent Gateway est le composant réseau de la suite Agent Governance de la plate-forme. Il sert de point d'entrée et de sortie réseau pour toutes les interactions des agents, ce qui permet aux administrateurs de sécurité d'appliquer une gouvernance centralisée sans que les développeurs aient à gérer des primitives réseau complexes.

Il facilite deux principaux chemins d'accès contrôlés :

Client vers agent (entrée) : sécurise les communications entre les clients externes (comme Cursor ou Gemini CLI) et vos agents.
Agent-to-Anywhere (sortie) : sécurise les communications entre les agents s'exécutant sur Google Cloud et les serveurs, outils ou API s'exécutant n'importe où.

Dans cet atelier de programmation, vous vous concentrerez sur le mode Agent-to-Anywhere (sortie).

Contrôle des accès avec Agent Gateway

Pour appliquer les règles de sécurité, Agent Gateway s'intègre étroitement au reste de l'écosystème :

Agent Registry : bibliothèque centrale des agents et outils approuvés (y compris les serveurs MCP tiers).
Identité de l'agent : une identité unique et traçable pour chaque agent, sécurisée automatiquement avec mTLS de bout en bout.
Identity-Aware Proxy (IAP) et IAM : couche d'application par défaut qui valide l'identité de l'agent par rapport aux autorisations IAM précises avant d'autoriser les appels à des outils spécifiques.
Model Armor : un garde-fou de sécurité de l'IA intégré via les Service Extensions pour assainir le contenu et protéger contre les attaques par injection de prompt ou les fuites de données.

Modes de déploiement (mise en réseau publique ou privée pour Cloud Run)

Pour rendre cet atelier de programmation accessible, vous pouvez choisir entre deux chemins réseau pour vos outils internes (serveurs MCP) déployés sur Cloud Run :

Par défaut (entrée publique) : les serveurs MCP sont déployés sur Cloud Run avec des noms d'hôte publics (ingress=all). Le trafic est acheminé de l'agent vers les outils via des URL *.run.app standards. Cette option ne nécessite aucun domaine DNS personnalisé et constitue le moyen le plus rapide d'apprendre les concepts de gouvernance.
Sécurisée (mise en réseau privée) : architecture entièrement privée et facultative. Les serveurs MCP sont limités (ingress=internal-and-cloud-load-balancing) et exposés via un équilibreur de charge d'application interne avec un NEG sans serveur. Pour provisionner un certificat géré par Google, vous devez posséder un domaine DNS public.

Vous sélectionnerez le chemin de votre choix lors de la configuration de Terraform.

Pour en savoir plus sur l'entrée de point de terminaison réseau pour Cloud Run, consultez notre documentation.

Objectifs de l'atelier

Provisionner la pile d'infrastructure de base à l'aide de Terraform
Créer et déployer des outils internes en tant que serveurs MCP sur Cloud Run
Déployer un agent ADK sur Agent Runtime à l'aide de la sortie de l'interface PSC
Configurer les extensions de service Agent Gateway pour l'accès basé sur l'identité (IAM) et le filtrage de contenu (Model Armor)
Tracer et valider l'exécution sécurisée de bout en bout de l'agent

Prérequis

Un navigateur Web (par exemple, Chrome)
Un projet Google Cloud avec la facturation activée et un accès Propriétaire
Autorisations IAM au niveau de l'organisation (l'atelier de programmation attribue des rôles à portée d'organisation)
Un domaine que vous contrôlez et qui est délégué à Cloud DNS (pour le certificat public géré)
Connaissance de Terraform, gcloud et des bases du réseau Google Cloud

Topologie de l'atelier de programmation

Architecture de bout en bout : Gemini Enterprise vers Agent Runtime vers Agent Gateway vers serveurs MCP sur Cloud Run

Dans cet atelier de programmation, vous allez déployer un agent de souscription hypothécaire de bout en bout qui communique de manière sécurisée avec trois outils internes.

Vous allez commencer par provisionner les éléments de base du réseau, y compris un VPC et un équilibreur de charge d'application interne configuré comme passerelle d'agent. Vous allez ensuite déployer trois serveurs MCP (Model Context Protocol) sur Cloud Run. Ils agissent comme vos outils propriétaires internes :

Gestion des documents (legacy-dms)
Adresse e-mail professionnelle (corporate-email)
Vérification des revenus (income-verification)

Maintenant que vous avez les outils nécessaires, vous allez déployer un assistant hypothécaire (mortgage-agent) créé avec ADK sur Agent Runtime. Vous configurerez cet agent pour qu'il utilise une interface PSC pour la sortie privée et activerez la découverte des outils d'exécution via le registre d'agents.

Pour sécuriser le flux, vous allez configurer votre passerelle d'agent avec deux extensions de service. Tout d'abord, une extension REQUEST_AUTHZ vérifie l'identité de l'agent par rapport aux stratégies IAM par outil, ce qui garantit que l'agent n'accède qu'aux outils autorisés. Ensuite, une extension CONTENT_AUTHZ utilisant Model Armor filtrera les prompts et les réponses de l'agent.

Enfin, vous enregistrerez l'agent dans Gemini Enterprise, déclencherez une tâche de souscription hypothécaire en tant qu'utilisateur final et vérifierez l'exécution sécurisée et régie à l'aide de Cloud Trace.

Cet atelier de programmation s'adresse aux ingénieurs de plate-forme et de sécurité de tous niveaux. Comptez environ 100 minutes pour le terminer.

2. Avant de commencer

Créer un projet et s'authentifier

Créez un projet GCP (ou réutilisez-en un) avec la facturation activée, puis authentifiez Cloud Shell ou votre ordinateur local :

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Activer les API d'amorçage

Le module de base de Terraform permet d'appliquer environ 30 API lors de sa première application, mais un petit ensemble d'amorçage est requis pour terraform init et le bucket d'état GCS :

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Installer les outils nécessaires

Installez la chaîne d'outils. Sur Cloud Shell, la plupart de ces éléments sont déjà présents. Sur un poste de travail :

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Vous avez également besoin de Terraform >= 1.12.2, de Python 3.12+ et du Google Cloud SDK (gcloud).

Définir des variables d'environnement

Le reste de l'atelier de programmation suppose que ces variables sont exportées dans votre shell.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

Vérifiez que toutes vos variables ont été correctement renseignées. Trois valeurs doivent être renvoyées.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Si votre ID d'organisation ne s'affiche pas, vous pouvez le trouver et le définir manuellement.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Cloner le dépôt

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Voici un aperçu du contenu du répertoire de démonstration :

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Créer le bucket d'état Terraform et la configuration du backend

Créez un bucket GCS pour stocker l'état distant, puis copiez le modèle de backend :

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Modifiez terraform/backend.conf avec vos valeurs :

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5. (Facultatif) Créer une zone Cloud DNS publique

Par défaut, la configuration d'entrée de Cloud Run pour cet atelier est définie sur all. Agent Registry enregistre chaque serveur MCP à son URL *.run.app publique. Aucun DNS, certificat ni équilibreur de charge supplémentaires ne sont requis. Si vous souhaitez passer à la mise en réseau privée (Cloud Run avec ingress = internal-and-cloud-load-balancing derrière un équilibreur de charge d'application interne), vous avez également besoin d'une zone Cloud DNS publique pour que Certificate Manager puisse valider le certificat de l'équilibreur de charge.

Procédure générale de mise en réseau privée

Procédure générale de l'option de mise en réseau privée

Pour utiliser l'approche de mise en réseau privée :

Créez la zone DNS publique Cloud DNS. Certificate Manager valide le certificat régional géré en y écrivant des enregistrements CNAME :

gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

La zone privée correspondante pour mcp.${DOMAIN_NAME} (utilisée par l'équilibreur de charge interne MCP et l'appairage DNS à partir d'Agent Runtime) est créée automatiquement par Terraform. Vous n'avez pas besoin de la créer manuellement. Si la mise en réseau privée est désactivée, aucune zone (publique ou privée) n'est provisionnée.

6. Configurer les variables Terraform

Copiez l'exemple tfvars et modifiez-le :

cp terraform/example.tfvars terraform/terraform.tfvars

Il existe deux chemins de démonstration, contrôlés par enable_cloud_run_private_networking.

Chemin par défaut : Cloud Run avec entrée publique

Configuration la plus simple : pour le chemin par défaut, il vous suffit de modifier trois valeurs dans terraform.tfvars. Toutes les autres variables du fichier ont déjà une valeur par défaut adaptée à la démonstration.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Mise en réseau privée (facultatif)

Définissez enable_cloud_run_private_networking = true et ajoutez les variables ci-dessous pour provisionner la pile sécurisée complète :

Équilibreur de charge d'application interne
Certificat géré par Google
Cloud Run avec ingress = internal-and-cloud-load-balancing
Appairage DNS de l'Agent Gateway.

enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. Déployer une infrastructure avec Terraform

Initialisez, examinez et appliquez :

cd terraform
terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply tfplan

terraform apply provisionne environ 40 ressources sur le chemin par défaut et prend 8 à 10 minutes sur un nouveau projet (environ 60 ressources / 15 à 20 minutes avec enable_cloud_run_private_networking = true). Il crée :

Bases du projet (API, identités de service, quotas)
VPC, sous-réseaux (principal, proxy réservé, PSC, interface PSC, colocation de l'Agent Gateway), Cloud NAT, règles de pare-feu
Dépôt Artifact Registry pour les images Cloud Run
Trois services Cloud Run + les comptes de service d'exécution par service (ingress = all par défaut ; internal-and-cloud-load-balancing lorsque la mise en réseau privée est activée)
Modèle Model Armor + IAM
Passerelle d'agent, rattachement au réseau PSC-I, extensions IAP et Model Armor, les deux règles d'autorisation et l'autorisation roles/iap.egressor au niveau du projet
Points de terminaison Agent Registry (Vertex AI, IAP, Discovery Engine, etc.) et trois serveurs MCP (enregistrés sur *.run.app/mcp par défaut, sur ./mcp lorsque la mise en réseau privée est activée)

Uniquement lorsque enable_cloud_run_private_networking = true :

Équilibreur de charge d'application interne régional avec un NEG sans serveur (routage par masque d'URL) + enregistrements A DNS privés
Zone DNS privée MCP (mcp..) associée au VPC
Module de zone DNS publique (autorisations DNS du gestionnaire de certificats) + certificat régional géré par Google
Zone DNS de l'interface PSC (orpheline lorsqu'il n'y a pas de noms d'hôte privés à résoudre, elle est donc également contrôlée par le signalement maître)
Appairage DNS de la passerelle d'agent pour mcp.. (préfixe automatique)

8. Inspecter les points de terminaison du registre d'agents

Agent Registry est un catalogue de services par projet (API Google et vos propres serveurs MCP) qu'un agent découvre au moment de l'exécution. L'agent hypothécaire le lit au démarrage et lie les outils de manière dynamique. Aucune URL MCP n'est intégrée au code de l'agent ni à sa commande de déploiement.

Points de terminaison

Ce que Terraform a exécuté en votre nom : pour chaque API Google dans agent_registry_google_apis, il a enregistré cinq variantes (globale, globale mTLS, régionale, régionale mTLS, régionale REP). Par exemple, pour aiplatform :

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

Serveurs MCP

Terraform enregistre également les trois serveurs MCP pour vous. Pour enregistrer d'autres serveurs MCP, vous pouvez suivre les étapes de la documentation.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Vérifiez les points de terminaison et les serveurs MCP enregistrés.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Source : terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl.

9. Examiner la configuration de l'Agent Gateway

Agent Gateway est un plan de gouvernance géré par Google entre Agent Runtime et vos outils. En mode AGENT_TO_ANYWHERE, il est lié au registre d'agents du projet et sort via une interface PSC appartenant au client afin de pouvoir atteindre les serveurs MCP privés de votre VPC.

Si vous importiez cette passerelle manuellement, le fichier YAML se présenterait comme suit :

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Vérifiez la passerelle créée par Terraform :

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

10. Examiner l'autorisation IAP et Model Armor

L'Agent Gateway délègue l'autorisation aux extensions de service. Deux profils de règles couvrent la démo :

REQUEST_AUTHZ : évalué une fois par requête au niveau des en-têtes. Utilisé ici pour appeler IAP, qui vérifie si l'identité de l'agent appelant dispose de roles/iap.egressor sur le serveur MCP cible.
CONTENT_AUTHZ : transmet les événements du corps du flux à l'extension pour la désinfection du contenu. Utilisé ici pour appeler Model Armor, qui filtre l'injection de prompt, le jailbreaking, les cas de non-respect de l'IA responsable et (facultativement) les informations permettant d'identifier personnellement l'utilisateur via Sensitive Data Protection (SDP).

Extension IAP REQUEST_AUTHZ

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Associez-le à l'Agent Gateway avec une règle REQUEST_AUTHZ :

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Extension CONTENT_AUTHZ de Model Armor

Le metadata.model_armor_settings de l'extension contient les ID de modèle de requête et de réponse que Model Armor utilise pour évaluer chaque encadré :

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Modèles DLP personnalisés

La fonctionnalité sdpSettings.basicConfig de Model Armor utilise une liste d'infoTypes intégrée. Pour un contrôle plus précis (infoTypes personnalisés, masquage partiel, remplacement par des substituts, effacement par probabilité), pointez Model Armor vers vos propres modèles inspect et de-identify Cloud DLP via sdpSettings.advancedConfig.

Créez un modèle d'inspection qui signale les numéros de sécurité sociale américains avec une probabilité de POSSIBLE ou plus :

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}"