Créer des agents de données

Ce document explique comment créer, modifier, gérer et supprimer des agents de données dans BigQuery.

Dans BigQuery, vous pouvez avoir des conversations avec des agents de données pour poser des questions sur les données BigQuery en langage naturel. Les agents de données contiennent des métadonnées de table et des instructions de traitement des requêtes spécifiques au cas d'utilisation qui définissent la meilleure façon de répondre aux questions des utilisateurs sur un ensemble de sources de connaissances, telles que les tables, les vues ou les fonctions définies par l'utilisateur (UDF) que vous sélectionnez.

Avant de commencer

1. Vérifiez que la facturation est activée pour votre projet Google Cloud .

2. Activez les API BigQuery, Gemini Data Analytics, Gemini pour Google Cloudet Knowledge Catalog, si elles ne le sont pas déjà.

   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

Rôles requis

Pour utiliser des agents de données, vous devez disposer d'autorisations IAM (Identity and Access Management) correspondant à votre cas d'utilisation. Les sections suivantes listent les rôles requis selon que vous créez et publiez des agents, provisionnez des agents dans Gemini Enterprise, ou découvrez et utilisez des agents sur différentes surfaces. Pour en savoir plus, consultez Rôles IAM pour l'API Conversational Analytics.

• Créer, modifier, publier, partager et supprimer des agents :
  • Pour créer des agents de données dans un projet : créateur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentCreator) sur le projet. Ce rôle vous attribue automatiquement le rôle de propriétaire d'agent de données des analyses de données Gemini sur les agents de données que vous créez.
  • Pour modifier, partager ou supprimer un agent de données : propriétaire d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentOwner) sur l'agent ou le projet.
  • Pour modifier un agent de données dans un projet : Éditeur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentEditor) sur le projet.
  • Pour afficher les agents de données d'un projet : Lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer) sur le projet.
• Provisionner des agents dans Gemini Enterprise :
  • Pour mettre un agent publié à la disposition des utilisateurs dans Gemini Enterprise, vous devez disposer des autorisations nécessaires pour enregistrer et gérer les agents personnalisés et configurer une passerelle d'agent dans la console d'administration Gemini Enterprise.
• Découvrir et utiliser des agents :
  • Pour discuter avec des agents de données : Utilisateur d'agent d'analyse de données Gemini (roles/geminidataanalytics.dataAgentUser).
  • Pour afficher tous les agents de données du projet : Lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer).
  • Pour interagir avec l'interface de chat optimisée par Gemini dans Data Studio : utilisateur BigQuery Studio (roles/bigquery.studioUser) ou utilisateur Gemini pour Google Cloud (roles/cloudaicompanion.user), qui fournissent chacun l'autorisation cloudaicompanion.topics.create. Attribuez ces rôles au niveau du projet. Les utilisateurs doivent également disposer du rôle Lecteur de composants Data Studio (roles/datastudio.viewer).
• Ajouter des sources de connaissances à un agent :
  • Lecteur Data Catalog (roles/datacatalog.viewer) sur le projet.

Pour avoir des conversations, consultez les rôles requis pour les conversations.

Les agents agissent en votre nom et utilisent vos autorisations. Les agents ne peuvent accéder qu'aux données et aux ressources auxquelles vous êtes autorisé à accéder.

Bonnes pratiques

L'analyse conversationnelle exécute automatiquement des requêtes en votre nom pour répondre à vos questions. Tenez compte des facteurs suivants qui peuvent augmenter le coût des requêtes :

• Tables volumineuses
• Utilisation de jointures de données dans les requêtes
• Appels fréquents aux fonctions d'IA dans les requêtes

Générer des insights

Vous pouvez éventuellement générer des insights sur les données dans Knowledge Catalog pour toute table que vous souhaitez utiliser comme source de connaissances.

Les insights générés fournissent des métadonnées de table que l'agent de données peut utiliser pour générer des réponses à vos questions.

Si vous ne générez pas d'insights au préalable, le système les génère automatiquement lorsque vous sélectionnez une table comme source de connaissances lors de la création d'un agent de données.

Utiliser l'agent d'exemples de données

Si vous ne savez pas comment configurer des agents pour l'analyse conversationnelle, vous pouvez éventuellement afficher l'exemple d'agent prédéfini généré pour chaque projetGoogle Cloud . Vous pouvez discuter avec lui et afficher ses paramètres pour voir comment il a été créé, mais vous ne pouvez pas le modifier.

Pour afficher l'agent exemple :

1. Dans la console Google Cloud , accédez à la page Agents de BigQuery.

   Accéder à la page "Agents"

2. Sélectionnez l'onglet Catalogue d'agents.

3. Dans la section Exemples d'agents par Google, cliquez sur la fiche de l'exemple d'agent.

Créer un agent de données

Les sections suivantes expliquent comment créer un agent de données.

Une fois que vous avez créé un agent, vous pouvez modifier ses paramètres.

Remarque : Si vous êtes dans une conversation avec une source de données, vous pouvez également créer un agent à partir de cette conversation.

Premières étapes

1. Dans la console Google Cloud , accédez à la page Agents de BigQuery.

   Accéder aux agents

2. Sélectionnez l'onglet Catalogue d'agents.

3. Cliquez sur New agent (Nouvel agent). La page Nouvel agent s'ouvre.

4. Dans la section Éditeur, dans le champ Nom de l'agent, saisissez un nom descriptif pour l'agent de données, par exemple Q4 sales data ou User activity logs.

5. Dans le champ Description de l'agent, saisissez une description de l'agent de données. Une bonne description explique ce que fait l'agent, quelles données il utilise et vous aide à savoir quand il s'agit du bon agent de données avec lequel discuter (par exemple, Ask questions about customer orders and revenue).

6. Dans la section Sources de connaissances, cliquez sur Ajouter une source. La page Ajouter une source de connaissances s'ouvre.

7. Dans la section Récents, sélectionnez les tables, vues, graphiques ou fonctions définies par l'utilisateur que vous souhaitez utiliser comme sources de connaissances. Les fonctions définies par l'utilisateur sont précédées d'un indicateur "fx" dans la console Google Cloud .

8. Pour afficher d'autres sources de connaissances, sélectionnez Afficher plus.

9. Facultatif : Ajoutez une source de connaissances qui ne figure pas dans la section Récents :

   1. Dans la section Rechercher, saisissez le nom de la source dans le champ Rechercher des tables, puis appuyez sur Entrée. Le nom de la source n'a pas besoin d'être exact.

   2. Dans la section Résultats de recherche, sélectionnez une ou plusieurs sources.

10. Cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

Personnaliser les descriptions des tables et des champs

Pour améliorer la précision de l'agent de données, vous pouvez éventuellement fournir des métadonnées de table supplémentaires. Seul l'agent de données utilise ces métadonnées, qui n'ont aucune incidence sur la table source.

Suivez ces bonnes pratiques lorsque vous créez des descriptions de tables et de champs :

• Utilisez ces descriptions comme guide pour comprendre comment l'agent de données interprète le schéma. Si les descriptions suggérées par l'agent sont correctes, vous pouvez les accepter.

• Si l'agent de données ne semble pas comprendre le schéma après que vous avez configuré ces descriptions, ajustez-les manuellement pour fournir les informations correctes.

Pour configurer les descriptions des tables et des champs, procédez comme suit :

1. Dans la section Sources de connaissances, cliquez sur le lien Personnaliser d'un tableau.

2. Créez une description de table. Vous pouvez saisir une description dans le champ Description de la table ou accepter la suggestion de Gemini.

3. Dans la section Champs, examinez les descriptions de champs suggérées par Gemini.

4. Sélectionnez les descriptions de champs que vous souhaitez accepter, puis cliquez sur Accepter les suggestions. Sélectionnez les descriptions que vous souhaitez refuser, puis cliquez sur Refuser les suggestions.

5. Modifiez manuellement la description d'un champ en cliquant sur Modifier à côté du champ. Le volet Modifier le champ s'ouvre.

   1. Dans le champ Description, saisissez une description du champ.
   2. Pour enregistrer la description du champ, cliquez sur Mettre à jour.

6. Pour enregistrer les modifications apportées à la description et aux champs, cliquez sur Mettre à jour. La page du nouvel agent s'ouvre à nouveau.

7. Répétez ces étapes pour chaque table à personnaliser.

Remarque : Si vos modifications apportées aux descriptions ne sont pas reflétées dans la console Google Cloud , vous pouvez utiliser la méthode list pour les vérifier ou la méthode patch pour les mettre à jour.

Créer des instructions pour l'agent

L'agent doit comprendre le contexte des questions des utilisateurs sans avoir besoin d'instructions personnalisées. Ne créez des instructions personnalisées pour l'agent que si vous devez modifier son comportement ou améliorer le contexte d'une manière qui n'est pas déjà prise en charge par d'autres fonctionnalités de contexte (par exemple, les métadonnées personnalisées des tables et des champs, ou les requêtes validées).

Dans la section Instructions, saisissez les instructions pour l'agent de données dans le champ Instructions pour l'agent. Étant donné que l'agent de données utilise ces instructions pour comprendre le contexte des questions des utilisateurs et fournir des réponses, veillez à ce qu'elles soient aussi claires que possible.

Si vous n'obtenez pas de réponse satisfaisante de l'agent, ajoutez du contexte structuré, comme des descriptions, des exemples ou des termes de glossaire. Si vous n'obtenez toujours pas de réponse satisfaisante, ajoutez des instructions personnalisées comme dans les exemples du tableau ci-dessous.

Pour voir d'autres exemples d'instructions, cliquez sur Afficher des exemples.

