Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Sortie de la passerelle d'agent depuis Agent Runtime vers le réseau VPC

1. Introduction

Cet atelier de programmation explore la gouvernance de sortie Agent Gateway pour les agents d'IA accédant à des points de terminaison distants via un réseau VPC privé. La passerelle d'agent fonctionnant en mode sortie (agent-to-anywhere) est compatible avec la connectivité privée à un réseau VPC à l'aide d'interfaces Private Service Connect (PSC). Dans ce scénario, Agent Runtime utilise Agent Gateway pour accéder à un serveur MCP HTTP transmissible distant hébergé sur Cloud Run à l'aide d'un point de terminaison Private Service Connect (PSC) pour les API Google dans le réseau VPC.

Les applications d'IA, qu'il s'agisse de chatbots autonomes ou de systèmes autonomes avec des workflows multi-agents, peuvent appeler des outils externes de manière dynamique. Il est essentiel de fournir aux agents un accès contrôlé pour interroger des bases de données, récupérer du contenu Web et exécuter des actions afin de garantir leur sécurité et leur productivité. Toutefois, dans les environnements d'entreprise, la sécurisation de l'exécution des outils d'agent est un défi. Si un agent dispose d'un accès direct au réseau, les attaques par injection de requêtes ou les hallucinations du modèle peuvent l'amener à exfiltrer des données sensibles ou à exécuter des commandes destructrices.

Pour gérer les agents autonomes à grande échelle, Agent Gateway fournit un point d'application centralisé et zéro confiance directement intégré à l'architecture Agent Platform. Au lieu de s'appuyer sur des implémentations personnalisées propres à chaque application ou code d'agent, Agent Gateway fournit un routage réseau, une gouvernance des agents et une sécurité d'exécution appliqués au niveau de la plate-forme.

Lorsque la passerelle d'agent fonctionne en mode sortie (agent-to-anywhere), elle sert de proxy pour toutes les requêtes sortantes des agents configurés pour utiliser la passerelle. Chaque demande de charge de travail de l'agent est authentifiée à l'aide de l'identité de l'agent unique et autorisée à l'aide des règles Identity-Aware Proxy (IAP). Les appels d'outil MCP sont décodés et inspectés de manière dynamique pour faire respecter les règles. Les administrateurs de sécurité peuvent appliquer de manière centralisée des autorisations précises pour s'assurer que les agents ne peuvent appeler que les points de terminaison et les méthodes approuvés.

Objectif de l'atelier

Passerelle d'agent en mode sortie (agent-to-anywhere)
Extension d'autorisation Identity-Aware Proxy (IAP)
Agent ADK Agent Runtime avec identité d'agent
Serveur MCP HTTP diffusable Cloud Run
Agent Registry avec l'API Google et des points de terminaison MCP personnalisés
Stratégies d'autorisation avec le contrôle des accès IAM
Ressources de réseau VPC, zone Cloud DNS et point de terminaison PSC pour les API Google
Rattachement de réseau PSC pour la sortie de la passerelle d'agent
Règles de stratégie de pare-feu Cloud Next Generation Firewall (NGFW)

Fig. 1. Architecture de l'atelier de programmation

Objectifs

Déployer la passerelle d'agent dans une séquence de configuration structurée
Configurer Agent Gateway avec une connectivité réseau VPC privé
Passer des règles d'autorisation du mode dry run au mode appliqué
Enregistrer des points de terminaison d'API Google et des serveurs MCP dans Agent Registry
Auditer les journaux Agent Gateway pour valider la gouvernance de sortie
Valider le trafic de sortie Agent Gateway à l'aide des journaux Cloud NGFW

Ce dont vous avez besoin

Un projet Google Cloud avec facturation activée
Autorisations IAM pour provisionner des services réseau, des ensembles de données BigQuery et des ressources de la plate-forme d'agents
Un shell compatible POSIX (bash ou zsh) avec Google Cloud CLI (composants gcloud et bq) installé
Outils de ligne de commande : git, curl, jq (processeur JSON), Python 3 et uv (gestionnaire de packages Python)

