QueryData をアプリケーションと統合する

このチュートリアルでは、 Google Cloud コンソールを使用して Spanner Graph で QueryData を設定して使用し、アプリケーションと統合する方法について説明します。FinGraph プロパティ グラフを設定する方法、コンテキスト エンジニアリング エージェントを使用して Graph Query Language(GQL)コンテキスト セット ファイルを構築する方法、Spanner Studio でコンテキスト セットを作成する方法、graph_ids を構成して 会話型分析 API の QueryData メソッドを呼び出して QueryData をテストする方法、MCP ツールボックスのカスタム HTTP ツールを使用してエージェント アプリケーションを QueryData に接続する方法について説明します。

詳細については、QueryData の概要をご覧ください。

目標

  • FinGraph プロパティ グラフ スキーマを作成し、サンプル グラフデータを入力します。
  • コンテキスト エンジニアリング エージェントを使用して、FinGraph のコンテキスト セット ファイルをビルドします。
  • コンテキスト セットを作成し、Spanner Studio でコンテキスト セット ファイルをアップロードします。
  • spanner_reference で指定された graph_ids を使用して QueryData REST API を呼び出し、QueryData をテストして GQL クエリを生成します。
  • QueryData REST API を呼び出す MCP ツールボックスのカスタム HTTP ツールを使用して、QueryData をアプリケーションに統合します。
  • クエリ テンプレート、クエリ ファセット、GRAPH_TABLE 値検索クエリを使用して、グラフデータで LLM レスポンスをグラウンディングします。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを算出できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントのタスクを完了したら、作成したリソースを削除して、それ以上の請求が発生しないようにします。詳細については、クリーンアップをご覧ください。

始める前に

コンテキスト セットを作成する前に、次の前提条件を満たす必要があります。

必要なサービスを有効にする

プロジェクトで次のサービスを有効にします。

Spanner インスタンスを準備する

必要なロールと権限

  • IAM ユーザーまたはサービス アカウントをインスタンスに追加します。詳細については、IAM ロールを適用するをご覧ください。
  • プロジェクト レベルで IAM ユーザーに roles/spanner.databaseReader、roles/serviceusage.serviceUsageConsumer、roles/geminidataanalytics.queryDataUser のロールを付与します。詳細については、プロジェクトの IAM ポリシー バインディングを追加するをご覧ください。
  • コンテキスト セットを作成、アップロード、管理するには、プロジェクト レベルで IAM ユーザーに Dataplex Catalog 編集者(roles/dataplex.catalogEditor)または Dataplex Catalog 管理者(roles/dataplex.catalogAdmin)ロールを付与します。詳細については、コンテキスト セットの権限をご覧ください。
  • 必要なデータベースに対して、プロジェクト レベルで IAM ユーザーにロールと権限を付与します。

FinGraph スキーマを作成してグラフデータを挿入する

このチュートリアルでは、FinGraph 金融プロパティ グラフ データセットを使用します。このデータセットは、Owns(PersonOwnAccount)エッジと Transfers(AccountTransferAccount)エッジで接続された Person ノードと Account ノードをモデル化します。

FinGraph スキーマを作成し、Spanner データベースにグラフデータを入力するには、Spanner Graph 設定ガイドの手順を完了します。

  1. スキーマを使用してグラフ データベースを作成するの手順に沿って、Person、Account、PersonOwnAccount、AccountTransferAccount テーブルと FinGraph プロパティ グラフ定義を作成します。
  2. グラフデータを挿入するの手順に沿って、サンプルの人物(Alex、Dana、Lee)、アカウント(7、16、20)、アカウント所有権エッジ、送金エッジを FinGraph に挿入します。

コンテキスト セットを作成する