Type d'information	Description	Exemples
Champs clés	Champs les plus importants pour l'analyse.	"Les champs les plus importants de cette table sont : Numéro client, ID produit, Date de la commande."
Filtrer et regrouper	Champs que l'agent doit utiliser pour filtrer et regrouper les données.	"Lorsqu'une question porte sur une chronologie ou sur une période, utilisez toujours la colonne order_created_date." "Quand quelqu'un dit 'par produit', regroupe les données par colonne product_category."
Filtrage par défaut	Champs sur lesquels filtrer par défaut.	"Sauf indication contraire, filtrez toujours les données sur order_status = 'Complete'."
Synonymes et termes métier	Termes alternatifs pour les champs clés.	"Si quelqu'un pose une question sur les revenus ou les ventes, utilisez la colonne total_sale_amount." "Nous considérons comme clients 'fidèles' ceux dont le nombre d'achats est supérieur à 5."
Champs exclus	Champs que l'agent de données doit éviter d'utiliser.	"Ne jamais utiliser ces champs : "Date de transaction déduite", "Ville déduite"."
Relations de jointure	La façon dont deux tables ou plus sont liées entre elles et les colonnes utilisées pour les joindre. L'agent doit utiliser des jointures SQL standard sur des paires de colonnes pour combiner les données. Consultez la colonne d'exemple.	Activité client order_items.user_id = users.id (pour associer les ventes aux clients) events.user_id = users.id (pour associer l'activité sur le site Web aux clients connectés)

Créer des requêtes validées

Un agent utilise des requêtes validées de deux manières :

• Si un agent peut utiliser une requête validée pour répondre à une question que vous lui posez, il l'appelle exactement telle qu'elle est écrite pour garantir une réponse fiable.
• Si l'agent ne peut pas utiliser la requête validée pour répondre à une question, il l'utilise tout de même comme référence pour comprendre les données et les bonnes pratiques pour les interroger.

Vous pouvez sélectionner des requêtes validées dans une liste générée par le système ou créer les vôtres.

Remarque : Pour créer une requête validée paramétrée, consultez Créer des requêtes validées paramétrées.

Pour créer une requête validée pour l'agent de données, anciennement appelée requête de référence, procédez comme suit :

1. Sélectionnez une ou plusieurs requêtes validées suggérées par Gemini :

   1. Dans la section Requêtes validées, cliquez sur Examiner les suggestions. La page Consulter les requêtes validées suggérées s'ouvre.
   2. Examinez les requêtes validées suggérées. Sélectionnez toutes les options qui s'appliquent à votre cas d'utilisation.
   3. Cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

2. Pour créer votre propre requête validée, cliquez sur Ajouter une requête. La page Ajouter une requête validée s'ouvre.

   1. Dans le champ Question, saisissez la question de l'utilisateur à laquelle la requête validée répond.
   2. Cliquez sur Générer du code SQL pour que Gemini génère une requête validée correspondant à la question de l'utilisateur que vous avez spécifiée.
   3. Modifiez la requête validée si vous le souhaitez.
   4. Cliquez sur Exécuter et vérifiez que la requête renvoie les résultats attendus.
   5. Cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

3. Répétez ces étapes si nécessaire pour créer d'autres requêtes validées.

Créer des requêtes validées paramétrées

Les requêtes validées paramétrées extraient les valeurs de la question d'un utilisateur pour l'agent d'analyse conversationnelle et fournissent des résultats personnalisés.

Les analystes et les créateurs peuvent créer des modèles SQL réutilisables contenant des espaces réservés pour ces valeurs. Les modèles remplacent dynamiquement les paramètres au moment de l'exécution pour répondre à un plus grand nombre de questions des utilisateurs que les requêtes validées standards.

Lorsqu'un utilisateur pose une question qui correspond au modèle, l'agent d'analyse conversationnelle extrait les valeurs des paramètres de la question (par exemple, le nom du produit, la région et la date). Il injecte ensuite ces valeurs dans la requête paramétrée. Les réponses correspondantes du modèle de requête s'affichent comme validées.

Les requêtes validées paramétrées améliorent considérablement la puissance et la flexibilité des requêtes validées. Elles garantissent des réponses cohérentes et fiables pour différentes entrées, et réduisent le nombre de requêtes individuelles à gérer.

Fonctionnement

Un expert, tel qu'un analyste de données, définit une requête validée à l'aide d'un modèle de question (par exemple, "Quelles ont été les ventes de @product en @region ?"). Ensuite, l'expert crée ou modifie la requête validée à l'aide de paramètres SQL, comme illustré dans l'exemple suivant :

SELECT * FROM sales WHERE region = @region AND product = @product

Une fois la requête validée enregistrée, un utilisateur peut poser une question à l'agent d'analyse conversationnelle en langage naturel. Par exemple, "Quelles ont été les ventes d'ordinateurs portables en Amérique du Nord ?"

Pour répondre à la question de l'utilisateur, l'agent effectue les étapes suivantes :

1. Fait correspondre la question au modèle associé à la requête validée paramétrée. L'agent utilise la compréhension du langage naturel (NLU) pour identifier et extraire les valeurs de @region (Amérique du Nord) et @product (ordinateurs portables) de la question de l'utilisateur.
2. Remplace les valeurs extraites dans les espaces réservés @region et @product du modèle SQL.
3. Exécute la requête SQL complète (par exemple, SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops').
4. Il renvoie les résultats à l'utilisateur. Les correspondances sont toujours marquées comme validées.

Conseils pour créer des requêtes paramétrées efficaces

• Utilisez des noms de paramètres clairs. Utilisez des noms descriptifs pour les paramètres (par exemple, @start_date au lieu de @d1).
• Créez des descriptions détaillées des paramètres. Le grand modèle de langage (LLM) pour l'analyse conversationnelle utilise les descriptions des paramètres pour identifier les paramètres et leurs valeurs à partir des questions des utilisateurs. Par exemple, num_enrollments est un nom de paramètre efficace, mais number of student enrollments from ages 5-14 est une description de paramètre qui donne plus de contexte sur la requête.
• Assurez la cohérence des types de données. Assurez-vous que les types de données attendus par la requête SQL correspondent aux types de données susceptibles d'être extraits de la question de l'utilisateur.
• Fournissez un champ d'application bien défini. Créez des modèles pour les modèles de questions courants et importants lorsque la construction de la requête est complexe ou que la logique n'est pas intuitive. Cela permet au LLM de renvoyer des résultats optimaux.
• Testez minutieusement. Effectuez des tests avec différentes formulations en langage naturel pour vous assurer que les paramètres sont extraits correctement.

Créer une requête validée paramétrée

Vous pouvez sélectionner des requêtes validées dans une liste générée par le système ou créer les vôtres.

Avant de créer ou de modifier une requête, rédigez-la en tenant compte du modèle de langage naturel et de votre question. Par exemple, si vous demandez "Connaît-on le stock total de bananes bio dans l'entrepôt US-EAST ?", vous pouvez reformuler la question en tant que requête validée paramétrée : "Quel est le stock total de @product dans l'entrepôt @region ?". L'agent transforme cette question en requête SQL que vous mettez à jour avec des valeurs par défaut.

Pour créer une requête paramétrée validée pour un agent de données, vous pouvez créer une requête lorsque vous créez un agent ou modifier une requête validée existante pour un agent nouveau ou existant.

Les instructions suivantes utilisent un exemple de requête validée à configurer avec des paramètres.

Sélectionner une requête validée existante suggérée par Gemini

1. Dans la section Requêtes validées d'un agent nouveau ou existant, cliquez sur Examiner les suggestions. La page Consulter les requêtes validées suggérées s'ouvre.
2. Cochez la case à côté d'une requête validée suggérée.
3. Dans la fenêtre de requête, cliquez sur Afficher plus pour développer la description de la requête.
4. Pour ouvrir la requête existante, cliquez sur Modifier.
5. Pour terminer la configuration de la requête, consultez Configurer les paramètres de la requête validée.

Créer un agent, puis créer une requête validée

1. Consultez Premières étapes et suivez les étapes de configuration restantes jusqu'à Requêtes validées.
2. Dans la console Google Cloud , dans la section Requêtes validées du nouvel agent, cliquez sur Ajouter une requête. La page Ajouter une requête validée s'ouvre.
3. Pour terminer la configuration de la requête, consultez Configurer les paramètres de la requête validée.

Configurer les paramètres de la requête validée

1. Dans le champ Question, saisissez la question de l'utilisateur à laquelle la requête validée répond.
2. Pour spécifier des paramètres, utilisez le symbole @ suivi d'un nom de paramètre. Cette syntaxe identifie un espace réservé qui ingère une valeur de la question de l'utilisateur. Utilisez une question en langage naturel qui montre comment les paramètres seront utilisés dans les questions des utilisateurs. Par exemple : "Quel est le stock total pour @product dans l'entrepôt @region ?"

3. Cliquez sur Generate SQL (Générer SQL). Le code SQL se présente comme suit :

      SELECT
          SUM(stock) AS total_stock
      FROM
          inventory
      WHERE
          product_id = @product
          AND region = @region;
   

4. Pour ajouter des valeurs par défaut aux espaces réservés de la requête, cliquez sur Gérer les paramètres de requête, puis sur Ajouter un paramètre de requête.

5. Pour le premier paramètre, quatre champs s'affichent : Nom, Type, Valeur et Description.

   • Dans le champ Nom, copiez @product de votre question et collez-le dans ce champ.
   • Dans le champ Type, sélectionnez STRING.
   • Pour Valeur, saisissez organic bananas.
   • Dans le champ Description, saisissez une description aussi précise que possible. Par exemple, un produit situé dans un entrepôt régional.

6. Pour le deuxième paramètre, cliquez sur Ajouter un paramètre de requête.

   • Dans le champ Name (Nom), copiez @region à partir de votre question et collez-le dans ce champ.
   • Pour Type, sélectionnez STRING.
   • Pour Valeur, saisissez US-EAST.
   • Dans le champ Description, saisissez une description aussi précise que possible, par exemple a regional warehouse where products are located..

7. Une fois que vous avez renseigné les champs des deux paramètres, cliquez sur Enregistrer.

Tester la requête validée paramétrée

1. Cliquez sur Exécuter et vérifiez que la requête renvoie les résultats attendus.
2. Pour tester la requête pour les utilisateurs sur un écran ultérieur, copiez l'intégralité du champ de question.
3. Cliquez sur Enregistrer pour quitter l'écran Ajouter une requête et revenir à la page Modifier de l'agent.
4. Sur la page Modifier de l'agent, collez le champ de question que vous avez copié précédemment dans la fenêtre Aperçu.
   1. Remplacez la variable @product par organic bananas.
   2. Remplacez la variable @region par US-EAST.
5. Appuyez sur la touche "Entrée". Vérifiez le résultat. Dans ce cas, une réponse valide est le nombre total de bananes en stock dans la région US-EAST, par exemple 1 000.
6. Pour créer ou modifier d'autres requêtes validées, répétez ces étapes si nécessaire.

Maintenant que vous avez enregistré la requête, un utilisateur peut poser la question suivante : "Connaissons-nous le stock total de bananes bio dans l'entrepôt US-EAST ?" L'analyse conversationnelle effectue ensuite les opérations suivantes :

1. Associe cette question au modèle.
2. Extrait le paramètre @product en tant que @product = "bananes bio" et le paramètre @region = "US-EAST" de la question.
3. Exécute la requête : SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';
4. Renvoie la valeur total_stock calculée.

Créer ou examiner des termes de glossaire

Vous pouvez créer des termes de glossaire BigQuery personnalisés locaux pour un agent ou examiner les termes de glossaire d'entreprise importés depuis Knowledge Catalog qui s'appliquent aux sources de connaissances que vous avez sélectionnées pour un agent.

• Étant donné que les termes du glossaire d'entreprise de Knowledge Catalog s'appliquent globalement aux ressources BigQuery, si vous utilisez Knowledge Catalog, créez et gérez les termes du glossaire d'entreprise dans Knowledge Catalog plutôt que pour des agents individuels.
• Si vous devez modifier des termes du glossaire d'entreprise importés depuis Knowledge Catalog, vous devez les modifier dans Knowledge Catalog, puis revenir à BigQuery pour les voir.
• Les termes de glossaire personnalisés BigQuery restent dans BigQuery. Ils n'apparaissent pas dans Knowledge Catalog.
• Si vous n'utilisez pas Knowledge Catalog, vous pouvez créer des termes de glossaire BigQuery personnalisés pour les termes que vous devez définir pour un agent spécifique.

Pour créer des termes de glossaire personnalisés pour un agent, procédez comme suit :

1. Dans la section Glossaire de la page Éditeur de l'agent, cliquez sur Ajouter un terme.
2. Dans la section Conditions personnalisées, vous pouvez modifier ou supprimer des conditions personnalisées existantes.
3. Pour créer un ou plusieurs termes, cliquez sur Créer un terme.
   1. Saisissez un terme, une définition et un ou plusieurs synonymes séparés par une virgule.
   2. Pour créer le terme, cliquez sur Ajouter.
   3. Si vous souhaitez supprimer le nouveau terme, cliquez sur Supprimer.
4. Pour créer d'autres termes personnalisés, répétez ces étapes.

Pour afficher les termes du glossaire d'entreprise importés depuis Knowledge Catalog, procédez comme suit :

1. Dans la section Glossaire de la page Éditeur de l'agent, cliquez sur Ajouter un terme.
2. Accédez à la section de la page intitulée Importé depuis Dataplex.
3. Pour modifier les termes importés dans Knowledge Catalog, cliquez sur Accéder aux glossaires Dataplex.
4. Après avoir modifié les termes dans Knowledge Catalog, vous pouvez revenir à la page Éditeur de l'agent pour afficher les termes modifiés.

Configurer les paramètres

Dans la section Paramètres, vous pouvez configurer les paramètres facultatifs suivants :

1. Dans la section Modèle, choisissez les types de modèles disponibles pour les utilisateurs dans une conversation avec l'agent. Les modèles en preview et en disponibilité générale sont disponibles par défaut. Les modèles en version preview peuvent utiliser le point de terminaison global.

2. Créez des libellés pour vous aider à organiser vos ressourcesGoogle Cloud . Les étiquettes sont des paires clé/valeur qui vous permettent de regrouper des objets associés ou de les combiner à d'autres Google Cloud ressources.

   1. Dans la section Paramètres, cliquez sur Gérer les libellés.
   2. Cliquez sur Ajouter une étiquette.
   3. Dans les champs clé et valeur, saisissez votre paire clé/valeur pour l'étiquette.
   4. Si vous souhaitez ajouter d'autres libellés, cliquez à nouveau sur Ajouter un libellé.
   5. Pour supprimer un libellé, cliquez sur Supprimer.
   6. Lorsque vous avez terminé, cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

3. Définissez une limite de taille pour les requêtes traitées par l'agent de données. Dans la section Paramètres, saisissez une valeur dans le champ Nombre maximal d'octets facturés. Vous devez définir cette limite sur 10485760 ou plus, sinon le message d'erreur suivant s'affiche :

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

Si vous ne spécifiez pas de valeur, maximum bytes billed est défini par défaut sur le quota d'utilisation des requêtes par jour du projet. Le quota d'utilisation par jour est illimité, sauf si vous avez spécifié un quota personnalisé.

Passez à la section suivante pour placer l'agent en mode brouillon ou le publier.

Prévisualiser et publier l'agent

1. Dans la section Aperçu, saisissez un exemple de question d'utilisateur dans le champ Poser une question, puis appuyez sur Entrée. Pour vérifier que l'agent de données renvoie les données attendues, examinez sa réponse. Si la réponse ne correspond pas à vos attentes, modifiez les paramètres de la section Éditeur pour affiner la configuration de l'agent de données jusqu'à obtenir des réponses satisfaisantes. Vous pouvez continuer à tester et à modifier votre agent pour affiner ses résultats.

2. Cliquez sur Enregistrer.

3. Pour placer l'agent de données en mode brouillon, que vous pourrez modifier ultérieurement, cliquez sur Retour pour revenir à la page Catalogue d'agents. Comme votre agent est désormais en mode brouillon, il apparaît dans la section Mes agents brouillons de l'onglet Catalogue d'agents.

   Pour publier votre agent, restez sur la page de création de l'agent et passez à l'étape suivante.

4. Cliquez sur Publier pour ouvrir le volet Canaux de publication et publier l'agent de données, le rendant disponible pour une utilisation dans le projet.

5. Facultatif : Dans la boîte de dialogue Votre agent a été publié, cliquez sur Partager pour partager l'agent de données avec d'autres utilisateurs.

   1. Dans le volet Autorisations de partage, cliquez sur Ajouter un compte principal.

   2. Dans le champ Nouveaux comptes principaux, saisissez un ou plusieurs comptes principaux.

   3. Cliquez sur la liste Sélectionner un rôle.

   4. Dans la liste Rôle, sélectionnez l'un des rôles suivants :

      • Utilisateur d'agent d'analyse de données Gemini (roles/geminidataanalytics.dataAgentUser) : accorde l'autorisation de discuter avec l'agent de données.
      • Éditeur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentEditor) : accorde l'autorisation de modifier l'agent de données.
      • Lecteur d'agent de données Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) : accorde l'autorisation d'afficher l'agent de données.

6. Cliquez sur Enregistrer.

7. Pour revenir à la page du nouvel agent, cliquez sur Fermer. Dès que vous avez enregistré ou publié votre agent, vous pouvez le voir dans le catalogue d'agents.

Vous pouvez créer des conversations avec l'agent de données à l'aide de BigQuery Studio ou de Data Studio. Vous pouvez également créer votre propre interface pour discuter avec l'agent de données à l'aide de l'API Conversational Analytics. Pour en savoir plus sur la publication dans Data Studio, consultez Publier un agent de données dans Data Studio. Pour savoir comment publier dans Gemini Enterprise, consultez Publier un agent de données dans Gemini Enterprise.

Gérer les agents de données

Vous trouverez les agents existants dans l'onglet Catalogue d'agents, qui se compose de trois sections :

• Mes agents : liste de tous les agents que vous créez et publiez. Vous pouvez modifier et partager des agents publiés avec d'autres utilisateurs.
• Mes agents brouillons : agents que vous n'avez pas encore publiés. Vous ne pouvez pas partager d'agents brouillons.
• Partagés par d'autres membres de votre organisation : agents créés par d'autres utilisateurs et partagés avec vous. Si d'autres personnes vous accordent des autorisations, vous pouvez modifier ces agents partagés.

Modifier un agent de données

Pour modifier un agent de données, procédez comme suit :

1. Accédez à la page Agents de BigQuery.

   Accéder à la page "Agents"

2. Sélectionnez l'onglet Catalogue d'agents.

3. Recherchez la fiche de l'agent de données que vous souhaitez modifier.

4. Pour ouvrir l'agent de données dans l'éditeur d'agents, cliquez sur Ouvrir les actions > cliquez sur Modifier sur la fiche de l'agent.

5. Modifiez la configuration de l'agent de données si nécessaire.

6. Pour enregistrer vos modifications sans les publier, cliquez sur Enregistrer.

7. Pour publier vos modifications, cliquez sur Publier . Dans la boîte de dialogue Partager, vous pouvez partager l'agent avec d'autres utilisateurs ou cliquer sur Annuler.

8. Pour revenir au volet Agents, cliquez sur Retour.

   

Partager un agent de données

Pour partager un agent de données publié, procédez comme suit. Vous ne pouvez pas partager d'agents brouillons.

1. Accédez à la page Agents de BigQuery.

   Accéder à la page "Agents"

2. Sélectionnez l'onglet Catalogue d'agents.

3. Recherchez la fiche de l'agent de données que vous souhaitez modifier.

4. Pour ouvrir l'agent de données dans l'éditeur d'agent, cliquez sur Ouvrir les actions > Modifier sur la fiche de l'agent.

5. Pour partager l'agent de données avec d'autres utilisateurs, cliquez sur Partager.

6. Dans le volet Autorisations de partage, cliquez sur Ajouter un compte principal.

7. Dans le champ Nouveaux comptes principaux, saisissez un ou plusieurs comptes principaux.

8. Cliquez sur la liste Sélectionner un rôle.

9. Dans la liste Rôle, sélectionnez l'un des rôles suivants :

   • Utilisateur d'agent de données Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser) : autorise à discuter avec l'agent de données.
   • Éditeur d'agent de données des analyses de données Gemini (roles/geminidataanalytics.dataAgentEditor) : autorise la modification de l'agent de données.
   • Lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer) : autorise l'affichage de l'agent de données.

