Intégrer QueryData à une application

Ce tutoriel explique comment configurer et utiliser QueryData dans Cloud SQL pour MySQL à l'aide de la console Google Cloud et comment l'intégrer à votre application. Découvrez comment créer le fichier d'ensemble de contextes, créer un ensemble de contextes qui utilise le fichier d'ensemble de contextes, utiliser MCP Toolbox pour appeler l'API QueryData afin de générer des requêtes SQL pour les questions en langage naturel et l'intégrer à votre application.

Pour en savoir plus, consultez la présentation de QueryData.

Objectifs

  • Créez des tables de base de données et remplissez-les avec des données.
  • Créez un fichier d'ensemble de contextes avec Gemini CLI et MCP Toolbox.
  • Créez un ensemble de contextes et importez le fichier correspondant.
  • Tester QueryData et générer des requêtes SQL dans Studio
  • Intégrez QueryData à votre application à l'aide de l'outil Gemini Data Analytics QueryData dans MCP Toolbox.
  • Ajoutez un ancrage aux réponses LLM à l'aide de requêtes de recherche de valeurs.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Pour éviter de continuer à payer des frais, supprimez les ressources que vous avez créées une fois que vous avez terminé les tâches décrites dans ce document. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Remplissez les conditions préalables suivantes avant de créer un ensemble de contexte.

Activer les services requis

Activez les services suivants pour votre projet :

Préparer une instance Cloud SQL

Rôles et autorisations nécessaires

Accorder l'autorisation executesql à l'instance Cloud SQL

Pour accorder l'autorisation executesql à l'instance Cloud SQL et activer l'API Cloud SQL Data, exécutez la commande suivante : 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Remplacez les éléments suivants :
  • PROJECT_ID : ID de votre projet Google Cloud .
  • INSTANCE_ID : ID de votre instance Cloud SQL.
Pour effectuer les étapes de ce tutoriel, connectez-vous à Google Cloud, puis authentifiez-vous auprès de la base de données à l'aide de l'authentification IAM.

Créer le schéma et les tables flights et airports

