QueryData in eine Anwendung einbinden

In dieser Anleitung wird beschrieben, wie Sie QueryData in Cloud SQL for PostgreSQL mit der Google Cloud Console einrichten und verwenden und in Ihre Anwendung einbinden. Hier erfahren Sie, wie Sie die Kontextset-Datei 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

  • Datenbanken erstellen und mit Daten füllen
  • Erstellen Sie mit dem Context-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.
  • LLM-Antworten mit Wertsuchanfragen fundieren

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, wenn Sie die Aufgaben in diesem Dokument abgeschlossen haben, um weitere Kosten zu vermeiden. 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

Achten Sie darauf, dass Sie Zugriff auf eine vorhandene Cloud SQL-Instanz haben, oder erstellen Sie eine neue. Weitere Informationen finden Sie unter Instanzen für Cloud SQL erstellen.

Für diese Anleitung benötigen Sie eine Datenbank in Ihrer Cloud SQL-Instanz. Weitere Informationen finden Sie unter Datenbank auf der Cloud SQL-Instanz erstellen.

Erforderliche Rollen und Berechtigungen

  • Fügen Sie der Instanz einen IAM-Nutzer oder ein Dienstkonto hinzu. Weitere Informationen finden Sie unter Nutzer mit IAM-Datenbankauthentifizierung für Cloud SQL verwalten.
  • Weisen Sie dem IAM-Nutzer auf Projektebene die Rollen cloudsql.studioUser, cloudsql.instanceUser und geminidataanalytics.queryDataUser zu. Weitere Informationen finden Sie unter IAM-Richtlinienbindung für ein Projekt hinzufügen.
  • Wenn Sie Kontextgruppen erstellen, hochladen und verwalten möchten, weisen Sie dem IAM-Nutzer auf Projektebene die Rolle „Dataplex Catalog Editor“ (roles/dataplex.catalogEditor) oder „Dataplex Catalog Admin“ (roles/dataplex.catalogAdmin) zu. Weitere Informationen finden Sie unter Berechtigungen für Kontextsets.
  • Außerdem müssen Sie einem IAM-Nutzer oder -Dienstkonto Leseberechtigungen für die Datenbank gewähren, indem Sie sich als Nutzer mit Superuser-Berechtigungen anmelden, z. B. als postgres-Nutzer.

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;

    Ersetzen Sie USER_NAME durch die E-Mail-Adresse des Nutzers. Da die E-Mail-Adresse Sonderzeichen (@ und .) enthält, muss sie in Anführungszeichen gesetzt werden.

    Weitere Informationen finden Sie unter Datenbankberechtigungen für einen einzelnen IAM-Nutzer oder ein einzelnes Dienstkonto gewähren.

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 erteilen 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 an, um die Schritte in dieser Anleitung auszuführen Google Cloud 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 und das Schema airports 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 ausfüllen

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

  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 "public"."flights" LIMIT 10;
SELECT * FROM "public"."airports" LIMIT 10;

Kontextsatz in Cloud SQL Studio erstellen

In diesem Abschnitt erstellen Sie einen Kontextsatz mit dem Namen flights-assistant. Dieser Kontextsatz enthält keine hochgeladene Kontextsatzdatei.

  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 Weitere Aktionen ().

  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 flights-assistant-Kontext, der durch Fragen in natürlicher Sprache festgelegt wurde, 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 Explorer-Bereich neben Ihrem Kontextset auf das Dreipunkt-Menü ().
  2. Klicken Sie auf Kontextset testen.
  3. Klicken Sie im Abfrageeditor auf SQL mit QueryData generieren: 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 für diese eindeutige Frage den richtigen SQL-Code.

      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. Das kann dazu führen, dass keine SQL-Abfrage generiert wird oder dass eine Abfrage generiert wird, in der der Begriff ignoriert wird, wie in der folgenden Abfrage zu sehen ist.

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

    flight to disney world

    Die Kontextsatzlogik generiert eine Abfrage, um einen Flughafen mit „disney world“ im Namen zu finden. Da es in der Datenbank keinen solchen Flughafen oder keine solche Stadt gibt, werden bei der Abfrage keine Zeilen zurückgegeben.

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
INNER JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."name" ILIKE '%Disney World%';

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 der 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 ein Projektmanager, das eine Voraussetzung für den Context Engineering-Agent 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 den Anweisungen des Skills. Weitere Informationen zur tools.yaml-Datei finden Sie in der Dokumentation zur MCP Toolbox.

  8. Führen Sie den folgenden Befehl in der Antigravity CLI aus, um die Konfiguration neu zu laden, nachdem die Datei tools.yaml erstellt wurde, und folgen Sie der Anleitung zum Neuladen des Toolbox-MCP-Servers:

    /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 Agenten-Plug-in für Context Engineering 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 den 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 Kontextsets.

  3. Sehen Sie sich die generierte Abfragevorlage an. 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üge nach Disney World“ fragt, kann die Wertesuche dies anhand des Konzepttyps, der der Spalte airports.city in Ihrer Datenbank entspricht, Disney World in „Orlando“ zuordnen.

