QueryData in eine Anwendung einbinden

In dieser Anleitung wird beschrieben, wie Sie QueryData in Cloud SQL for MySQL über die Google Cloud Console einrichten und verwenden und in Ihre Anwendung einbinden. Hier erfahren Sie, wie Sie die Datei für das Kontextset erstellen, ein Kontextset erstellen, das die Kontextset-Datei verwendet, mit der MCP Toolbox die QueryData-Methode in der Conversational Analytics API aufrufen, um SQL-Abfragen für Fragen in natürlicher Sprache zu generieren, und diese in Ihre Anwendung einbinden.

Weitere Informationen finden Sie unter QueryData – Übersicht.

Ziele

In dieser Anleitung werden die folgenden Ziele behandelt:

  • Datenbanken erstellen und mit Daten füllen
  • Erstellen Sie mit dem Kontext-Engineering-Agenten eine Kontextset-Datei.
  • Erstellen Sie ein Kontextset und laden Sie eine Kontextset-Datei hoch.
  • QueryData testen und SQL-Abfragen in Cloud SQL Studio generieren
  • Mit dem Tool Gemini Data Analytics QueryData in der MCP Toolbox können Sie QueryData in Ihre Anwendung einbinden.
  • Fundierung zu LLM-Antworten mithilfe von Suchanfragen hinzufügen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Neuen Nutzern von Google Cloud steht möglicherweise eine kostenlose Testversion zur Verfügung.

Löschen Sie die von Ihnen erstellten Ressourcen, um weitere Kosten zu vermeiden, wenn Sie die Aufgaben in diesem Dokument abgeschlossen haben. Weitere Informationen finden Sie unter Bereinigen.

Hinweis

Erfüllen Sie die folgenden Voraussetzungen, bevor Sie einen Kontextsatz erstellen.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

Cloud SQL-Instanz vorbereiten

Erforderliche Rollen und Berechtigungen

Berechtigung executesql für die Cloud SQL-Instanz gewähren

Führen Sie den folgenden Befehl aus, um der Cloud SQL-Instanz die Berechtigung executesql zu gewähren und die Cloud SQL Data API zu aktivieren: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Ersetzen Sie Folgendes:
  • PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
  • INSTANCE_ID: Die ID Ihrer Cloud SQL-Instanz.
Melden Sie sich zum Ausführen der Schritte in dieser Anleitung bei Google Cloud an und authentifizieren Sie sich dann mit der IAM-Authentifizierung bei der Datenbank.

Schema und Tabellen für flights und airports erstellen

In diesem Abschnitt erstellen Sie die Datenbanktabellen flights und airports für diese Anleitung.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der Authentifizierung über Identity and Access Management in Studio an.

  5. Klicken Sie auf Authentifizieren. Im Bereich „Explorer“ wird eine Liste der Objekte in Ihrer Datenbank angezeigt.

  6. Klicken Sie auf Neuer SQL-Editor-Tab oder Neuer Tab, um einen neuen Tab zu öffnen.

  7. Führen Sie die folgende SQL-Anweisung aus, um die Tabelle airports und das Schema zu erstellen:

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

  8. Erstellen Sie die Tabelle flights und das Schema:

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

Tabellen flights und airports füllen

In diesem Abschnitt füllen Sie die Tabellen flights und airports mit den bereitgestellten SQL-Skripts.

  1. Füllen Sie die Tabelle airports aus.

  2. Füllen Sie die Tabelle flights aus.

  3. Führen Sie die folgende Abfrage aus, um zu prüfen, ob die Tabellen gefüllt sind:

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

Datenbank für die Suche nach Werten vorbereiten