Dans cette section, vous allez créer les tables de base de données flights et airports pour ce tutoriel.

  1. Dans la console Google Cloud , accédez à la page Cloud SQL.

    Accéder à Cloud SQL

  2. Sélectionnez une instance dans la liste.

  3. Dans le menu de navigation, cliquez sur Cloud SQL Studio.

  4. Connectez-vous à Studio à l'aide de l'authentification Identity and Access Management.

  5. Cliquez sur Authentifier. Le volet "Explorateur" affiche la liste des objets de votre base de données.

  6. Cliquez sur Nouvel onglet de l'éditeur SQL ou Nouvel onglet pour en ouvrir un.

  7. Pour créer la table et le schéma airports, exécutez l'instruction SQL suivante :

    CREATE TABLE IF NOT EXISTS airports (
  id INT PRIMARY KEY,
  iata TEXT,
  name TEXT,
  city TEXT,
  country TEXT
  );

  8. Créez la table et le schéma flights :

    CREATE TABLE IF NOT EXISTS flights (
  id INT PRIMARY KEY,
  airline VARCHAR(10),
  flight_number INT,
  departure_airport VARCHAR(5),
  arrival_airport VARCHAR(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate VARCHAR(10),
  arrival_gate VARCHAR(10)
);

Remplissez les tableaux flights et airports.

Dans cette section, vous allez remplir les tables flights et airports à l'aide des scripts SQL fournis.

  1. Remplissez la table airports.

  2. Remplissez la table flights.

  3. Exécutez la requête suivante pour vérifier que les tables sont remplies :

    SELECT * FROM flights LIMIT 10;
SELECT * FROM airports LIMIT 10;

Préparer la base de données pour les recherches de valeurs

Pour utiliser les recherches de valeurs sémantiques et trigrammes, vous devez configurer votre instance Cloud SQL pour MySQL afin qu'elle soit compatible avec les embeddings vectoriels et l'indexation des n-grammes.

  1. Pour permettre à l'instance Cloud SQL pour MySQL d'effectuer des recherches de valeurs sémantiques, vous devez activer les options suivantes.

    1. Activez l'option cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Activez le flag enable-google-ml-integration pour permettre à l'instance Cloud SQL pour MySQL de s'intégrer à Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Créer une colonne de vecteur pour stocker les embeddings de villes

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. générer et stocker des embeddings vectorielles pour les noms de villes ;

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Pour permettre à l'instance Cloud SQL pour MySQL d'effectuer des recherches de valeurs trigrammes, procédez comme suit.

    1. Activez l'option ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Créez un index FULLTEXT pour la correspondance de trigrammes sur le nom de l'aéroport.

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Créer un ensemble de contextes dans Studio

Dans cette section, créez un ensemble de contextes nommé flights-assistant. Cet ensemble de contexte n'inclut aucun fichier d'ensemble de contexte importé.

  1. Dans la console Google Cloud , accédez à la page Cloud SQL.

    Accéder à Cloud SQL

  2. Sélectionnez une instance dans la liste.

  3. Dans le menu de navigation, cliquez sur Cloud SQL Studio.

  4. Connectez-vous à Studio à l'aide de l'authentification IAM.

  5. Dans le volet Explorateur, à côté de Ensembles de contexte, cliquez sur Afficher les actions.

  6. Cliquez sur Créer un ensemble de contexte.

  7. Dans Nom de l'ensemble de contexte, saisissez flights-assistant.

  8. Cliquez sur Créer.

Tester QueryData dans Studio

Dans cette section, utilisez le contexte flights-assistant défini en posant des questions en langage naturel pour générer une requête SQL. Étant donné qu'aucun fichier de contexte n'est importé dans l'ensemble de contexte, même après avoir posé une question avec un contexte tel que nighttime traffic, QueryData génère une requête sous-optimale.

  1. Dans le volet Explorateur, à côté de votre ensemble de contexte, cliquez sur Afficher les actions.
  2. Cliquez sur Tester le contexte défini.
  3. Dans l'éditeur de requête, cliquez sur Générer du code SQL à l'aide de QueryData avec flights-assistant.

  4. Saisissez la question en langage naturel suivante pour générer une requête SQL, puis cliquez sur Générer.

    Find flights from SFO to JFK.

    Examinez la requête SQL. Notez que QueryData génère le code SQL correct pour cette question non ambiguë.

      SELECT
    *
  FROM
    "flights"
  WHERE
    "departure_airport" = 'SFO' AND "arrival_airport" = 'JFK';

  5. Dans la fenêtre Générer du code SQL à l'aide de QueryData avec flights-assistant, cliquez sur Modifier.

  6. Saisissez la question en langage naturel suivante pour générer une requête SQL, puis cliquez sur Mettre à jour.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    La base de données ne comprend pas le terme "trafic nighttime". Cela peut l'empêcher de générer une requête SQL ou l'amener à générer une requête qui ignore le terme, comme le montre la requête suivante.

    -- The database schema does not contain information about traffic.
-- Returning all flights departing from New York airports.
SELECT
  f.airline,
  f.flight_number,
  a.name AS departure_airport_name,
  f.departure_time,
  b.name AS arrival_airport_name,
  f.arrival_time
FROM
  flights AS f
JOIN
  airports AS a
  ON f.departure_airport = a.iata
JOIN
  airports AS b
  ON f.arrival_airport = b.iata
WHERE
  a.city = 'New York'
ORDER BY
  f.departure_time;

  7. Dans la fenêtre Générer du code SQL à l'aide de QueryData avec flights-assistant, cliquez sur Modifier.

  8. Saisissez la question en langage naturel suivante pour générer une requête SQL, puis cliquez sur Mettre à jour.

    Find flights heading into Manhattan

    La logique de définition du contexte génère une requête pour trouver un aéroport dont le nom contient "Manhattan". Comme aucun aéroport ni aucune ville de ce nom n'existe dans la base de données, la requête ne renverra aucune ligne.

    SELECT
  `skybot`.`flights`.*
FROM
  `skybot`.`flights`
JOIN
  `skybot`.`airports`
ON
  `skybot`.`flights`.`arrival_airport` = `skybot`.`airports`.`iata`
WHERE
  `skybot`.`airports`.`city` = 'Manhattan';

Générer un contexte pour l'ensemble de contextes

Dans cette section, vous allez créer un fichier de contexte qui permet d'améliorer les capacités d'interrogation de l'ensemble de contexte.

Configurer votre environnement

Avant de pouvoir générer du contexte, vous devez préparer votre environnement.

Pour configurer votre environnement, procédez comme suit :

  1. Installez Gemini CLI. Pour en savoir plus, consultez le guide de démarrage rapide de Gemini CLI.
  2. Installez la gcloud CLI.

  3. Configurez les Identifiants par défaut de l'application (ADC). Exécutez les commandes suivantes dans votre terminal pour vous authentifier et sélectionner votre projet :

    gcloud auth application-default login

  4. Installez l'extension DB Context Enrichment, qui inclut des workflows pour la génération de contexte.

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

    Assurez-vous que la version est 0.4.2 ou ultérieure. Pour mettre à jour l'extension d'enrichissement du contexte de la base de données, exécutez la commande suivante :

    gemini extensions update mcp-db-context-enrichment

  5. Pour mettre à jour l'extension d'enrichissement du contexte de la base de données ou remplacer GEMINI_API_KEY, exécutez la commande suivante :

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Remplacez GEMINI_API_KEY par votre clé API Gemini.

  6. Dans votre terminal, démarrez Gemini CLI.

    gemini

  7. Suivez la procédure de configuration de l'authentification Gemini CLI.

  8. Configurez la connexion à la base de données. L'extension nécessite une connexion à une base de données pour générer du contexte. Cette connexion est prise en charge par MCP Toolbox et définie dans le fichier de configuration tools.yaml.

    Pour créer le fichier de configuration tools.yaml dans votre répertoire actuel, saisissez une requête telle que Help me set up the database connection, puis suivez les instructions fournies par la skill. Pour en savoir plus sur le fichier tools.yaml, consultez la documentation MCP Toolbox.

  9. Pour recharger la configuration après la création du fichier tools.yaml, exécutez la commande suivante dans Gemini CLI :

    /mcp reload

  10. Vérifiez que la boîte à outils MCP et l'extension d'enrichissement de la base de données sont connectées et prêtes à l'emploi.

    /mcp list

Générer le contexte du modèle

Dans cette section, pour résoudre le problème de la section précédente où QueryData ne reconnaissait pas le terme nighttime traffic, définissez le terme dans le fichier de contexte comme le trafic se produisant entre 5:00 PM et 7:00 PM.

Pour générer le contexte du modèle, procédez comme suit :

  1. Exécutez la commande /generate_targeted_templates et suivez le workflow :

    /generate_targeted_templates

  2. Dans le terminal, indiquez la requête en langage naturel que vous souhaitez ajouter au modèle de requête.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

  3. Fournissez la requête SQL correspondante que vous souhaitez ajouter au modèle de requête. Ce modèle de requête définit le terme nighttime comme se produisant entre 5:00 PM et 7:00 PM.

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
  ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  4. Appuyez sur Entrée. Gemini convertit votre entrée dans un format spécifique qui améliore les performances de l'ensemble de contexte pour un large éventail de requêtes utilisateur. Pour en savoir plus, consultez Présentation des ensembles de contexte.

    Vous pouvez également exécuter le workflow /generate_bulk_templates pour permettre à Gemini CLI de générer plus de contexte en analysant le schéma de votre base de données et en suggérant un contexte associé.

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

  6. Sélectionnez l'option permettant de créer un fichier de contexte d'agent. Gemini crée un fichier nommé INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json dans le même répertoire, avec le contenu suivant :

    {
  "templates": [
    {
      "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
      "parameterized": {
        "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
      }
    }
  ]
}

Générer un contexte de recherche de valeurs

Dans cette section, vous allez générer un contexte de recherche de valeurs pour aider la logique de définition du contexte à mapper les expressions de valeur sur des valeurs spécifiques stockées dans les colonnes de votre base de données. Par exemple, si un utilisateur demande des "vols à destination de Manhattan", Manhattan est d'abord extrait en tant qu'expression de valeur, puis la recherche de similarité sémantique associe Manhattan à "New York", qui est stocké dans la colonne airports.city.

Pour générer un contexte de recherche de valeurs, procédez comme suit :

  1. Exécutez la commande /generate_targeted_value_searches :

    /generate_targeted_value_searches

  2. Saisissez mysql pour sélectionner MySQL comme base de données.

  3. Saisissez la version de MySQL que vous souhaitez utiliser. Sélectionnez default pour sélectionner MySQL 8.0.

  4. Saisissez la configuration de recherche de valeurs comme suit.

    Table: airports
Column: name
Concept: airport name
Match Function: TRIGRAM_STRING_MATCH

  5. Répétez le processus pour la correspondance sémantique.

    Table: airports
Column: city
Concept: airport city
Match Function: SEMANTIC_STRING_MATCH
Column Embedding: city_embedding

  6. Confirmez si vous souhaitez générer la définition de recherche de valeurs.

  7. Examinez la définition de la recherche de valeurs générée. Vous pouvez enregistrer la définition de recherche de valeur en tant que nouveau fichier d'ensemble de contexte ou l'ajouter à un fichier d'ensemble de contexte existant.

  8. Sélectionnez l'option permettant d'ajouter des données à un fichier d'ensemble de contextes existant. La définition de recherche de valeur est alors ajoutée au fichier de contexte créé dans la section précédente.

  9. Saisissez le nom de l'instance et de la base de données pour lesquels le fichier d'ensemble de contexte a été généré.

    Le fichier de contexte existant est mis à jour avec la définition de recherche de valeur. Gemini crée un fichier nommé INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json dans le même répertoire, avec le contenu suivant :

      {
"templates": [
  {
    "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
    "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
    "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
    "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
    "parameterized": {
      "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
    }
  }
],
"facets": [],
"value_searches": [
  {
    "query": "SELECT * FROM (  WITH TrigramMetrics AS (    SELECT T.`name` AS original_value,     MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) AS raw_score     FROM `airports` AS T     WHERE MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) > 0     ORDER BY raw_score DESC LIMIT 10  ),   NormalizationParams AS (    SELECT MAX(raw_score) AS max_score     FROM TrigramMetrics  )   SELECT original_value AS value, 'name' AS `columns`,   'airport city' AS concept_type,   (CASE WHEN n.max_score > 0 THEN (1 - (m.raw_score / n.max_score)) ELSE 0 END) AS distance,   JSON_OBJECT() AS context   FROM TrigramMetrics m, NormalizationParams n) AS wrapped_query ",
    "concept_type": "airport city",
    "description": null
  },
  {
    "query": "SELECT * FROM (  WITH search_embedding AS (    SELECT mysql.ml_embedding('text-embedding-005', $value) AS val  )   SELECT T.`city` AS value, 'city' AS `columns`,   'airport name' AS concept_type,   COSINE_DISTANCE(T.`city_embedding`, search_embedding.val) AS distance,   JSON_OBJECT() AS context   FROM `airports` AS T, search_embedding   WHERE T.`city_embedding` IS NOT NULL) AS wrapped_query ",
    "concept_type": "airport name",
    "description": null
  }
]
}

Importer un fichier d'ensemble de contexte dans QueryData

Dans cette section, vous allez importer le fichier de jeu de contexte dans QueryData afin d'améliorer les capacités de génération de code SQL de QueryData sur votre base de données.

Pour importer le contexte, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Cloud SQL.

    Accéder à Cloud SQL

  2. Sélectionnez une instance dans la liste.

  3. Dans le menu de navigation, cliquez sur Cloud SQL Studio.

  4. Connectez-vous à Studio à l'aide de l'authentification Identity and Access Management.

  5. Dans le volet Explorateur, à côté de Ensembles de contexte, cliquez sur l'icône Actions ().

  6. Cliquez sur Modifier l'ensemble de contexte.

  7. Facultatif : modifiez la description de l'ensemble de contexte.

  8. Cliquez sur Parcourir dans la section Importer un fichier d'ensemble de contexte, puis sélectionnez le fichier d'ensemble de contexte généré précédemment.

  9. Cliquez sur Enregistrer.

Générer une requête SQL à l'aide de QueryData

Dans cette section, vous allez utiliser le fichier de définition du contexte que vous avez importé pour poser des questions en langage naturel. Cela vous permet de vérifier que QueryData comprend et applique correctement les définitions de termes tels que nighttime traffic et d'autres expressions associées.

Pour générer des requêtes SQL, procédez comme suit :

  1. Dans le volet Explorateur, à côté de votre ensemble de contexte, cliquez sur Afficher les actions.
  2. Cliquez sur Tester le contexte défini.
  3. Dans l'éditeur de requête, cliquez sur Générer du code SQL à l'aide de QueryData avec l'assistant de vols.

  4. Saisissez la question en langage naturel suivante pour générer une requête SQL, puis cliquez sur Générer.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    La requête SQL générée ressemble à ce qui suit :

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

    Il s'agit de la même question que celle que vous avez ajoutée au contexte de QueryData. Notez que QueryData peut désormais interpréter précisément le terme nighttime traffic.

    Bien que le contexte provienne d'une question spécifique, QueryData l'utilise pour améliorer la génération de requêtes SQL pour un large éventail de questions similaires.

  5. Dans la fenêtre Générer du code SQL à l'aide de QueryData avec flights-assistant, cliquez sur Modifier.

  6. Saisissez une question semblable à celle-ci pour générer une requête SQL, puis cliquez sur Mettre à jour.

    What are the flights that can help me avoid evening traffic if departing from Boston

    Étant donné que la question remplace le terme nighttime traffic par un terme similaire, evening traffic, QueryData fournit une réponse cohérente à cette question en appliquant la même interprétation.

    La requête SQL générée ressemble à ce qui suit :

    -- What are the flights that can help me avoid evening traffic if departing from Boston
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
ON
  f.departure_airport = a.iata
WHERE
  a.city = 'Boston'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  7. Dans la fenêtre Générer du code SQL à l'aide de QueryData avec flights-assistant, cliquez sur Modifier.

  8. Dans la fenêtre Générer du code SQL à l'aide de QueryData avec flights-assistant, cliquez sur Modifier.

  9. Saisissez la question suivante pour générer une requête SQL, puis cliquez sur Mettre à jour.

    Find flights heading into Manhattan

    La requête SQL générée ressemble à ce qui suit :

    SELECT
  *
FROM `skybot`.`flights` AS t1
INNER JOIN `skybot`.`airports` AS t2
  ON t1.`arrival_airport` = t2.`iata`
WHERE t2.`city` = 'New York';

    Notez que QueryData peut désormais interpréter avec précision que "Manhattan" est lié à "New York" dans la base de données à l'aide de la mise en correspondance sémantique.

Intégrer QueryData à votre application

Dans cette section, vous allez créer un agent QueryData pour une application de recherche de vols. Cet agent QueryData fournit une interface conversationnelle aux tables flights et airports que vous avez créées précédemment. Il explique également comment créer et intégrer cet agent QueryData dans votre application à l'aide de l'Agent Development Kit (ADK), de l'outil Gemini Data Analytics QueryData MCP et de l'ensemble de contextes pour améliorer la qualité des réponses.

  1. Téléchargez MCP Toolbox version 0.31.0 ou ultérieure. La boîte à outils MCP expose l'agent QueryData en tant qu'outil permettant aux applications de se connecter. La boîte à outils MCP diffère de l'extension Gemini CLI MCP Toolbox que vous avez installée précédemment et qui génère du contexte.

  2. Configurez les identifiants par défaut de l'application.

    gcloud auth application-default login

  3. Recherchez l'ID de l'ensemble de contexte. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez Trouver l'ID de l'ensemble de contexte.

  4. Créez la configuration tools.yaml pour vous connecter à l'agent QueryData à l'aide de la boîte à outils MCP. Pour en savoir plus, consultez Source Gemini Data Analytics et l'outil QueryData Gemini Data Analytics.

    kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: "PROJECT_ID"
---
kind: tool
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
location: "REGION_ID"
context:
  datasourceReferences:
    cloudSqlReference:
      databaseReference:
        engine: "MYSQL"
        projectId: "PROJECT_ID"
        region: "REGION_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • 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.
    • CONTEXT_SET_ID : ID de l'ensemble de contexte. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez Trouver l'ID de l'ensemble de contexte.

  5. Exécutez le serveur MCP Toolbox avec le fichier tools.yaml.

    ./toolbox --config "tools.yaml"

  6. Créez une application ADK qui appelle l'outil Gemini Data Analytics QueryData à l'aide du SDK Python de MCP Toolbox. Pour en savoir plus sur l'utilisation du SDK Python de la boîte à outils MCP, consultez le guide de démarrage rapide de la boîte à outils. Pour en savoir plus sur le SDK Python ADK, consultez le guide de démarrage rapide de l'ADK.

    1. Créez un répertoire pour stocker l'application, par exemple flight-assistant-app.

    2. Remplacez le répertoire par le répertoire flight-assistant-app.

      mkdir flight-assistant-app
cd flight-assistant-app

    3. Exécutez les commandes suivantes dans le répertoire flight-assistant-app pour créer un environnement virtuel et installer les composants requis.

      python3 -m venv .venv
source .venv/bin/activate
pip install toolbox-core
pip install google-genai
pip install google-adk

    4. Configurez un agent ADK.

      1. Créez un agent ADK.

        adk create my_agent

      2. Sélectionnez le modèle gemini-2.5-flash.

      3. Sélectionnez Google AI, puis saisissez votre clé API Gemini. Pour savoir comment trouver votre clé API, consultez Utiliser des clés API Gemini.

    5. Remplacez le contenu du fichier agent.py par le code d'exemple suivant de l'application Flight Data Assistant.

      from typing import cast

from google.adk.agents.llm_agent import Agent
from google.adk.agents.llm_agent import ToolUnion

from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = "http://127.0.0.1:5000"

INSTRUCTION = """
# ROLE
You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
- use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.

# OPERATIONAL CONSTRAINTS
- TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides.
- TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance.
- SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with.

# COMMUNICATION STYLE
- Be concise and scannable when listing answers.
- Maintain a helpful, professional persona.

=====

# QUERY DATA TOOL

Inputs:
1. query: A natural language formulation of a database query.

Outputs: (all optional)
1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
2. generated_query: The generated query for the user query.
3. intent_explanation: An explanation for why the tool produced `generated_query`.
4. query_result: The result of executing `generated_query`.
5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.

Usage guidance:
1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user.
3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning.
"""

client = ToolboxSyncClient(TOOLBOX_URL)

mcp_tool = client.load_tool("cloud_gda_query_tool")

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. Exécutez les commandes suivantes dans le répertoire flight-assistant-app pour démarrer l'application et accéder au serveur Web ADK à l'adresse http://127.0.0.1:8000.

    adk web --port 8000

  8. Saisissez du texte, par exemple hello, pour commencer à interagir avec l'agent.

    L'agent ADK répond aux questions générales et appelle les outils MCP requis.

  9. Saisissez la question suivante sur un vol.

    How many flights depart from the west side?

    L'outil MCP est appelé à répondre à cette question. Toutefois, comme le terme the west est ambigu et ne spécifie aucun aéroport, l'outil MCP renvoie une question de clarification que l'agent utilise pour construire une réponse.

    I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like:

1. How many flights depart from a specific airport?

2. What are the departure airports for all flights?

3. How many flights depart from each airport? Would you like to rephrase your question based on these options?

  10. Saisissez une question semblable à celle du modèle de requête généré pour l'agent.

    Help me find flights from San Francisco that avoid the evening rush hour.

    En fonction du contexte QueryData ajouté précédemment, l'outil MCP comprend que evening traffic se produit entre 17h et 19h. L'outil MCP renvoie les données associées que l'agent utilise pour construire sa réponse.

    Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM):

