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 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 la méthode QueryData dans l'API Conversational Analytics 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

Ce tutoriel vise les objectifs suivants :

  • Créer des bases de données et les remplir avec des données
  • Créez un fichier d'ensemble de contextes avec l'agent d'ingénierie contextuelle.
  • Créez un ensemble de contextes et importez un fichier d'ensemble de contextes.
  • Tester QueryData et générer des requêtes SQL dans Cloud SQL Studio.
  • Intégrez QueryData à votre application à l'aide de l'outil Gemini Data Analytics QueryData dans MCP Toolbox.
  • Ajoutez l'ancrage aux réponses du 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 lorsque vous avez terminé les tâches décrites dans ce document. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Avant de créer un ensemble de contextes, assurez-vous de remplir les conditions préalables suivantes.

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 suivre 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 sur Nouvel onglet pour ouvrir un nouvel onglet.

  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)
);

Remplir les tables 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 renseignées :

    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 sémantiques et de valeurs de trigrammes, vous devez configurer votre instance Cloud SQL pour MySQL afin qu'elle soit compatible avec les embeddings vectoriels et l'indexation n-gramme.

  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 l'option 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 vectorielle pour stocker les embeddings de villes

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

    4. Générer et stocker des embeddings vectoriels 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 de 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éer 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 contexte dans Cloud SQL Studio

Dans cette section, créez un ensemble de contextes nommé flights-assistant. Cet ensemble de contextes n'inclut aucun fichier d'ensemble de contextes 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 contextes, cliquez sur Afficher les actions ().

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

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

  8. Cliquez sur Créer.

Tester QueryData dans Studio

Dans cette section, utilisez l'ensemble de contexte flights-assistant en posant des questions en langage naturel pour générer une requête SQL. Étant donné que l'ensemble de contextes ne contient aucun fichier d'ensemble de contextes, 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 l'ensemble de contextes.
  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 suivante en langage naturel 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 sans ambiguïté.

      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 l'ensemble de contextes 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 type 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 préparer l'environnement et 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 commencer à générer du contexte, vous devez préparer votre environnement.

Pour configurer votre environnement, procédez comme suit :

  1. Installez la CLI Antigravity. Pour en savoir plus, consultez Premiers pas avec la CLI Antigravity.
  2. Installez la Google Cloud 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 uv, un gestionnaire de packages et de projets Python requis pour l'agent d'ingénierie de contexte. Si Python n'est pas déjà installé sur votre système, uv peut l'installer pour vous.

  5. Installez l'agent d'ingénierie de contexte :

    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

  6. Dans votre terminal, démarrez la CLI Antigravity.

    agy

  7. Configurer une connexion à une base de données pour la génération de contexte à l'aide de MCP Toolbox. La connexion est 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 a database connection.

    Suivez les instructions fournies par la skill. Pour en savoir plus sur le fichier tools.yaml, consultez la documentation de MCP Toolbox.

  8. Pour actualiser la configuration après la création du fichier tools.yaml, exécutez la commande suivante dans la CLI Antigravity et suivez les instructions pour actualiser le serveur MCP de la boîte à outils :

    /mcp

    1. Sélectionnez db-context-engineering_toolbox.

    2. Sélectionnez Restart.

  9. Vérifiez que la boîte à outils MCP et le plug-in de l'agent d'ingénierie de contexte sont connectés et prêts à être utilisés.

    /mcp

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 d'ensemble 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. Saisissez le prompt suivant dans la CLI Antigravity :

    Generate a template for the question: "Tell me flights that can help me beat nighttime traffic if traveling from New York" with the following SQL query:

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;

  2. L'agent convertit votre entrée dans un format spécifique qui affine les performances de l'ensemble de contexte sur un large éventail de requêtes utilisateur. Pour en savoir plus, consultez Présentation des ensembles de contextes.

  3. 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.

  4. Demandez à l'agent d'enregistrer le modèle :

    Save it to context_set.json.

    L'agent crée le fichier 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 valeur

Dans cette section, vous allez générer un contexte de recherche de valeurs pour aider la logique de l'ensemble de contextes à mapper les expressions de valeur à des valeurs spécifiques stockées dans les colonnes de votre base de données. Par exemple, si un utilisateur demande "vols vers 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 valeur, procédez comme suit :

  1. Saisissez le prompt suivant dans le harnais d'agent.

  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.

    Generate a trigram value search on table "airports" for column "name" with concept "airport name". Then generate a semantic value search on table "airports" for column "city" with concept "airport city" using embedding column "city_embedding".

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

  5. Envoyez le prompt Append the context to context_set.json à l'agent. La définition de la recherche de valeur est alors ajoutée au fichier de contexte créé dans la section précédente.

  6. Saisissez l'instance de base de données et le nom 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, 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 le fichier de l'ensemble de contextes dans QueryData

