Gérer les agents avec Agent Gateway

Agent Gateway vous permet de gérer le trafic sortant des agents IA que vous créez et hébergez sur Cloud Run. En acheminant le trafic de sortie de votre service Cloud Run via une Agent Gateway autogérée qui s'exécute sur Secure Web Proxy, vous pouvez appliquer des règles d'accès centralisées, inspecter les charges utiles pour vérifier la sécurité du contenu et collecter des données de télémétrie d'observabilité sur vos charges de travail agentiques.

Ce document explique comment configurer une architecture centralisée pour Agent Gateway sur Cloud Run et aborde les points suivants :

Architecture

Dans un déploiement autogéré centralisé, Secure Web Proxy agit comme point d'application des règles et s'exécute dans votre réseau cloud privé virtuel (VPC). Le conteneur side-car de mise en réseau ambiante intercepte le trafic sortant de votre agent Cloud Run et l'achemine via la sortie VPC directe vers votre instance Secure Web Proxy. Secure Web Proxy applique des règles d'accès et de contenu à partir de points de décision de règles tels que Identity-Aware Proxy (IAP) et Model Armor.

Diagramme d'architecture montrant un service Cloud Run avec un conteneur d'agent et un conteneur de proxy side-car ambiant acheminant le trafic via la sortie VPC directe vers une Agent Gateway autogérée soutenue par Secure Web Proxy dans un réseau VPC.
Figure 1. Architecture d'Agent Gateway autogérée pour un agent Cloud Run.

Pour acheminer et gérer le trafic dans cette architecture, vous devez configurer les composants suivants :

  • Sortie VPC directe et mise en réseau ambiante : votre service Cloud Run se connecte à votre réseau VPC avec --vpc-egress=all et --ambient-networking, qui utilise le champ d'application régional par défaut et achemine tout le trafic sortant vers votre réseau VPC.
  • Agent Gateway autogérée : une ressource Agent Gateway logique en mode autogéré pointe vers l'instance Secure Web Proxy de votre réseau VPC.
  • Règle de routage de sortie : une règle EgressRouting de l'API Network Services dirige le trafic sortant de votre service Cloud Run vers votre instance Secure Web Proxy.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Activez l'API Cloud Run Admin, l'API Network Services, l'API Network Security, l'API Service Extensions, l'API Model Armor, l'API Certificate Authority Service, l'API Certificate Manager, l'API Cloud Resource Manager, l'API App Hub, l'API Identity and Access Management, l'API Identity-Aware Proxy, l'API Compute Engine, l'API Traffic Director, l'API Cloud DNS, l'API Network Connectivity et l'API Agent Registry, si elles ne sont pas déjà activées.

    Rôles requis pour activer les API

    Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  13. Créez un réseau VPC et un sous-réseau avec l'accès privé à Google activé sur le sous-réseau.
  14. Configurez Agent Registry dans votre projet ou votre organisation.
  15. Installez et initialisez la Google Cloud CLI.
  16. Mettez à jour les composants de gcloud CLI : 
    gcloud components update

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer Agent Gateway pour Cloud Run, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Si vous configurez un déploiement multiprojet avec un VPC partagé, demandez à votre administrateur de vous accorder le rôle roles/compute.xpnAdmin au niveau de l'organisation ou du dossier.

Créer une Agent Gateway autogérée

Avant de créer la ressource Agent Gateway, déployez et configurez une instance Secure Web Proxy dans votre réseau VPC, comme décrit dans Déployer Secure Web Proxy en tant qu'Agent Gateway :

  1. Configurez l'inspection TLS et créez une stratégie de sécurité de passerelle qui associe votre TlsInspectionPolicy. Vous n'avez pas besoin de règles de stratégie de sécurité ni de listes d'URL Secure Web Proxy.
  2. Créez une ressource ServerTlsPolicy avec allowOpen: false et mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. Ne définissez pas clientValidationTrustConfig.
  3. Déployez une instance Secure Web Proxy en mode de routage proxy explicite avec addresses, ports, certificateUrls, gatewaySecurityPolicy et serverTlsPolicy configurés lorsque vous créez la passerelle afin que Cloud Run transmette l'identité de charge de travail de votre agent à Secure Web Proxy et à IAP via mTLS.