* UA 1532 departing at 05:50:00
* UA 1158 departing at 05:57:00
* CY 922 departing at 06:38:00
* OO 5441 departing at 07:08:00
* UA 616 departing at 07:14:00
* AA 24 departing at 07:14:00
* B6 434 departing at 08:00:00
* AA 242 departing at 08:18:00
* UA 1739 departing at 08:22:00
* OO 6336 departing at 08:32:00
* US 1784 departing at 08:47:00
* DL 1631 departing at 09:00:00
* DL 1106 departing at 09:06:00
* OO 5427 departing at 09:06:00
* CY 352 departing at 09:25:00

  11. Saisissez une question basée sur le type de concept que vous avez ajouté dans le contexte de l'agent.

    Find flights heading into Manhattan

    En fonction du contexte de recherche de valeur ajouté précédemment, l'agent comprend que Manhattan fait référence à la ville New York et renvoie les données associées que l'agent peut utiliser pour construire sa réponse.

    There are 6 flights heading into New York City, specifically arriving at JFK airport, which serves Manhattan.

Here are the details for these flights:

AA 24 from SFO, departing 2025-01-01 07:14:00 and arriving 2025-01-01 15:46:00.
UA 758 from SFO, departing 2025-01-02 07:07:00 and arriving 2025-01-02 15:53:00.
AA 24 from SFO, departing 2025-01-02 07:06:00 and arriving 2025-01-02 15:29:00.
DL 2040 from SFO, departing 2025-01-02 15:09:00 and arriving 2025-01-02 23:20:00.
DL 1370 from SFO, departing 2025-01-02 23:04:00 and arriving 2025-01-03 07:36:00.
CY 34 from SFO, departing 2025-01-02 23:15:00 and arriving 2025-01-03 07:54:00.