So generieren Sie einen Suchkontext für Werte:

  1. Geben Sie den folgenden Prompt in die Agent Harness ein:

  2. Geben Sie postgresql ein, um Cloud SQL als Datenbankmodul auszuwählen.

  3. Geben Sie die Konfiguration für die Wertsuche so ein:

    Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "SEMANTIC_SIMILARITY_MATCH".

  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 Kontextsatzdatei generiert wurde.

    Die vorhandene Kontextdatei wird mit der Wertesuchdefinition mit folgendem Inhalt aktualisiert:

      {
    "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 = $1 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 $1"
        }
      }
    ],
    "value_searches": [
      {
          "query": "/* Requires extensions: vector, google_ml_integration */ WITH SemanticMetrics AS (    SELECT T.city AS original_value, (        (google_ml.embedding('gemini-embedding-001', $value)::vector <=>          google_ml.embedding('gemini-embedding-001', T.city)::vector) / 2.0    ) AS normalized_dist     FROM airports T     WHERE T.city IS NOT NULL) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, ''::text AS context FROM SemanticMetrics",
          "concept_type": "Airport City",
          "description": "Semantic search for airport city name"
      }
  ]
  }

Kontextsatzdatei in QueryData hochladen

In diesem Abschnitt laden Sie die Kontextset-Datei in QueryData hoch, damit die SQL-Generierungsfunktionen von QueryData für Ihre Datenbank verbessert werden.

Führen Sie die folgenden Schritte aus, um den Kontext hochzuladen:

  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 Kontextsätze auf das Symbol Aktionen ().

  6. Klicken Sie auf Kontextgruppe bearbeiten.

  7. Klicken Sie im Abschnitt Kontextset-Datei hochladen auf Durchsuchen und wählen Sie die zuvor generierte Kontextset-Datei 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 überprüfen, ob QueryData Definitionen für Begriffe wie nighttime traffic und andere ähnliche Begriffe richtig versteht und anwendet und ob die Wertsuche Wertbegriffe bestimmten Werten zuordnet, die in Ihren Datenbankspalten gespeichert sind (z. B. „Disney World“ zu „Orlando“).

So generieren Sie SQL-Abfragen:

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

  4. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie 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.

    flights to disney world

    Die generierte SQL-Abfrage sieht in etwa so aus:

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."city" = 'Orlando';

    QueryData kann jetzt korrekt interpretieren, dass sich „disney world“ auf die Stadt „Orlando“ 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 konversationelle 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-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 ein.

    gcloud auth application-default login

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

  4. Hängen Sie Folgendes an die tools.yaml-Konfiguration an, um über die MCP Toolbox eine Verbindung zum KI-Datenagenten 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: "POSTGRESQL"
        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 autoctx/tools.yaml

  6. Erstellen Sie eine ADK-Anwendung, die das Gemini Data Analytics QueryData-Tool ü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-Agent erstellen

        uv run adk create my_agent

      2. Wählen Sie das Modell gemini-3.8-flash oder neuer aus.

      3. Wählen Sie Google AI aus und geben Sie Ihren Gemini API-Schlüssel ein. Weitere Informationen zum Abrufen Ihres API-Schlüssels 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-3.8-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 und über http://127.0.0.1:8000 auf den ADK-Webserver zuzugreifen.

    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 zum Erstellen einer Antwort verwendet.

    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 weiß 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 zum Erstellen seiner Antwort verwenden kann.

    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 Kontext des QueryData-Agenten hinzugefügt haben.

    Get me flights to disney world

    Basierend auf dem zuvor hinzugefügten Wertsuchkontext versteht der QueryData-Agent, dass sich „disney world“ auf die Stadt „Orlando“ bezieht, und gibt die zugehörigen Daten zurück, die der QueryData-Agent zum Erstellen seiner Antwort verwenden kann.

    Here are the flights heading to Orlando, which is the location of Disney World:

* Flight UA 1249 departs from SFO and arrives at MCO on 2025-01-02 at 18:15:00Z.
* Flight UA 698 departs from SFO and arrives at MCO on 2025-01-02 at 22:33:00Z.
* Flight UA 292 departs from SFO and arrives at MCO on 2025-01-03 at 06:37:00Z.

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, das Ergebnisset, die Intent-Erklärung, die Disambiguierungsfrage und die Antwort in natürlicher Sprache beobachten, um die Richtigkeit der Antworten Ihres KI-Agenten zu überprüfen.

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 die 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 verbessern

Sie können die Genauigkeit der Antworten des Gemini Data Analytics-Tools „QueryData“ 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 flights-assistant-Datenagenten hoch. Weitere Informationen finden Sie unter Kontextsets in Cloud SQL Studio verwalten. Die Console übernimmt den 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 Data Agent-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 KI-Datenagenten 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: Ihre Google Cloud Projekt-ID
  • V1_YOUR_CONTEXT_SET_ID: Die ID des Kontextsets für Version 1.
  • V2_YOUR_CONTEXT_SET_ID: Die Kontext-Set-ID für Version 2.

Bereinigen

Nachdem Sie diese Anleitung abgeschlossen haben, sollten Sie die erstellten Ressourcen löschen, 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 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 Identity and Access Management-Authentifizierung in Studio an.

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

  6. Geben Sie im Fenster Kontextgruppe löschen im Bestätigungsfeld flight-assistant ein.

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