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 permettant 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 contacte des outils internes de manière sécurisée.

À propos de la passerelle d'agent

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

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

1. 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.
2. 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, de gcloud et des bases du réseau Google Cloud

Topologie de l'atelier de programmation

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)
• Validation 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 règles IAM par outil, en s'assurant que l'agent n'accède qu'aux outils autorisés. Ensuite, une extension CONTENT_AUTHZ utilisant Model Armor filtrera les requêtes et les réponses de l'agent.

Enfin, vous allez enregistrer l'agent dans Gemini Enterprise, déclencher une tâche de souscription hypothécaire en tant qu'utilisateur final et vérifier 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 une station 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.

Si vous suivez le chemin d'accès facultatif pour la mise en réseau sécurisée, définissez DOMAIN_NAME (par exemple, agw.example.com). Sinon, vous pouvez l'ignorer.

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é renseignées correctement. 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"

terraform/backend.conf est ignoré par Git. Chaque utilisateur conserve sa propre copie.

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

Ignorez cette étape si vous utilisez le chemin par défaut. Si vous souhaitez utiliser la configuration la plus simple avec des URL Cloud Run publiques, passez directement à l'étape suivante.

Par défaut, la configuration d'entrée de Cloud Run pour cet atelier est définie sur all. Le registre d'agents 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.

Étapes clés de la mise en réseau privée

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

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

Pour obtenir une présentation plus détaillée du modèle DNS à horizon partagé public et privé utilisé par cette démonstration (configuration de la zone gérée, appairage DNS entre les VPC, flux de validation des certificats), consultez le guide de configuration DNS.

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:[e-mail]"]

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

Nous allons configurer IAP en mode simulation d'audit uniquement pour tester la règle d'autorisation IAP sans l'appliquer. Une fois notre déploiement validé, nous définirons le mode d'application sur "APPLIQUÉ".

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

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"

Les images Cloud Run ci-dessus pointent vers un espace réservé Google. C'est intentionnel : Terraform crée les services Cloud Run avec lifecycle { ignore_changes = [template[0].containers[0].image] }. Les appels skaffold run suivants remplacent donc l'image sans que Terraform ne s'y oppose.

agent_gateway_subnet_cidr doit être au moins /28, RFC 1918 et ne doit pas chevaucher 10.0.0.0/24, 10.0.1.0/24 ni 10.0.2.0/24. Ces plages sont réservées à la sortie de la passerelle d'agent.

L'équilibreur de charge interne MCP sert TLS pour *.mcp.${DOMAIN_NAME} en utilisant le même certificat régional géré par Google. Ne définissez pas mcp_internal_dns_zone.domain sur un suffixe non routable tel que mcp-server.internal. lorsque enable_agent_gateway = true ET enable_cloud_run_private_networking = true.

La passerelle d'agent ne valide pas actuellement le certificat de secours autosigné. La configuration Terraform applique cette règle avec un bloc check au moment de la planification (ignoré lorsque le réseau privé est désactivé, car il n'y a pas de certificat LB à valider).

7. Déployer l'infrastructure avec Terraform

Initialisez, examinez et appliquez :

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

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 la passerelle d'agent), 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 du registre d'agents (Vertex AI, IAP, Discovery Engine, etc.) et les 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

Pour référence uniquement. Les commandes de cette section ont déjà été exécutées pour vous par le module agent-registry-endpoints de Terraform. Ils sont affichés pour que vous puissiez voir exactement à quoi ressemble l'enregistrement d'un point de terminaison détectable par MCP.

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. Vérifier la configuration de la passerelle d'agent

Pour référence uniquement. Terraform a déjà importé cette passerelle d'agent. Le code YAML ci-dessous est l'équivalent littéral de terraform/modules/agent-gateway/main.tf.

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

La terraform-provider-google-beta actuelle n'expose pas encore network_config.dns_peering_config. Terraform l'applique via un PATCH post-apply sur networkservices.googleapis.com/v1beta1. Vous le verrez dans terraform_data.dns_peering dans le module.

10. Examiner l'autorisation IAP et Model Armor

Pour référence uniquement. Terraform a déjà créé les deux extensions et les deux règles. Les commandes ci-dessous proviennent directement de terraform/modules/agent-gateway/main.tf.