Améliorer les performances de l'agent

L'interface utilisateur Web de l'ADK vous permet d'inspecter la requête et la réponse de l'outil MCP QueryData de Gemini Data Analytics. Vous pouvez utiliser cette réponse pour observer les réponses de l'outil, telles que la requête SQL générée, l'ensemble de résultats, l'explication de l'intention, la question de clarification et la réponse en langage naturel, afin de vérifier l'exactitude des réponses de votre agent.

Par exemple, pour le texte d'entrée How many flights depart from the west side? que vous avez saisi précédemment, cliquez sur la bulle de l'agent. Dans l'onglet Événement du panneau de navigation de gauche, développez functionResponse pour afficher la réponse suivante.

"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"

Améliorer la précision des réponses

Vous pouvez affiner en continu la précision des réponses de l'outil QueryData Gemini Data Analytics en ajoutant du contexte. Utilisez Gemini CLI pour générer le contexte, puis importez le fichier d'ensemble de contextes mis à jour dans l'agent flights-assistant QueryData existant. Pour en savoir plus, consultez Créer des contextes à l'aide de Gemini CLI. La console ingère immédiatement le nouveau contexte après l'avoir importé, ce qui vous permet d'améliorer la précision de l'agent sans aucun temps d'arrêt de l'application.

Plusieurs agents