2. Concepts

Séquence de déploiement

Cet atelier de programmation suit une séquence de configuration structurée afin que les agents aient accès aux ressources nécessaires lors de l'initialisation et que la connectivité puisse être confirmée avant l'application des règles d'accès appliquées.

Cet atelier de programmation utilise la séquence de déploiement suivante :

Démarrer en mode DRY_RUN : assurez-vous que les requêtes de l'agent arrivent bien à la passerelle et qu'elles la traversent (mode audit uniquement).
Enregistrez tous les services : enregistrez tous les composants agentiques dans le registre d'agents et confirmez l'accès aux outils de l'agent. Utilisez Cloud Logging et le tableau de bord d'observabilité de la passerelle d'agent pour afficher les requêtes envoyées à Agent Registry.
Créez des règles d'autorisation : créez et appliquez des règles d'autorisation pour autoriser le trafic sortant des agents vers les serveurs et points de terminaison MCP.
Passez au mode ENFORCED : mettez à jour la règle d'extension d'autorisation pour appliquer les règles et bloquer le trafic de sortie non autorisé.

Fig. 2. Séquence de déploiement

Topologie de routage de sortie

La sortie Agent Gateway (agent-to-anywhere) sert de proxy sortant centralisé et zéro confiance pour les charges de travail agentiques. Lorsqu'un agent envoie une requête à un outil ou une API externes, la requête sortante est interceptée par Agent Gateway et évaluée par rapport aux règles de gouvernance avant d'être acheminée vers sa destination. Dans une architecture Google Cloud Agent Platform, Agent Gateway fournit une connectivité au plan de données pour :

Réseaux privés (VPC) : trafic sortant ciblant les API, les microservices et les bases de données d'entreprise internes hébergés dans des VPC privés, ainsi que les réseaux sur site ou multicloud accessibles via une connectivité hybride.
Réseaux externes (Internet) : trafic sortant ciblant des services Web tiers, des API SaaS ou des points de terminaison publics.
Services d'IA et plate-forme d'agents : trafic sortant ciblant les API Google Cloud gérées, les modèles de base, les points de terminaison Google MCP (tels que BigQuery) et les services de gouvernance de la plate-forme (Agent Registry et les règles IAP).

Fig. 3. Topologie de routage de sortie Agent Gateway

Cet atelier de programmation se concentre sur le trafic sortant d'un agent personnalisé sur Agent Runtime ciblant un point de terminaison PSC pour les API Google déployé dans un réseau VPC. Cette architecture permet un accès privé au serveur MCP hébergé sur Cloud Run à l'aide de l'association de réseau PSC pour la sortie Agent Gateway.

Connectivité VPC

La sortie Agent Gateway (agent-to-anywhere) peut se connecter à un réseau VPC en spécifiant networkConfig: egress: networkAttachment: [URI] dans le fichier de configuration YAML du déploiement. Ce paramètre configure des règles de routage sur Agent Gateway pour envoyer le trafic qui est résolu en adresses IP privées via la pièce jointe réseau PSC dans le réseau VPC.

Fig. 4. Connectivité VPC de la passerelle d'agent

Agent Gateway peut résoudre les noms d'hôte DNS privés à l'aide de l'appairage Cloud DNS vers un projet cible et un réseau VPC spécifiés. Toutes les zones privées listées dans la configuration dnsPeeringConfig: domains: [NAME] utiliseront les enregistrements Cloud DNS dans le projet cible. Toutes les autres requêtes DNS utiliseront le résolveur public Cloud DNS VPC par défaut.

La partie sur les concepts est terminée. Passons à la section Configuration.

3. Configuration

Rôles IAM requis

Les rôles suivants sont requis pour créer les ressources dans cet atelier de programmation :

