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

Sortie de l'Agent Gateway d'Agent Runtime vers Google MCP

1. Introduction

Cet atelier de programmation explore la gouvernance de sortie de Agent Gateway pour les agents d'IA qui accèdent à des serveurs MCP (Model Context Protocol) Google Cloud distants.

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 prompt 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 l'Agent Gateway 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 requête 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

Agent Gateway en mode sortie (agent-to-anywhere)
Extension d'autorisation Identity-Aware Proxy (IAP)
Agent ADK Agent Runtime avec identité d'agent
Agent Registry avec les points de terminaison de l'API Google et du MCP
Stratégies d'autorisation avec contrôle des accès IAM
Ensemble de données BigQuery à interroger à l'aide de MCP

Fig. 1. Architecture de l'atelier de programmation

Objectifs

Déployer la passerelle d'agent dans une séquence de configuration structurée
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

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 Agent Platform
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

Lorsque vous déployez Agent Gateway avec des contrôles de gouvernance, il est important de suivre une séquence de configuration structurée afin que les agents aient accès aux ressources nécessaires lors de l'initialisation et que les requêtes réseau aboutissent.

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

Démarrer en mode simulation : si un environnement d'exécution d'agent est configuré pour acheminer les appels sortants vers la passerelle avant que celle-ci ne soit entièrement provisionnée, la charge de travail ne pourra pas s'initialiser. La configuration de l'extension d'autorisation de la passerelle en mode DRY_RUN garantit qu'aucune requête n'est abandonnée lorsque le trafic de l'agent arrive à la passerelle.
Enregistrez tous les services : tous les agents, serveurs MCP et points de terminaison qui utilisent Agent Gateway doivent être enregistrés dans Agent Registry. Les requêtes sont refusées pour toute source ou destination non enregistrée. Les agents déployés sur Agent Runtime et les serveurs MCP Google sont automatiquement enregistrés. Tout point de terminaison d'API Google ou serveur MCP personnalisé doit être enregistré manuellement.
Appliquer les règles d'autorisation : les règles d'autorisation permettent aux agents enregistrés d'accéder aux composants agentiques en attribuant le rôle roles/iap.egressor au principal d'identité de l'agent et en l'associant à la ressource de registre cible. Évaluez le comportement de l'agent à l'aide du mode de simulation, puis définissez des règles pour autoriser le trafic de sortie choisi via la passerelle. Une fois les règles en place, passez au mode ENFORCED pour permettre à la passerelle d'appliquer activement les règles de gouvernance.

Fig. 2. Séquence de déploiement

Topologie de routage de sortie

