QueryData in eine Anwendung einbinden

In dieser Anleitung wird beschrieben, wie Sie QueryData in Spanner Graph mit der Google Cloud Console einrichten und verwenden und in Ihre Anwendung einbinden. Sie erfahren, wie Sie den Property-Graphen FinGraph einrichten, mit dem Context-Engineering-Agenten eine Kontextset-Datei in der Graph Query Language (GQL) erstellen, ein Kontextset in Spanner Studio erstellen, QueryData testen, indem Sie die QueryData-Methode in der Conversational Analytics API mit konfiguriertem graph_ids aufrufen, und ein benutzerdefiniertes HTTP-Tool in der MCP Toolbox verwenden, um eine Agent-Anwendung mit QueryData zu verbinden.

Weitere Informationen finden Sie unter QueryData – Übersicht.

Ziele

  • Erstellen Sie das Attributdiagrammschema FinGraph und füllen Sie es mit Beispieldiagrammdaten.
  • Erstellen Sie mithilfe des Kontext-Engineering-Agenten eine Kontextset-Datei für FinGraph.
  • Erstellen Sie ein Kontextset und laden Sie die Kontextset-Datei in Spanner Studio hoch.
  • Testen Sie QueryData und generieren Sie GQL-Abfragen, indem Sie die QueryData REST API mit graph_ids in spanner_reference aufrufen.
  • Integrieren Sie QueryData in Ihre Anwendung, indem Sie ein benutzerdefiniertes HTTP-Tool in der MCP Toolbox verwenden, das die QueryData REST API aufruft.
  • Fundieren Sie LLM-Antworten in Ihren Grafikdaten mithilfe von Abfragevorlagen, Abfragefacetten und GRAPH_TABLE-Wert-Suchanfragen.

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

FinGraph-Schema erstellen und Grafikdaten einfügen

In diesem Tutorial wird das Finanz-Property-Graph-Dataset FinGraph verwendet, das Person- und Account-Knoten modelliert, die durch Owns- (PersonOwnAccount) und Transfers-Kanten (AccountTransferAccount) verbunden sind.

Führen Sie die folgenden Schritte aus dem Einrichtungsleitfaden für Spanner Graph aus, um das Schema FinGraph zu erstellen und die Grafikdaten in Ihrer Spanner-Datenbank zu füllen:

  1. Folgen Sie der Anleitung unter Graphdatenbank mit einem Schema erstellen, um die Tabellen Person, Account, PersonOwnAccount und AccountTransferAccount sowie die Definition des Property Graphs FinGraph zu erstellen.
  2. Folgen Sie der Anleitung unter Grafikdaten einfügen, um die Beispielpersonen (Alex, Dana und Lee), Konten (7, 16 und 20), Kontoinhaberkanten und Geldtransferkanten in FinGraph einzufügen.

Kontextset erstellen

Erstellen Sie ein leeres Kontextset mit dem Namen fingraph-assistant. Später in dieser Anleitung laden Sie eine Kontextsatzdatei in diesen Bucket hoch.

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

    Spanner aufrufen

  2. Wählen Sie Ihre Instanz aus der Liste und dann die Datenbank aus, die FinGraph enthält.

  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 im Feld Name des Kontextsets den Wert fingraph-assistant ein.

  7. Klicken Sie auf Erstellen.

QueryData ohne Kontext testen

