Créer des contextes à l'aide de la CLI Gemini

Ce document explique comment utiliser la CLI Gemini et la boîte à outils MCP pour créer des fichiers de contexte d'agent. Ces fichiers contiennent des modèles et des facettes qui fournissent un contexte pour générer des requêtes SQL à partir du langage naturel. Vous utiliserez également le serveur MCP d'enrichissement du contexte de la base de données.

Pour créer un fichier de contexte d'agent, procédez comme suit :

• Préparer votre environnement
• Générer des modèles ciblés
• Générer des facettes ciblées
• Facultatif. Générer des modèles groupés

Avant de commencer

Avant de créer un agent, remplissez les conditions préalables suivantes.

Activer les services requis

• API Gemini Data Analytics
• API Gemini pour Google Cloud

Préparer une instance Cloud SQL

• Assurez-vous d'avoir accès à une instance Cloud SQL existante ou créez-en une. Pour en savoir plus, consultez la page Créer des instances pour Cloud SQL.
• Assurez-vous de créer une base de données dans votre instance où vous créerez les tables. Pour en savoir plus, consultez la page Créer une base de données sur l' instance Cloud SQL.

Rôles et autorisations requis

• Ajoutez un compte d'utilisateur ou de service IAM au niveau de l'instance. Pour en savoir plus , consultez la section Ajouter une liaison de stratégie IAM à un utilisateur, un compte de service ou un groupe.
• Accordez les rôles cloudsql.studioUser et cloudsql.instanceUser à l'utilisateur IAM au niveau du projet. Pour en savoir plus, consultez la section Ajouter une liaison de stratégie IAM pour un projet.
• Vous devez également accorder des droits sur une base de données à un utilisateur ou à un compte de service IAM en vous connectant en tant qu'utilisateur de la base de données basé sur un mot de passe.
  
  GRANT ALL PRIVILEGES ON * TO "IAM_USERNAME";.
  
  Pour en savoir plus, consultez la section Accorder des droits sur une base de données à un utilisateur ou à un compte de service IAM individuel.

Accorder l'autorisation executesql à l'instance Cloud SQL

gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Préparer votre environnement

Vous pouvez créer des fichiers de contexte d'agent à partir de n'importe quel environnement de développement local ou IDE. Pour préparer l'environnement, procédez comme suit :

• Installer la CLI Gemini
• Installer et configurer la boîte à outils MCP
• Installer et configurer le serveur MCP d'enrichissement du contexte de la base de données

Installer la CLI Gemini

Pour installer la CLI Gemini, consultez la section Premiers pas avec la CLI Gemini. Assurez-vous d'installer la CLI Gemini dans un répertoire distinct, qui est également utilisé pour installer la boîte à outils MCP et le serveur MCP d'enrichissement du contexte de la base de données.

Installer et configurer la boîte à outils MCP

1. Dans le même répertoire où vous avez installé la CLI Gemini, installez l'extension de la boîte à outils MCP pour la CLI Gemini :

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. Créez un fichier de configuration tools.yaml dans le même répertoire où vous avez installé la boîte à outils MCP pour configurer la connexion à la base de données :

     sources:
       my-cloud-sql-mysql-source:
         kind: cloud-sql-mysql
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   Remplacez les éléments suivants :

   • PROJECT_ID: ID de votre Cloud de Confiance projet.
   • REGION_ID : région de votre instance Cloud SQL, par exemple us-central1.
   • INSTANCE_ID : ID de votre instance Cloud SQL.
   • DATABASE_ID : nom de la base de données à laquelle se connecter.
   • USER_NAME : utilisateur de la base de données. Pour en savoir plus sur la définition de cette valeur, consultez la section Sources dans la boîte à outils MCP.
   • PASSWORD : mot de passe de l'utilisateur de la base de données. Pour en savoir plus sur la définition de cette valeur, consultez la section Sources dans la boîte à outils MCP.

3. Vérifiez que le fichier tools.yaml est correctement configuré :

   ./toolbox --tools-file "tools.yaml"

Installer le serveur MCP d'enrichissement du contexte de la base de données

Le serveur MCP d'enrichissement du contexte de la base de données fournit un workflow interactif guidé pour générer des modèles NL2SQL structurés à partir de vos schémas de base de données. Il s'appuie sur l'extension de la boîte à outils MCP pour la connectivité à la base de données. Pour en savoir plus sur l'installation du serveur MCP d'enrichissement du contexte de la base de données, consultez la section Serveur MCP d'enrichissement du contexte de la base de données.