Catégorie	Rôle IAM requis (ID)	Description
Gestion des API	`roles/serviceusage.serviceUsageAdmin`	Activer les services d'API Google Cloud
Mise en réseau et passerelle	`roles/networkservices.admin`	Provisionner une passerelle d'agent
Extensions de service	`roles/serviceextensions.admin`	Configurer les extensions de routage
Sécurité du réseau	`roles/networksecurity.admin`	Déployer des règles d'autorisation
Agent Registry	`roles/agentregistry.admin`	Hôtes autorisés du catalogue
Vertex AI et les agents	`roles/aiplatform.admin`	Déployer des charges de travail Agent Runtime
Règles de sortie	`roles/iap.admin`	Appliquer les règles `roles/iap.egressor`
Cloud Storage	`roles/storage.admin`	Gérer les buckets de préproduction des déploiements
Journaux et audit	`roles/logging.viewer`	Inspecter les traces et les journaux d'audit
Développeur Cloud Run	`roles/run.developer`	Déployer des services Cloud Run
Lecteur Artifact Registry	`roles/artifactregistry.reader`	Extraire des images de conteneurs
Administrateur de réseaux Compute	`roles/compute.networkAdmin`	Gérer les ressources réseau VPC
Administrateur DNS	`roles/dns.admin`	Gérer les zones et les enregistrements Cloud DNS

Vous pouvez également utiliser un rôle de base étendu, comme roles/admin, ou un rôle hérité, comme roles/owner.

Accéder à votre projet

Cet atelier de programmation utilise un seul projet Google Cloud. Les étapes de configuration utilisent la CLI gcloud et les commandes du shell Linux.

Commencez par accéder à la ligne de commande de votre projet Google Cloud :

Cloud Shell à l'adresse shell.cloud.google.com, ou
Un terminal local avec gcloud CLI installé

Définir votre ID de projet

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Authentifier la session

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Définir des variables d'environnement de shell

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Mettre à jour `gcloud cli` (recommandé)