fingraph-assistant という名前の空のコンテキスト セットを作成します。このチュートリアルの後半で、コンテキスト セット ファイルをアップロードします。

  1. Google Cloud コンソールで、[Spanner] ページに移動します。

    Spanner に移動

  2. リストからインスタンスを選択し、FinGraph を含むデータベースを選択します。

  3. ナビゲーション メニューで [Spanner Studio] をクリックします。

  4. [エクスプローラ] ペインで、[コンテキスト セット] の横にある [アクションを表示] をクリックします。

  5. [コンテキスト セットを作成] をクリックします。

  6. [コンテキスト セット名] フィールドに「fingraph-assistant」と入力します。

  7. [作成] をクリックします。

コンテキストなしで QueryData をテストする

このセクションでは、QueryData REST API を呼び出して、コンテキスト セットのない自然言語の質問に対する GQL クエリを生成します。コンテキストがない場合、QueryData は FinGraph スキーマに直接マッピングされる質問に回答できますが、high-risk transfers などのカスタム ビジネス用語を解釈したり、Czech Republic と Czech_Republic などの値の形式の違いを解決したりすることはできません。

  1. ターミナルで、次の環境変数を設定します。

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

    次のように置き換えます。

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • INSTANCE_ID: Spanner インスタンス ID。
    • DATABASE_ID: FinGraph を含むデータベースの ID。
  2. graph_ids を FinGraph に設定して QueryData REST API に質問を送信する query_data.sh という名前のヘルパー スクリプトを作成します。CONTEXT_SET_ID 環境変数が設定されている場合、スクリプトはコンテキスト セット 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
    

    スクリプトは質問をリクエスト本文にそのまま挿入するため、質問に二重引用符(")を使用しないでください。

  3. FinGraph スキーマに直接マッピングされる質問をします。

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

    レスポンスで、generatedQuery フィールドと queryResult フィールドを確認します。この明確な質問に対して、QueryData は次のような GQL クエリを生成します。

    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;
    

    これにより、次のような結果が返されます。

    +----------------+----------------------+-----------------+
    | recipient_name | recipient_account_id | transfer_amount |
    +----------------+----------------------+-----------------+
    | Alex           | 7                    | 500             |
    | Lee            | 16                   | 200             |
    +----------------+----------------------+-----------------+
    
  4. ビジネス用語 high-risk transfers を含む質問をします。

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

    FinGraph スキーマでは、high-risk transfer を構成する要素(ビジネス ロジックでは、is_blocked = true のブロックされたアカウントへの 200 以上の送金を意味する)が定義されていないため、QueryData は、ブロックされたアカウントと金額のしきい値フィルタを適用しないか、この用語を独自に解釈して適用します。たとえば、QueryData は、行を返さない金額しきい値を考案したり、この用語を無視して次のようなクエリを生成したりすることがあります。

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

    これにより、しきい値を満たしていない 100 の転送を含む、Alex の両方の転送が返されます。

    +-------------------+------------------------+-----------------+-----------------+
    | source_account_id | destination_account_id | transfer_amount | order_number    |
    +-------------------+------------------------+-----------------+-----------------+
    | 7                 | 16                     | 300             | 304330008004315 |
    | 7                 | 16                     | 100             | 304120005529714 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. 国を参照する質問をします。

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

    コンテキストまたは値のリンクがない場合、QueryData はスペースを含む 'Czech Republic' をフィルタする GQL クエリを生成します。FinGraph の Person.country プロパティは値をアンダースコア付きの 'Czech_Republic' として保存するため、クエリは行を返しません。

    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;
    

コンテキスト セットのコンテキストを生成する

このセクションでは、ローカル環境を準備し、コンテキスト エンジニアリング エージェントを使用して、Spanner データベースの FinGraph プロパティ グラフのコンテキスト セット ファイル(context_set.json)を作成します。

環境の設定

コンテキスト エンジニアリング エージェントの環境を設定する手順は次のとおりです。

  1. Antigravity CLI をインストールします。詳細については、Antigravity CLI を使ってみるをご覧ください。
  2. Google Cloud CLI をインストールします。
  3. アプリケーションのデフォルト認証情報(ADC)を設定します。ターミナルで次のコマンドを実行して認証します。

    gcloud auth application-default login
  4. コンテキスト エンジニアリング エージェントをインストールする。

  5. ターミナルで、Antigravity CLI を起動します。

    agy
  6. Spanner データベースのデータベース接続を設定します。Spanner データベースのプロパティ グラフのコンテキストを生成することを明示的に指定し、FinGraph プロパティ グラフ名を含むプロンプトを入力して、エージェントが GQL 固有のコンテキスト エンジニアリング ワークフローをトリガーするようにします。

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

    エージェントの指示に沿って autoctx/tools.yaml と autoctx/state.md を作成します。次に、autoctx/state.md を開き、## Active Database セクションに - **Graph Ids**: ["FinGraph"] 行が含まれていることを確認します。コンテキスト エンジニアリング エージェントは、評価構成を生成するときに、この行からプロパティ グラフ名を読み取ります。tools.yaml の詳細については、MCP ツールボックスのドキュメントをご覧ください。

  7. autoctx/tools.yaml の作成後に構成を再読み込みするには、Antigravity CLI で次のコマンドを実行します。

    /mcp
  8. [toolbox]、[Restart] の順に選択します。

  9. MCP ツールボックスとコンテキスト エンジニアリング エージェント プラグインが接続され、使用可能な状態であることを確認します。

    /mcp

GQL テンプレート コンテキストを生成する

QueryData がビジネス用語 high-risk transfers を認識しなかった問題に対処するには、コンテキスト セット ファイルで high-risk transfers を、ブロックされたアカウント(dst.is_blocked = true)に送信された 200 以上の送金として定義します。

GQL テンプレート コンテキストを生成する手順は次のとおりです。

  1. エージェント ハーネスに次のプロンプトを入力し、FinGraph が Spanner データベースのプロパティ グラフであることを指定します。

    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. エージェントは、入力を、人名全体で一般化するパラメータ化された GQL テンプレートに変換します。詳細については、コンテキスト セットの概要をご覧ください。

  3. 生成された GQL クエリ テンプレートを確認し、エージェントに Save it to context_set.json をプロンプトします。エージェントは、次の内容の context_set.json をディレクトリに作成します。

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

ファセットと値の検索コンテキストを生成する

このセクションでは、GQL ファセットと 2 つの GRAPH_TABLE 値検索クエリを context_set.json に追加します。前のセクションで追加したテンプレートは、「Alex が開始した高リスクの送金をすべて検索する」と同じ構造の質問に回答します。ファセットは、ブロックされた口座のパターンをキャプチャします。これにより、QueryData は、「ブロックされた口座が関与するすべての送金を検索する」など、テンプレートに一致しない質問にもこのパターンを適用できます。値検索により、QueryData は Czech Republic などの値フレーズを Person.country の保存された値 Czech_Republic にマッピングし、大文字と小文字を区別せずに Account.nick_name のアカウントのニックネームを照合できます。

  1. エージェント ハーネスに次のプロンプトを入力し、FinGraph が Spanner データベースのプロパティ グラフであることを指定します。

    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. 更新された context_set.json ファイルを確認します。このファイルには、GQL テンプレート、GQL ファセット、値検索の定義が含まれています。

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

    各値検索では、GRAPH_TABLE 演算子を使用して FinGraph のノードラベルを照合し、保存されたプロパティ値、プロパティの場所(FinGraph.Person.country)、コンセプト タイプ、一致の距離 0、空の JSON コンテキストを返します。詳細については、値の検索クエリをご覧ください。

コンテキスト セット ファイルを QueryData にアップロードする

このセクションでは、Spanner Studio で context_set.json ファイルを fingraph-assistant コンテキスト セットにアップロードします。

  1. Google Cloud コンソールで、[Spanner] ページに移動します。

    Spanner に移動

  2. リストからインスタンスを選択し、Spanner データベースを選択します。

  3. ナビゲーション メニューで [Spanner Studio] をクリックします。

  4. [エクスプローラ] ペインで、fingraph-assistant コンテキスト セットの横にある [アクションを表示] をクリックします。

  5. [コンテキスト セットを編集] をクリックします。

  6. 省略可: [コンテキスト セットの説明] を編集します。

  7. [コンテキスト セット ファイルのアップロード] セクションで [参照] をクリックし、生成した context_set.json ファイルを選択します。

  8. [保存] をクリックします。

QueryData を使用して GQL クエリを生成する

このセクションでは、fingraph-assistant コンテキストを設定して QueryData REST API を呼び出し、QueryData が high-risk transfers などのビジネス用語を正確に変換し、GQL クエリで Czech Republic を Czech_Republic に解決することを確認します。

  1. fingraph-assistant のコンテキスト セット ID を確認します。手順については、コンテキスト セット ID を確認するをご覧ください。
  2. CONTEXT_SET_ID 環境変数を設定して、query_data.sh がコンテキスト セットを送信するようにします。

    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    

    CONTEXT_SET_ID は、完全なコンテキスト セット ID(projects/my-project/locations/us-central1/contextSets/fingraph-assistant など)に置き換えます。

  3. 高リスクの転送に関する質問をもう一度行います。

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

    生成された GQL クエリに、ブロックされた移行先のアカウント フィルタ(is_blocked: true)と金額のしきい値(t.amount >= 200)が適用されます。

    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;
    

    これにより、Alex の 100 からブロックされたアカウント 16 への転送が除外され、次のような結果が返されます。

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 300             |
    +------------------------+-----------------+
    
  4. Dana について同様の質問をします。

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

    context_set.json の GQL テンプレートはパラメータ化されている({name: ?})ため、QueryData は Dana に同じ high-risk transfers 定義を適用します。

    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;
    

    これにより、Dana の 500 からブロックされていないアカウント 7 への転送が除外され、次のような結果が返されます。

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 200             |
    +------------------------+-----------------+
    
  5. 国に関する質問をもう一度行います。

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

    QueryData は Person country 値検索を実行し、Czech Republic を保存された値 Czech_Republic にリンクして、次のようなクエリを生成します。

    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;
    

    これにより、次のような結果が返されます。

    +------------+------------+----------------+
    | owner_name | account_id | nick_name      |
    +------------+------------+----------------+
    | Dana       | 20         | Rainy Day Fund |
    +------------+------------+----------------+
    
  6. blocked-account ファセットを使用する質問をします。

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

    QueryData は、ファセットを使用して、ブロックされた口座 16 が関与する双方向の送金を照合し、4 つの送金を返します。

QueryData をアプリケーションと統合する

このセクションでは、Agent Development Kit(ADK)、MCP ツールボックス、fingraph-assistant コンテキスト セットを使用して、FinGraph の会話型データ エージェント アプリケーションを作成します。Spanner Graph で GQL クエリの生成を有効にするには、tools.yaml ファイルでカスタム HTTP ツールを定義します。このツールは、spanner_reference.database_reference で graph_ids を設定して QueryData REST API を呼び出します。

  1. MCP ツールボックス バージョン 1.4.0 以降をダウンロードします。MCP ツールボックスは、アプリケーションが接続できるように、QueryData REST API を MCP ツールとして公開します。
  2. アプリケーションのデフォルト認証情報(ADC)を設定します。

    gcloud auth application-default login
  3. Conversational Analytics API の HTTP ソースと、QueryData メソッドを呼び出す HTTP ツールを定義する tools.yaml 構成ファイルを作成します。リクエスト本文の spanner_reference.database_reference で graph_ids(["FinGraph"] に設定)を指定します。

    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.
    

    MCP ツールボックスは、tools.yaml を読み込むときに ${...} 参照を対応する環境変数の値に置き換え、{{json .query}} をエージェントがツールに送信する質問(JSON 文字列としてエンコード)に置き換えます。

  4. MCP ツールボックスを実行するターミナルで、tools.yaml が参照する環境変数を設定します。

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

    次のように置き換えます。

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • INSTANCE_ID: Spanner インスタンスの ID。
    • DATABASE_ID: FinGraph を含む Spanner データベースの ID。
    • CONTEXT_SET_ID: fingraph-assistant の完全なコンテキスト セット ID。
  5. tools.yaml ファイルを使用して MCP ツールボックス サーバーを実行します。

    ./toolbox --config "tools.yaml"
  6. MCP ツールボックス Python SDK を使用して fingraph_query_data_tool ツールを呼び出す ADK アプリケーションを作成します。

    1. アプリケーションのディレクトリ(fingraph-assistant-app など)を作成し、そのディレクトリに移動します。

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. 仮想環境を作成し、必要なパッケージをインストールします。

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. ADK エージェントを作成します。

      adk create my_agent
    4. gemini-2.5-flash モデルを選択し、[Google AI] を選択して、Gemini API キーを入力します。詳細については、Gemini API キーを使用するをご覧ください。

    5. my_agent/agent.py の内容を、次の Financial Graph 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 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. http://127.0.0.1:8000 で ADK ウェブサーバーを起動します。

    adk web --port 8000
  8. ADK ウェブ UI にマルチホップ グラフの質問を入力します。

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

    エージェントは fingraph_query_data_tool ツールを呼び出し、graph_ids を FinGraph に設定して QueryData REST API に質問を送信します。QueryData が生成された GQL クエリを実行し、エージェントが次のようなレスポンスを返します。

    Dana transferred money from account 20 to the following recipients:
    
    * Alex (account 7): 500
    * Lee (account 16): 200
    
  9. コンテキスト セットに追加した high-risk transfers GQL テンプレートを使用する質問を入力します。

    What are the high-risk transfers initiated by Alex?
    

    fingraph-assistant の GQL テンプレートに基づいて、QueryData はブロックされたアカウントへの 200 以上の送金を特定し、エージェントは次のようなレスポンスを返します。

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

エージェントのパフォーマンスを反復処理する

ADK ウェブ UI を使用すると、fingraph_query_data_tool ツールからのリクエストとレスポンスのペイロードを検査できます。ナビゲーション パネルの [Event] タブで、functionResponse を展開して、生成された FinGraph GQL クエリ(generatedQuery)、queryResult、intentExplanation、disambiguationQuestion、naturalLanguageAnswer を確認します。QueryData REST API は、これらのフィールド名をキャメルケースで返します。

回答の精度を向上させる

GQL テンプレート、ファセット、値検索を追加することで、QueryData からの回答の精度を継続的に向上させることができます。コンテキスト エンジニアリング エージェントを使用して、Spanner データベースの FinGraph プロパティ グラフの更新されたコンテキストを生成して評価し、更新されたコンテキスト セット ファイルを Spanner Studio にアップロードします。詳細については、Spanner Studio でコンテキスト セットを管理するをご覧ください。

複数のエージェント

開発環境では、tools.yaml ファイルに複数の HTTP ツール(fingraph_query_data_tool_v1 や fingraph_query_data_tool_v2 など)を定義することで、複数の Spanner Graph コンテキスト セットで A/B テストを実行できます。各ツールのリクエスト本文で、graph_ids を ["FinGraph"] に設定し、異なる context_set_id を設定します。

クリーンアップ

このチュートリアルを終了した後、作成したリソースを削除すると、それ以上の請求は発生しません。

コンテキスト セットを削除する

Spanner データベースまたはインスタンスを削除する前に、fingraph-assistant コンテキスト セットを削除します。

  1. Google Cloud コンソールで、[Spanner] ページに移動します。

    Spanner に移動

  2. リストからインスタンスを選択し、Spanner データベースを選択します。

  3. ナビゲーション メニューで [Spanner Studio] をクリックします。

  4. [エクスプローラ] ペインで、fingraph-assistant の横にある [アクションを表示] をクリックします。

  5. [コンテキスト セットを削除] をクリックし、確認フィールドに「fingraph-assistant」と入力して、[確認] をクリックします。

データベースとインスタンスを削除する

FinGraph プロパティ グラフ、Spanner データベース、Spanner インスタンスを削除するには、Spanner Graph を設定してクエリを実行する: クリーンアップの手順に沿って操作します。

次のステップ