La passerelle d'agent 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 les injections de prompt, le jailbreak, les cas de non-respect de l'IAR 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 à la passerelle d'agent 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 Cloud DLP inspect et de-identify 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}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Créez un modèle d'anonymisation qui remplace chaque résultat par son jeton d'infoType (par exemple, [US_SOCIAL_SECURITY_NUMBER]) :

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Ensuite, pointez la configuration de la réponse d'un modèle Model Armor vers la paire via sdpSettings.advancedConfig (c'est là que le module model_armor de Terraform définirait advanced_config si vous l'aviez câblé) :

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

L'extension Model Armor CONTENT_AUTHZ ci-dessus sélectionnera automatiquement ces modèles de configuration avancée la prochaine fois qu'elle évaluera une réponse. Aucune modification de l'extension n'est nécessaire. Assurez-vous que l'agent de service Model Armor (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) dispose des rôles roles/dlp.user et roles/dlp.reader dans le projet (le module model-armor de Terraform les accorde déjà).

IAM de l'egressor IAP (par serveur MCP uniquement)

Terraform ne crée pas de liaison roles/iap.egressor à l'échelle du projet dans le registre d'agents IAP implicite. La liaison IAP REQUEST_AUTHZ évaluée est en fait par serveur MCP et par moteur de raisonnement. Elle est accordée après le déploiement de l'agent et lorsque vous connaissez l'ID de l'agent. L'étape "Accorder à l'agent l'accès à la sortie par serveur MCP" exécute scripts/grant_agent_mcp_egress.sh à cet effet.

11. Créer et déployer les serveurs MCP sur Cloud Run

