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
- Modifier et redéployer votre requête
- 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. Pour suivre 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 Agent Platform (
roles/aiplatform.user) -
Activer les API requises : Administrateur Service Usage (
roles/serviceusage.serviceUsageAdmin) -
Attribuez 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 compilations en votre nom, demandez à votre administrateur d'attribuer les rôles IAM suivants au compte de service Compute Engine par défaut dans votre projet :
- Agent de service Agent Platform (
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 requêtes d'Agent Studio, puis cliquez sur Ajouter une variable dans la zone de saisie de la requête.
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 s'affiche, car l'enregistrement est obligatoire avant de pouvoir déployer une requête. La boîte de dialogue de déploiement s'ouvrira automatiquement une fois l'invite enregistrée.
Activer les API pour le premier déploiement et accorder des autorisations
- Une fois la requête enregistrée, le processus de déploiement se poursuit. Si c'est votre premier déploiement, une boîte de dialogue s'affiche pour vous inviter à 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 vous choisissez l'authentification requise, suivez le guide pour accorder l'accès (y compris à vous-même).
- Si vous sélectionnez Autoriser l'accès public, cela signifie que tout le monde 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.
- Si c'est 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 Autoriser tout pour continuer.
Début du déploiement
Agent Studio créera un fichier ZIP contenant le code source de l'application Web et l'importera 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, comme le nom de votre application, la date de sa dernière mise à jour, 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 l'accès non authentifié activé par défaut. Vous pouvez le 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. Vous devriez pouvoir voir les résultats à droite.
Ouvrez 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 une requête peut ne pas fonctionner si vous avez laissé l'application Web inactive trop longtemps. Actualiser la page devrait résoudre ce 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. L'URL de la page Cloud Run ne contient pas la clé secrète. Vous devrez l'ajouter manuellement au format ?key=SECRET_KEY.
Mettre à jour et redéployer votre prompt
Vous pouvez affiner votre requête dans Agent Studio et la 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 modifiée.
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'UI de conversation s'affiche avec la variable de prompt. Saisissez la valeur et saisissez du 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 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 le bouton en forme de trombone dans la zone de saisie de la conversation.
Vous pourrez interagir avec le modèle à l'aide des entrées 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 d'icône 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 sur la sécurité de 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 pas 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 de l'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 la case Utiliser Cloud IAM pour authentifier les requêtes entrantes et sélectionnez Authentification requise. Cliquez sur Enregistrer.
Votre application Web ne sera alors plus accessible via l'URL. Si vous essayez d'y accéder, la page Erreur : Accès refusé 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. Si vous choisissez l'option Autoriser les appels non authentifiés, elle 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
Le contrôle des accès n'est pas encore disponible dans la version Preview publique. Par conséquent, une fois l'accès public désactivé, le seul moyen d'accéder à l'application Web est de configurer un proxy local. Pour ce faire, vous pouvez utiliser les 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 et cliquez sur le bouton d'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 est ajoutée à votre Cloud Shell. Appuyez sur Entrée et attendez la fin de l'impression. Cliquez sur le lien de la ligne commençant par Click on the
link to preview. Vous pourrez consulter votre demande. 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 invite. Si vous disposez d'une clé secrète provenant d'une autre invite, elle ne fonctionnera pas. Suivez les instructions pour ouvrir correctement l'application Web.
400 Argument non valide : entrée vide
L'erreur suivante se produit lorsque vous avez des entrées dans la variable d'invite, mais que le chat est vide. Un message d'erreur 400 s'affiche alors. Pour résoudre ce problème, saisissez une valeur non vide, puis renvoyez le formulaire.
400 Argument non valide : mimeType n'est pas compatible
Si vous choisissez un type de fichier non compatible avec le modèle, une erreur 400 sera 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
Guide de démarrage rapide d'Agent Studio : envoyer des prompts textuels à Gemini
Découvrez comment envoyer des requêtes textuelles à Gemini à l'aide d'Agent Studio.