Wenn Sie die semantische Suche und die Suche nach Trigrammwerten verwenden möchten, müssen Sie Ihre Cloud SQL for MySQL-Instanz so konfigurieren, dass sie Vektoreinbettungen und die n-Gramm-Indexierung unterstützt.

  1. Damit die Cloud SQL for MySQL-Instanz semantische Wertesuchen durchführen kann, müssen Sie die folgenden Flags aktivieren.

    1. Aktivieren Sie das Flag cloudsql_vector.

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

    2. Aktivieren Sie das Flag enable-google-ml-integration, damit die Cloud SQL for MySQL-Instanz in Vertex AI eingebunden werden kann.

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

    3. Vektorspalte zum Speichern von Stadteinbettungen erstellen

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

    4. Vektoreinbettungen für Städtenamen generieren und speichern

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

  2. Führen Sie die folgenden Schritte aus, um die Cloud SQL for MySQL-Instanz für die Suche nach Trigrammwerten zu aktivieren.

    1. Aktivieren Sie das Flag ngram_token_size.

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

    2. FULLTEXT-Index für den Trigramm-Abgleich des Flughafennamens erstellen

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

Kontextsatz in Cloud SQL Studio erstellen

In diesem Abschnitt erstellen Sie einen Kontextsatz mit dem Namen flights-assistant. Dieses Kontextset enthält keine hochgeladene Kontextset-Datei.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der IAM-Authentifizierung in Studio an.

  5. Klicken Sie im Bereich Explorer neben Kontextsätze auf Aktionen ansehen ().

  6. Klicken Sie auf Kontextgruppe erstellen.

  7. Geben Sie unter Name des Kontextsets flights-assistant ein.

  8. Klicken Sie auf Erstellen.

QueryData in Studio testen

In diesem Abschnitt verwenden Sie den Kontextsatz flights-assistant, indem Sie Fragen in natürlicher Sprache stellen, um eine SQL-Abfrage zu generieren. Da in das Kontextset keine Kontextset-Datei hochgeladen wurde, generiert QueryData auch nach einer Frage mit Kontext wie nighttime traffic eine suboptimale Abfrage.

  1. Klicken Sie im Bereich Explorer neben Ihrem Kontextsatz auf Aktionen ansehen ().
  2. Klicken Sie auf Kontextset testen.
  3. Klicken Sie im Abfrageeditor auf SQL mit QueryData generieren mit: flights-assistant.

  4. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Generieren.

    Find flights from SFO to JFK.

    Prüfen Sie die SQL-Abfrage. QueryData generiert die richtige SQL-Abfrage für diese eindeutige Frage.

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

  5. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  6. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

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

    Die Datenbank versteht den Begriff „nighttime-Traffic“ nicht. Dies kann dazu führen, dass keine SQL-Abfrage generiert wird oder eine Abfrage generiert wird, die den Begriff ignoriert, wie die folgende Abfrage zeigt. 

    -- 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. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  8. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    Find flights heading into Manhattan

    Die Logik des Kontextsets generiert eine Abfrage, um einen Flughafen mit „Manhattan“ im Namen zu finden. Da in der Datenbank kein solcher Flughafen oder keine solche Stadt vorhanden ist, werden bei der Abfrage keine Zeilen zurückgegeben.

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

Kontext für das Kontextset generieren

In diesem Abschnitt bereiten Sie die Umgebung vor und erstellen eine Kontextdatei, mit der die Abfragefunktionen des Kontextsets verbessert werden.

Umgebung einrichten

Bevor Sie mit dem Generieren von Kontext beginnen können, müssen Sie Ihre Umgebung vorbereiten.

