QueryData in eine Anwendung einbinden

In dieser Anleitung wird beschrieben, wie Sie QueryData in Spanner über die Google Cloud Console einrichten und verwenden und in Ihre Anwendung einbinden. Hier erfahren Sie, wie Sie die Datei für Kontextsets erstellen, ein Kontextset erstellen, das die Kontextset-Datei verwendet, mit der MCP Toolbox die QueryData-Methode in der konversationellen Analyse-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 Spanner Studio generieren
  • QueryData mit dem Tool Gemini Data Analytics QueryData in der MCP Toolbox 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

Bevor Sie einen Kontextsatz erstellen, müssen Sie die folgenden Voraussetzungen erfüllen.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

Spanner-Instanz vorbereiten

Erforderliche Rollen und Berechtigungen

flights- und airports-Schema und -Tabellen 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 „Spanner“ auf.

    Spanner aufrufen

  2. Wählen Sie eine Instanz aus der Liste und dann eine Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

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

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

    CREATE TABLE IF NOT EXISTS airports (
      id INT64 PRIMARY KEY,
      iata STRING(MAX),
      name STRING(MAX),
      city STRING(MAX),
      country STRING(MAX)
    );
    
  6. Erstellen Sie die Tabelle flights und das Schema:

    CREATE TABLE flights (
      id INT64 NOT NULL,
      airline STRING(10),
      flight_number INT64,
      departure_airport STRING(5),
      arrival_airport STRING(5),
      departure_time TIMESTAMP,
      arrival_time TIMESTAMP,
      departure_gate STRING(10),
      arrival_gate STRING(10)
    ) PRIMARY KEY (id);
    

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;
    

Tokenisierte Spalten und Suchindexe erstellen

Mit den integrierten Textsuchfunktionen von Spanner kann QueryData unstrukturierte Formulierungen in natürlicher Sprache, z. B. Tippfehler oder unvollständige Namen, bestimmten Werten in Ihrer Datenbank genau zuordnen. Dazu muss eine ausgeblendete TOKENLIST-Spalte generiert werden, die Ihre Strings in n-grams aufschlüsselt, und ein Suchindex für diese Spalte erstellt werden.

Führen Sie die folgenden SQL-Anweisungen aus, um tokenisierte Spalten und Suchindexe zu erstellen:

  1. Erstellen Sie die Tokenspalte und den Index für Flughafennamen:

    ALTER TABLE `airports` ADD COLUMN `name_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`name`)) STORED HIDDEN;
    CREATE SEARCH INDEX `airports_name_idx` ON `airports`(`name_tokens`);
    
  2. Erstellen Sie die Tokenspalte und den Index für Flughafenstädte:

    ALTER TABLE `airports` ADD COLUMN `city_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`city`)) STORED HIDDEN;
    CREATE SEARCH INDEX `airports_city_idx` ON `airports`(`city_tokens`);
    

Kontextset in Spanner 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 „Spanner“ auf.

    Spanner aufrufen

  2. Wählen Sie eine Instanz aus der Liste und dann eine Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

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

  5. Klicken Sie auf Kontextgruppe erstellen.

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

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

    Show me the flight to Houston Intercontinental
    

    Die Kontextset-Logik generiert eine Abfrage, um einen Flughafen mit „Houston Intercontinental“ 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
      f.*
    FROM
      `flights` AS f
    JOIN
      `airports` AS a
    ON
      f.arrival_airport = a.id
    WHERE
      a.name LIKE '%Houston Intercontinental%';
    

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
    gcloud auth application-default set-quota-project PROJECT_ID
  4. Installieren Sie uv, ein Python-Paket und einen Projektmanager, der für den Context 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 .context-engineering/tools.yaml definiert.

    Geben Sie einen Prompt wie den folgenden ein, um die Konfigurationsdatei .context-engineering/tools.yaml zu erstellen:

    Help me set up a database connection.
    

    Folge der Anleitung des Skills. 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 .context-engineering/tools.yaml neu zu laden. Folgen Sie dann 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 beheben Sie das Problem aus dem vorherigen Abschnitt, bei dem QueryData den Begriff nighttime traffic nicht erkannt hat. Definieren Sie den Begriff in der Kontextdatei als Traffic, der zwischen 5:00 PM und 7:00 PM auftritt.

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 AT TIME ZONE 'UTC') < 17
        OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19
      )
    ORDER BY
      f.departure_time;
    
  2. Der KI-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. Sehen Sie sich die generierte Abfragevorlage an. Sie können die Abfragevorlage entweder als neue Agentenkontextdatei speichern oder an eine vorhandene Agentenkontextdatei 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 AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 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 AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 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 Kontextlogik Wertphrasen mithilfe von Stringähnlichkeit (Trigramm-Abgleich) bestimmten Werten zuordnen kann, die in Ihren Datenbankspalten gespeichert sind. Wenn ein Nutzer beispielsweise nach Flügen nach „Houston Intercontinental“ sucht, kann die Wertsuche dies dem genauen Datenbankwert „George Bush Intercontinental Houston Airport“ zuordnen.

