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 allez également utiliser le serveur MCP d'enrichissement du contexte de base de données.

Pour en savoir plus sur les agents de données, consultez Présentation des agents de données.

Pour créer le contexte de l'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.

Préparer une instance Spanner

  • Assurez-vous qu'une instance Spanner est disponible. Pour en savoir plus, consultez Créer une instance.
  • Remplissez la base de données avec les données et le schéma auxquels l'utilisateur final souhaite accéder.

Rôles et autorisations nécessaires

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 Gemini CLI
  • 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 Gemini CLI

Pour installer la CLI Gemini, consultez Premiers pas avec la CLI Gemini. Assurez-vous d'installer Gemini CLI 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 MCP Toolbox Gemini CLI :

    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-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • INSTANCE_ID : ID de votre instance Spanner.
    • DATABASE_ID : nom de la base de données à laquelle se connecter.

  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 et guidé pour générer des modèles NL2SQL structurés à partir de vos schémas de base de données. Il repose sur l'extension MCP Toolbox pour la connectivité aux bases de données. Pour en savoir plus sur l'installation du serveur MCP d'enrichissement du contexte de base de données, consultez Serveur MCP d'enrichissement du contexte de base de données.

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

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

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  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 savoir comment trouver votre clé API, consultez Utiliser des clés API Gemini.

Pour exporter la clé API Gemini, exécutez la commande suivante :

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 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 répertoire où vous avez installé la CLI Gemini, démarrez Gemini :

    gemini

  2. Configurez 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 à l'emploi :

    /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 de l'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 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_fragments. Pour en savoir plus sur les facettes, consultez Présentation des agents de données.

Pour ajouter un aspect au contexte de l'agent, procédez comme suit :

  1. Exécutez la commande /generate_targeted_fragments :

    /generate_targeted_fragments

  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 le facette générée. Vous pouvez enregistrer le facette dans un fichier de contexte d'agent ou l'ajouter à un fichier de contexte existant.

Le fichier de contexte de l'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 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 du schéma et des données de votre base de 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 du schéma de votre base de données, la génération de code SQL basée sur des modèles vous pose une série de questions pour vérifier les informations de la base de données et accorder les 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 modifier une paire de requêtes que vous souhaitez réviser.

  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 le modèle de requête approuvé, 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é sous forme de fichier JSON dans votre répertoire local.

Le fichier de contexte de l'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 de l'agent, consultez Contexte de l'agent.

Étapes suivantes