Pour installer le serveur MCP d'enrichissement du contexte de la base de données, procédez comme suit :

1. Dans le même répertoire où vous avez installé la CLI Gemini, installez le programme d'installation du package Python uv à l'aide de pip.

   pip install uv

   Si pip n'est pas installé, installez-le d'abord.

2. Installez le serveur MCP d'enrichissement du contexte de la base de données.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Le serveur utilise l'API Gemini pour la génération. Assurez-vous d'exporter votre clé API en tant que variable d'environnement. Pour en savoir plus sur la recherche de votre clé API, consultez la section Utiliser des clés API Gemini.

Exportez la clé API Gemini :

export GEMINI_API_KEY="YOUR_API_KEY"

Remplacez YOUR_API_KEY par votre clé API Gemini.

Générer des modèles ciblés

Si vous souhaitez ajouter une paire de requêtes spécifique en tant que modèle de requête au contexte de l'agent, vous pouvez utiliser la commande /generate_targeted_templates. Pour en savoir plus sur les modèles, consultez la présentation des agents de données.

Pour ajouter un modèle de requête au contexte de l'agent, procédez comme suit :

1. Dans le même répertoire où vous avez installé la CLI Gemini, démarrez Gemini :

   gemini

2. Effectuez la configuration de l'authentification de la CLI Gemini.

3. Vérifiez que la boîte à outils MCP et l'extension d'enrichissement de la base de données sont prêtes à être utilisées :

   /mcp list

4. Exécutez la commande /generate_targeted_templates :

   /generate_targeted_templates

5. Saisissez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

6. Saisissez la requête SQL correspondante dans le modèle de requête.

7. Examinez le modèle de requête généré. Vous pouvez enregistrer le modèle de requête en tant que fichier de contexte d'agent ou l'ajouter à un fichier de contexte existant.

Le fichier de contexte d'agent, semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json, est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur le fichier de contexte et le modèle de requête, consultez la section Contexte de l'agent.

Générer des facettes ciblées

Si vous souhaitez ajouter une paire de requêtes spécifique en tant que facette au fichier de contexte de l'agent, vous pouvez utiliser la commande /generate_targeted_facets. Pour en savoir plus sur les facettes, consultez la présentation des agents de données.

Pour ajouter une facette au contexte de l'agent, procédez comme suit :

1. Exécutez la commande /generate_targeted_facets :

   /generate_targeted_facets

2. Saisissez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

3. Saisissez la requête SQL correspondante dans le modèle de requête.

4. Examinez la facette générée. Vous pouvez enregistrer la facette dans un fichier de contexte d'agent ou l'ajouter à un fichier de contexte existant.

Le fichier de contexte d'agent, semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json, est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur le fichier de contexte et les facettes, consultez la section Contexte de l'agent.

Facultatif : Générer des modèles groupés

Si vous souhaitez générer automatiquement le fichier de contexte de l'agent en fonction de votre schéma de base de données et de vos données, vous pouvez utiliser la commande /generate_bulk_templates.

Pour générer automatiquement des modèles groupés, procédez comme suit :

1. Exécutez la commande /generate_bulk_templates :

   /generate_bulk_templates

2. En fonction de votre schéma de base de données, la génération SQL basée sur un modèle vous guide à travers une série de questions liées à la vérification des informations de la base de données et à l'octroi d'autorisations d'accès au schéma de la base de données.

3. Examinez le modèle de requête généré. Vous pouvez approuver le modèle ou mettre à jour une paire de requêtes que vous souhaitez modifier.

4. Saisissez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

5. Saisissez la requête SQL correspondante dans le modèle de requête.

6. Examinez le modèle de requête généré. Vous pouvez enregistrer le modèle de requête en tant que fichier de contexte d'agent ou l'ajouter à un fichier de contexte existant.

7. Une fois que vous avez approuvé le modèle de requête, vous pouvez créer un fichier de modèle ou ajouter les paires de requêtes à un fichier de modèle existant. Le modèle de requête est enregistré en tant que fichier JSON dans votre répertoire local.

Le fichier de contexte d'agent, semblable à my-cluster-psc-primary_postgres_templates_20251104111122.json, est enregistré dans le répertoire où vous avez exécuté les commandes.

Pour en savoir plus sur le fichier de contexte d'agent, consultez la section Contexte de l'agent.

Étape suivante

• En savoir plus sur les agents de données.
• Découvrez comment créer ou supprimer un agent de données dans Cloud SQL Studio.
• Découvrez comment inspecter et appeler un agent de données.