Si vous exécutez une installation autogérée du SDK Google Cloud (c'est-à-dire en dehors de Cloud Shell), mettez à jour les composants vers la dernière version.

# update gcloud cli
gcloud components update

Activer les services d'API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

La partie concernant la configuration est terminée. Passons à la section Réseau.

4. Réseau

Le réseau VPC est déployé en mode personnalisé pour créer des sous-réseaux standards compatibles avec l'association réseau PSC pour Agent Gateway et la sortie VPC directe Cloud Run.

Le point de terminaison PSC pour les API Google est déployé à l'aide d'une seule /32adresse IPv4 interne globale pour permettre un accès interne privé à Cloud Run. Cette adresse IP n'est attribuée à aucun sous-réseau régional.

Créer des réseaux

Créez un réseau VPC mondial.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Créez des sous-réseaux pour le rattachement de réseau PSC de la passerelle d'agent et la sortie VPC directe Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Créer des règles de pare-feu

Créez une règle et une stratégie de pare-feu pour autoriser tout le trafic sortant avec la journalisation activée. Il servira à surveiller le trafic sortant de la passerelle d'agent vers le réseau VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

Créer un rattachement de réseau PSC

Créez un rattachement de réseau PSC configuré pour accepter automatiquement les nouvelles connexions de producteurs.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

Vérifier le rattachement de réseau PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Créer un point de terminaison PSC

Créez une réservation d'adresse IP pour le point de terminaison PSC mondial. L'adresse utilisée ici ne peut pas provenir d'un sous-réseau existant ni le chevaucher.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Créez un point de terminaison PSC pour les API Google à l'aide du bundle all-apis, qui inclut Cloud Run (run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

Valider le point de terminaison PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

Créer une zone et des enregistrements DNS

Créez une zone gérée Cloud DNS privée pour le domaine run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Créez un enregistrement DNS générique A pour *.run.app. pointant vers l'adresse IP du point de terminaison PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Créez une règle Cloud DNS pour activer la journalisation des requêtes DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Créer Cloud NAT

Créez un routeur Cloud et Cloud NAT pour prendre en charge la sortie VPC directe de Cloud Run afin que le serveur MCP puisse accéder aux données météorologiques externes via le réseau VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

La partie concernant le réseau est terminée. Passons à la section Passerelle.

5. Passerelle

Avant d'appliquer des contrôles d'accès, déployez Agent Gateway et configurez l'extension d'autorisation en mode DRY_RUN. Cela permet aux appels d'outils sortants de réussir tout en enregistrant les résultats de l'évaluation à des fins d'audit.

Ici, Agent Gateway utilise un registre régional pour prendre en charge les ressources Agent Runtime régionales et spécifie les champs networkConfig pour la configuration de l'appairage DNS et du rattachement de réseau PSC au réseau VPC.

Créer une passerelle

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

Valider la passerelle

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Vérifiez qu'il existe un point de terminaison de connexion accepté.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

La partie concernant la passerelle est terminée. Passons à la section Autorisation.

6. Autorisation

L'extension d'autorisation Agent Gateway pour Identity-Aware Proxy (IAP) est un type d'extension de service utilisé pour déléguer les décisions d'autorisation pour toutes les communications de la plate-forme d'agent.

Flux de délégation : lorsqu'un agent tente d'appeler un point de terminaison externe ou un serveur MCP, il achemine la requête vers la passerelle d'agent. Au lieu d'évaluer l'accès localement, la passerelle utilise l'extension d'autorisation pour envoyer un callout au service d'évaluation IAP. IAP évalue l'identité de l'agent (basée sur SPIFFE) par rapport à la stratégie IAM de la ressource cible dans le registre des agents. IAP renvoie une décision ALLOW ou DENY à la passerelle, qui transfère le trafic ou le bloque avec un code d'état HTTP 403 Forbidden.
Modes d'application : en mode DRY_RUN, IAP évalue les requêtes et consigne les décisions dans Cloud Logging sans bloquer le trafic. En mode ENFORCE, toute requête provenant d'un agent non autorisé ou envoyée à une cible non enregistrée est immédiatement bloquée.
Couche de liaison : l'extension de service est connectée à Agent Gateway à l'aide d'une règle d'autorisation configurée avec le profil REQUEST_AUTHZ.

Extension d'autorisation

Une extension d'autorisation spécifie le service de fournisseur de sécurité avec les paramètres de connectivité et d'autres paramètres qui définissent le fonctionnement du service et son intégration à Agent Gateway.

Créer une extension d'autorisation

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

Importer une extension d'autorisation

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

Valider l'extension d'autorisation

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Règle d'autorisation

Une règle d'autorisation lie le fournisseur de sécurité (IAP) à la ressource de passerelle cible et spécifie le profil d'interception (REQUEST_AUTHZ).

Créer une règle d'autorisation

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

Lier une règle d'autorisation

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Valider la règle d'autorisation

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

La partie concernant l'autorisation est terminée. Passons à la section Codebase.

7. Codebase

L'agent, le serveur MCP et le code d'enregistrement du point de terminaison utilisés pour cet atelier de programmation sont gérés dans un dépôt GitHub Google Cloud distant. Les étapes suivantes cloneront le dépôt en local, copieront les fichiers nécessaires dans la structure du répertoire de travail actuel, puis supprimeront les fichiers temporaires.

Un bucket de préproduction de stockage est créé pour que l'environnement d'exécution de l'agent puisse importer, compiler et déployer le code d'application de l'agent empaqueté et ses artefacts de dépendance.

Récupérer des artefacts distants

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

Créer un bucket de préproduction

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

La partie concernant le codebase est terminée. Passons à la section Registre.

8. Registre

Agent Registry est un inventaire centralisé de tous les agents, serveurs MCP et points de terminaison (API) de l'écosystème d'IA. Il s'agit également d'un catalogue qui peut être utilisé pour lister, rechercher et découvrir d'autres outils et services enregistrés pour une utilisation par les applications d'IA. Agent Gateway utilise le modèle de données du registre comme framework de gouvernance pour appliquer le contrôle des accès sortants. Les attributions de rôle IAM pour les agents appelants principaux sont vérifiées par rapport à la stratégie liée à la ressource de registre.

Pour amorcer l'environnement et prendre en charge l'agent à l'aide de divers services et API Google, créez un service de point de terminaison de registre unique qui regroupe les interfaces d'API de base nécessaires pour cet atelier. Cela facilitera la gestion des règles de gouvernance pour les ensembles d'outils courants que la plupart des agents utiliseront.

Enregistrer des points de terminaison

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Vérifier l'enregistrement du point de terminaison

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

La partie concernant le registre est terminée. Passons à la section Serveur MCP.

9. Serveur MCP

Accorder des autorisations IAM pour le déploiement

Accordez des autorisations au compte de service Compute par défaut pour permettre le déploiement de services Cloud Run à partir du code source.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Vérifier les autorisations IAM

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Déployer le serveur MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

Accorder des autorisations IAM pour l'entrée

Règle d'association pour l'accès utilisateur

Accordez des autorisations au compte utilisateur (vous-même) pour appeler le serveur MCP hébergé Cloud Run. Cette option est nécessaire pour exécuter le script de génération toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

Vérifier les autorisations IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Créer un SA personnalisé pour l'invocation MCP

Créez un compte de service personnalisé pour appeler le serveur MCP hébergé sur Cloud Run. Ce compte de service sera utilisé par l'agent pour récupérer un jeton d'ID OIDC signé par Google et valide afin d'accéder à Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Lier une stratégie pour un compte de service

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

Vérifier les autorisations IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Accorder des autorisations IAM pour l'authentification

Attribuez des rôles d'usurpation d'identité de compte de service au compte de service Compute par défaut. Cela permettra à l'agent, exécuté sous les identifiants par défaut de l'application (ADC), de générer des jetons d'identité OIDC signés par Google au nom du compte de service de l'invocateur personnalisé pour authentifier les appels à Cloud Run.

Règle d'association pour l'authentification

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

Vérifier les autorisations IAM

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Créer un MCP `toolspec`

Lors de l'enregistrement manuel d'un serveur MCP, un fichier de spécification d'outil doit être inclus. Un fichier toolspec.json liste tous les outils mis à disposition par le serveur MCP et permet aux autres utilisateurs de les découvrir une fois enregistrés.

Le script test_mcp.py, inclus dans la base de code mcp-weather/, génère un fichier toolspec.json en se connectant au serveur MCP cible (via SSE ou HTTP) et en appelant list_tools() pour récupérer tous les outils disponibles exposés par le serveur.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Un examen de la sortie toolspec générée montre les attributs MCP que l'Agent Gateway peut utiliser pour l'évaluation et l'application des règles de sortie.

Valider le MCP `toolspec`

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Mettre à jour l'entrée Cloud Run

Modifiez le paramètre d'entrée du service Cloud Run afin qu'il n'accepte que les requêtes entrantes provenant du réseau VPC. Cela empêche l'accès public direct au point de terminaison MCP et n'autorise que les ressources internes à y accéder. Le trafic destiné au point de terminaison PSC des API Google dans le réseau VPC sera considéré comme un trafic entrant interne et sera autorisé.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Vérifier l'entrée Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

Enregistrer un serveur MCP

Maintenant que vous avez le toolspec, enregistrez le serveur MCP auprès de l'Agent Registry régional.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

Vérifier l'enregistrement MCP

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

La section sur le serveur MCP est terminée. Passons à la section sur l'agent ADK.

10. Agent ADK

L'agent ADK agent-weather déployé sur Agent Runtime est configuré avec les paramètres suivants dans le script de déploiement pour s'intégrer à Agent Platform :

"identity_type": types.IdentityType.AGENT_IDENTITY pour provisionner une identité principale basée sur SPIFFE unique pour l'agent
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } pour rediriger tout le trafic sortant initié par l'agent vers Agent Gateway afin d'évaluer et d'appliquer les règles

L'agent est également configuré pour utiliser le serveur MCP en transmettant l'URL et le compte de service pour récupérer le jeton d'identité OIDC.

Déployer l'agent

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Vérifier le déploiement

Récupérer les constantes vitales du déploiement

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Vérifier l'entrée de registre

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

Vérifier la configuration de la passerelle

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Accorder des autorisations IAM pour l'authentification

Lorsqu'un agent est configuré pour utiliser Agent Identity, il reçoit un jeton (au format JWT-SVID) du service STS (Security Token Service) fédéré, signé par sts.googleapis.com (le fournisseur d'identité SPIFFE).