In diesem Abschnitt rufen Sie die QueryData REST API auf, um GQL-Abfragen für Fragen in natürlicher Sprache ohne Kontext zu generieren. Ohne Kontext kann QueryData Fragen beantworten, die sich direkt auf das Schema FinGraph beziehen. Es kann jedoch keine benutzerdefinierte Geschäftsterminologie wie high-risk transfers interpretieren oder Unterschiede bei der Wertformatierung wie Czech Republic im Vergleich zu Czech_Republic auflösen.

  1. Legen Sie im Terminal die folgenden Umgebungsvariablen fest:

    export PROJECT_ID="PROJECT_ID"
    export INSTANCE_ID="INSTANCE_ID"
    export DATABASE_ID="DATABASE_ID"
    

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Projekt-ID in Google Cloud .
    • INSTANCE_ID: Ihre Spanner-Instanz-ID.
    • DATABASE_ID: die ID der Datenbank, die FinGraph enthält.
  2. Erstellen Sie ein Hilfsskript mit dem Namen query_data.sh, das eine Frage an die QueryData REST API sendet, wobei graph_ids auf FinGraph gesetzt ist. Wenn die Umgebungsvariable CONTEXT_SET_ID festgelegt ist, sendet das Script auch Ihre Kontextsatz-ID:

    cat > query_data.sh <<'EOF'
    #!/bin/bash
    # Usage: ./query_data.sh "NATURAL_LANGUAGE_QUESTION"
    if [[ -n "${CONTEXT_SET_ID}" ]]; then
      AGENT_CONTEXT=", \"agent_context_reference\": {\"context_set_id\": \"${CONTEXT_SET_ID}\"}"
    fi
    curl -sS -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: ${PROJECT_ID}" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global:queryData" \
      -d @- <<JSON
    {
      "prompt": "$1",
      "context": {
        "datasource_references": {
          "spanner_reference": {
            "database_reference": {
              "engine": "GOOGLE_SQL",
              "project_id": "${PROJECT_ID}",
              "instance_id": "${INSTANCE_ID}",
              "database_id": "${DATABASE_ID}",
              "graph_ids": ["FinGraph"]
            }${AGENT_CONTEXT}
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }
    JSON
    EOF
    chmod +x query_data.sh
    

    Das Skript fügt Ihre Frage unverändert in den Anfragetext ein. Verwenden Sie daher keine doppelten Anführungszeichen (") in der Frage.

  3. Stellen Sie eine Frage, die sich direkt auf das Schema FinGraph bezieht:

    ./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
    

    Prüfen Sie in der Antwort die Felder generatedQuery und queryResult. Für diese eindeutige Frage generiert QueryData eine GQL-Abfrage, die etwa so aussieht:

    GRAPH FinGraph
    MATCH
      (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account),
      (recipient:Person)-[:Owns]->(dst)
    RETURN
      recipient.name AS recipient_name,
      dst.id AS recipient_account_id,
      t.amount AS transfer_amount;
    

    Dies gibt Ergebnisse wie die folgenden zurück:

    +----------------+----------------------+-----------------+
    | recipient_name | recipient_account_id | transfer_amount |
    +----------------+----------------------+-----------------+
    | Alex           | 7                    | 500             |
    | Lee            | 16                   | 200             |
    +----------------+----------------------+-----------------+
    
  4. Stellen Sie eine Frage, die den Unternehmensbegriff high-risk transfers enthält:

    ./query_data.sh "Find all high-risk transfers initiated by Alex"
    

    Da im FinGraph-Schema nicht definiert ist, was eine high-risk transfer ist (was in Ihrer Geschäftslogik eine Überweisung von 200 oder mehr auf ein gesperrtes Konto bedeutet, wobei is_blocked = true), wendet QueryData entweder die Filter für gesperrte Konten und Betragsschwellenwerte nicht an oder wendet seine eigene Interpretation des Begriffs an. QueryData könnte beispielsweise einen Betragsschwellenwert erfinden, der keine Zeilen zurückgibt, oder den Begriff ignorieren und eine Abfrage wie die folgende generieren:

    -- Returning transfers initiated by Alex because 'high-risk' is not defined in the schema.
    GRAPH FinGraph
    MATCH
      (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account)
    RETURN
      src.id AS source_account_id,
      dst.id AS destination_account_id,
      t.amount AS transfer_amount,
      t.order_number;
    

    Dadurch werden beide Übertragungen von Alex zurückgegeben, einschließlich der Übertragung von 100, die den Schwellenwert nicht erreicht:

    +-------------------+------------------------+-----------------+-----------------+
    | source_account_id | destination_account_id | transfer_amount | order_number    |
    +-------------------+------------------------+-----------------+-----------------+
    | 7                 | 16                     | 300             | 304330008004315 |
    | 7                 | 16                     | 100             | 304120005529714 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. Stellen Sie eine Frage, die sich auf ein Land bezieht:

    ./query_data.sh "Find accounts owned by people from Czech Republic"
    

    Ohne Kontext oder Wertverknüpfung generiert QueryData eine GQL-Abfrage, die nach 'Czech Republic' mit einem Leerzeichen filtert. Da das Attribut Person.country in FinGraph den Wert als 'Czech_Republic' mit einem Unterstrich speichert, gibt die Abfrage keine Zeilen zurück:

    GRAPH FinGraph
    MATCH
      (p:Person {country: 'Czech Republic'})-[:Owns]->(a:Account)
    RETURN
      p.name AS owner_name,
      a.id AS account_id,
      a.nick_name;
    

Kontext für das Kontextset generieren

In diesem Abschnitt bereiten Sie Ihre lokale Umgebung vor und verwenden den Kontext-Engineering-Agenten, um eine Kontextset-Datei (context_set.json) für den Eigenschaftsgraphen FinGraph in Ihrer Spanner-Datenbank zu erstellen.

Umgebung einrichten

So richten Sie Ihre Umgebung für den Kontext-Engineering-Agenten 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 den folgenden Befehl aus, um sich zu authentifizieren:

    gcloud auth application-default login
  4. Kontext-Engineering-Agent installieren

  5. Starten Sie in Ihrem Terminal die Antigravity CLI:

    agy
  6. Richten Sie die Datenbankverbindung für Ihre Spanner-Datenbank ein. Geben Sie einen Prompt ein, der explizit angibt, dass Sie Kontext für die Property-Graphen in Ihrer Spanner-Datenbank generieren, und der den Namen des Property-Graphen FinGraph enthält, damit der Agent den GQL-spezifischen Kontext-Engineering-Workflow auslöst:

    Help me set up the database connection for the FinGraph property graph in my Spanner database.
    

    Folgen Sie der Anleitung des KI-Agenten, um autoctx/tools.yaml und autoctx/state.md zu erstellen. Öffnen Sie dann autoctx/state.md und prüfen Sie, ob der Abschnitt ## Active Database die Zeile - **Graph Ids**: ["FinGraph"] enthält. Der Kontext-Engineering-Agent liest die Namen der Eigenschaftsgraphen aus dieser Zeile, wenn er Bewertungskonfigurationen generiert. Weitere Informationen zu tools.yaml finden Sie in der Dokumentation zur MCP Toolbox.

  7. Führen Sie den folgenden Befehl in der Antigravity CLI aus, um die Konfiguration nach dem Erstellen von autoctx/tools.yaml neu zu laden:

    /mcp
  8. Wählen Sie toolbox und dann 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

GQL-Vorlagenkontext generieren

Um das Problem zu beheben, dass QueryData den Geschäftsbegriff high-risk transfers nicht erkannt hat, definieren Sie high-risk transfers in der Kontextsatzdatei als Überweisungen von 200 oder mehr, die an ein gesperrtes Konto (dst.is_blocked = true) gesendet wurden.

So generieren Sie den GQL-Vorlagenkontext:

  1. Geben Sie den folgenden Prompt in das Agenten-Framework ein und geben Sie an, dass FinGraph ein Property-Graph in Ihrer Spanner-Datenbank ist:

    For the FinGraph property graph in my Spanner database, generate a GQL template for the question: "Find all high-risk transfers initiated by Alex" with the following GQL query:
    GRAPH FinGraph
    MATCH
      (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true})
    WHERE
      t.amount >= 200
    RETURN
      dst.id AS destination_account_id,
      t.amount AS transfer_amount
    ORDER BY
      t.amount DESC;
  2. Der Agent wandelt Ihre Eingabe in eine parametrisierte GQL-Vorlage um, die für alle Personennamen gilt. Weitere Informationen finden Sie unter Kontextsätze – Übersicht.

  3. Prüfen Sie die generierte GQL-Abfragevorlage und geben Sie dann den Prompt Save it to context_set.json ein. Der Agent erstellt context_set.json in Ihrem Verzeichnis mit folgendem Inhalt:

    {
      "templates": [
        {
          "nl_query": "Find all high-risk transfers initiated by Alex",
          "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;",
          "intent": "Find all high-risk transfers initiated by Alex",
          "manifest": "Find all high-risk transfers initiated by a given person",
          "parameterized": {
            "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;",
            "parameterized_intent": "Find all high-risk transfers initiated by ?"
          }
        }
      ]
    }
    

Suchkontext für Facetten und Werte generieren

In diesem Abschnitt fügen Sie context_set.json ein GQL-Attribut und zwei GRAPH_TABLE-Wert-Suchanfragen hinzu. Die Vorlage, die Sie im vorherigen Abschnitt hinzugefügt haben, beantwortet Fragen, die dieselbe Struktur haben wie „Finde alle von Alex initiierten Übertragungen mit hohem Risiko“. Die Facette erfasst das Muster für gesperrte Konten, sodass QueryData es auch auf Fragen anwenden kann, die nicht mit der Vorlage übereinstimmen, z. B. „Finde alle Geldtransfers, an denen ein gesperrtes Konto beteiligt ist“. Mit der Wertsuche kann QueryData Wertphrasen wie Czech Republic dem gespeicherten Wert Czech_Republic in Person.country zuordnen und Konto-Spitznamen in Account.nick_name unabhängig von der Groß-/Kleinschreibung abgleichen.

  1. Geben Sie den folgenden Prompt in das Agenten-Framework ein und geben Sie an, dass FinGraph ein Property-Graph in Ihrer Spanner-Datenbank ist:

    For the FinGraph property graph in my Spanner database, generate a GQL facet with the GQL clause "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})" for intent "transfers involving a blocked account". Then generate two GRAPH_TABLE value searches on FinGraph: one on Person.country that ignores case and treats underscores as spaces, with concept type "Person country", and one on Account.nick_name that ignores case, with concept type "Account nickname". Validate the value search queries against the database, and then append the facet and value searches to context_set.json.
    
  2. Sehen Sie sich die aktualisierte Datei context_set.json an, die jetzt die GQL-Vorlage, die GQL-Facette und die Definitionen für die Wertsuche enthält:

    {
      "templates": [
        {
          "nl_query": "Find all high-risk transfers initiated by Alex",
          "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;",
          "intent": "Find all high-risk transfers initiated by Alex",
          "manifest": "Find all high-risk transfers initiated by a given person",
          "parameterized": {
            "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;",
            "parameterized_intent": "Find all high-risk transfers initiated by ?"
          }
        }
      ],
      "facets": [
        {
          "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})",
          "intent": "transfers involving a blocked account",
          "manifest": "transfers involving a blocked account",
          "parameterized": {
            "parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})",
            "parameterized_intent": "transfers involving a blocked account"
          }
        }
      ],
      "value_searches": [
        {
          "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)",
          "concept_type": "Person country",
          "description": "Match for country names on Person nodes in FinGraph that ignores case and treats underscores as spaces"
        },
        {
          "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE LOWER(a.nick_name) = LOWER($value) RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 0 AS distance, JSON '{}' AS context)",
          "concept_type": "Account nickname",
          "description": "Case-insensitive match for account nicknames on Account nodes in FinGraph"
        }
      ]
    }
    

    Bei jeder Wertsuche wird der Operator GRAPH_TABLE verwendet, um ein Knotenlabel in FinGraph abzugleichen. Zurückgegeben werden der gespeicherte Attributwert, der Attributspeicherort (FinGraph.Person.country), der Konzepttyp, eine Distanz von 0 für eine Übereinstimmung und ein leerer JSON-Kontext. Weitere Informationen finden Sie unter Suchanfragen für Werte.

Kontextsatzdatei in QueryData hochladen

In diesem Abschnitt laden Sie die Datei context_set.json in den Kontextsatz fingraph-assistant in Spanner Studio hoch.

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

    Spanner aufrufen

  2. Wählen Sie Ihre Instanz aus der Liste und dann Ihre Spanner-Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

  4. Klicken Sie im Bereich Explorer neben Ihrem fingraph-assistant-Kontextsatz auf Aktionen ansehen.

  5. Klicken Sie auf Kontextgruppe bearbeiten.

  6. Optional: Bearbeiten Sie die Beschreibung der Kontextgruppe.

  7. Klicken Sie im Abschnitt Kontextsatzdatei hochladen auf Durchsuchen und wählen Sie die von Ihnen generierte context_set.json-Datei aus.

  8. Klicken Sie auf Speichern.

GQL-Abfragen mit QueryData generieren

In diesem Abschnitt rufen Sie die QueryData REST API mit dem Kontext fingraph-assistant auf, um zu prüfen, ob QueryData Geschäftsbegriffe wie high-risk transfers korrekt übersetzt und Czech Republic in GQL-Abfragen in Czech_Republic auflöst.

  1. Suchen Sie die Kontextset-ID für fingraph-assistant. Eine Anleitung finden Sie unter Kontextsatz-ID ermitteln.
  2. Legen Sie die Umgebungsvariable CONTEXT_SET_ID fest, damit query_data.sh Ihren Kontextsatz sendet:

    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    

    Ersetzen Sie CONTEXT_SET_ID durch die vollständige Kontext-Set-ID, z. B. projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

  3. Stelle die Frage zu Überweisungen mit hohem Risiko noch einmal:

    ./query_data.sh "Find all high-risk transfers initiated by Alex"
    

    Die generierte GQL-Abfrage wendet jetzt den Filter für blockierte Zielkonten (is_blocked: true) und den Schwellenwert für den Betrag (t.amount >= 200) an:

    GRAPH FinGraph
    MATCH
      (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true})
    WHERE
      t.amount >= 200
    RETURN
      dst.id AS destination_account_id,
      t.amount AS transfer_amount
    ORDER BY
      t.amount DESC;
    

    Dadurch wird die Übertragung von 100 durch Alex an das blockierte Konto 16 ausgeschlossen und es werden Ergebnisse wie die folgenden zurückgegeben:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 300             |
    +------------------------+-----------------+
    
  4. Stellen Sie eine ähnliche Frage für Dana:

    ./query_data.sh "What are the high-risk transfers initiated by Dana?"
    

    Da die GQL-Vorlage in context_set.json parametrisiert ist ({name: ?}), wendet QueryData dieselbe high-risk transfers-Definition auf Dana an:

    GRAPH FinGraph
    MATCH
      (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true})
    WHERE
      t.amount >= 200
    RETURN
      dst.id AS destination_account_id,
      t.amount AS transfer_amount
    ORDER BY
      t.amount DESC;
    

    Dadurch wird die Übertragung von 500 durch Dana an das nicht blockierte Konto 7 ausgeschlossen und es werden Ergebnisse wie die folgenden zurückgegeben:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 200             |
    +------------------------+-----------------+
    
  5. Stellen Sie die Frage nach dem Land noch einmal:

    ./query_data.sh "Find accounts owned by people from Czech Republic"
    

    QueryData führt die Suche nach dem Wert Person country aus, verknüpft Czech Republic mit dem gespeicherten Wert Czech_Republic und generiert eine Abfrage, die etwa so aussieht:

    GRAPH FinGraph
    MATCH
      (p:Person {country: 'Czech_Republic'})-[:Owns]->(a:Account)
    RETURN
      p.name AS owner_name,
      a.id AS account_id,
      a.nick_name;
    

    Dies gibt Ergebnisse wie die folgenden zurück:

    +------------+------------+----------------+
    | owner_name | account_id | nick_name      |
    +------------+------------+----------------+
    | Dana       | 20         | Rainy Day Fund |
    +------------+------------+----------------+
    
  6. Stellen Sie eine Frage, die die Facette „blocked-account“ verwendet:

    ./query_data.sh "Find all money transfers involving a blocked account."
    

    QueryData verwendet die Facette, um Übertragungen in beide Richtungen abzugleichen, die das gesperrte Konto 16 betreffen, und gibt vier Übertragungen zurück.

QueryData in Ihre Anwendung einbinden

In diesem Abschnitt erstellen Sie eine Konversations-KI-Daten-Agenten-Anwendung für FinGraph mit dem Agent Development Kit (ADK), der MCP Toolbox und Ihrem fingraph-assistant-Kontextset. Wenn Sie die GQL-Abfragegenerierung für Spanner Graph aktivieren möchten, definieren Sie in Ihrer tools.yaml-Datei ein benutzerdefiniertes HTTP-Tool, das die QueryData REST API mit graph_ids in spanner_reference.database_reference aufruft.

  1. Laden Sie die MCP Toolbox in Version 1.4.0 oder höher herunter. Die MCP Toolbox stellt die QueryData REST API als MCP-Tool bereit, mit dem Anwendungen eine Verbindung herstellen können.
  2. Richten Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein:

    gcloud auth application-default login
  3. Erstellen Sie eine tools.yaml-Konfigurationsdatei, die eine HTTP-Quelle für die konversationelle Analyse-API und ein HTTP-Tool definiert, das die Methode QueryData aufruft. Geben Sie im Anfragetext unter spanner_reference.database_reference das Feld graph_ids (auf ["FinGraph"] festgelegt) an:

    kind: source
    name: gda-rest-source
    type: http
    baseUrl: https://geminidataanalytics.googleapis.com
    timeout: 120s
    headers:
      Authorization: Bearer ${GDA_ACCESS_TOKEN}
      Content-Type: application/json
      x-goog-user-project: ${PROJECT_ID}
    ---
    kind: tool
    name: fingraph_query_data_tool
    type: http
    source: gda-rest-source
    method: POST
    path: /v1beta/projects/${PROJECT_ID}/locations/global:queryData
    description: Use this tool to send natural language questions about the FinGraph property graph to the QueryData API and receive GQL queries, query results, natural language answers, and explanations.
    requestBody: |
      {
        "parent": "projects/${PROJECT_ID}/locations/global",
        "prompt": {{json .query}},
        "context": {
          "datasource_references": {
            "spanner_reference": {
              "database_reference": {
                "engine": "GOOGLE_SQL",
                "project_id": "${PROJECT_ID}",
                "instance_id": "${INSTANCE_ID}",
                "database_id": "${DATABASE_ID}",
                "graph_ids": ["FinGraph"]
              },
              "agent_context_reference": {
                "context_set_id": "${CONTEXT_SET_ID}"
              }
            }
          }
        },
        "generation_options": {
          "generate_query_result": true,
          "generate_natural_language_answer": true,
          "generate_explanation": true,
          "generate_disambiguation_question": true
        }
      }
    bodyParams:
      - name: query
        type: string
        description: A natural language question about the FinGraph property graph.
    

    Die MCP Toolbox ersetzt die ${...}-Verweise durch die Werte der entsprechenden Umgebungsvariablen, wenn sie tools.yaml lädt, und ersetzt {{json .query}} durch die Frage, die der Agent an das Tool sendet, codiert als JSON-String.

  4. Legen Sie im Terminal, in dem Sie die MCP Toolbox ausführen, die Umgebungsvariablen fest, auf die tools.yaml verweist:

    export PROJECT_ID="PROJECT_ID"
    export INSTANCE_ID="INSTANCE_ID"
    export DATABASE_ID="DATABASE_ID"
    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    export GDA_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
    

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Projekt-ID in Google Cloud .
    • INSTANCE_ID: die ID Ihrer Cloud Spanner-Instanz.
    • DATABASE_ID: die ID der Spanner-Datenbank, die FinGraph enthält.
    • CONTEXT_SET_ID: die vollständige Kontext-Set-ID von fingraph-assistant.
  5. Führen Sie den MCP Toolbox-Server mit der Datei tools.yaml aus:

    ./toolbox --config "tools.yaml"
  6. Erstellen Sie eine ADK-Anwendung, die das Tool fingraph_query_data_tool über das MCP Toolbox Python SDK aufruft:

    1. Erstellen Sie ein Verzeichnis für die Anwendung, z. B. fingraph-assistant-app, und wechseln Sie dorthin:

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. Erstellen Sie eine virtuelle Umgebung und installieren Sie die erforderlichen Pakete:

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. ADK-Agenten erstellen:

      adk create my_agent
    4. Wählen Sie das Modell gemini-2.5-flash aus, wählen Sie Google AI aus und geben Sie Ihren Gemini API-Schlüssel ein. Weitere Informationen finden Sie unter Gemini API-Schlüssel verwenden.

    5. Ersetzen Sie den Inhalt von my_agent/agent.py durch den folgenden Beispielcode für die Financial Graph 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 factual financial graph data assistant for FinGraph. Your goal is to help users analyze account ownership, money transfers, and risk patterns by providing accurate information with a helpful, professional tone.
      - Always call the Query Data Tool first to answer questions about the graph data, including questions with domain-specific terms (such as "high-risk"), because the tool resolves domain definitions against the database context. Ask the user to clarify only if the tool returns a disambiguation question or fails to generate a valid query.
      
      # 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 GQL. 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 and guide the user toward 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 graph database query.
      
      Outputs: (all optional)
      1. disambiguationQuestion: Clarification questions or comments where the tool needs the user's input.
      2. generatedQuery: The generated GQL query for the user query.
      3. intentExplanation: An explanation for why the tool produced `generatedQuery`.
      4. queryResult: The result of executing `generatedQuery`.
      5. naturalLanguageAnswer: The natural language answer that summarizes the `query` and `queryResult`.
      
      Usage guidance:
      1. If `disambiguationQuestion` is produced, solicit the needed inputs from the user and try the tool with a new `query` that includes the clarification.
      2. If `naturalLanguageAnswer` is produced, use `intentExplanation` and `generatedQuery` 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("fingraph_query_data_tool")
      
      root_agent = Agent(
          model="gemini-2.5-flash",
          name="root_agent",
          instruction=INSTRUCTION,
          tools=cast(list[ToolUnion], [mcp_tool]),
      )
      
  7. Starten Sie den ADK-Webserver unter http://127.0.0.1:8000:

    adk web --port 8000
  8. Geben Sie in der ADK-Web-UI eine Frage ein, die mehrere Schritte im Diagramm erfordert:

    Who did Dana transfer money to, and what were the amounts?
    

    Der KI-Agent ruft das fingraph_query_data_tool-Tool auf, das die Frage an die QueryData-REST API sendet, wobei graph_ids auf FinGraph gesetzt ist. QueryData führt die generierte GQL-Abfrage aus und der Agent gibt eine Antwort ähnlich der folgenden zurück:

    Dana transferred money from account 20 to the following recipients:
    
    * Alex (account 7): 500
    * Lee (account 16): 200
    
  9. Geben Sie eine Frage ein, die die GQL-Vorlage high-risk transfers verwendet, die Sie dem Kontextset hinzugefügt haben:

    What are the high-risk transfers initiated by Alex?
    

    Basierend auf der GQL-Vorlage in fingraph-assistant identifiziert QueryData Überweisungen von mindestens 200 auf ein gesperrtes Konto und der Agent gibt eine Antwort ähnlich der folgenden zurück:

    Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account):
    
    * Blocked destination account 16: amount 300
    