So richten Sie Ihre Umgebung ein:

  1. Installieren Sie die Antigravity CLI. Weitere Informationen finden Sie unter Erste Schritte mit Antigravity CLI.
  2. Installieren Sie die Google Cloud CLI.

  3. Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) einrichten Führen Sie im Terminal die folgenden Befehle aus, um sich zu authentifizieren und Ihr Projekt auszuwählen:

    gcloud auth application-default login

  4. Installieren Sie uv, ein Python-Paket und einen Projektmanager, der für den Kontext-Engineering-Agenten erforderlich ist. Wenn Python noch nicht auf Ihrem System installiert ist, kann uv es für Sie installieren.

  5. Kontext-Engineering-Agent installieren:

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

  6. Starten Sie im Terminal die Antigravity CLI.

    agy

  7. Datenbankverbindung für die Kontextgenerierung mit der MCP Toolbox einrichten Die Verbindung ist in der Konfigurationsdatei tools.yaml definiert.

    Wenn Sie die Konfigurationsdatei tools.yaml im aktuellen Verzeichnis erstellen möchten, geben Sie einen Prompt wie den folgenden ein: 

    Help me set up a database connection.

    Folge der Anleitung für den Skill. Weitere Informationen zur Datei tools.yaml finden Sie in der Dokumentation zur MCP Toolbox.

  8. Führen Sie den folgenden Befehl in der Antigravity CLI aus, um die Konfiguration nach dem Erstellen der Datei tools.yaml neu zu laden, und folgen Sie der Anleitung, um den MCP-Server der Toolbox neu zu laden:

    /mcp

    1. Wählen Sie db-context-engineering_toolbox aus.

    2. Wählen Sie Restart aus.

  9. Prüfen Sie, ob die MCP-Toolbox und das Plug-in für den Context Engineering-Agenten verbunden und einsatzbereit sind.

    /mcp

Vorlagenkontext generieren

In diesem Abschnitt definieren Sie den Begriff nighttime traffic in der Kontextdatei als Traffic zwischen 5:00 PM und 7:00 PM, um das Problem aus dem vorherigen Abschnitt zu beheben, bei dem QueryData den Begriff nicht erkannt hat.

So generieren Sie Vorlagenkontext:

  1. Geben Sie den folgenden Prompt in die Antigravity CLI ein:

    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. Der Agent wandelt Ihre Eingabe in ein bestimmtes Format um, das die Leistung des Kontextsets für eine Vielzahl von Nutzeranfragen optimiert. Weitere Informationen finden Sie unter Kontextsätze – Übersicht.

  3. Prüfen Sie die generierte Abfragevorlage. Sie können die Abfragevorlage entweder als neue Kontextdatei für den KI-Agenten speichern oder an eine vorhandene Kontextdatei für den KI-Agenten anhängen.

  4. Fordern Sie den KI-Agenten auf, die Vorlage zu speichern:

    Save it to context_set.json.

    Der Agent erstellt die Datei im selben Verzeichnis mit folgendem Inhalt:

    {
  "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 ?"
      }
    }
  ]
}

Kontext für die Wertsuche generieren

In diesem Abschnitt generieren Sie einen Wertesuchkontext, damit die Kontextsetzungslogik Wertphrasen bestimmten Werten zuordnen kann, die in Ihren Datenbankspalten gespeichert sind. Wenn ein Nutzer beispielsweise nach „Flügen nach Manhattan“ fragt, wird zuerst „Manhattan“ als Wertphrase extrahiert. Die semantische Ähnlichkeitssuche verknüpft dann „Manhattan“ mit „New York“, das in der Spalte airports.city gespeichert ist.

So generieren Sie einen Suchkontext für Werte:

  1. Geben Sie den folgenden Prompt in das Agenten-Framework ein.

  2. Geben Sie mysql ein, um MySQL als Datenbank auszuwählen.

  3. Geben Sie die MySQL-Version ein, die Sie verwenden möchten. Wählen Sie default aus, um MySQL 8.0 auszuwählen.

    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. Sehen Sie sich die generierte Definition der Wertsuche an. Sie können die Definition der Wertsuche entweder als neue Kontextsatzdatei speichern oder an eine vorhandene Kontextsatzdatei anhängen.

  5. Senden Sie den Prompt Append the context to context_set.json an den KI-Agenten. Dadurch wird die Definition der Wertsuche der Kontextdatei hinzugefügt, die im vorherigen Abschnitt erstellt wurde.

  6. Geben Sie die Datenbankinstanz und den Datenbanknamen ein, für die die Kontextset-Datei generiert wurde.

    Die vorhandene Kontextdatei wird mit der Definition der Wertsuche aktualisiert und enthält dann folgenden Inhalt:

      {
"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
  }
]
}

Laden Sie die Kontextdatei in QueryData hoch.