10. Cliquez sur Enregistrer.

11. Pour revenir à la page de modification de l'agent, cliquez sur Fermer.

12. Pour revenir au volet Agents, cliquez sur Retour.

    

Supprimer un agent de données

1. Accédez à la page Agents de BigQuery.

   Accéder à la page "Agents"

2. Sélectionnez l'onglet Catalogue d'agents.

3. Dans la section Mes agents ou Mes brouillons d'agents de l'onglet Catalogue d'agents, recherchez la fiche de l'agent de données que vous souhaitez supprimer.

4. Cliquez sur Ouvrir les actions > Supprimer.

5. Dans la boîte de dialogue Supprimer l'agent ?, cliquez sur Supprimer.

Publier un agent de données dans Data Studio

Lorsque vous publiez votre agent et que vous le partagez avec les utilisateurs de Data Studio, l'agent s'affiche automatiquement pour ces utilisateurs sur la page Discuter avec vos données de Data Studio.

Créer et publier votre agent dans Data Studio

En tant qu'analyste de données, vous pouvez créer, modifier et publier un agent dans Data Studio en procédant comme suit :

1. Créez ou modifiez votre agent de données dans BigQuery.
2. Publiez l'agent. Lorsque vous publiez l'agent, sélectionnez Data Studio comme option de publication.
3. Suivez les instructions pour partager l'agent, en accordant les rôles Identity and Access Management appropriés à vos utilisateurs Data Studio.

