1. Introduction
Présentation
Cet atelier explique comment implémenter de manière sécurisée une invocation basée sur les événements d'un agent ADK déployé sur Cloud Run à l'aide des services Eventarc et Pub/Sub. Le plus souvent, un agent est appelé directement par un utilisateur ou un autre agent. Toutefois, lorsqu'un agent est intégré à des workflows existants basés sur des événements, un appel direct nécessite de modifier le logiciel existant. Le déclenchement d'un appel d'agent basé sur un événement permet d'intégrer un agent dans des workflows existants sans les modifier.
Objectifs de l'atelier
Dans cet atelier, vous allez créer une application agentique ZooKeeper qui comporte un agent d'IA et utilise plusieurs outils pour fournir des informations sur les animaux du zoo imaginaire.
Vous allez déployer l'application ZooKeeper en tant que service sur Cloud Run, une plate-forme de calcul sans serveur entièrement gérée qui exécute des conteneurs sans état sur l'infrastructure de Google. Vous configurerez ensuite un déclencheur Eventarc qui appellera le point de terminaison du service pour gérer de manière asynchrone les messages publiés dans un sujet Pub/Sub. Vous veillerez à ce que le déploiement suive les bonnes pratiques, y compris en utilisant des comptes de service IAM désignés, en accordant un accès avec le moins de privilèges possible et en minimisant la surface d'attaque potentielle en n'exposant le point de terminaison de l'application ZooKeeper qu'à Eventarc. Vous allez le faire à l'aide de Cloud Shell et de la console Cloud. Vous utiliserez les bibliothèques ADK et Cloud SDK pour Python. Pour vérifier le comportement, vous allez utiliser gcloud CLI.
Points abordés
- Déployez votre agent ADK sur Google Cloud Run.
- Intégrez un déclencheur Eventarc à un agent ADK exécuté sur Google Cloud Run.
- Sécurisez votre déploiement et votre intégration à Eventarc en utilisant le principe du moindre privilège avec Google Cloud IAM.
- Publiez et extrayez des messages vers et depuis Pub/Sub.
- Réduisez l'exposition publique de votre application déployée sur Google Cloud Run.
Prérequis
- Navigateur Web Chrome†
- Un compte Google personnel‡
- Un projet Google Cloud associé à un compte de facturation actif
Notez que votre compte doit disposer d'un accès IAM au projet qui vous permet de provisionner des ressources et de configurer l'accès IAM à ces ressources.
† L'expérience utilisateur avec d'autres navigateurs peut différer de celle décrite dans l'atelier.
‡ L'utilisation d'un compte d'entreprise ou scolaire peut être limitée pour certaines opérations décrites dans l'atelier.
2. Configuration de l'environnement
Pour vous assurer de disposer d'un environnement de développement entièrement fonctionnel pour l'atelier, vous utiliserez Google Cloud Shell, qui inclut tous les outils nécessaires préinstallés. Suivez les instructions pour configurer l'environnement.
Si vous n'en possédez pas, créez-en un.
Instructions de configuration
- Connectez-vous à la console Google Cloud à l'aide de votre compte Google.
- 👉 Ouvrez le sélecteur de projet dans la barre de navigation supérieure (il peut indiquer "Sélectionner un projet" ou afficher le nom d'un projet existant), ou cliquez sur le raccourci clavier
Ctrl+O, puis choisissez un projet existant ou créez-en un.La création d'un projet prend quelques secondes. Attendez qu'il soit prêt, puis sélectionnez-le à l'aide du sélecteur de projet.
- 👉 Cliquez sur l'icône Cloud Shell en haut de la console Google Cloud. (marqué d'un rectangle rouge) :
Si vous y êtes invité, cliquez sur **Autoriser** dans la boîte de dialogue pop-up pour autoriser Cloud Shell à utiliser les identifiants de votre compte.
- 👉💻 Assurez-vous que gcloud CLI est configuré pour utiliser le projet que vous avez sélectionné (ou créé). Exécutez la commande suivante pour vérifier l'ID de projet configuré :
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]correspond à l'ID du projet que vous avez sélectionné ou créé.👉💻 Si vous voyez une autre valeur, exécutez la commande suivante pour configurer l'ID de votre projet comme ID de projet par défaut pour les commandes gcloud CLI :gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Définissez l'emplacement pour le provisionnement des ressources, ainsi que l'ID et le numéro de votre projet dans les variables d'environnement :
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Activez les API Google requises pour cet atelier.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. Déployer l'application de démonstration ZooKeeper
Les étapes suivantes permettent de provisionner et de configurer des ressources, y compris le déploiement de l'application d'IA agentique.
Configurer les ressources Pub/Sub
Vous allez créer deux sujets Pub/Sub. L'un sera utilisé par un service tiers pour envoyer des événements à votre application d'IA agentique. Une autre pour que l'application publie les résultats du traitement des événements.
- 👉💻 Créez un sujet Pub/Sub utilisé pour déclencher l'application d'IA agentique :
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Créez un sujet Pub/Sub où l'application peut publier ses réponses :
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Configurer des comptes de service et des stratégies IAM au niveau du projet
Vous allez créer deux comptes de service pour limiter le champ d'application de l'accès au service Cloud Run et au déclencheur Eventarc au minimum, conformément au principe du moindre privilège. Le service Cloud Run nécessite des autorisations pour écrire des journaux et des traces, pour appeler le LLM Gemini sur Google Vertex AI et pour publier des résultats dans un sujet Pub/Sub. L'accès minimal du déclencheur Eventarc nécessite des autorisations pour appeler le service Cloud Run ZooKeeper et accéder à Pub/Sub pour lire les événements publiés. Ces instructions vous guident pour accorder au compte de service du déclencheur les autorisations nécessaires pour emprunter l'identité du service système Pub/Sub. Après avoir créé la ressource de déclencheur Eventarc, vous exécuterez la commande qui attribue le rôle roles/run.invoker pour permettre au compte de service du déclencheur d'appeler le service Cloud Run.
- 👉💻 Créez un compte de service pour le service Cloud Run :
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Accordez au compte de service les autorisations nécessaires pour écrire des journaux et des traces, et utiliser les modèles Gemini sur Vertex AI :
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Accordez au compte de service les autorisations nécessaires pour publier des messages dans le sujet "agent_responses" :
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Créez un compte de service pour le déclencheur Eventarc :
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Accordez au compte de service système Pub/Sub les autorisations nécessaires pour effectuer des requêtes push authentifiées :
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Déployer l'application ZooKeeper sur Cloud Run
Vous allez télécharger le code de l'application de démonstration depuis GitHub. Déployez ensuite le code sur Cloud Run.
- 👉💻 Téléchargez l'application d'IA agentive :
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Déployez l'application d'IA agentique sur Cloud Run :
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Configurer le déclencheur Eventarc
Une fois toutes les ressources préparées (sujets Pub/Sub, comptes de service IAM et service Cloud Run), il est temps de configurer la ressource de déclencheur Eventarc. Vous allez créer la ressource de déclencheur Eventarc et accorder les autorisations d'appel du service Cloud Run au compte de service du déclencheur.
- 👉💻 Créez un déclencheur Eventarc :
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Accordez des autorisations au compte de service du déclencheur pour appeler le service Cloud Run :
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Fonctionnement de la solution
Examinez maintenant ce que vous venez de déployer. Le schéma suivant reflète toutes les ressources et la façon dont elles interagissent les unes avec les autres. Vous utiliserez gcloud CLI pour publier un message dans le sujet "invoke_agent". Cela simulera un événement qu'un service tiers enregistre dans le service de messagerie pour appeler l'application d'IA agentique.
Le déploiement est sécurisé en suivant le principe du moindre privilège. Le service Cloud Run applique l'authentification (voir l'argument --no-allow-unauthenticated à l'étape 9 de la section précédente). Seules les identités disposant du rôle roles/run.invoker ou d'autorisations similaires peuvent appeler le service. Ce rôle n'est attribué qu'au compte de service du déclencheur Eventarc. De même, l'accès au sujet "invoke_agent" est réduit au minimum pour empêcher la publication non autorisée d'événements. Il est toujours possible d'appeler l'agent ZooKeeper directement, sans publier dans le sujet Pub/Sub. Consultez la section 6 pour savoir comment masquer le point de terminaison de l'application et empêcher l'accès public.
Exécuter le workflow
Vous allez simuler un événement externe en publiant une question en langage naturel dans ZooKeeper.
👉💻 Utilisez la commande suivante pour publier un message dans le sujet Pub/Sub :
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
En réalité, les informations sur l'événement seront probablement moins lisibles. Pour le traiter, une application d'IA agentique aura besoin d'instructions détaillées concernant le format de l'événement, les données et ce que l'agent doit faire avec les informations sur l'événement.
Vous pouvez vérifier que l'agent a reçu l'événement, traité la requête et publié la réponse dans la rubrique "agent_responses". Pour lire la réponse, vous utiliserez l'abonnement "agent_responses" (l'atelier de programmation utilise le même ID pour le sujet et l'abonnement aux réponses).
👉💻 Utilisez la commande suivante pour lire la réponse de l'agent à partir de l'abonnement Pub/Sub :
gcloud pubsub subscriptions pull agent_responses --auto-ack
Le résultat affichera un tableau avec les métadonnées du message et la charge utile contenant la réponse indiquant qu'il y a 33 espèces dans le zoo. L'indicateur --auto-ack confirme automatiquement le message une fois qu'il a été extrait. Il ne sera donc pas distribué à nouveau.
Fonctionnement
Consultez le code source de l'application d'IA agentique en ouvrant l'éditeur Cloud Shell et en affichant les fichiers du dossier ~/zoo-keeper-lab. Vous pouvez également consulter le code source sur GitHub.
- Le fichier main.py implémente une application Web FastAPI de base avec un seul gestionnaire qui traite les événements Eventarc.
- Le fichier processor.py analyse le message de l'événement pour récupérer l'ID utilisateur et la requête. Il crée ensuite une session dans le runner ADK et appelle l'agent Zookeeper pour traiter la requête. La réponse de l'agent est publiée dans le sujet Pub/Sub "agent_responses".
- Le sous-dossier zookeeper_agent héberge le code source de l'agent ADK. Vous pouvez exécuter la commande
adk run zookeeper_agentà partir du dossier racine de l'application pour interagir avec l'agent à l'aide de la CLI ADK.
Résoudre les problèmes
Si l'une des commandes précédentes échoue, lisez attentivement le message d'erreur. Si le déploiement sur Cloud Run échoue, la première étape consiste à déterminer à quelle étape du processus l'échec s'est produit.
- Si le résultat de la commande "gcloud run deploy..." indique que la compilation a échoué, consultez l'URL des journaux de compilation dans le résultat et ouvrez-la dans une fenêtre distincte.
- Si le résultat indique "le service n'a pas pu démarrer" ou quelque chose de similaire, cela signifie que le service est déployé, mais que l'exécution échoue au niveau du contrôle de l'état. Dans ce cas, ouvrez l'explorateur de journaux ou consultez le paragraphe suivant pour obtenir la commande gcloud CLI. Lisez les journaux pour identifier la cause de l'échec.
Que faire si vous avez publié un message sur Pub/Sub, mais que l'agent ne répond pas ou que la réponse semble étrange ?
👉💻 Utilisez la commande suivante pour lire les journaux d'application publiés lors de la dernière exécution :
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Les journaux suivent l'exécution et signalent les erreurs telles que la charge utile du message incorrecte ou non analysable, la réponse non valide du modèle Gemini, les paramètres d'environnement non valides et d'autres problèmes potentiels.
5. Renforcer la sécurité du déploiement
Le service Cloud Run que vous avez déployé expose un point de terminaison public qui peut être appelé par n'importe qui sur Internet. Bien que le point de terminaison soit protégé contre les appels non autorisés et qu'il valide rigoureusement la structure de la requête, il laisse toujours ce vecteur d'attaque qui permet les attaques par déni de service et par déni de portefeuille. Étant donné que le seul chemin d'appel du service dans la conception actuelle passe par le déclencheur Eventarc, le service n'a pas besoin d'exposer son point de terminaison sur Internet.
👉💻 Fermez ce vecteur d'attaque en limitant les appels au service à la collection limitée de sources, y compris les déclencheurs Eventarc :
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Désormais, si vous essayez d'appeler l'URL du service depuis votre machine locale, vous obtiendrez une erreur "404 Page introuvable".
👉💻 Utilisez curl pour envoyer une requête au point de terminaison du service :
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Un résultat semblable aux lignes suivantes s'affiche :
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Après ce changement, il n'est plus possible d'appeler directement ZooKeeper en appelant le point de terminaison du service Cloud Run, sauf si vous effectuez l'appel depuis le VPC du même projet, le réseau VPC partagé vers lequel votre révision est configurée pour envoyer du trafic ou un hôte faisant partie du périmètre VPC Service Controls.
6. Résumé
Félicitations ! Vous avez configuré un environnement pour appeler de manière asynchrone votre application d'IA agentique déclenchée par des événements entrants.
Effectuer un nettoyage
Notez que la conservation des ressources que vous avez provisionnées peut entraîner des frais sur votre compte de facturation. Si vous ne prévoyez pas d'utiliser cet environnement pour d'autres expériences et pour éviter les frais à venir, nous vous recommandons de supprimer les ressources créées lors de cet atelier de programmation.
Deux méthodes sont possibles :
Méthode 1 : Arrêter le projet
L'arrêt (suppression) du projet libère toutes les ressources et données du projet, et dissocie le compte de facturation. Cette méthode permet d'éviter que des frais supplémentaires ne soient facturés pour les ressources ou les données utilisées dans cet atelier de programmation. Utilisez la commande suivante pour arrêter le projet :
gcloud projects delete $(gcloud config get-value project) --quiet
Méthode 2 : Supprimer des ressources dans le projet
La suppression du service Cloud Run permet d'éviter d'autres frais d'utilisation de la plate-forme sans serveur. Notez que cette méthode ne supprime pas complètement toutes les données générées pendant l'atelier de programmation, telles que les journaux Cloud Build et d'application, les images de conteneur, etc. Exécutez la commande suivante pour supprimer le service :
gcloud run services delete zookeeper-agent --region=${LOCATION}
La définition du déclencheur Eventarc et les sujets Pub/Sub n'entraînent pas de frais de gestion (pour en savoir plus, consultez les tarifs d'Eventarc et les tarifs de Pub/Sub).
En savoir plus sur l'arrêt du projet
Étape suivante
- Pour en savoir plus sur le code, consultez la démo sur GitHub.
- Examinez l'architecture qui orchestre l'accès à différents systèmes d'entreprise.
- Découvrez comment déclencher Cloud Run à l'aide de déclencheurs Eventarc.
- En savoir plus sur l'ADK