Une fois votre instance Secure Web Proxy prête, créez une ressource Agent Gateway autogérée qui pointe vers votre instance Secure Web Proxy :

  1. Créez un fichier de configuration YAML nommé my-agent-gateway.yaml :

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    Remplacez les éléments suivants :

    • AGENT_GATEWAY_NAME : nom que vous souhaitez attribuer à votre ressource Agent Gateway.
    • PROJECT_ID : ID du projet qui héberge votre instance Secure Web Proxy.
    • REGION : région de votre instance Secure Web Proxy, par exemple us-central1.
    • SWP_NAME : nom de votre instance Secure Web Proxy.

  2. Importez la configuration de l'Agent Gateway :

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. Vérifiez votre ressource Agent Gateway :

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    Vérifiez que la sortie affiche votre configuration selfManaged et l'URI de ressource de votre instance Secure Web Proxy avant de passer à la section suivante.

Configurer la mise en réseau ambiante Cloud Run pour accéder à l'API Traffic Director

Lorsque vous configurez un service Cloud Run avec la sortie VPC directe et --vpc-egress=all, toutes les connexions sortantes de l'instance de conteneur sont acheminées via votre réseau VPC. Cela inclut la connexion du side-car Envoy à trafficdirector.REGION.rep.googleapis.com.

Pour permettre au side-car de résoudre et d'atteindre l'API Traffic Director, configurez une zone Cloud DNS privée dans votre réseau VPC selon que votre environnement utilise ou non VPC Service Controls :

Sans VPC Service Controls

Si votre projet n'utilise pas VPC Service Controls, créez une zone DNS privée Cloud DNS qui achemine les requêtes pour trafficdirector.REGION.rep.googleapis.com vers l'adresse IP de votre passerelle Secure Web Proxy afin que Secure Web Proxy laisse passer le trafic :

  1. Récupérez l'adresse IP interne de votre passerelle Secure Web Proxy :

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    Remplacez les éléments suivants :

    • SWP_NAME : nom de votre instance Secure Web Proxy.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région de votre déploiement.

  2. Créez une zone gérée Cloud DNS privée pour l'API Traffic Director :

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    Remplacez VPC_NETWORK_NAME par le nom de votre réseau VPC.

  3. Ajoutez un enregistrement A qui pointe le domaine régional de l'API Traffic Director vers l'adresse IP de votre Secure Web Proxy :

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. Vérifiez que le jeu d'enregistrements DNS est actif dans la zone privée :

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    Vérifiez que l'enregistrement A pour trafficdirector.REGION.rep.googleapis.com. correspond à l'adresse IP de votre proxy Web sécurisé.

Avec VPC Service Controls

Pour les environnements VPC Service Controls, provisionnez un point de terminaison régional Private Service Connect ciblant l'API Traffic Director régionale dans votre sous-réseau VPC et mappez le domaine à l'aide d'une zone Cloud DNS privée :

  1. Créez un point de terminaison régional Private Service Connect ciblant l'API Traffic Director régionale :

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • REGION : région de votre déploiement.
    • VPC_NETWORK_NAME : nom de votre réseau VPC.
    • VPC_SUBNET_NAME : nom de votre sous-réseau VPC.

  2. Récupérez l'adresse IP interne du point de terminaison régional :

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Créez une zone gérée Cloud DNS privée pour l'API Traffic Director :

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Ajoutez un enregistrement A résolvant le domaine régional de l'API Traffic Director vers l'adresse IP du point de terminaison régional :

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. Vérifiez votre point de terminaison régional et votre jeu d'enregistrements DNS :

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    Vérifiez que l'enregistrement A pour trafficdirector.REGION.rep.googleapis.com. pointe vers l'adresse IP du point de terminaison régional.