Partager votre agent avec des utilisateurs Data Studio

Vous pouvez partager des agents avec des utilisateurs Data Studio directement en copiant un lien qui ouvre une conversation avec l'agent dans Data Studio. Vous pouvez également envoyer un e-mail pour informer l'utilisateur qu'il a accès à un agent.

Pour partager un lien direct vers l'agent, vous pouvez copier l'URL dédiée de l'agent de l'une des manières suivantes :

• Dans le catalogue d'agents : sélectionnez Ouvrir les actions > sélectionnez Copier le lien > sélectionnez Data Studio.
• Dans la vue détaillée de l'agent, sélectionnez Copier le lien de l'agent > sélectionnez Data Studio.
• Dans le menu à développer Partager, sélectionnez Copier le lien vers l'agent dans Data Studio.
• Après avoir cliqué sur Enregistrer dans le panneau Autorisations de partage, sélectionnez Copier le lien.

Pour envoyer une notification par e-mail informant les destinataires de leur accès à un agent, sélectionnez Envoyer un e-mail dans le panneau Partager les autorisations. Les notifications par e-mail ne sont envoyées qu'aux utilisateurs ou aux groupes avec lesquels vous venez de partager l'agent au cours de cette session de modification. Tous les membres d'un groupe reçoivent la notification par e-mail, même si un utilisateur donné dispose déjà d'une autorisation au niveau de l'agent. L'e-mail inclut le nom de l'utilisateur qui a partagé l'agent, le nom de l'agent et un lien pour ouvrir l'agent dans Data Studio.