Les fichiers cloudrun/*.yaml.tmpl et skaffold.yaml.tmpl font référence à ${PROJECT_ID}, ${REGION} et ${MCP_INGRESS} (l'annotation d'entrée Cloud Run). Source MCP_INGRESS à partir d'un résultat Terraform afin que les fichiers manifestes affichés restent synchronisés avec enable_cloud_run_private_networking, puis affichez-les avec envsubst :

Exportez votre configuration d'entrée Cloud Run.

• all
• internal-and-cloud-load-balancing (lors de l'utilisation de l'approche de mise en réseau privée)

export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Chaque service Cloud Run s'exécute en tant que compte de service d'exécution par service créé par Terraform (par exemple, mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Pour effectuer un déploiement en tant que ces comptes de service, vous devez disposer de roles/iam.serviceAccountUser :

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Compiler avec Cloud Build et déployer avec Skaffold :

skaffold run

Skaffold compile trois images (legacy-dms, corporate-email, income-verification-api) dans votre dépôt Artifact Registry et met à jour chaque service Cloud Run pour qu'il pointe vers le nouveau résumé.

Vérifiez :

gcloud run services list --region=${REGION}

Les trois services doivent s'afficher avec l'état ACTIVE.

12. Déployer l'agent hypothécaire sur Agent Runtime

Installez les dépendances de l'agent et déployez-le :

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

L'agent découvre les outils MCP au moment de l'exécution en listant mcpServers dans Agent Registry sous projects/${PROJECT_ID}/locations/${REGION}.

Une fois le script terminé, copiez le reasoningEngines/ imprimé dans votre shell :

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Accorder à l'agent l'accès sortant par serveur MCP

L'extension IAP REQUEST_AUTHZ autorise chaque appel d'outil en vérifiant le roles/iap.egressor de l'agent sur le serveur MCP spécifique ou le point de terminaison qu'il appelle. Consultez Créer une règle de sortie de serveur d'agent vers MCP.

Le script (scripts/grant_agent_mcp_egress.sh) énumère les serveurs MCP dans le registre des agents sous projects/${PROJECT_ID}/locations/${REGION} et fusionne une liaison roles/iap.egressor pour le compte principal de l'agent dans la stratégie IAM de chaque serveur (en reprenant la sémantique de gcloud add-iam-policy-binding).

Cas d'utilisation 1 : Accord inconditionnel limité à des serveurs MCP spécifiques

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Cas d'utilisation 2 : Accord conditionnel (CEL) limité à un serveur MCP spécifique

Pour limiter l'agent à un sous-ensemble d'outils sur un seul serveur MCP, associez une condition IAM. La passerelle d'agent publie des attributs par outil que IAP REQUEST_AUTHZ expose à CEL, y compris :

• iap.googleapis.com/mcp.toolName
• iap.googleapis.com/mcp.tool.isReadOnly
• iap.googleapis.com/request.auth.type.

Limitez l'agent aux outils en lecture seule sur corporate-email :

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Une fois cette opération exécutée, les outils d'écriture sur corporate-email renvoient 403 PermissionDenied à partir de IAP REQUEST_AUTHZ. Les outils en lecture seule continuent de fonctionner.

Valider les liaisons

Accédez à l'onglet Règles. La liste des règles créées pour les points de terminaison et les serveurs Mcp s'affiche.

Autres cas d'utilisation :

Autorisation inconditionnelle sur chaque serveur MCP, limitée à un seul agent

Exécutez cette commande après chaque redéploiement de l'agent. Sans filtre ni condition, l'agent nommé obtient roles/iap.egressor sur chaque serveur MCP du registre :

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Tester l'agent dans la console Agent Platform

La console Agent Platform est fournie avec un bac à sable qui vous permet de discuter directement avec l'agent déployé. Il s'agit du moyen le plus rapide de tester les appels d'outils et d'inspecter les traces avant de connecter l'agent à Gemini Enterprise.

1. Ouvrez la page Déploiements de la plate-forme d'agent dans la console Google Cloud.
2. Utilisez le champ Filtrer si vous devez affiner la liste des environnements d'exécution, puis cliquez sur votre environnement d'exécution mortgage-agent.
3. Ouvrez l'onglet Playground.
4. Saisissez un prompt pour discuter avec l'agent :

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Cela devrait renvoyer une réponse de l'outil de gestion des documents et de l'outil de validation des revenus. Les numéros de sécurité sociale doivent également être masqués dans cette réponse. 5. Saisissez une question complémentaire :

Can you send a summary of this to my email [e-mail]

L'agent doit indiquer qu'il n'a pas accès à l'outil send_email et répondre en conséquence.

Comme l'agent a été déployé avec l'instrumentation OpenTelemetry, le Playground expose quatre vues de panneau latéral entre lesquelles vous pouvez basculer à mesure que l'agent répond :

• Trace : traces complètes de la conversation, y compris les étendues Agent Gateway, IAP REQUEST_AUTHZ et Model Armor CONTENT_AUTHZ
• Événement : graphique des outils appelés et détails des événements pour le tour actuel
• État : état de session de l'agent et entrées/sorties des outils
• Sessions : chaque session que vous avez lancée par rapport à ce temps d'exécution

Le bac à sable contourne complètement l'authentification Gemini Enterprise, ce qui en fait l'endroit le plus rapide pour confirmer que l'extension IAP REQUEST_AUTHZ accorde correctement les appels d'outils. Si un outil renvoie un code 403 ici, réexécutez scripts/grant_agent_mcp_egress.sh avant de procéder à un débogage plus approfondi.

15. Appliquer l'autorisation IAP

Maintenant que nous avons validé le déploiement, nous pouvons définir le mode d'application IAP sur null pour appliquer les règles. Ouvrez terraform.tfvars et remplacez le mode DRY_RUN par null.

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

Appliquez la modification.

terraform apply

Revenez à l'atelier et réessayez la conversation.

1. Ouvrez la page Déploiements de la plate-forme d'agent dans la console Google Cloud.
2. Utilisez le champ Filtrer si vous devez affiner la liste des environnements d'exécution, puis cliquez sur votre environnement d'exécution mortgage-agent.
3. Ouvrez l'onglet Playground.
4. Saisissez un prompt pour discuter avec l'agent :

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Cela devrait renvoyer une réponse de l'outil de gestion des documents et de l'outil de validation des revenus. Les numéros de sécurité sociale doivent également être masqués dans cette réponse. 5. Saisissez une question complémentaire :

Can you send a summary of this to my email [e-mail]

Si tout a été configuré correctement, l'agent devrait répondre qu'il ne peut pas envoyer l'e-mail en raison du règlement sur l'autorisation.

16. Configuration et test de Gemini Enterprise

Configurer Gemini Enterprise

Suivez le guide de démarrage de Gemini Enterprise.

Enregistrer notre agent ADK auprès de Gemini Enterprise

Pour enregistrer notre agent dans Gemini Enterprise, suivez ces étapes.

1. Dans la console Google Cloud, accédez à la page Gemini Enterprise.
2. Sélectionnez l'application Gemini Enterprise dans laquelle l'agent est enregistré.
3. Ouvrez l'URL indiquée dans la section Votre application Web Gemini Enterprise est prête.
4. Sélectionnez l'onglet Agent dans le menu de gauche pour ouvrir la Galerie d'agents.
5. Sélectionnez Agent Assistant hypothécaire et commencez à discuter.

Essayez les mêmes requêtes que dans l'atelier de programmation Agent Runtime :

Prompt initial :

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Question complémentaire :

Can you send a summary of this to my email [e-mail]

Si vous revenez à la section "Déploiement de l'agent" de la console, sélectionnez le déploiement de notre agent et accédez à l'onglet "Traces". Vous verrez alors l'agent Gemini Assistant dans la portée indiquant que l'appel provient de Gemini Enterprise.

17. Dépannage et solutions courantes

• terraform apply échoue sur la passerelle d'agent avec le message "la ressource est en cours de création et ne peut donc pas être mise à jour" : le projet locataire de la passerelle prend environ 30 secondes à s'établir avant que les règles d'autorisation puissent être associées. Le module time_sleep.wait_for_gateway s'en charge. Il vous suffit de réexécuter terraform apply.
• L'agent indique "aucun serveur MCP trouvé" ou démarre avec des outils utilitaires uniquement : vérifiez enable_agent_registry_endpoints = true dans terraform.tfvars, puis :

  gcloud alpha agent-registry mcp-servers list \
    --project=${PROJECT_ID} --location=${REGION}
  

  Vous devriez voir trois entrées (une par service Cloud Run MCP). Si la liste est vide, vérifiez que les services MCP sont accessibles depuis le VPC et que la passerelle d'agent a rempli le registre (elle le fait de manière différée lors de la première liste d'outils proxy).
• Les appels d'outils renvoient l'erreur 403 PermissionDenied : réexécutez scripts/grant_agent_mcp_egress.sh. La cause la plus fréquente est l'oubli de réaccorder l'accès après le redéploiement de l'agent (le reasoningEngines/ change à chaque déploiement).
• skaffold run échoue avec le message "Autorisation refusée pour le compte de service" : il vous manque roles/iam.serviceAccountUser. Réexécutez l'auto-attribution de l'étape précédente.
• Erreurs d'appairage DNS de l'Agent Gateway au MCP LB : vérifiez que agent_gateway_dns_peering_config.target_network correspond exactement à projects/${PROJECT_ID}/global/networks/${VPC_NAME} et que chaque entrée domains se termine par un point.
• terraform plan continue de vouloir mettre à jour les tags d'image Cloud Run : cela ne devrait pas se produire en raison de la règle lifecycle { ignore_changes }. Si c'est le cas, vérifiez que vous n'avez pas modifié mcp_services[*].image dans terraform.tfvars après skaffold run.

18. Effectuer un nettoyage

Le moteur de raisonnement n'est pas géré par Terraform (il est créé par le SDK ADK). Supprimez-le manuellement :

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Supprimez tout ce que Terraform a créé :

cd terraform
terraform destroy
cd ..

Si vous avez créé la zone DNS publique uniquement pour cet atelier de programmation :

gcloud dns managed-zones delete agw-example-com

Enfin, supprimez le bucket d'état Terraform :

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. Félicitations

Félicitations ! Vous avez réussi à implémenter une gouvernance complète des agents pour un agent ADK multi-outils à l'aide d'Agent Gateway. En agissant comme plan de contrôle réseau centralisé, Agent Gateway vous permettait d'établir un chemin de sortie sécurisé vers des outils privés, d'appliquer des règles IAM précises basées sur l'identité via Identity-Aware Proxy et d'assainir les interactions de contenu à l'aide de consignes Model Armor intégrées.

Connaissances acquises

• Découvrez comment déployer et configurer la passerelle d'agent en tant que couche de gouvernance centrale pour le trafic de sortie Agent-to-Anywhere.
• Comment intégrer Agent Registry pour la découverte d'outils d'exécution dynamiques et régis.
• Découvrez comment rédiger et appliquer des stratégies IAM par outil et basées sur des conditions pour contrôler strictement les chemins d'exécution des agents.
• Découvrez comment utiliser les extensions de service Agent Gateway pour appliquer les règles Model Armor, en interceptant et en masquant automatiquement le trafic d'agent sensible.

Documents de référence

• Présentation des règles de gouvernance des agents
• Documentation Agent Gateway
• Documentation sur l'identité de l'agent
• Présentation de Gemini Enterprise Agent Platform