Déployer ou mettre à jour un service Cloud Run avec la mise en réseau ambiante et la sortie VPC directe

Pour connecter votre agent Cloud Run à l'instance Secure Web Proxy de votre réseau VPC, activez la sortie VPC directe et la mise en réseau ambiante régionale, puis configurez le service avec une identité d'agent. Lorsque vous déployez avec --functional-type=agent et --identity-type=agent-identity, Cloud Run accorde roles/run.agentDefaultAccess, qui inclut les autorisations roles/trafficdirector.client et roles/cloudtrace.agent :

  1. Déployez un nouveau service d'agent Cloud Run ou mettez à jour un service existant pour activer la mise en réseau ambiante régionale, la sortie VPC directe pour tout le trafic sortant et l'identité de l'agent :

    Nouveau service

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Service existant

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom de votre service d'agent Cloud Run.
    • IMAGE_URL : référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL respecte le format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • VPC_NETWORK_NAME : nom du réseau VPC qui héberge votre instance Secure Web Proxy. Pour en savoir plus sur la création d'un réseau et d'un sous-réseau VPC, consultez Créer et gérer des réseaux VPC.
    • VPC_SUBNET_NAME : nom du sous-réseau VPC où votre instance Secure Web Proxy est accessible.
    • REGION : région de votre service.
    • PROJECT_ID : ID de votre projet Google Cloud .

  2. Vérifiez que votre service Cloud Run utilise la mise en réseau ambiante, la sortie VPC directe et l'identité de l'agent :

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    Vérifiez que le résultat affiche le sous-réseau de sortie VPC directe, la sortie all-traffic, la mise en réseau ambiante régionale et le compte principal d'identité de l'agent attribué.

Configurer votre agent Cloud Run pour qu'il fasse confiance à Agent Gateway

Pour que Secure Web Proxy puisse inspecter les charges utiles HTTPS et appliquer des règles, il doit mettre fin aux sessions TLS sortantes de votre agent. Votre conteneur d'agent Cloud Run doit faire confiance au certificat de l'autorité de certification (CA) racine ou subordonnée associé à votre stratégie d'inspection TLS Secure Web Proxy dans CA Service ou à votre PKI d'entreprise privée :

  1. Exportez le certificat CA encodé au format PEM à partir du pool CA Service pour votre instance Secure Web Proxy :

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    Remplacez les éléments suivants :

    • CA_POOL_NAME : nom du pool d'autorités de certification associé à votre règle d'inspection TLS Secure Web Proxy.
    • REGION : région de votre pool d'autorités de certification.
    • PROJECT_ID : ID de votre projet Google Cloud .

  2. Mettez à jour votre service Cloud Run pour transmettre le contenu du certificat dans une variable d'environnement :

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom de votre service d'agent Cloud Run.
    • REGION : région de votre service.
    • PROJECT_ID : ID de votre projet Google Cloud .

    Par exemple, le script de point d'entrée de conteneur Debian ou Ubuntu suivant, entrypoint.sh, installe AGENT_GATEWAY_ROOT_CERT dans le magasin de confiance du système et exporte les chemins d'accès du bundle d'autorités de certification pour les clients Python et gRPC avant de démarrer votre application :

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. Vérifiez que votre service définit la variable d'environnement AGENT_GATEWAY_ROOT_CERT :

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

Acheminer le trafic sortant vers Agent Gateway