Remarque : Si vous envoyez un e-mail à un groupe Google dont le paramètre Qui peut publier des messages est défini sur Membres du groupe uniquement, un propriétaire ou un gestionnaire du groupe doit modifier le paramètre du groupe et le définir sur Toute l'organisation pour activer la distribution.

Publier un agent de données dans Gemini Enterprise

Vous pouvez publier un agent de données BigQuery dans Gemini Enterprise afin que les utilisateurs professionnels puissent interroger et analyser des données en langage naturel directement dans Gemini Enterprise. Ce processus implique généralement une collaboration entre les analystes de données, les administrateurs Gemini Enterprise et les utilisateurs professionnels. Pour en savoir plus sur les rôles requis pour ces utilisateurs, consultez Rôles requis.

Pour publier un agent de données dans Gemini Enterprise, procédez comme suit :

1. Vérifiez les conditions préalables.
2. Créez et publiez l'agent de données dans BigQuery.
3. Provisionnez l'agent dans Gemini Enterprise.
4. Découvrez l'agent et discutez avec lui.

Consulter les prérequis

La méthode recommandée pour publier des agents d'analyse conversationnelle BigQuery consiste à utiliser Agent Registry. Suivez les conditions préalables de cette section pour vous assurer que l'agent est détectable dans Gemini Enterprise.

Vous pouvez également publier l'agent à l'aide du fichier JSON de la carte A2A. Si vous utilisez cette méthode, consultez Créer et publier l'agent de données dans BigQuery.

Pour utiliser Agent Registry, vous devez d'abord configurer la passerelle d'agent avec le mappage de région approprié. La région de stockage de l'agent de données BigQuery et la liaison de registre Agent Gateway dans Gemini Enterprise doivent correspondre.

Vous configurez la région de stockage de l'agent dans la section Région de l'éditeur d'agent de l'interface utilisateur Web de BigQuery. Vous ne pourrez plus modifier la région une fois l'agent enregistré.

L'image suivante montre les options de région disponibles dans Agent Gateway :

En tant qu'administrateur Gemini Enterprise, configurez une passerelle d'agent pour votre application Gemini Enterprise en procédant comme suit :

1. Configurez une passerelle Agent Gateway qui inclut la liaison Agent Registry correspondant à la région de votre agent de données. Les options sont États-Unis, Europe ou Monde.
2. Dans Gemini Enterprise, ouvrez votre application, accédez à Sécurité > Configuration, puis saisissez le nom de ressource de la passerelle dans la section Configuration de la passerelle d'agent. Pour obtenir des instructions détaillées, consultez Router le trafic Gemini Enterprise via Agent Gateway.

Créer et publier l'agent de données dans BigQuery

En tant qu'analyste de données, vous créez, configurez et publiez un agent dans BigQuery en procédant comme suit :

1. Dans BigQuery, créez ou modifiez votre agent de données.
2. Dans la section Région, vérifiez que la région de stockage correspond à vos sources de données et à la configuration de votre Agent Gateway. Les options sont US, EU ou Global.
3. Cliquez sur Publier ou sur Publier les mises à jour si l'agent a déjà été publié.
4. Dans le volet Canaux de publication, sous Canaux supplémentaires, choisissez votre méthode de publication :
   • Si BigQuery et Gemini Enterprise se trouvent dans le même projet, dans la section Registre d'agents, cochez la case Enregistrer cet agent.
     • Si vous souhaitez supprimer l'agent du registre, cliquez sur Annuler l'enregistrement.
   • Si BigQuery et Gemini Enterprise se trouvent dans des projets différents, dans la section Intégrer via A2A (Agent2Agent), cliquez sur Copier le JSON pour copier les données JSON du point de terminaison A2A, puis partagez les données JSON avec votre administrateur Gemini Enterprise. Ces données JSON sont utilisées lorsque vous provisionnez l'agent dans Gemini Enterprise.
5. Cliquez sur Publier ou Publier les modifications.
6. Partagez l'agent avec les utilisateurs et les groupes qui ont besoin d'y accéder, en leur attribuant le rôle Utilisateur d'agent de données des analyses de données Gemini (roles/geminidataanalytics.dataAgentUser).

Provisionner l'agent dans Gemini Enterprise

En tant qu'administrateur Gemini Enterprise, mettez l'agent de données à la disposition des utilisateurs de votre application à l'aide de l'une des méthodes suivantes :

Option 1 : Importer depuis Agent Registry

Pour importer l'agent agréé, procédez comme suit :

1. Si Gemini Enterprise se trouve dans un projet différent de celui de BigQuery, suivez les étapes ci-dessous pour enregistrer manuellement l'agent dans le registre d'agents. Sinon, ignorez cette étape :
   1. Dans la console Google Cloud , accédez à Registre d'agents dans le même projet que Gemini Enterprise, sélectionnez l'onglet Agents, puis cliquez sur Ajouter un agent.
   2. Dans le volet Détails de l'agent, sélectionnez A2A pour Type.
   3. Pour Région, sélectionnez la région qui correspond à la configuration de votre agent de données et de votre Agent Gateway.
   4. Sélectionnez Coller le code JSON, collez les données JSON du point de terminaison A2A de BigQuery, puis cliquez sur Enregistrer.