Leistung des KI-Agenten iterieren

In der ADK-Web-UI können Sie die Anfrage- und Antwortnutzlasten des fingraph_query_data_tool-Tools prüfen. Maximieren Sie im Navigationsbereich auf dem Tab Ereignis den Eintrag functionResponse, um die generierte GQL-Abfrage FinGraph (generatedQuery), queryResult, intentExplanation, disambiguationQuestion und naturalLanguageAnswer zu prüfen. Die QueryData REST API gibt diese Feldnamen in camelCase zurück.

Antwortgenauigkeit optimieren

Sie können die Accuracy der Antworten von QueryData kontinuierlich verbessern, indem Sie GQL-Vorlagen, Facetten und Wertsuchen hinzufügen. Verwenden Sie den Kontext-Engineering-Agenten, um aktualisierten Kontext für den Eigenschaftsgraphen FinGraph in Ihrer Spanner-Datenbank zu generieren und zu bewerten. Laden Sie dann die aktualisierte Kontextdatei in Spanner Studio hoch. Weitere Informationen finden Sie unter Kontextsätze in Spanner Studio verwalten.

Mehrere KI-Agenten

In Ihrer Entwicklungsumgebung können Sie A/B-Tests für mehrere Spanner Graph-Kontextsätze durchführen, indem Sie mehrere HTTP-Tools in Ihrer tools.yaml-Datei definieren (z. B. fingraph_query_data_tool_v1 und fingraph_query_data_tool_v2). Im Anfragetext jedes Tools wird graph_ids auf ["FinGraph"] und ein anderer context_set_id festgelegt.

Bereinigen

Löschen Sie die von Ihnen erstellten Ressourcen, um weitere Kosten zu vermeiden, wenn Sie diese Anleitung abgeschlossen haben.

Kontextset löschen

Bevor Sie die Spanner-Datenbank oder -Instanz löschen, müssen Sie das Kontextset fingraph-assistant löschen:

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

    Spanner aufrufen

  2. Wählen Sie Ihre Instanz aus der Liste und dann Ihre Spanner-Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

  4. Klicken Sie im Bereich Explorer neben fingraph-assistant auf Aktionen anzeigen.

  5. Klicken Sie auf Kontextgruppe löschen, geben Sie fingraph-assistant in das Bestätigungsfeld ein und klicken Sie auf Bestätigen.

Datenbank und Instanz löschen

Wenn Sie den Property-Graphen FinGraph, die Cloud Spanner-Datenbank und die Cloud Spanner-Instanz löschen möchten, folgen Sie der Anleitung unter Cloud Spanner Graph einrichten und abfragen: Bereinigen.

Nächste Schritte