Dans Agent Studio, vous pouvez concevoir et affiner vos requêtes, et comparer les résultats de différentes configurations et modèles. Une fois que vous avez terminé de concevoir votre requête, vous pouvez la déployer en tant qu'application Web pour la partager avec vos collaborateurs ou vos utilisateurs cibles afin qu'ils puissent la tester. L'application Web est hébergée sur Cloud Run et est disponible en dehors de la console Google Cloud .
Dans ce guide de démarrage rapide, vous allez :
- Créer un prompt avec des variables de prompt
- Déployer votre requête en tant qu'application Web
- Surveiller la progression du déploiement et tester l'application déployée
- Mettre à jour et redéployer votre prompt
- Tester l'envoi de requêtes avec la compatibilité multimodale
Avant de commencer
Si vous n'avez jamais utilisé Agent Studio, vous pouvez suivre un autre guide de démarrage rapide ou suivre le cours Google Cloud Skills Boost pour apprendre les bases d'Agent Studio. Dans ce guide, vous devez disposer des éléments suivants :
- Un projet Google Cloud avec la facturation et l'API Agent Platform activées.
- Les rôles requis pour déployer un prompt Agent Studio en tant qu'application Web. Si vous avez créé un projet pour ce guide, vous disposez déjà des autorisations requises.
Vous pouvez également vous assurer que le compte de service Compute Engine par défaut dispose des rôles requis pour le compte de service de déploiement. Si vous êtes autorisé à attribuer des rôles, vous pouvez les attribuer lors du déploiement de votre application.
Rôles requis
Pour obtenir les autorisations nécessaires pour déployer un prompt Agent Studio en tant qu'application Web, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :
- Utilisateur de la plate-forme d'agents (
roles/aiplatform.user) -
Activer les API requises : Administrateur Service Usage (
roles/serviceusage.serviceUsageAdmin) -
Attribuer les rôles requis au compte de service Compute Engine par défaut : Administrateur de projet IAM (
roles/resourcemanager.projectIamAdmin) -
Déployez une application Cloud Run :
- Administrateur Cloud Run (
roles/run.admin) - Développeur de source Cloud Run (
roles/run.sourceDeveloper)
- Administrateur Cloud Run (
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.
Rôles requis pour le compte de service de déploiement
Pour vous assurer que le compte de service Compute Engine par défaut dispose des autorisations nécessaires pour exécuter des builds en votre nom, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service Compute Engine par défaut sur votre projet :
- Agent de service Vertex AI (
roles/aiplatform.serviceAgent) - Compte de service Cloud Build (
roles/cloudbuild.builds.builder)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Votre administrateur peut également attribuer au compte de service Compute Engine par défaut les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
Si vous êtes autorisé à attribuer des rôles, vous pouvez les attribuer lors du déploiement de votre application.
Créer un prompt avec des variables de prompt
Accédez à la page de création de prompt d'Agent Studio, puis cliquez sur Ajouter une variable dans la zone de saisie du prompt.
Dans la boîte de dialogue Gérer les variables de prompt, saisissez un nom de variable et attribuez-lui une valeur. Cliquez ensuite sur Appliquer.
Dans la zone de saisie du prompt, composez le prompt à l'aide de la variable, puis ajustez les autres paramètres. Par exemple, vous pouvez activer l'ancrage avec la recherche Google et définir "Toujours obtenir la météo actuelle sur le Web" comme instructions système.
Déployer votre requête en tant qu'application Web
Pour déployer votre requête en tant qu'application Web, cliquez sur , puis sur Déployer en tant qu'application.
Enregistrer le prompt
La boîte de dialogue d'enregistrement de la requête s'affiche, car l'enregistrement est requis avant de pouvoir déployer une requête. La boîte de dialogue de déploiement s'ouvre automatiquement une fois la requête enregistrée.
Activer les API pour le premier déploiement et accorder des autorisations
- Une fois l'invite enregistrée, le processus de déploiement se poursuit. S'il s'agit de votre premier déploiement, une boîte de dialogue s'affiche pour vous permettre d'activer les API requises. Cliquez sur Activer les API requises.
-
Une fois les API activées, la boîte de dialogue Créer une application Web s'affiche. Vous pouvez choisir Exiger l'authentification (via Identity-Aware Proxy) ou Autoriser l'accès public.
- Si l'authentification requise est choisie, suivez le guide pour accorder l'accès (y compris à vous-même).
- Lorsque vous sélectionnez Autoriser l'accès public, cela signifie que n'importe qui peut accéder à l'application. Par conséquent, n'incluez pas d'informations sensibles ou d'informations permettant d'identifier personnellement l'utilisateur (PII) dans votre requête. Cochez la case Je comprends que cette application sera déployée publiquement pour confirmer.
- Cliquez sur Créer une application pour lancer le déploiement.
- S'il s'agit de votre premier déploiement, une autre boîte de dialogue s'affiche pour vous demander d'accorder les rôles requis au compte de service. Cliquez sur Tout accorder pour continuer.
Début du déploiement
Agent Studio crée un fichier ZIP contenant le code source de l'application Web et l'importe dans un bucket Cloud Storage. Une fois le déploiement lancé, la boîte de dialogue Gérer l'application Web s'affiche avec des informations sur votre déploiement, telles que le nom de votre application, la date de son dernier déploiement, son état de déploiement, etc.
Surveiller l'état du déploiement
Le déploiement prend deux à trois minutes. Son état s'affiche dans la colonne État de la boîte de dialogue Gérer l'application Web. Si vous fermez la boîte de dialogue Gérer l'application Web, vous pouvez la rouvrir à partir du menu situé sous le bouton Compiler avec du code.
Une fois le déploiement terminé, la colonne d'état passe à Prêt et le bouton Ouvrir s'affiche à côté du nom de l'application.
Contrôle des accès et clé secrète
Votre application Web est déployée avec le contrôle des accès Autoriser les appels non authentifiés activé par défaut. Vous pouvez la désactiver en cliquant sur l'icône en forme de crayon . Pour en savoir plus, consultez la section Désactiver l'accès public.
Pour assurer une protection de base, l'application Web nécessite l'ajout d'une clé secrète à l'URL pour l'envoi de la requête. Vous trouverez la clé secrète dans la colonne Clé secrète. Si vous ouvrez l'application Web depuis Agent Studio, la clé sera ajoutée à l'URL pour vous.
Ouvrez l'application Web et envoyez le prompt
Cliquez sur Ouvrir dans la boîte de dialogue Gérer l'application Web pour accéder à l'application déployée. L'application doit être ouverte avec la clé secrète ajoutée à l'URL au format ?key=SECRET_KEY.
Saisissez une valeur pour la variable, puis cliquez sur Envoyer. Les résultats devraient s'afficher à droite.
Ouvrir l'application Web à partir du menu du bouton "Compiler avec du code"
Si votre application Web est prête, vous pouvez également l'ouvrir à partir du menu du bouton Compiler avec du code.
Cloud Run est un service sans serveur, ce qui signifie que le conteneur de l'application sera arrêté s'il n'est pas utilisé activement. Par conséquent, l'application Web peut parfois mettre quelques secondes à se charger, ou un envoi peut ne pas fonctionner si vous avez laissé l'application Web inactive trop longtemps. Actualiser la page devrait résoudre le problème.
Surveiller l'état depuis la cloche de notification
Vous pouvez également surveiller l'état à partir du menu Notifications en cliquant sur l'icône en forme de cloche. L'icône en forme de cloche arrête son animation de chargement et affiche un cercle vert si le déploiement s'est terminé correctement.
Si vous cliquez sur la notification, vous serez redirigé vers la page Cloud Run. La clé secrète n'est pas ajoutée à l'URL de la page Cloud Run. Vous devrez l'ajouter manuellement au format ?key=SECRET_KEY.
Mettre à jour et redéployer votre prompt
Vous pouvez modifier davantage votre prompt dans Agent Studio et le transformer en conversation. Cliquez ensuite sur le bouton Compiler avec du code, puis sur Gérer l'application pour ouvrir la boîte de dialogue Gérer l'application Web. Cliquez sur Mettre à jour l'application pour redéployer votre application Web avec la requête mise à jour.
Une boîte de dialogue de confirmation s'affiche. Il vous indique que si vous redéployez, vous perdrez toutes les modifications que vous avez apportées à l'application Web déployée en dehors d'Agent Studio (par exemple, dans l'éditeur de code source Cloud Run). Cliquez sur Confirmer pour continuer.
La boîte de dialogue Gérer l'application Web s'affiche à nouveau. Le processus est semblable au déploiement initial. Vous pouvez surveiller la progression de la même manière que pour le premier déploiement.
Une fois la mise à jour terminée, vous pouvez rouvrir l'application Web. L'interface utilisateur de la conversation s'affiche avec la variable de prompt. Renseignez la valeur et saisissez un contenu non vide pour poursuivre la conversation.
Insérer du contenu multimodal
Vous pouvez insérer des entrées telles que des images, des vidéos, des fichiers audio et des documents dans l'interface utilisateur de la conversation. Les entrées acceptées dépendent du modèle sélectionné pour la requête. Consultez la documentation sur la compatibilité multimodale pour chaque modèle.
Pour insérer un fichier, cliquez sur l'icône (trombone) dans la zone de saisie de la conversation.
Vous pourrez interagir avec le modèle à l'aide de l'entrée que vous fournissez.
Informations supplémentaires
Une fois que vous êtes familiarisé avec le processus de déploiement, vous pouvez envisager les actions suivantes.
Modifier le code source dans Cloud Run
Si vous souhaitez personnaliser l'application Web, vous pouvez modifier le code source dans Cloud Run. Ouvrez la page du code source Cloud Run à partir de la boîte de dialogue Gérer l'application Web en cliquant sur le bouton Plus à la fin de la ligne.
Vous pouvez également accéder à la page de sécurité depuis l'application Web en cliquant sur le lien éditeur de code source.
Sur la page du code source Cloud Run, cliquez sur Modifier la source pour passer en mode Édition. Lorsque vous avez terminé, cliquez sur Enregistrer et redéployer.
Une fois le redéploiement terminé, vous devez ouvrir l'application depuis Agent Studio. Vous pouvez accéder à la page Agent Studio à partir du lien figurant dans le badge Déployé depuis Agent Platform.
Accorder l'accès
Pour accorder l'accès à l'application à des utilisateurs ou des groupes, procédez comme suit :
- Ouvrez la boîte de dialogue Manage Web App (Gérer l'application Web).
- Cliquez sur l'icône en forme de crayon dans la colonne Contrôle des accès. La page de sécurité Cloud Run s'ouvre dans un nouvel onglet.
- Sur la page de sécurité de Cloud Run, recherchez la case à cocher "Identity-Aware Proxy (IAP)". Assurez-vous qu'elle est cochée, puis cliquez sur Modifier la règle.
-
Une tâche secondaire s'affiche pour vous permettre de modifier l'accès. Saisissez les adresses e-mail des utilisateurs ou des groupes dans le champ Compte principal.
Si vous êtes un utilisateur d'une organisation, vous ne pouvez ajouter que des utilisateurs de la même organisation.
- Laissez le champ des niveaux d'accès vide.
- Cliquez sur Enregistrer.
-
Une fois la sous-tâche fermée, cliquez à nouveau sur Enregistrer sur la page Cloud Run.
Désactiver l'accès public
Lorsque vous n'avez plus besoin que l'application Web soit accessible au public, vous pouvez la désactiver dans Cloud Run. Ouvrez la boîte de dialogue Gérer l'application Web, puis cliquez sur l'icône en forme de crayon dans la colonne Contrôle des accès. La page de sécurité Cloud Run s'ouvre dans un nouvel onglet.
Vous pouvez également accéder à la page de sécurité depuis l'application Web en cliquant sur le lien Paramètres de sécurité.
Sur la page "Sécurité" du service Cloud Run correspondant à votre application Web, cochez l'option Utiliser Cloud IAM pour authentifier les requêtes entrantes, puis sélectionnez Exiger l'authentification. Cliquez sur Enregistrer.
Votre application Web ne sera alors plus accessible via l'URL. Si vous essayez d'y accéder, une page Erreur : Interdit s'affiche.
Réactiver l'accès public
Si vous souhaitez rétablir l'accès public, décochez la case Utiliser Cloud IAM pour authentifier les requêtes entrantes, puis enregistrez les modifications. Si vous choisissez Autoriser les appels non authentifiés, cela ne fonctionnera pas si votre projet se trouve dans une organisation. Pour en savoir plus, consultez Authentification dans Cloud Run.
Configurer l'accès local pour le développement
Dans la version Preview publique, le contrôle des accès n'est pas encore disponible. Par conséquent, une fois que vous avez désactivé l'accès public, le seul moyen d'accéder à l'application Web est de configurer un proxy local. Pour ce faire, vous pouvez utiliser des commandes gcloud. Tout d'abord, ouvrez Cloud Shell en cliquant sur l'icône de terminal en haut à droite de la console Google Cloud . Vous serez invité à autoriser Cloud Shell. Cliquez sur Autoriser pour continuer.
Une fois l'opération terminée, ouvrez la boîte de dialogue Gérer l'application Web, puis cliquez sur l'icône (Plus) à la fin de la ligne pour afficher d'autres actions. Cliquez sur Configurer l'accès local via Cloud Shell.
Une commande sera ajoutée à votre Cloud Shell. Appuyez sur Entrée et attendez que l'impression se termine. Cliquez sur le lien de la ligne commençant par Click on the
link to preview. Vous pourrez voir votre application. Ce lien ne fonctionne que lorsque la commande gcloud est en cours d'exécution.
Problèmes courants
Erreur d'authentification : aucune clé secrète
Si l'erreur suivante s'affiche, cela signifie qu'aucune clé secrète n'est ajoutée à l'URL. Suivez les instructions pour ouvrir l'application Web depuis Agent Studio, ou copiez la clé secrète depuis la boîte de dialogue Gérer l'application et ajoutez-la à l'URL au format ?key=SECRET_KEY.
Erreur d'authentification : clé secrète non valide
L'erreur suivante signifie que la clé ajoutée à l'URL n'est pas valide. La clé secrète est unique pour chaque requête. Si vous disposez d'une clé secrète provenant d'une autre invite, elle ne fonctionnera pas. Suivez les instructions pour ouvrir l'application Web correctement.
400 Argument non valide : entrée vide
L'erreur suivante se produit lorsque vous avez des entrées dans la variable de requête, mais que le chat est vide. Un message d'erreur 400 s'affiche. Pour résoudre ce problème, saisissez une valeur non vide, puis renvoyez le formulaire.
400 Argument non valide : mimeType n'est pas accepté
Si vous choisissez un type de fichier non compatible avec le modèle, une erreur 400 est renvoyée. C'est normal. Vous devrez utiliser d'autres types de fichiers compatibles avec le modèle. Consultez la documentation sur la compatibilité multimodale pour chaque modèle.
Étapes suivantes
Présentation de la compilation
Découvrez comment créer des agents dans Google Agent Platform.
Guide de démarrage rapide d'Agent Studio : envoyer des prompts textuels à Gemini
Découvrez comment envoyer des prompts textuels à Gemini à l'aide d'Agent Studio.