2. Dans Gemini Enterprise, cliquez sur le nom de l'application à laquelle vous souhaitez ajouter l'agent.
3. Dans le menu de navigation, cliquez sur Agents > Ajouter un agent.
4. Dans le volet Choisir un type d'agent, recherchez Agents du registre d'agents, puis cliquez sur Ajouter.
5. Dans le volet Ajouter un agent, recherchez l'agent par nom, ID de registre d'agent, type, producteur ou cas d'utilisation, ou recherchez la fiche de l'agent dans la liste.
6. Sur la fiche de l'agent, cliquez sur Ajouter un agent.
7. À l'étape Vérifier les détails de l'agent, vérifiez les métadonnées de l'agent renseignées à partir de sa fiche A2A, y compris le nom, la description, l'URL de l'agent, les capacités et les compétences, puis cliquez sur Suivant.
8. À l'étape Authentifier l'agent, sélectionnez la manière dont Gemini Enterprise s'authentifie auprès du fournisseur d'agent :
   • Identifiants gérés par Google par défaut : Google gère automatiquement les identifiants OAuth. Vous n'avez pas besoin de configurer ni de saisir manuellement les identifiants client.
   • OAuth personnalisé : ne sélectionnez cette option que si votre organisation nécessite des identifiants client OAuth personnalisés, puis saisissez l'ID client, le code secret du client, l'URL d'autorisation et l'URL du jeton.
9. Cliquez sur Terminer.
10. L'agent apparaît dans le tableau des agents avec l'état Activé et le type d'agent A2A (personnalisé).
11. Partagez l'agent avec les utilisateurs ou les groupes qui ont besoin d'y accéder.

Option 2 : Importer à l'aide du fichier JSON de la carte A2A

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Si BigQuery et Gemini Enterprise se trouvent dans des projets différents, procédez comme suit pour importer l'agent à l'aide du fichier JSON de la fiche A2A :