Après avoir configuré votre service Cloud Run et Agent Gateway, créez une règle d'API Network Services EgressRouting pour diriger le trafic sortant de votre service Cloud Run vers votre passerelle Secure Web Proxy :

  1. Créez la ressource EgressRouting :

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    Remplacez les éléments suivants :

    • REGION : région de votre service et de votre passerelle Cloud Run.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • SWP_NAME : nom de votre ressource Secure Web Proxy Gateway sous-jacente, et non de la ressource AgentGateway.
    • SERVICE_NAME : nom de votre service d'agent Cloud Run. Pour acheminer tous les services Cloud Run du projet via la passerelle avec une seule règle, définissez workloadUri sur //run.googleapis.com/projects/PROJECT_ID ou //run.googleapis.com/projects/PROJECT_NUMBER.

    Une fois que EgressRouting prend effet, tout le trafic sortant de votre service Cloud Run est acheminé via Secure Web Proxy. Configurez des règles dans la section suivante pour autoriser et régir les requêtes sortantes.

  2. Vérifiez que la ressource EgressRouting est active :

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    Vérifiez que sources liste l'URI de votre charge de travail Cloud Run et que gateway référence votre ressource de passerelle Secure Web Proxy.

Configurer des règles sur Agent Gateway

Après avoir acheminé le trafic de sortie via Agent Gateway, gérez les requêtes sortantes de votre agent en associant des règles d'autorisation et des liaisons d'extension Service Extensions à votre ressource Agent Gateway :

  • Filtrage du trafic de référence et des outils MCP : autorisez les points de terminaison de modèle ainsi que les méthodes et outils MCP (Model Context Protocol) approuvés à l'aide de règles d'autorisation ALLOW.
  • Contrôle des accès basé sur l'identité : associez IAP à une ressource ExtensionBinding et configurez une stratégie d'accès unifié IAM pour contrôler quels agents peuvent appeler des serveurs MCP, des outils ou des points de terminaison spécifiques.
  • Sécurité du contenu : associez Model Armor à une ressource ExtensionBinding pour inspecter et nettoyer les prompts et les réponses afin de détecter les injections de prompts, les fuites de données sensibles ou les cas de non-respect des règles.

Toutes les règles d'autorisation ou règles de stratégie de sécurité de passerelle associées à la ressource Secure Web Proxy Gateway sous-jacente sont ignorées. Une fois que vous avez créé ou mis à jour une ressource ExtensionBinding, la propagation des modifications vers la passerelle peut prendre jusqu'à cinq minutes. Pour connaître la séquence d'évaluation des règles réseau, de l'inspection TLS, des liaisons d'extension et des règles HTTP, consultez Ordre d'évaluation des règles d'autorisation.

Autoriser le trafic de référence sortant et MCP

Secure Web Proxy refuse par défaut tout le trafic sortant avec des erreurs 403 Forbidden jusqu'à ce qu'une AuthzPolicy ALLOW sur votre ressource Agent Gateway l'autorise.

Comme votre service Cloud Run utilise --vpc-egress=all, tout le trafic sortant du conteneur, y compris les appels d'outils MCP et les requêtes LLM, est acheminé via la passerelle. Associez des règles d'autorisation ALLOW à votre ressource Agent Gateway pour les deux types de trafic :

Configurer des règles de sortie IAP

Agent Gateway utilise IAP comme moteur de décision liée aux règles pour évaluer les Règles d'accès unifiées IAM. Pour appliquer des règles d'identité d'agent, définissez vos règles d'accès dans une stratégie d'accès unifiée IAM et associez IAP à votre passerelle :

  1. Créez une stratégie d'accès unifié IAM à l'aide du compte principal Identité de l'agent de votre service Cloud Run, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME, et liez la stratégie à votre projet ou à votre passerelle en suivant les instructions des sections Créer des stratégies d'accès IAM et Lier une stratégie d'accès unifié à un projet.
  2. Associez IAP (iap.googleapis.com) à votre Agent Gateway avec un ExtensionBinding en suivant les instructions de la section Associer IAP à votre Agent Gateway.