In diesem Abschnitt laden Sie die Kontextdatei in QueryData hoch, um die SQL-Generierungsfunktionen von QueryData für Ihre Datenbank zu verbessern.

So laden Sie den Kontext hoch:

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der Authentifizierung über Identity and Access Management in Studio an.

  5. Klicken Sie im Bereich Explorer unter Kontextsätze neben dem Kontextsatz flights-assistant auf das Symbol Aktionen ansehen ().

  6. Klicken Sie auf Kontextgruppe bearbeiten.

  7. Klicken Sie im Abschnitt Kontextdatei hochladen auf Durchsuchen und wählen Sie die zuvor generierte Kontextdatei aus.

  8. Klicken Sie auf Speichern.

SQL-Abfrage mit QueryData generieren

In diesem Abschnitt verwenden Sie die hochgeladene Kontextdatei, um Fragen in natürlicher Sprache zu stellen. So können Sie prüfen, ob QueryData Definitionen für Begriffe wie nighttime traffic und andere verwandte Wortgruppen richtig versteht und anwendet.

So generieren Sie SQL-Abfragen:

  1. Klicken Sie im Bereich Explorer neben Ihrem Kontextset auf Aktionen ansehen ().
  2. Klicken Sie auf Kontextset testen.
  3. Klicken Sie im Abfrageeditor auf SQL mit QueryData generieren mit: flights-assistant.

  4. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie dann auf Generieren.

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

    Die generierte SQL-Abfrage sieht in etwa so aus:

    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;

    Das ist dieselbe Frage, die Sie dem Kontext von QueryData hinzugefügt haben. QueryData kann den Begriff nighttime traffic jetzt richtig interpretieren.

    Obwohl der Kontext aus einer bestimmten Frage stammt, verwendet QueryData ihn, um die SQL-Generierung für eine Vielzahl ähnlicher Fragen zu verbessern.

  5. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  6. Geben Sie die folgende ähnliche Frage ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

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

    Da in der Frage der Begriff nighttime traffic durch einen ähnlichen Begriff, evening traffic, ersetzt wird, liefert QueryData eine konsistente Antwort auf diese Frage, indem dieselbe Interpretation angewendet wird.

    Die generierte SQL-Abfrage sieht in etwa so aus:

    -- 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. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  8. Geben Sie die folgende Frage ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    Find flights heading into Manhattan

    Die generierte SQL-Abfrage sieht in etwa so aus:

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

    Beachten Sie, dass QueryData jetzt mithilfe des semantischen Abgleichs genau interpretieren kann, dass sich „Manhattan“ auf „New York“ in der Datenbank bezieht.

QueryData in Ihre Anwendung einbinden