Dans votre environnement de développement, vous pouvez effectuer des tests A/B sur plusieurs contextes d'agent QueryData en attribuant des noms distincts aux outils de votre fichier tools.yaml. Par exemple, vous pouvez créer des configurations tools.yaml uniques en définissant deux outils cloud-gemini-data-analytics-query avec des noms différents, tels que cloud_gda_query_tool_v1 et cloud_gda_query_tool_v2. Cette configuration vous permet d'implémenter une logique d'application qui sélectionne de manière programmatique la version de contexte requise en choisissant le nom de l'outil correspondant.

L'exemple tools.yaml suivant montre comment configurer plusieurs agents QueryData pour une source de données de base de données :

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: <var>PROJECT_ID</var>
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • V1_YOUR_CONTEXT_SET_ID : ID de l'ensemble de contexte pour la version 1.
  • V2_YOUR_CONTEXT_SET_ID : ID de l'ensemble de contexte pour la version 2

Effectuer un nettoyage

Dans les sections suivantes, nous allons voir comment supprimer ces ressources et ces objets.

Supprimer l'ensemble de contextes

Avant de supprimer l'instance, supprimez l'ensemble de contexte que vous avez créé.

  1. Dans la console Google Cloud , accédez à la page Cloud SQL.

    Accéder à Cloud SQL

  2. Sélectionnez une instance dans la liste.

  3. Dans le menu de navigation, cliquez sur Cloud SQL Studio.

  4. Connectez-vous à Studio à l'aide de l'authentification Identity and Access Management.

  5. Dans le volet Explorateur, à côté de votre ensemble de contexte, cliquez sur Afficher les actions.

  6. Dans la fenêtre Supprimer l'ensemble de contexte, saisissez flight-assistant dans la zone de confirmation.

  7. Cliquez sur Confirmer.

Supprimer l'instance

Lorsque vous supprimez l'instance que vous avez créée dans la section Avant de commencer, tous les objets que vous avez créés sont également supprimés.

  1. Dans la console Google Cloud , accédez à la page Cloud SQL.

    Accéder à Cloud SQL

  2. Sélectionnez une instance dans la liste.

  3. Cliquez sur Supprimer.

  4. Confirmez que vous souhaitez supprimer l'instance en saisissant son nom et en cliquant sur Supprimer.

Étapes suivantes