Étant donné que --vpc-egress=all envoie des appels de modèle tels que REGION-aiplatform.googleapis.com via la passerelle, limitez le champ d'application de matchConditions dans votre ExtensionBinding IAP à prefix: "urn:mcp" afin que les appels de modèle contournent l'évaluation IAP. Pour régir également le trafic entre agents, ajoutez prefix: "urn:agent". Si votre liaison d'extension correspond à d'autres hôtes, ajoutez une règle d'autorisation pour chaque hôte dans votre stratégie d'accès unifié IAM, par exemple destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. Pour obtenir un exemple, consultez Créer une règle d'agent vers un point de terminaison non enregistré.

Configurer des règles Model Armor

Pour inspecter et nettoyer les prompts et les réponses qui transitent par votre Agent Gateway, créez des modèles Model Armor et associez-les à votre Agent Gateway :

  1. Créez des modèles de requête et de réponse Model Armor régionaux, puis accordez les rôles requis à l'agent de service Service Extensions en suivant les instructions de la section Configurer Model Armor sur une passerelle.
  2. Associez vos modèles à votre Agent Gateway avec un ExtensionBinding en suivant les instructions de la section Associer Model Armor pour la désinfection des prompts et des réponses.

Configurer un déploiement inter-projets centralisé avec un VPC partagé

Dans une organisation multiprojet, vous pouvez déployer vos agents Cloud Run dans un ou plusieurs projets de service tout en hébergeant une instance Agent Gateway, une instance Secure Web Proxy et un Agent Registry dans un projet hôte de mise en réseau dédié à l'aide d'un VPC partagé :

  • Projet A, projet de service de l'agent : héberge le service de l'agent Cloud Run et la règle EgressRouting locale.
  • Projet B, projet hôte de la passerelle et de la mise en réseau : sert de projet hôte de VPC partagé et doit héberger l'Agent Gateway, l'instance Secure Web Proxy, l'Agent Registry, les ressources ExtensionBinding et les liaisons de stratégie IAM.
Diagramme de l'architecture interprojets montrant le projet A hébergeant un service Cloud Run et une règle de routage de sortie, connecté via un réseau VPC partagé au projet B hébergeant l'Agent Gateway, Secure Web Proxy et l'Agent Registry.
Figure 2. Déploiement d'Agent Gateway sur plusieurs projets à l'aide d'un VPC partagé.

Avant de commencer, activez run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com et trafficdirector.googleapis.com dans le projet A, ainsi que aiplatform.googleapis.com si votre agent appelle Vertex AI. Dans le projet B, déployez l'instance Secure Web Proxy et la ressource Agent Gateway sur le réseau VPC partagé, comme décrit dans Créer une Agent Gateway autogérée, et configurez le routage DNS ou Private Service Connect, comme décrit dans Configurer la mise en réseau ambiante Cloud Run pour accéder à l'API Traffic Director, afin que les side-cars ambiants du projet A puissent accéder à l'API Traffic Director.