Toutefois, la vérification intégrée de l'invocateur IAM Cloud Run ne fait confiance qu'aux jetons d'ID OIDC standards signés par l'émetteur OIDC Google principal (accounts.google.com) et ne peut vérifier que ces jetons.

Un compte de service personnalisé est donc utilisé pour échanger le jeton STS fédéré (JWT-SVID) obtenu par l'identité de l'agent contre un jeton Google (OIDC) standard obtenu à l'aide de l'emprunt d'identité du compte de service au moment de l'exécution.

Créez les liaisons de rôle nécessaires pour le compte de service personnalisé.

Règle d'association pour l'authentification (usurpation d'identité)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

Vérifier les autorisations IAM

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Accorder des autorisations IAM pour l'exécution

Accorder des autorisations IAM pour l'exécution permet à l'agent d'accéder aux services AI Platform et à d'autres API et services Google principaux à l'aide de son identité d'agent principal basée sur SPIFFE. Ces règles sont appliquées à l'aide d'IAM au niveau de la ressource.

Créez les liaisons de rôle nécessaires pour l'identité de l'agent.

Associer des règles pour l'accès des agents

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Vérifier les autorisations IAM

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

La partie concernant l'agent ADK est terminée. Passons à la section Règles.

11. Règles

Les règles d'autorisation de gouvernance des agents permettent au trafic d'être acheminé depuis un agent d'IA via la passerelle d'agent jusqu'à la destination finale de la ressource (par exemple, un point de terminaison de serveur MCP privé pour la récupération de données). Une fois le trafic arrivé à destination, les autorisations standards au niveau du service ou de l'application autorisent l'accès aux données.

L'attribution de rôles IAM pour la sortie de la passerelle d'agent permet d'accéder aux stratégies d'accès qui autorisent l'identité principale de l'agent à accéder aux ressources de destination enregistrées via la passerelle d'agent. Les stratégies sont appliquées au niveau de la passerelle d'agent et validées à l'aide des stratégies IAM Identity-Aware Proxy (IAP).

Attribuer des rôles IAM pour la sortie Agent Gateway

Agent Gateway vérifie les requêtes entrantes pour valider que l'identité de l'agent appelant dispose de l'autorisation iap.webServiceVersions.egressViaIAP (accordée par le rôle roles/iap.egressor) sur la ressource cible.

L'attribution de roles/iap.egressor à l'identité de l'agent ou à l'ensemble de comptes principaux Agent Runtime sur la ressource de destination sélectionnée autorise ce trafic de sortie. Dans cet atelier de programmation, le rôle est appliqué au compte principal agent, ce qui accorde l'autorisation à l'identité d'agent Agent Runtime spécifique.

Les stratégies IAM sont liées aux ressources de destination, comme défini dans le modèle de données du registre d'agents. La ressource iap_web/agentRegistry représente un niveau "à l'échelle du registre" dans la hiérarchie IAM. Où agentRegistry sert de parent aux ressources enfants individuelles pour agents, mcpServers et endpoints. Dans cet atelier de programmation, la stratégie IAM est liée aux niveaux mcpServer et endpoint, ce qui applique l'autorisation aux ressources enfants spécifiques.

Configurer la règle de l'agent pour le serveur MCP

Créer une règle pour l'agent sur le serveur MCP

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

REMARQUE : etag: doit renvoyer la valeur par défaut ACAB, car aucune règle n'a encore été définie.

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

Stratégie de liaison de l'agent au serveur MCP

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

Vérifier les autorisations IAM

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

La partie sur les règles est terminée. Passons à la section Audit.

12. Audit

L'extension d'autorisation de la passerelle d'agent fonctionne en mode DRY_RUN. Les requêtes sortantes sont observées et consignées, mais pas bloquées. L'analyse des journaux avant de passer en mode ENFORCED permet de confirmer les stratégies à configurer pour autoriser le trafic souhaité.

Tester les requêtes de l'agent

Ouvrez une fenêtre de navigateur dans l'interface utilisateur de la console Google Cloud et accédez à :

Agent Platform → Agents → Déploiements → agent-weather
Sélectionnez l'onglet Terrain de jeu.

Vous pouvez également faire écho à cette commande de terminal et cliquer sur le lien pour accéder au bac à sable de l'agent :

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Envoyez quelques requêtes de test…

What is the weather like in London?
How warm is it in New York?

Vérifiez que les requêtes renvoient des réponses valides.

Analyser les journaux d'audit

Affichez les journaux et inspectez les évaluations des règles de simulation.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Configurer la stratégie de l'agent pour les points de terminaison

Étant donné que les API Google de base pour agent-weather ont été enregistrées sous un service de point de terminaison collectif dans le registre (gapi.core.services), une seule règle est nécessaire pour accorder des autorisations de sortie d'agent pour l'accès aux points de terminaison.

Créer une règle pour l'agent vers le point de terminaison

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Lier une règle pour l'agent au point de terminaison

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

Vérifier les autorisations IAM

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

La partie concernant l'audit est terminée. Passons à la section Appliquer.

13. Appliquer

L'agent a pu effectuer des requêtes avec succès via la passerelle en mode DRY_RUN. Les journaux d'accès et les points de terminaison ont été analysés pour créer un ensemble de règles de gouvernance autorisant le trafic de sortie nécessaire à l'agent. Passez maintenant l'extension d'autorisation IAP de la passerelle d'agent en mode ENFORCE en mettant à jour la règle d'autorisation.

Mettre à jour l'extension d'autorisation

Créer une extension d'autorisation

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

Importer une extension d'autorisation

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

Valider l'extension d'autorisation

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Mettre à jour une règle d'autorisation

Créer une règle d'autorisation

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

Lier une règle d'autorisation

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Valider la règle d'autorisation

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Vérifier l'application des règles

Revenez au bac à sable de l'agent dans l'interface utilisateur de la console.

Cliquez sur le bouton + Nouvelle session pour créer une session de chat.

Envoyez une requête de test supplémentaire…

What is the current temperature in Los Angeles?

Notez que les requêtes de l'agent envoyées au modèle de base Gemini (${REGION}-aiplatform.googleapis.com/...) et au point de terminaison du serveur MCP (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) sont transmises avec les codes d'état HTTP 200 OK.

Analyser les journaux de passerelle

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Vérifiez qu'aucune requête n'est bloquée. Recherchez les tentatives de sortie refusées avec des codes d'état HTTP 403 Forbidden dans les journaux d'audit de la passerelle.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Affichez les journaux MCP de la passerelle d'agent et notez comment la charge utile de l'application MCP (JSON-RPC) est inspectée pour exposer les métadonnées du protocole, y compris les outils exécutés.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Analyser les journaux de pare-feu

Affichez les journaux pour la priorité 1001 des règles de stratégie de pare-feu réseau.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Notez la vue au niveau du réseau des différents chemins de trafic :

Passerelle d'agent communiquant avec les ressources du réseau VPC interne à l'aide de subnet-${REGION}-agw
Serveur MCP hébergé sur Cloud Run appelant des API météo externes à l'aide de subnet-${REGION}-crun

TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

Analyser les journaux DNS

Affichez les journaux des requêtes DNS pour les requêtes résolues par la zone DNS privée (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Notez que les recherches DNS pour le service Cloud Run (mcp-weather...run.app) proviennent du réseau VPC à l'aide de l'appairage DNS et sont résolues avec succès au point de terminaison PSC interne pour les API Google (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

La partie sur l'application des règles est terminée. Passons à la section Nettoyage.

14. Nettoyage

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

La partie nettoyage est terminée. Passons à la conclusion !

15. Conclusion

Félicitations ! Vous avez réussi à déployer Agent Gateway et à régir le trafic sortant des agents d'IA.

cosmopup

Cosmopup pense que les ateliers de programmation sont géniaux !

Et ensuite ?

Consultez la documentation Gemini Enterprise Agent Platform pour découvrir les fonctionnalités avancées et les tutoriels.
Configurer les garde-fous Model Armor sur Agent Gateway pour renforcer la sécurité de l'IA
Découvrez les Règles de gouvernance sémantique pour appliquer les règles commerciales et la conformité aux requêtes en langage naturel.

N'hésitez pas à nous faire part de vos commentaires, questions ou corrections en utilisant ce formulaire.

Merci !

Sortie de la passerelle d'agent depuis Agent Runtime vers le réseau VPC

1. Introduction

Objectif de l'atelier

Objectifs

Ce dont vous avez besoin

2. Concepts

Séquence de déploiement

Topologie de routage de sortie

Connectivité VPC

3. Configuration

Rôles IAM requis

Accéder à votre projet

Définir votre ID de projet

Authentifier la session

Définir des variables d'environnement de shell

Mettre à jour gcloud cli (recommandé)

Activer les services d'API

4. Réseau

Créer des réseaux

Créer des règles de pare-feu

Créer un rattachement de réseau PSC

Vérifier le rattachement de réseau PSC

Créer un point de terminaison PSC

Valider le point de terminaison PSC

Créer une zone et des enregistrements DNS

Créer Cloud NAT

5. Passerelle

Créer une passerelle

Valider la passerelle

6. Autorisation

Extension d'autorisation

Créer une extension d'autorisation

Importer une extension d'autorisation

Valider l'extension d'autorisation

Règle d'autorisation

Créer une règle d'autorisation

Lier une règle d'autorisation

Valider la règle d'autorisation

7. Codebase

Récupérer des artefacts distants

Créer un bucket de préproduction

8. Registre

Enregistrer des points de terminaison

Vérifier l'enregistrement du point de terminaison

9. Serveur MCP

Accorder des autorisations IAM pour le déploiement

Vérifier les autorisations IAM

Déployer le serveur MCP

Accorder des autorisations IAM pour l'entrée

Règle d'association pour l'accès utilisateur

Vérifier les autorisations IAM

Créer un SA personnalisé pour l'invocation MCP

Lier une stratégie pour un compte de service

Vérifier les autorisations IAM

Accorder des autorisations IAM pour l'authentification

Règle d'association pour l'authentification

Vérifier les autorisations IAM

Créer un MCP toolspec

Valider le MCP toolspec

Mettre à jour l'entrée Cloud Run

Vérifier l'entrée Cloud Run

Enregistrer un serveur MCP

Vérifier l'enregistrement MCP

10. Agent ADK

Déployer l'agent

Vérifier le déploiement

Récupérer les constantes vitales du déploiement

Vérifier l'entrée de registre

Vérifier la configuration de la passerelle

Accorder des autorisations IAM pour l'authentification

Règle d'association pour l'authentification (usurpation d'identité)

Vérifier les autorisations IAM

Accorder des autorisations IAM pour l'exécution

Associer des règles pour l'accès des agents

Vérifier les autorisations IAM

11. Règles

Attribuer des rôles IAM pour la sortie Agent Gateway

Configurer la règle de l'agent pour le serveur MCP

Créer une règle pour l'agent sur le serveur MCP

Stratégie de liaison de l'agent au serveur MCP

Mettre à jour `gcloud cli` (recommandé)

Créer un MCP `toolspec`

Valider le MCP `toolspec`