Les passerelles gèrent généralement le trafic entrant (entrée) vers les services de backend. Agent Gateway, qui fonctionne en mode sortie (agent vers n'importe quelle destination), sert de proxy sortant centralisé et zéro confiance pour les charges de travail agentiques.

Lorsqu'une application d'IA ou une charge de travail agentique tente d'appeler 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 routée vers sa destination :

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 Agent Platform : 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 plate-forme (Agent Registry et les règles IAP).

Fig. 3. Topologie de routage de sortie Agent Gateway

Ce codelab se concentre sur le trafic sortant d'un agent personnalisé sur Agent Runtime ciblant le point de terminaison du serveur MCP Google distant pour BigQuery.

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 la 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`
BigQuery	`roles/bigquery.admin`	Configurer des schémas et des ensembles de données de test
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

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)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

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 \
  discoveryengine.googleapis.com

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

4. Passerelle

Avant d'appliquer des contrôles d'accès, déployez Agent Gateway et configurez son 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.

Créer une passerelle

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. 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 Agent Gateway. 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 adressé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

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

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

# show authz extension details (verify extension state)
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

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

# show authz policy details (verify dry run mode)
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.

6. Codebase

Le code de l'agent, l'ensemble de données BigQuery et le script d'enregistrement utilisés pour cet atelier de programmation sont conservé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 inutiles.

Un bucket de préproduction de stockage est créé pour qu'Agent Runtime 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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Créer un ensemble de données BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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.

7. 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 à utiliser par les applications d'IA. Le mode de sortie Agent Gateway (agent-to-anywhere) utilise le modèle de données du registre comme framework de gouvernance pour appliquer le contrôle des accès de sortie. 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.

Afin d'amorcer l'environnement et d'aider les agents à utiliser divers services et API Google, un script est utilisé pour enregistrer rapidement un ensemble commun de points de terminaison d'API à l'aide des noms d'hôte et des emplacements de endpoints/googleapis.txt.

Enregistrer des points de terminaison

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Valider les points de terminaison

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

La partie concernant le registre est terminée. Passons à la section Environnement d'exécution.

8. Environnement d'exécution

L'agent ADK agent-dj 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 unique basée sur SPIFFE 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

Déployer l'agent

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Vérifier l'entrée de registre

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

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Vérifier la configuration de la passerelle

# verify agent gateway routing specification
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}'

Attribuer des rôles IAM d'agent pour les ressources

Les autorisations de rôle IAM pour les ressources permettent à l'identité principale de l'agent d'accéder à BigQuery, aux outils MCP (pour les API Google) et à d'autres services AI Platform requis. Ces règles sont appliquées à l'aide d'IAM au niveau de la ressource.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# 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 rôles IAM de l'agent pour les ressources

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

La partie sur l'exécution est terminée. Passons à la section Règles.

9. Règles

Les règles d'autorisation de gouvernance des agents permettent au trafic d'un agent d'IA de transiter par Agent Gateway et d'atteindre la destination (par exemple, le point de terminaison du serveur MCP Google Cloud pour BigQuery). Une fois le trafic arrivé à destination, les autorisations IAM standards autorisent l'accès aux données (elles ont été activées dans la section précédente).

Les autorisations de rôle IAM pour la sortie de la passerelle d'agent permettent 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 l'Agent Gateway et validées à l'aide des stratégies IAM Identity-Aware Proxy (IAP).

Attribuer des rôles IAM d'agent pour la sortie Agent Gateway

Agent Gateway vérifie les requêtes entrantes pour s'assurer 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 principal set, qui accorde des autorisations à toutes les identités d'agent Agent Runtime du projet.

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 au niveau registry, ce qui applique l'autorisation à toutes les ressources enfants.

Configurer la stratégie IAM du registre régional IAP

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

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

10. Audit

L'extension d'autorisation de l'Agent Gateway fonctionne en mode DRY_RUN. Les requêtes sortantes sont observées et consignées, mais pas bloquées.

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-dj
Sélectionnez l'onglet Terrain de jeu.

Vous pouvez également exécuter cette commande de terminal et cliquer sur le lien pour accéder à l'atelier 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…

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

Vérifiez que les requêtes renvoient des réponses valides (par exemple, Il y a 12 DJ dans le fichier).

Analyser les journaux d'audit

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

# query gateway logs for dry run
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
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. Appliquer

L'agent a pu effectuer des requêtes avec succès via la passerelle en mode DRY_RUN. Faites passer l'extension d'autorisation IAP de l'Agent Gateway en mode ENFORCE en mettant à jour la règle d'autorisation.

Mettre à jour l'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

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

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

Mettre à jour 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

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

# 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 à l'atelier de l'agent dans l'interface utilisateur de la console.

Envoyez une requête de test supplémentaire…

What DJ Fishfry's credit card number?

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 (bigquery.googleapis.com/mcp) sont transmises avec les codes d'état HTTP 200 OK.

# 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
  )"

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

12. Nettoyage

# delete agent
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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "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 storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
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}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. Conclusion

Félicitations ! Vous avez réussi à déployer et à gérer les communications sortantes pour un agent accédant à des outils à l'aide d'Agent Gateway.

cosmopup

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

Que se passe-t-il 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 de commentaires.

Merci !