Pour configurer un déploiement multiprojet, procédez comme suit :

  1. Configurez le projet B en tant que projet hôte de VPC partagé, associez le projet A en tant que projet de service et partagez le sous-réseau qui héberge votre instance Secure Web Proxy. L'activation du VPC partagé et l'association de projets de service nécessitent roles/compute.xpnAdmin au niveau de l'organisation ou du dossier. Pour obtenir des instructions, consultez Envoyer du trafic vers un réseau VPC partagé avec la sortie VPC directe et Provisionner un VPC partagé.

  2. Dans le projet B, accordez le rôle roles/compute.networkUser sur le sous-réseau partagé à l'agent de service Cloud Run du projet A :

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    Remplacez les éléments suivants :

    • SHARED_SUBNET_NAME : nom du sous-réseau partagé dans le projet B.
    • PROJECT_B_ID : ID du projet B, qui est le projet hôte de la passerelle et du VPC partagé.
    • REGION : région du sous-réseau partagé.
    • PROJECT_A_NUMBER : numéro du projet A, le projet de service de l'agent.

  3. Déployez le service d'agent Cloud Run dans le projet A en pointant vers le sous-réseau partagé du projet B :

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    Remplacez les éléments suivants :

    • SERVICE_NAME : nom de votre service d'agent Cloud Run dans le projet A.
    • PROJECT_A_ID : ID du projet A, le projet de service de l'agent.
    • IMAGE_URL : référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL respecte le format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

    Après avoir déployé le service, configurez votre agent dans le projet A pour qu'il approuve le certificat d'autorité de certification racine de l'instance Secure Web Proxy dans le projet B en suivant les étapes de la section Configurer votre agent Cloud Run pour qu'il approuve Agent Gateway.

  4. Créez une règle EgressRouting dans le projet A qui référence la passerelle Secure Web Proxy du projet B. Vous devez disposer de roles/networkservices.admin dans le projet A :

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    Remplacez CENTRAL_SWP_NAME par le nom de la passerelle Secure Web Proxy dans le projet B. Pour acheminer tous les services Cloud Run du projet A via la passerelle du projet B, définissez workloadUri sur //run.googleapis.com/projects/PROJECT_A_ID ou //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. Vérifiez que la ressource EgressRouting multiprojet est active dans le projet A :

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Configurez des règles de référence, IAP et Model Armor centralisées sur la ressource Agent Gateway du projet B, comme décrit dans Configurer des règles sur Agent Gateway :

    • Autorisez le trafic MCP et le trafic du modèle de référence sur la ressource Agent Gateway du projet B en suivant les instructions de la section Autoriser le trafic de sortie et le trafic MCP de référence.
    • Pour autoriser l'agent du projet A à appeler les serveurs MCP enregistrés dans le projet B, créez une stratégie d'accès unifié IAM dans le projet B dont la liste principals fait référence au numéro du projet A, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME, liez la stratégie au projet B ou à sa ressource Agent Gateway, puis associez l'IAP ExtensionBinding dans le projet B.
    • Pour appliquer des garde-fous Model Armor centralisés dans le projet B, créez vos modèles Model Armor régionaux, attribuez les rôles requis à l'agent de service des extensions de service du projet B, puis associez le ExtensionBinding Model Armor à la ressource Agent Gateway dans le projet B.

Afficher les journaux et les traces

Les interactions des agents sortants acheminées via Agent Gateway génèrent des journaux et des traces distribuées qui vous permettent de surveiller les décisions liées aux règles et de déboguer le comportement des agents :

Si les requêtes sortantes échouent ou contournent la passerelle, consultez Résoudre les problèmes liés à Agent Gateway.

Régions où le service est disponible

Vous pouvez utiliser Agent Gateway sur Cloud Run dans les régions suivantes :

  • europe-west1
  • us-central1

Limites

Outre les limites de la mise en réseau ambiante et les considérations liées à Secure Web Proxy dans Déployer Secure Web Proxy en tant qu'Agent Gateway, les limites suivantes s'appliquent lorsque vous utilisez Agent Gateway avec Cloud Run :

  • Les requêtes d'agent sortantes acheminées via une instance de proxy Web sécurisé inspectant TLS vers les points de terminaison *.mtls.googleapis.com et *.mtls.run.app échouent avec des erreurs 503, car le proxy Web sécurisé met fin aux sessions TLS et les recrée sans transférer le certificat client.
  • Chaque Agent Gateway autogéré régional accepte au maximum un Agent Registry régional dans sa liste registries.
  • Par défaut, chaque projet accepte jusqu'à 10 ressources AgentGateway régionales et 10 ressources EgressRouting régionales par région. Les nouveaux projets peuvent commencer avec une limite de deux par région. Pour demander une augmentation de quota, contactez l'équipe responsable de votre compte.
  • Vous devez exporter le certificat racine ou subordonné depuis votre pool CA Service ou votre PKI d'entreprise privée, et configurer votre conteneur d'agent pour qu'il lui fasse confiance.

Étapes suivantes