So generieren Sie einen Suchkontext für Werte:

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

    Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "TRIGRAM_STRING_MATCH".
  2. 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.

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

  4. Geben Sie die Datenbankinstanz und den Datenbanknamen ein, für die die Kontextsatzdatei generiert wurde.

    Die vorhandene Kontextdatei wird mit der Definition der Wertsuche aktualisiert und enthält dann den 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 AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 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 AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 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 CAST(T.`name` AS STRING) AS value, 'name' AS `columns`, 'airport name' AS concept_type, 1 - SCORE_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) ",
        "concept_type": "airport name",
        "description": "String similarity using Spanner Search Indexes."
      },
      {
        "query": "SELECT CAST(T.`city` AS STRING) AS value, 'city' AS `columns`, 'airport city' AS concept_type, 1 - SCORE_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) ",
        "concept_type": "airport city",
        "description": "String similarity using Spanner Search Indexes."
      }
    ]
    }
    

Kontextsatzdatei in QueryData hochladen

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 „Spanner“ auf.

    Spanner aufrufen

  2. Wählen Sie eine Instanz aus der Liste und dann eine Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

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

  5. Klicken Sie auf Kontextgruppe bearbeiten.

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

  7. 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 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 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 AT TIME ZONE 'UTC') < 17
        OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 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 korrekt 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 AT TIME ZONE 'UTC') < 17
        OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19
      )
    ORDER BY
      f.departure_time;
    
  7. Geben Sie die folgende Frage ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    Show me the flight to Houston Intercontinental
    

    Die generierte SQL-Abfrage sieht in etwa so aus:

    SELECT
      f.*
    FROM
      flights AS f
    INNER JOIN
      airports AS a
    ON
      f.arrival_airport = a.iata
    WHERE
      a.name = 'George Bush Intercontinental Houston Airport'
    

    QueryData kann jetzt korrekt interpretieren, dass sich „Houston Intercontinental“ auf den „George Bush Intercontinental Houston Airport“ 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 QueryData-MCP-Tool von Gemini Data Analytics 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 (Application Default Credentials, ADC) ein.

    gcloud auth application-default login
    gcloud auth application-default set-quota-project PROJECT_ID
  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 .context-engineering/tools.yaml-Konfiguration (oder tools.yaml in Ihrem Arbeitsverzeichnis) 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:
        spannerReference:
          databaseReference:
            engine: "GOOGLE_SQL"
            projectId: "PROJECT_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 Spanner-Instanz (z. B. us-central1).
    • INSTANCE_ID: Die ID Ihrer Cloud Spanner-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 zuvor erstellten tools.yaml-Datei (z. B. .context-engineering/tools.yaml oder 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 und für das Python ADK 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 höher 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, ein Google Cloud Projekt mit aktivierter Abrechnung angeben und global eingeben, wenn Sie nach der Google Cloud Region (Enter Google Cloud region) gefragt werden, damit GOOGLE_CLOUD_LOCATION=global in my_agent/.env festgelegt wird.)

    5. Ersetzen Sie den Inhalt der Datei agent.py durch den folgenden Beispielcode für die Flight Data Assistant-Anwendung.

      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. Greifen Sie unter http://127.0.0.1:8000 auf den ADK-Webserver zu.

    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 in der Abfragevorlage für den Agenten generierten Frage ä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 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 Kontext des QueryData-Agenten hinzugefügt haben.

    Show me the flight to Houston Intercontinental
    

    Basierend auf dem zuvor hinzugefügten Suchkontext für Werte versteht der Agent, dass sich „Houston Intercontinental“ auf „George Bush Intercontinental Houston Airport“ (Flughafencode IAH) bezieht, und gibt die zugehörigen Daten zurück, die der Agent zum Erstellen seiner Antwort verwenden kann.

    Here are the flights heading to Houston Intercontinental (IAH):
    
    * Flight UA 1285 departs from SFO and arrives at IAH on 2025-01-01 at 15:20:00Z.
    * Flight F9 1056 departs from SFO and arrives at IAH on 2025-01-02 at 12:09:00Z.
    * Flight UA 1722 departs from SFO and arrives at IAH on 2025-01-02 at 18:29:00Z.
    * Flight UA 1705 departs from SFO and arrives at IAH on 2025-01-02 at 18:50:00Z.
    * Flight UA 1762 departs from SFO and arrives at IAH on 2025-01-02 at 23:11:00Z.
    

Leistung des KI-Agenten iterieren

In der ADK-Web-UI können Sie die Anfrage und Antwort des MCP-Tools „QueryData“ von Gemini Data Analytics 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 Spanner Studio verwalten. Die Konsole ü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 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 tools.yaml-Beispiel 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 „Spanner“ auf.

    Spanner aufrufen

  2. Wählen Sie eine Instanz aus der Liste und dann eine Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

  4. Klicken Sie im Bereich Explorer neben Ihrem Kontextset auf Aktionen ansehen ().

  5. Klicken Sie auf Kontextset löschen.

  6. Geben Sie im Fenster Kontextgruppe löschen den Wert flights-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 „Spanner“ auf.

    Spanner aufrufen

  2. Klicken Sie auf den Namen der Instanz, die Sie löschen möchten, z. B. Testinstanz.

  3. Klicken Sie auf Instanz 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