Cette page explique comment utiliser Agent Studio dans la consoleGoogle Cloud .
Agent Studio est un outil de conception visuelle low-code de la console Google Cloud qui simplifie le développement d'agents. Vous pouvez cartographier visuellement les workflows agentiques, tester les réponses en temps réel et tester différentes configurations avant de déployer ou de passer au code.
Ce document présente Agent Studio et explique comment configurer votre environnement, créer et tester des agents, et les déployer directement dans un environnement d'exécution de production.
Configurer votre environnement
Avant d'utiliser Agent Studio, configurezGoogle Cloud.
Obtenir les rôles requis
Pour obtenir les autorisations nécessaires pour utiliser Agent Studio, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur de la plate-forme d'agents (roles/aiplatform.user) 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.
Créer un agent
Vous pouvez créer un agent dans Agent Studio à l'aide de requêtes ou de l'outil de création de flux.
Créer un agent à l'aide de prompts
Pour créer un agent à l'aide de prompts, procédez comme suit :
Dans la console Google Cloud , accédez à la page Agents.
Cliquez sur Créer un agent pour ouvrir le canevas Agent Studio d'un nouvel agent.
Dans la zone de chat, saisissez un prompt décrivant l'objectif et le comportement prévu de votre agent.
Cliquez sur .
Selon votre requête, l'une des situations suivantes se produit :
Réussite : le générateur de flux se met à jour immédiatement pour afficher l'aperçu en direct de votre agent, et le chat fournit un résumé des modifications apportées. Toutes les modifications sont enregistrées automatiquement.
Clarification nécessaire : si votre prompt est ambigu, l'assistant pose une question de clarification dans le chat pour mieux comprendre ce que vous souhaitez créer.
Erreur : si l'assistant ne peut pas appliquer votre prompt, un message d'erreur vous invite à reformuler votre demande.
Vous pouvez continuer à mettre à jour l'agent à l'aide de prompts ou du générateur de flux.
Pour enregistrer votre agent, cliquez sur Enregistrer dans l'en-tête du canevas et suivez les instructions. Pour en savoir plus, consultez Enregistrer un agent.
Pour tester les capacités et les réponses de l'agent au fur et à mesure que vous le créez, cliquez sur l'onglet Aperçu et discutez avec votre agent.
Limites
Les limites suivantes s'appliquent lorsque vous créez un agent à l'aide de requêtes :
| Capacité | Limite |
|---|---|
| Connaissances | Impossible d'ajouter des connaissances à un agent. Vous pouvez utiliser l'interface du générateur de flux pour ajouter des connaissances à un agent. |
Créer un agent à l'aide du compilateur de flux
Pour concevoir et tester un agent à l'aide du flow builder, procédez comme suit :
Dans la console Google Cloud , accédez à la page Agents.
Cliquez sur Créer un agent pour ouvrir le canevas Agent Studio d'un nouvel agent.
Concevez et enregistrez votre agent dans le canevas Agent Studio. Vous pouvez créer un agent principal et ajouter des sous-agents. L'agent principal est toujours un agent local. Les sous-agents peuvent être des agents locaux ou des agents d'Agent Registry :
- Agent local : agent dont les instructions, le modèle et les outils sont créés et configurés directement dans le canevas Agent Studio.
- Agent Agent Registry : agent enregistré et publié dans Agent Registry. Vous pouvez utiliser ces agents en tant que sous-agents distants dans le flux de votre agent principal.
Lorsque vous concevez un flux, vous pouvez basculer entre les onglets Flux et Aperçu :
Flow
Créez l'agent principal et les sous-agents à l'aide d'une représentation visuelle du workflow et de la logique de contrôle de votre agent.
- Cliquez sur un agent pour ouvrir le panneau Détails de cet agent. Vous pouvez également cliquer sur Ajouter un sous-agent (+) pour ajouter des sous-agents.
Configurez votre agent principal et vos sous-agents dans le panneau Détails :
Pour l'agent principal et les sous-agents locaux :
- Nom : ajoutez un nom pour identifier l'agent.
- Description : résumé de l'objectif de votre agent.
- Instructions : ajoutez des instructions pour guider votre agent.
- Modèle : sélectionnez le modèle qui alimentera votre agent.
- Outils : cliquez sur Ajouter des outils (+) pour ajouter des outils permettant à l'agent d'effectuer des tâches. Pour en savoir plus, consultez Configurer et ajouter des outils.
Pour les sous-agents (locaux ou issus du registre des agents) :
Source du sous-agent : sélectionnez la source du sous-agent :
- Local : créez les instructions, le modèle et les outils du sous-agent directement sur le canevas.
- Registre d'agents : sélectionnez un agent enregistré dans le registre d'agents en tant que sous-agent distant. Cette option n'est disponible qu'après l'enregistrement de l'agent. Pour en savoir plus, consultez Enregistrer un agent.
Lorsque vous sélectionnez un agent enregistré, son nom et sa description sont importés depuis le registre et deviennent en lecture seule sur le canevas. L'agent parent achemine les tâches vers ce sous-agent en fonction de sa fiche d'agent.
Pour exécuter ou déployer l'agent parent, l'identité de l'agent parent doit disposer des autorisations nécessaires pour découvrir et appeler les sous-agents A2A. La boîte de dialogue des autorisations gère automatiquement cette action. Si vous devez gérer les autorisations manuellement, consultez Accorder l'accès pour la délégation agent à agent (A2A).
Pour enregistrer votre agent, cliquez sur Enregistrer dans l'en-tête du canevas et suivez les instructions. Pour en savoir plus, consultez Enregistrer un agent.
Aperçu
Discutez avec votre agent dans le volet d'aperçu pour tester ses capacités et ses réponses.
- Pour prévisualiser un agent enregistré, Agent Studio vérifie les autorisations d'identité de l'agent. Si des rôles requis sont manquants, une notification s'affiche. Cliquez sur Gérer pour ouvrir la boîte de dialogue des autorisations et gérer les autorisations d'identité de l'agent.
- Vous pouvez inspecter les événements de chaque exécution d'agent pour déboguer le comportement de votre agent. Pour en savoir plus, consultez Inspecter les événements de l'agent.
Cliquez sur Obtenir le code pour afficher le code de votre agent. Si vous souhaitez continuer à développer votre agent ailleurs, vous pouvez copier le code et le coller dans l'éditeur de code de votre choix.
Si votre agent utilise un sous-agent distant d'Agent Registry, le code Python généré inclut un appel à
AgentRegistry.get_remote_a2a_agentpour résoudre dynamiquement le sous-agent au moment de l'exécution.
Une fois votre agent terminé, vous pouvez le déployer directement depuis Agent Studio. Pour en savoir plus, consultez Déployer un agent depuis Agent Studio.
Créer un agent à l'aide du bouton "Mode Agents" dans le prompt Studio
Vous pouvez commencer à créer un agent directement à partir du prompt de bienvenue d'Agent Studio en passant en mode Agents. Lorsque cette option est activée, l'envoi de votre requête lance directement le générateur d'agents dans le canevas de l'Agent Designer.
Pour créer un agent à partir de la requête Studio, procédez comme suit :
Dans la console Google Cloud , accédez à Agent Studio.
Dans la zone de saisie du prompt principal de l'espace de travail d'accueil, recherchez le bouton d'activation/de désactivation du mode.
Activez le mode Agents.
Saisissez un prompt décrivant l'objectif, le workflow et le comportement de l'agent que vous souhaitez concevoir.
Cliquez sur .
Agent Studio lance directement l'outil de création d'agents dans le canevas du concepteur d'agents, en préremplissant le flux et la configuration de l'agent en fonction de votre requête. Vous pouvez ensuite continuer à modifier les instructions, à sélectionner des modèles et à ajouter des outils ou des sous-agents.
Inspecter les événements de l'agent
L'inspection des événements vous aide à déboguer le comportement de votre agent, ainsi qu'à résoudre les problèmes et à suivre le processus de raisonnement et les requêtes de modèle de votre agent.
Vous pouvez déboguer l'exécution de l'agent en inspectant les événements de l'agent dans l'onglet Prévisualiser d'Agent Studio. Cette action vous permet de diagnostiquer les problèmes liés aux événements individuels produits par l'agent lors d'une exécution.
Pour inspecter les événements de l'agent, procédez comme suit :
- Ouvrez votre agent dans le canevas Agent Studio, puis ouvrez l'onglet Aperçu.
- Démarrez une discussion avec votre agent dans le volet d'aperçu pour lancer une exécution.
Sélectionnez un événement dans la conversation pour en afficher les détails. Les détails disponibles dépendent de l'événement et peuvent inclure les éléments suivants :
- Auteur : agent ou sous-agent qui a produit l'événement. Utilisez l'auteur pour identifier le sous-agent qui a effectué une étape dans un workflow multi-agents.
- Requête et réponse : charge utile envoyée au modèle et réponse renvoyée.
- Appels d'outils : arguments transmis aux outils lors de l'exécution de l'agent.
- Métadonnées : informations de diagnostic supplémentaires, telles que le nom du modèle, l'utilisation des jetons et le code temporel.
Si l'agent renvoie une erreur lors de l'aperçu, elle s'affiche dans l'onglet Aperçu pour vous permettre de diagnostiquer le problème.
Enregistrer un agent
Vous devez enregistrer un agent avant de pouvoir le prévisualiser, le déployer ou importer des fichiers de connaissances, car un agent non enregistré n'a pas encore d'identité. Cette exigence s'applique également aux sous-agents du registre d'agents.
De plus, vous devez enregistrer un agent avant d'ajouter des serveurs MCP publiés dans Agent Registry en tant qu'outils au niveau du nœud.
Pour enregistrer un agent pour la première fois :
Dans le canevas Agent Studio, cliquez sur Enregistrer.
Dans la boîte de dialogue Enregistrer l'agent, saisissez un nom d'agent.
Cliquez sur Enregistrer.
Après le premier enregistrement, Agent Studio enregistre automatiquement toutes les modifications que vous apportez. Si vous essayez de quitter le canevas avant d'enregistrer un nouvel agent, Agent Studio vous invite d'abord à l'enregistrer.
Mettre à jour un agent
Pour mettre à jour un agent, procédez comme suit :
Dans la console Google Cloud , accédez à la page Agents.
Sur l'agent que vous souhaitez modifier, cliquez sur , puis sur Modifier.
Mettez à jour l'agent à l'aide d'invites ou du générateur de flux.
Agent Studio enregistre automatiquement vos modifications.
Configurer et ajouter des outils dans Agent Studio
Vous pouvez configurer les outils suivants pour votre agent :
Recherche Google : permet à l'agent d'effectuer des recherches sur le Web à l'aide de la recherche Google. Activé par défaut.
Contexte de l'URL : permet au modèle d'analyser les URL des requêtes envoyées à l'agent. Activée par défaut.
Serveur MCP depuis Agent Registry : associez un serveur MCP publié dans Agent Registry en tant qu'outil au niveau du nœud. Cette option n'est disponible qu'après l'enregistrement de l'agent. Pour en savoir plus, consultez Enregistrer un agent.
- Cliquez sur Ajouter (+) à côté de Serveur MCP depuis Agent Registry.
- Emplacement : sélectionnez la région pour filtrer les outils enregistrés.
- Serveur MCP : sélectionnez le serveur MCP Google enregistré dans la liste.
- Configuration de l'authentification : sélectionnez Aucune pour utiliser l'accès standard aux services résolu par le biais des liaisons IAM.
- Cliquez sur Ajouter.
- Si vous enregistrez l'agent pour la première fois, cliquez sur Enregistrer dans l'en-tête du canevas. Les modifications ultérieures sont enregistrées automatiquement.
Votre agent peut utiliser tous les outils de votre serveur MCP connecté.
Migrer les anciens outils
Pour renforcer la sécurité et standardiser la gestion des outils via Agent Registry, Agent Studio abandonne l'intégration directe avec les datastores Vertex AI Search et les serveurs MCP (Model Context Protocol) directs.
Pour les agents existants, ces outils obsolètes sont en lecture seule. Pour conserver toutes les fonctionnalités, migrez vers un serveur MCP depuis Agent Registry.
Migrer depuis les anciens datastores Vertex AI Search
Si votre agent utilise un outil de datastore Agent Platform Search obsolète, migrez vers le serveur MCP Agent Search disponible dans Agent Registry. Cet outil s'affiche sous la forme discoveryengine.googleapis.com dans le registre des agents.
Lorsque vous connectez le serveur MCP Agent Search, vous devez définir la configuration de diffusion cible dans les instructions de l'agent. De plus, l'identité de l'agent nécessite des autorisations d'accès.
Pour migrer, procédez comme suit :
- Ouvrez votre agent dans le canevas Agent Studio.
- Recherchez l'outil "Datastore Vertex AI Search" dans le panneau Outils.
- Notez les paramètres de l'outil, tels que l'ID du projet, l'emplacement et l'ID du data store.
- Créez un agent et enregistrez-le.
- Attribuez le rôle Lecteur Discovery Engine (
roles/discoveryengine.viewer) à l'identité de l'agent. Nous vous recommandons d'accorder ce rôle directement sur le data store ou l'application de recherche cible. Toutefois, à des fins de dépannage, vous pouvez l'accorder au niveau du projet. Pour trouver le compte principal de l'agent et lui attribuer le rôle, consultez Gérer les rôles manuellement. L'agent a également besoin du rôle Utilisateur de l'outil MCP (roles/mcp.toolUser), que la boîte de dialogue des autorisations accorde automatiquement. - Dans le panneau Outils, cliquez sur Ajouter (+) à côté de Serveur MCP depuis Agent Registry.
- Renseignez les champs suivants :
- Emplacement : sélectionnez la région dans laquelle vos outils sont enregistrés.
- Serveur MCP : sélectionnez Recherche d'agent ou
discoveryengine.googleapis.comdans la liste des serveurs MCP enregistrés. - Configuration d'authentification : sélectionnez Aucune. L'accès est résolu par le biais de liaisons IAM standards.
- Cliquez sur Ajouter.
Dans les instructions du nouvel agent, spécifiez la configuration de diffusion cible à l'aide des valeurs que vous avez notées à l'étape 3. Exemple :
Use the search tool to answer questions about YOUR_TOPIC. When using the search tool, use this servingConfig: projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_searchPour une application de recherche, remplacez
dataStores/DATA_STORE_IDparengines/APP_ID. Pour connaître les formats et arguments acceptés, consultez Référence des outils MCP : discoveryengine.googleapis.com.
Migrer depuis un ancien serveur MCP direct
Si votre agent se connecte directement à un serveur MCP à l'aide d'une URL de point de terminaison, vous devez d'abord enregistrer le catalogue de votre serveur MCP dans Agent Registry.
Pour migrer votre outil, procédez comme suit :
- Assurez-vous que votre serveur MCP est enregistré dans Agent Registry.
- Mettez à jour votre agent dans Agent Studio :
- Ouvrez votre agent dans le canevas Agent Studio.
- Recherchez et supprimez l'ancienne connexion directe au serveur MCP.
- Cliquez sur Ajouter (+) à côté de Serveur MCP depuis Agent Registry.
- Sélectionnez votre serveur MCP enregistré dans la liste.
- Cliquez sur Ajouter.
- Si vous enregistrez l'agent pour la première fois, cliquez sur Enregistrer dans l'en-tête du canevas. Les modifications ultérieures sont enregistrées automatiquement.
Ancrer des agents avec des fichiers de connaissances
Importez des documents de référence statiques pour ancrer les réponses de votre agent dans Agent Studio :
- Sélectionnez le nœud de l'agent parent sur le canevas auquel vous souhaitez joindre des fichiers de référence. Notez que vous ne pouvez pas joindre de fichiers de connaissances aux sous-agents.
- Dans le panneau Détails du nœud, recherchez la section Connaissances. La section Connaissances n'apparaît qu'après avoir enregistré l'agent pour la première fois. Pour en savoir plus, consultez Enregistrer un agent.
- Cliquez sur le composant d'importation de fichier, puis parcourez votre ordinateur pour sélectionner votre fichier de référence.
Vous pouvez joindre jusqu'à 10 fichiers par agent. La taille du fichier ne doit pas dépasser 2 Mo. Le canevas d'importation est compatible avec les types de fichiers suivants :
- Texte brut
Si vous enregistrez l'agent pour la première fois, cliquez sur Enregistrer dans l'en-tête du canevas pour stocker les fichiers dans un bucket Cloud Storage dédié sous un préfixe de chemin correspondant à l'
AGENT_IDde l'agent parent. Les modifications ultérieures sont enregistrées automatiquement.La boîte de dialogue d'autorisation accorde le rôle "Lecteur des objets Storage" (
roles/storage.objectViewer) à l'identité de l'agent sur le bucket.Accédez à l'onglet Aperçu et envoyez une requête de test pour vérifier que l'agent fonde sa réponse sur le contenu du fichier sans halluciner.
Facultatif : Vous pouvez cliquer sur Obtenir le code pour copier le code Python généré (
agent.py) et inspecter la configuration du fichier d'ancrage. Vous pouvez passer cette étape.
Gérer les autorisations d'identité des agents
Chaque agent d'Agent Studio possède une identité unique, qui sert de compte principal IAM pour accéder à d'autres ressources Google Cloud .
Le format du compte principal est le suivant :
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID
Remplacez les éléments suivants :
ORGANIZATION_ID: ID numérique de votre organisation.PROJECT_NUMBER: numéro de votre projetGoogle Cloud .LOCATION: région dans laquelle votre agent est déployé.REASONING_ENGINE_ID: ID de ressource de votre moteur de raisonnement.
Pour en savoir plus sur les identités d'agent, consultez Créer un agent avec une identité d'agent et Présentation de l'identité d'agent.
Comportement de la boîte de dialogue des autorisations
Lorsque vous cliquez sur Déployer ou que vous ouvrez l'onglet Prévisualiser pour un agent enregistré, Agent Studio vérifie automatiquement si l'identité de l'agent dispose de l'ensemble des rôles IAM requis pour s'exécuter correctement. Certaines autorisations manquantes peuvent empêcher votre agent de fonctionner si elles ne sont pas configurées correctement. Accorder ces autorisations à l'identité de l'agent l'aide à fonctionner comme prévu.
Si le système détecte des problèmes d'autorisation, la boîte de dialogue des autorisations affiche un message d'erreur.
- Rôles manquants : si des rôles requis sont manquants, une boîte de dialogue s'affiche et liste les rôles détaillés. Dans la boîte de dialogue, cliquez sur Accorder tout pour accorder automatiquement tous les rôles nécessaires à l'identité de l'agent en une seule action. Pour prévisualiser ou déployer l'agent sans accorder les rôles, cliquez sur Continuer quand même.
- Tous les rôles sont attribués : si tous les rôles requis sont déjà attribués, la boîte de dialogue des autorisations ne s'affiche pas.
- Agents non enregistrés : les agents non enregistrés n'ont pas encore d'identité. La boîte de dialogue des autorisations ne s'affiche pas, et les options Prévisualiser et Déployer sont désactivées tant que vous n'avez pas enregistré l'agent.
Rôles requis
La boîte de dialogue des autorisations accorde automatiquement la liste de rôles suivante :
roles/storage.objectViewer: obligatoire si l'agent utilise des fichiers importés. Ce rôle doit être attribué sur le bucket Cloud Storage spécifique pour les fichiers de l'agent (par exemple,{projectNumber}_{location}_agent_studio_files).roles/mcp.toolUser: obligatoire si l'agent utilise un outil MCP Agent Registry.roles/agentregistry.viewer: obligatoire si l'agent utilise un outil ou un sous-agent MCP Agent Registry.roles/iamconnectors.user: obligatoire si un outil MCP Agent Registry spécifie unauthProviderName.roles/aiplatform.viewer: obligatoire si l'agent appelle des sous-agents distants via la délégation agent à agent (A2A).
Gérer les rôles manuellement dans la console Google Cloud
La boîte de dialogue des autorisations accorde automatiquement les rôles requis. Toutefois, si vous préférez gérer les rôles manuellement ou si vous devez résoudre des problèmes d'autorisation, procédez comme suit :
Copiez le compte principal d'identité unique de l'agent. Dans l'en-tête du canevas Agent Studio, cliquez sur le menu déroulant à côté du nom de l'agent, puis copiez la chaîne du compte principal.
Le format du compte principal ressemble à l'exemple suivant :
principal://agents.global.org-ORG_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_IDDans la console Google Cloud , accédez à IAM :
Recherchez le compte principal d'identité de l'agent dans la liste des comptes principaux. Vous pouvez effectuer une recherche à l'aide de l'
REASONING_ENGINE_IDspécifique à la fin de la chaîne du compte principal. Pour obtenir le principal de l'identité de l'agent, vous avez le choix entre les options suivantes :- Si le compte principal d'identité d'agent est déjà listé, cliquez sur Modifier le compte principal à côté de l'identité d'agent.
- Si le compte principal de l'identité de l'agent n'est pas répertorié, cliquez sur Accorder l'accès pour l'ajouter en tant que compte principal.
Ajoutez ou modifiez les rôles requis pour votre configuration, tels que
roles/storage.objectViewerouroles/mcp.toolUser.Cliquez sur Enregistrer.
Selon votre configuration, vous devrez peut-être accorder manuellement des rôles supplémentaires que la boîte de dialogue des autorisations ne gère pas automatiquement. Par exemple, si votre outil MCP enregistré accède à d'autres ressources Google Cloud , comme l'interrogation de données depuis BigQuery, vous devez attribuer manuellement les rôles nécessaires, tels que le rôle de lecteur de données BigQuery (roles/bigquery.dataViewer), à l'identité de l'agent.
Déployer un agent depuis Agent Studio
Une fois que vous avez créé et prévisualisé un agent, vous pouvez le déployer en production. Pour déployer un agent à partir d'Agent Studio, procédez comme suit :
- Sur la page de la liste Agents, cliquez sur l'agent que vous souhaitez déployer. La page d'informations sur l'agent s'affiche pour l'agent sélectionné.
Cliquez sur Déployer pour ouvrir la boîte de dialogue Déployer sur une instance Agent Runtime.
Si l'identité de l'agent ne dispose pas des autorisations requises, la boîte de dialogue des autorisations s'affiche et gère cette action automatiquement. Si vous devez gérer les autorisations manuellement, consultez Gérer les autorisations d'identité d'agent et Accorder l'accès pour la délégation d'agent à agent (A2A).
Dans la fenêtre de configuration du déploiement, configurez les options suivantes :
- Nom à afficher et Description : modifiez le nom à afficher et, si vous le souhaitez, ajoutez une description pour votre agent.
- Déployer en tant qu'A2A : cochez cette case pour déployer l'agent en tant qu'élément Agent-to-Agent (A2A) que d'autres agents peuvent réutiliser. Pour les applications autonomes, ne cochez pas la case pour empaqueter l'agent en tant qu'application ADK standard.
Sélectionnez une région de déploiement dans la liste des régions disponibles, puis cliquez sur OK.
Cliquez sur Déployer.
Le déploiement crée une instance d'exécution et peut prendre jusqu'à cinq minutes. En cas de réussite, un message s'affiche dans l'onglet Flux du canevas Agent Studio. Votre agent est désormais disponible en production et peut s'intégrer de manière sécurisée à vos applications externes.
Afficher un agent déployé
Pour afficher votre agent déployé :
Dans la console Google Cloud , accédez à la page Déploiements d'Agent Platform.
Utilisez la liste Région pour filtrer par région de déploiement.
Les agents déployés qui font partie du projet sélectionné apparaissent dans la liste.
Cliquez sur le nom de l'agent spécifié. La page Métriques de l'agent s'ouvre.
Sélectionnez l'onglet Playground pour tester votre agent.
Saisissez une requête de test dans le volet de chat pour vérifier que l'agent s'exécute correctement.
Pour en savoir plus sur les métriques disponibles pour votre agent, consultez Afficher les métriques de votre agent déployé.