Dans cette section, vous allez importer le fichier d'ensemble de contexte dans QueryData afin d'améliorer les capacités de génération 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, sous Ensembles de contextes et à côté de l'ensemble de contextes flights-assistant, cliquez sur l'icône Afficher les actions ().

  6. Cliquez sur Modifier l'ensemble de contextes.

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

  8. Cliquez sur Enregistrer.

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

Dans cette section, vous allez utiliser le fichier d'ensemble de 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 l'ensemble de contextes.
  3. Dans l'éditeur de requête, cliquez sur Générer du code SQL à l'aide de QueryData avec : flights-assistant.

  4. Pour générer une requête SQL, saisissez la question suivante en langage naturel, 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 à celle-ci :

    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 correctement le terme nighttime traffic.

    Bien que le contexte provienne d'une question particulière, QueryData l'utilise pour améliorer la génération 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 la question similaire suivante 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 à celle-ci :

    -- 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. 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 à celle-ci :

    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 grâce à la correspondance sémantique.

Intégrer QueryData à votre application

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

  1. Téléchargez MCP Toolbox version 1.14.0 ou ultérieure. MCP Toolbox expose l'agent de données en tant qu'outil auquel les applications peuvent se connecter. MCP Toolbox est différent du moteur contextuel que vous avez installé précédemment, qui génère du contexte.

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

    gcloud auth application-default login

  3. Recherchez l'ID de l'ensemble de contextes que vous avez créé précédemment. Pour savoir comment trouver l'ID de l'ensemble de contextes, consultez Trouver l'ID de l'ensemble de contextes.

  4. Ajoutez ce qui suit à la configuration tools.yaml pour vous connecter à l'agent de données à l'aide de MCP Toolbox. Pour en savoir plus, consultez Source d'analyse de données Gemini et Outil QueryData d'analyse de données Gemini.

    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 contextes. Pour savoir comment trouver l'ID de l'ensemble de contextes, consultez Trouver l'ID de l'ensemble de contextes.

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

    ./toolbox --config PATH_TO_TOOLS_YAML

    Remplacez PATH_TO_TOOLS_YAML par le chemin d'accès au fichier tools.yaml que vous avez créé précédemment.

  6. Créez une application ADK qui appelle l'outil QueryData de Gemini Data Analytics à l'aide du SDK Python de MCP Toolbox. Pour en savoir plus sur l'utilisation du SDK Python de MCP Toolbox, consultez le guide de démarrage rapide de Toolbox. Pour en savoir plus sur l'ADK Python, 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. Accédez au 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.

      uv init
uv add google-adk toolbox-core google-genai

    4. Configurer un agent ADK

      1. Créer un agent ADK

        uv run adk create my_agent

      2. Sélectionnez le modèle gemini-2.5-flash ou un modèle plus récent.

      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. (Si vous n'avez pas besoin d'un essai sans frais, vous pouvez sélectionner Vertex AI et spécifier un projet Google Cloud avec la facturation activée.)

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

      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",  # Or newer.
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. Pour démarrer l'application, exécutez les commandes suivantes dans le répertoire flight-assistant-app. Accédez au serveur Web ADK à l'adresse http://127.0.0.1:8000.

    uv run adk web --port 8000

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

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

  9. Saisissez la question suivante concernant les vols.

    How many flights depart from the west side?

    L'outil MCP est appelé pour 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 désambiguïsation 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 peut utiliser pour élaborer 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" est lié à la ville de "New York" et renvoie les données associées que l'agent utilisera 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 de manière itérative

L'UI 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 désambiguïsation et la réponse en langage naturel, afin de vous aider à confirmer 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 de Gemini Data Analytics en ajoutant du contexte. Utilisez l'agent d'ingénierie contextuelle pour générer le contexte, puis importez le fichier d'ensemble de contextes mis à jour dans l'agent de données flights-assistant existant. Pour en savoir plus, consultez Gérer les ensembles de contexte dans Cloud SQL Studio. La console ingère immédiatement le nouveau contexte après son importation, ce qui vous permet d'améliorer la précision de l'agent sans 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 de données en attribuant des noms distincts aux outils dans 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 de données pour une source de base de données :

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: PROJECT_ID
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    DB_SOURCE:
      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:
    DB_SOURCE:
      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 contextes pour la version 1.
  • V2_YOUR_CONTEXT_SET_ID : ID de l'ensemble de contextes pour la version 2.
  • DB_SOURCE : configurations de la source de base de données.

Effectuer un nettoyage

Une fois que vous avez terminé ce tutoriel, supprimez les ressources que vous avez créées pour éviter des coûts récurrents. Dans les sections suivantes, nous allons voir comment supprimer ces ressources.

Supprimer l'ensemble de contexte

Avant de supprimer l'instance, supprimez l'ensemble de contextes 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. Cliquez sur Supprimer l'ensemble de contexte.

  7. Dans la fenêtre Supprimer l'ensemble de contextes, saisissez flights-assistant.

  8. Cliquez sur Confirmer.

Supprimer l'instance

Lorsque vous supprimez l'instance que vous avez créée dans la section Avant de commencer, vous supprimez également tous les objets que vous avez créé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