In diesem Abschnitt erstellen Sie einen Daten-Agenten für eine Anwendung zur Flugsuche. Dieser KI-Datenagent bietet eine dialogorientierte Oberfläche für die Tabellen flights und airports, die Sie zuvor erstellt haben. Außerdem wird erläutert, wie Sie diesen Daten-Agenten mit dem Agent Development Kit (ADK), dem Gemini Data Analytics QueryData MCP-Tool und einem Kontextset erstellen und in Ihre Anwendung einbinden, um die Qualität der Antworten zu verbessern.

  1. Laden Sie die MCP Toolbox in der Version 1.14.0 oder höher herunter. Die MCP Toolbox stellt den Daten-Agenten als Tool bereit, mit dem Anwendungen eine Verbindung herstellen können. Die MCP Toolbox unterscheidet sich vom zuvor installierten Context Engineering-Agenten, der Kontext generiert.

  2. Richten Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein.

    gcloud auth application-default login

  3. Suchen Sie die ID des zuvor erstellten Kontextsets. Weitere Informationen zum Ermitteln der Kontextsatz-ID finden Sie unter Kontextsatz-ID ermitteln.

  4. Hängen Sie Folgendes an die tools.yaml-Konfiguration an, um über die MCP Toolbox eine Verbindung zum Daten-Agenten herzustellen. Weitere Informationen finden Sie unter Gemini Data Analytics-Quelle und Gemini Data Analytics-QueryData-Tool.

    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

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • REGION_ID: Die Region Ihrer Cloud SQL-Instanz (z. B. us-central1).
    • INSTANCE_ID: Die ID Ihrer Cloud SQL-Instanz.
    • DATABASE_ID: Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.
    • CONTEXT_SET_ID: Die ID des Kontext-Sets. Weitere Informationen zum Ermitteln der Kontextsatz-ID finden Sie unter Kontextsatz-ID ermitteln.

  5. Führen Sie den MCP Toolbox-Server mit der Datei tools.yaml aus.

    ./toolbox --config PATH_TO_TOOLS_YAML

    Ersetzen Sie PATH_TO_TOOLS_YAML durch den Pfad zur Datei tools.yaml, die Sie zuvor erstellt haben.

  6. Erstellen Sie eine ADK-Anwendung, die das QueryData-Tool von Gemini Data Analytics über das Python SDK der MCP Toolbox aufruft. Weitere Informationen zur Verwendung des Python SDK der MCP Toolbox finden Sie in der Kurzanleitung für die Toolbox. Informationen zum Python ADK finden Sie in der Kurzanleitung für das ADK.

    1. Erstellen Sie ein Verzeichnis zum Speichern der Anwendung, z. B. flight-assistant-app.

    2. Wechseln Sie in das Verzeichnis flight-assistant-app.

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

    3. Führen Sie die folgenden Befehle im Verzeichnis flight-assistant-app aus, um eine virtuelle Umgebung zu erstellen und die erforderlichen Komponenten zu installieren.

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

    4. ADK-Agenten einrichten

      1. ADK-Agenten erstellen

        uv run adk create my_agent

      2. Wählen Sie das Modell gemini-2.5-flash oder ein neueres Modell aus.

      3. Wählen Sie Google AI aus und geben Sie Ihren Gemini API-Schlüssel ein. Weitere Informationen dazu, wie Sie Ihren API-Schlüssel finden, finden Sie unter Gemini API-Schlüssel verwenden. (Wenn Sie keinen kostenlosen Testzeitraum benötigen, können Sie alternativ Vertex AI auswählen und ein Google Cloud -Projekt mit aktivierter Abrechnung angeben.)

    5. Ersetzen Sie den Inhalt der Datei agent.py durch den folgenden Beispielanwendungscode für den 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",  # Or newer.
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. Führen Sie die folgenden Befehle im Verzeichnis flight-assistant-app aus, um die Anwendung zu starten. Rufen Sie den ADK-Webserver unter http://127.0.0.1:8000 auf.

    uv run adk web --port 8000

  8. Geben Sie einen beliebigen Text ein, z. B. hello, um mit dem KI-Agenten zu interagieren.

    Der ADK-Agent beantwortet allgemeine Fragen und ruft die erforderlichen MCP-Tools auf.

  9. Geben Sie die folgende Frage zu einem Flug ein:

    How many flights depart from the west side?

    Das MCP-Tool wird aufgerufen, um diese Frage zu beantworten. Da der Begriff the west jedoch mehrdeutig ist und keine Flughäfen angibt, gibt das MCP-Tool eine Frage zur Mehrdeutigkeitsauflösung zurück, die der KI-Agent verwendet, um eine Antwort zu erstellen.

    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. Geben Sie eine Frage ein, die der Frage in der für den Agenten generierten Abfragevorlage ähnelt.

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

    Basierend auf dem zuvor hinzugefügten QueryData-Kontext versteht das MCP-Tool, dass evening traffic zwischen 17:00 Uhr und 19:00 Uhr stattfindet. Das MCP-Tool gibt die zugehörigen Daten zurück, die der Agent dann für die Antwort verwendet.

    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. Geben Sie eine Frage ein, die auf dem Konzepttyp basiert, den Sie im KI-Agentenkontext hinzugefügt haben.

    Find flights heading into Manhattan

    Basierend auf dem zuvor hinzugefügten Wertsuchkontext versteht der KI-Agent, dass sich „Manhattan“ auf die Stadt „New York“ bezieht, und gibt die zugehörigen Daten zurück, die der KI-Agent dann für die Erstellung seiner Antwort verwenden kann.

    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.