1. Dans Gemini Enterprise, cliquez sur le nom de l'application à laquelle vous souhaitez ajouter l'agent.
2. Dans le menu de navigation, cliquez sur Agents > Ajouter un agent.
3. Dans le volet Choisir un type d'agent, recherchez Agent personnalisé via A2A, puis cliquez sur Ajouter.
4. Dans le champ Agent card JSON (JSON de la fiche de l'agent), saisissez le JSON de la fiche de l'agent reçu de l'analyste de données.
5. Cliquez sur Prévisualiser les détails de l'agent > cliquez sur Suivant.
6. À l'étape Autorisation de l'agent, sélectionnez votre méthode d'authentification :
   • Identifiants par défaut gérés par Google : Google gère automatiquement les identifiants OAuth sans que vous ayez à saisir ou à générer manuellement un ID client et un code secret du client.
   • OAuth personnalisé : sélectionnez cette option si vous souhaitez fournir manuellement des identifiants OAuth personnalisés en suivant les étapes décrites dans Enregistrer et gérer les agents A2A.
7. À l'étape Autorisations de l'outil, cliquez sur Terminer.
8. L'agent apparaît dans le tableau des agents avec l'état Activé et le type d'agent A2A (personnalisé).
9. Partagez l'agent avec les utilisateurs ou les groupes qui ont besoin d'y accéder.

Découvrir et utiliser un agent

Vous pouvez découvrir et utiliser un agent de données dans Gemini Enterprise de l'une des manières suivantes :

• Découverte manuelle : recherchez un agent de données dans la galerie d'agents et utilisez-le avec l'une des méthodes suivantes :
  • Parcourir la galerie : sélectionnez l'agent et lancez une discussion dédiée.
  • Lien direct : utilisez l'URL dédiée de l'agent pour ouvrir Gemini Enterprise directement dans une session avec cet agent de données BigQuery spécifique.
  • Intention dirigée : invoquez l'agent en utilisant @mention (par exemple, @sales_pipeline_agent) dans le chat Gemini Enterprise.
  • Orchestration fluide : posez une question analytique générale (par exemple, "Comment notre pipeline de vente a-t-il évolué au cours des trois derniers mois ?") et Gemini Enterprise transmet automatiquement la requête à l'agent de données approprié.

Une fois l'agent découvert, vous pouvez interagir avec lui en procédant comme suit :

• S'authentifier : effectuez la connexion OAuth unique pour vous authentifier de manière sécurisée auprès de BigQuery.
• Chat : posez des questions en langage naturel à l'agent. Les requêtes sont traitées par l'agent, et la réponse est renvoyée à Gemini Enterprise sous forme de texte, de code Markdown, de graphiques ou de tableaux.
• Afficher l'historique des conversations : les conversations sont automatiquement enregistrées dans le volet de l'historique.

Surveiller les agents et les conversations

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Remarque : Pour envoyer des commentaires ou demander de l'aide concernant cette fonctionnalité, envoyez un e-mail à l'adresse [e-mail].

Vous pouvez surveiller les performances, l'adoption, la latence et les coûts de vos agents de données et de leurs conversations à l'aide de Google Cloud Observability dans BigQuery. Lorsque vous activez l'observabilité des agents, vous pouvez afficher des métriques telles que les suivantes :

• Nombre d'agents utilisés dans les conversations
• Nombre d'utilisateurs ayant posé des questions
• Nombre de conversations créées
• Les agents qui ont répondu au plus grand nombre de questions
• Sources de connaissances les plus couramment utilisées
• Engagement utilisateur
• Utilisation prévue des jetons
• Latence de réponse horaire

Avant de commencer

Activez les API Cloud Trace, Cloud Monitoring et Cloud Logging si elles ne le sont pas déjà.

Rôles requis pour activer les API

Pour activer les 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

Rôles et autorisations nécessaires

Pour activer l'observabilité des agents, vous devez disposer des autorisations suivantes sur votre projet :

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate
• cloudaicompanion.settingBindings.gibqObservabilitySettingsList
• cloudaicompanion.settingBindings.gibqObservabilitySettingsUse
• geminidataanalytics.dataAgents.create
• geminidataanalytics.operations.get
• observability.traceScopes.create
• resourcemanager.projects.update
• serviceusage.services.enable
• serviceusage.values.test

Pour obtenir les autorisations nécessaires pour surveiller vos agents à l'aide de métriques, de traces et de journaux, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

• Afficher les données et les configurations de surveillance : Lecteur Monitoring (roles/monitoring.viewer)
• Afficher les traces : Utilisateur Cloud Trace (roles/cloudtrace.user)
• Afficher les journaux : Visionneuse de journaux (roles/logging.viewer)
• Afficher les ensembles de données et leur contenu : Lecteur de données BigQuery (roles/bigquery.dataViewer)
• Afficher les paramètres d'administration : Utilisateur Gemini pour Google Cloud (roles/cloudaicompanion.user)

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.

Activer l'observabilité

L'observabilité des agents est désactivée par défaut. Un administrateur peut l'activer pour votre projet ou votre organisation. Pour activer l'observabilité pour vos agents, sélectionnez l'une des options suivantes :

Console

1. Dans la console Google Cloud , accédez à la page Agents de BigQuery.

   Accéder aux agents

2. Sélectionnez l'onglet Surveillance.

3. Si l'observabilité est désactivée, suivez les instructions pour l'activer.

Google Cloud CLI

1. Créez un paramètre d'observabilité :

   gcloud gemini gibq-observability-settings create SETTING_NAME \
     --conversational-analytics-setting-metrics-enabled \
     --conversational-analytics-setting-traces-enabled \
     --project=PROJECT_ID \
     --location=global

   Remplacez les éléments suivants :

   • SETTING_NAME : nom du paramètre d'observabilité.
   • PROJECT_ID : ID du projet.

2. Associez le paramètre d'observabilité à votre projet :

   gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
     --gibq-observability-setting=SETTING_NAME \
     --target=projects/PROJECT_ID \
     --location=global \
     --project=PROJECT_ID

   Remplacez BINDING_NAME par le nom de la liaison de paramètre. Nous vous recommandons d'utiliser binding-PROJECT_ID pour le nom de votre liaison.

API

1. Créez un paramètre d'observabilité :

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "conversational_analytics_setting": {
               "metrics_enabled": true
             }
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

   Remplacez les éléments suivants :

   • SETTING_NAME : nom du paramètre d'observabilité.
   • PROJECT_ID : ID du projet.

2. Associez le paramètre d'observabilité à votre projet :

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "target": "projects/PROJECT_ID",
             "product": "GEMINI_IN_BIGQUERY"
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

   Remplacez BINDING_NAME par le nom de la liaison de paramètre. Nous vous recommandons d'utiliser binding-PROJECT_ID pour le nom de votre liaison.

Afficher les métriques

Les métriques sont collectées après l'activation de l'observabilité. Les données ne sont pas remplies. Pour afficher les métriques de l'agent, sélectionnez l'une des options suivantes :

BigQuery

1. Dans la console Google Cloud , accédez à la page Agents de BigQuery.

   Accéder à la page "Agents"

2. Sélectionnez l'onglet Surveillance.

Cloud Monitoring

1. Dans la console Google Cloud , accédez à la page Tableaux de bord de Cloud Monitoring.

   Accéder à la page "Tableaux de bord"

2. Dans le volet Mes tableaux de bord, recherchez le tableau de bord nommé BigQuery Conversational Analytics.

3. Pour ouvrir le tableau de bord, cliquez sur son nom.

4. Facultatif : Créez un tableau de bord personnalisé.

5. Facultatif : Pour afficher les métriques individuellement, accédez à la page Explorateur de métriques.

   Accéder à l'explorateur de métriques

   Les métriques d'agent incluent l'utilisation de l'agent, les appels de modèle, l'utilisation d'outils, l'état, la latence et l'utilisation de jetons.

Déboguer les appels de modèle

Vous pouvez visualiser la séquence d'opérations au cours d'un tour de conversation, comme les appels de modèle et les appels d'outil, pour vous aider à résoudre les erreurs et la latence.

1. Dans la console Google Cloud , accédez à la page Explorateur Trace de Cloud Monitoring.

   Accéder à l'Explorateur Trace

2. Cliquez sur un segment pour l'examiner.

3. Examinez les informations du volet Détails.

4. Facultatif : Créez un tableau de bord de trace personnalisé.

Conserver les traces

Vos données Cloud Trace sont stockées dans un ensemble de données d'observabilité pendant 30 jours. Pour stocker vos données de trace plus longtemps, déplacez-les vers un ensemble de données BigQuery.

Rôles requis

Pour obtenir les autorisations nécessaires pour exposer des traces en direct à BigQuery en créant un ensemble de données associé, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

• Administrateur Cloud Trace (roles/cloudtrace.admin)
• Éditeur d'observabilité (roles/observability.editor)
• Utilisateur BigQuery (roles/bigquery.user)

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.

Migrer les données de trace vers BigQuery

Pour conserver vos données de trace, procédez comme suit :

1. Ouvrez Cloud Shell.

2. Recherchez l'emplacement de votre bucket _Trace :

   gcloud beta observability buckets list --location=-

   Notez l'emplacement de votre bucket _Trace pour l'étape suivante.

3. Créez un ensemble de données associé dans votre projet BigQuery qui pointe vers votre bucket _Trace :

   gcloud beta observability buckets datasets links create \
       projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
       --dataset=Spans \
       --bucket=_Trace \
       --location=LOCATION \
       --project=PROJECT_ID

   Remplacez les éléments suivants :

   • PROJECT_ID : ID de votre projet
   • LOCATION : emplacement de votre bucket _Trace de l'étape précédente.
   • LINK_NAME : nom de l'ensemble de données associé

4. Créez un ensemble de données standard dans lequel stocker vos traces historiques. La commande suivante définit le délai d'expiration par défaut de la partition sur 90 jours (7 776 000 secondes) :

   bq --location=LOCATION mk \
       --dataset \
       --default_partition_expiration=7776000 \
       --description="Archive storage for historical traces" \
       PROJECT_ID:STORAGE_DATASET

   Remplacez STORAGE_DATASET par le nom de l'ensemble de données.

5. Créez une table partitionnée vide dans votre ensemble de données de stockage avec le même schéma que l'ensemble de données associé. Le partitionnement par date vous aide à gérer la conservation des données et les coûts des requêtes. Pour créer la table, exécutez la requête suivante dans l'éditeur SQL :

   CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   PARTITION BY DATE(start_time)
   AS
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE FALSE;

   Remplacez TABLE_NAME par le nom de la table.

6. Créez une requête planifiée pour copier quotidiennement les données de trace de l'ensemble de données associé dans votre table d'archive. La requête suivante copie les données de la veille :

   INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE start_time >=
     TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
     AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

Pour en savoir plus, découvrez comment rechercher et explorer des traces.

Désactiver l'observabilité

Pour désactiver l'observabilité de vos agents de données, modifiez votre paramètre d'observabilité :

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

Remplacez les éléments suivants :

• SETTING_NAME : nom du paramètre d'observabilité que vous avez créé pour activer l'observabilité. Si vous avez activé l'observabilité à l'aide de la console Google Cloud , le nom du paramètre est default.
• PROJECT_ID : ID du projet.

Étapes suivantes

• En savoir plus sur Conversational Analytics dans BigQuery
• En savoir plus sur l'API Conversational Analytics
• Analysez les données à l'aide de conversations.
• Découvrez comment le rôle Lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer) permet d'afficher l'agent de données.