Leistung des KI-Agenten iterieren

In der ADK-Web-UI können Sie die Anfrage und Antwort des MCP-Tools „Gemini Data Analytics QueryData“ prüfen. Anhand dieser Antwort können Sie die Toolantworten wie die generierte SQL-Abfrage, die Ergebnismenge, die Erklärung der Absicht, die Frage zur Mehrdeutigkeitsauflösung und die Antwort in natürlicher Sprache prüfen, um die Richtigkeit der Antworten Ihres KI-Agenten zu bestätigen.

Klicken Sie beispielsweise für den zuvor eingegebenen Eingabetext How many flights depart from the west side? auf die Agent-Blase. Maximieren Sie auf dem Tab Ereignis im linken Navigationsbereich functionResponse, um die folgende Antwort zu sehen.

"{"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?"]}"

Antwortgenauigkeit optimieren

Sie können die Genauigkeit der Antworten des QueryData-Tools von Gemini Data Analytics kontinuierlich verbessern, indem Sie zusätzlichen Kontext hinzufügen. Verwenden Sie den Kontext-Engineering-Agenten, um Kontext zu generieren, und laden Sie dann die aktualisierte Kontextset-Datei in den vorhandenen KI-Datenagenten flights-assistant hoch. Weitere Informationen finden Sie unter Kontextsätze in Cloud SQL Studio verwalten. Die Konsole übernimmt neuen Kontext sofort nach dem Hochladen. So können Sie die Genauigkeit des KI-Agenten ohne Ausfallzeiten der Anwendung verbessern.

Mehrere KI-Agenten

In Ihrer Entwicklungsumgebung können Sie A/B-Tests für mehrere KI-Datenagenten-Kontexte durchführen, indem Sie Tools in Ihrer tools.yaml-Datei unterschiedliche Namen zuweisen. Sie können beispielsweise eindeutige tools.yaml-Konfigurationen erstellen, indem Sie zwei cloud-gemini-data-analytics-query-Tools mit unterschiedlichen Namen definieren, z. B. cloud_gda_query_tool_v1 und cloud_gda_query_tool_v2. Mit dieser Einrichtung können Sie eine Anwendungslogik implementieren, die die erforderliche Kontextversion programmatisch auswählt, indem der entsprechende Toolname ausgewählt wird.

Im folgenden Beispiel tools.yaml wird gezeigt, wie Sie mehrere Daten-Agenten für eine Datenbankquelle einrichten:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • V1_YOUR_CONTEXT_SET_ID: die Kontext-Set-ID für Version 1.
  • V2_YOUR_CONTEXT_SET_ID: die Kontext-Set-ID für Version 2.
  • DB_SOURCE: die Konfigurationen der Datenbankquelle.

Bereinigen

Nachdem Sie diese Anleitung abgeschlossen haben, löschen Sie die erstellten Ressourcen, um laufende Kosten zu vermeiden. In den folgenden Abschnitten erfahren Sie, wie Sie diese Ressourcen löschen.

Kontextset löschen

Bevor Sie die Instanz löschen, müssen Sie den von Ihnen erstellten Kontextsatz löschen.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der Authentifizierung über Identity and Access Management in Studio an.

  5. Klicken Sie im Bereich Explorer neben Ihrem Kontextsatz auf Aktionen ansehen ().

  6. Klicken Sie auf Kontextset löschen.

  7. Geben Sie im Fenster Kontextgruppe löschen den Wert flights-assistant ein.

  8. Klicken Sie auf Bestätigen.

Instanz löschen

Wenn Sie die Instanz löschen, die Sie im Abschnitt Vorbereitung erstellt haben, werden auch alle von Ihnen erstellten Objekte gelöscht.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie auf Löschen.

  4. Bestätigen Sie, dass Sie die Instanz löschen möchten, indem Sie den Instanznamen eingeben und auf Löschen klicken.

Nächste Schritte