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

このチュートリアルでは、 Google Cloud コンソールを使用して Spanner で QueryData を設定して使用し、アプリケーションと統合する方法について説明します。コンテキスト セット ファイルを作成し、コンテキスト セット ファイルを使用するコンテキスト セットを作成します。MCP ツールボックスを使用して Conversational Analytics API の QueryData メソッドを呼び出し、自然言語の質問に対して SQL クエリを生成して、アプリケーションに統合する方法を学習します。

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

目標

  • データベースを作成してデータを入力する。
  • コンテキスト エンジニアリング エージェントを使用してコンテキスト セット ファイルをビルドします。
  • コンテキスト セットを作成し、コンテキスト セット ファイルをアップロードします。
  • Spanner Studio で QueryData をテストし、SQL クエリを生成します。
  • MCP ツールボックスの Gemini データ分析 QueryData ツールを使用して、QueryData をアプリケーションと統合します。
  • 値検索クエリを使用して、LLM レスポンスにグラウンディングを追加します。

費用

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

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

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

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

始める前に

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

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

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

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


このチュートリアルでは、Spanner インスタンスにデータベースが必要です。詳細については、データベースを作成するをご覧ください。

必要なロールと権限

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

flights スキーマと airports スキーマ、テーブルを作成する

このセクションでは、このチュートリアルの flights データベース テーブルと airports データベース テーブルを作成します。

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

    Spanner に移動

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

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

  4. [新しい SQL エディタタブ] または [新しいタブ] をクリックして、新しいタブを開きます。

  5. airports テーブルとスキーマを作成するには、次の SQL ステートメントを実行します。

    CREATE TABLE IF NOT EXISTS airports (
  id INT64 PRIMARY KEY,
  iata STRING(MAX),
  name STRING(MAX),
  city STRING(MAX),
  country STRING(MAX)
);

  6. flights テーブルとスキーマを作成します。

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

flights テーブルと airports テーブルにデータを入力する

このセクションでは、提供されている SQL スクリプトを使用して flights テーブルと airports テーブルにデータを入力します。

  1. airports テーブルにデータを入力します。

  2. flights テーブルにデータを入力します。

  3. 次のクエリを実行して、テーブルにデータが入力されていることを確認します。

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

トークン化された列と検索インデックスを作成する

Spanner の組み込みテキスト検索機能を使用すると、QueryData で、タイプミスや部分的な名前などの非構造化自然言語フレーズをデータベース内の特定の値に正確にマッピングできます。これには、文字列を n-grams に分割する非表示の TOKENLIST 列を生成し、その列に検索インデックスを構築する必要があります。

トークン化された列と検索インデックスを作成するには、次の SQL ステートメントを実行します。

  1. 空港名のトークン列とインデックスを作成します。

    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. 空港都市のトークン列とインデックスを作成します。

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

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

このセクションでは、flights-assistant という名前のコンテキスト セットを作成します。このコンテキスト セットには、アップロードされたコンテキスト セット ファイルが含まれていません。

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

    Spanner に移動

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

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

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

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

  6. [コンテキスト セット名] に「flights-assistant」と入力します。

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

Studio で QueryData をテストする

このセクションでは、自然言語の質問をして flights-assistant コンテキスト セットを使用し、SQL クエリを生成します。コンテキスト セットにはコンテキスト セット ファイルがアップロードされていないため、nighttime traffic などのコンテキストを含む質問をしても、QueryData は最適ではないクエリを生成します。

  1. [エクスプローラ] ペインで、コンテキスト セットの横にある [その他のアクション（）] をクリックします。
  2. [テスト コンテキスト セット] をクリックします。
  3. クエリエディタで、[Generate SQL using QueryData with: flights-assistant] をクリックします。

  4. 次の自然言語の質問を入力して SQL クエリを生成し、[生成] をクリックします。

    Find flights from SFO to JFK.

    SQL クエリを確認します。QueryData は、この曖昧さのない質問に対して正しい SQL を生成します。

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

  5. [Generate SQL using QueryData with: flights-assistant] ウィンドウで、[編集] をクリックします。

  6. 次の自然言語の質問を入力して SQL クエリを生成し、[更新] をクリックします。

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

    データベースが nighttime トラフィックという用語を理解できません。これにより、SQL クエリが生成されなかったり、次のクエリに示すように、用語を無視するクエリが生成されたりする可能性があります。

    -- 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. [Generate SQL using QueryData with: flights-assistant] ウィンドウで、[編集] をクリックします。

  8. 次の自然言語の質問を入力して SQL クエリを生成し、[更新] をクリックします。

    Show me the flight to Houston Intercontinental

    コンテキスト セット ロジックは、名前に「Houston Intercontinental」が含まれる空港を検索するクエリを生成します。そのような空港や都市はデータベースに存在しないため、クエリは行を返しません。

    SELECT
  f.*
FROM
  `flights` AS f
JOIN
  `airports` AS a
ON
  f.arrival_airport = a.id
WHERE
  a.name LIKE '%Houston Intercontinental%';

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

このセクションでは、環境を準備し、コンテキスト セットのクエリ機能を向上させるコンテキスト ファイルを作成します。

環境の設定

コンテキストの生成を開始する前に、環境を準備する必要があります。

環境を設定する手順は次のとおりです。

  1. Antigravity CLI をインストールします。詳細については、Antigravity CLI を使ってみるをご覧ください。
  2. Google Cloud CLI をインストールします。

  3. アプリケーションのデフォルト認証情報（ADC）を設定します。ターミナルで次のコマンドを実行して、認証を行い、プロジェクトを選択します。

    gcloud auth application-default login

  4. uv をインストールします。これは、コンテキスト エンジニアリング エージェントの前提条件となる Python のパッケージおよびプロジェクト マネージャーです。システムに Python がまだインストールされていない場合は、uv でインストールできます。

  5. コンテキスト エンジニアリング エージェントをインストールする:

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

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

    agy

  7. MCP ツールボックスを使用して、コンテキスト生成用のデータベース接続を設定します。接続は tools.yaml 構成ファイルで定義されます。

    現在のディレクトリに tools.yaml 構成ファイルを作成するには、次のようなプロンプトを入力します。

    Help me set up a database connection.

    スキルの指示に沿って操作します。tools.yaml ファイルの詳細については、MCP ツールボックスのドキュメントをご覧ください。

  8. tools.yaml ファイルの作成後に構成を再読み込みするには、Antigravity CLI で次のコマンドを実行し、手順に沿ってツールボックス MCP サーバーを再読み込みします。

    /mcp

    1. [db-context-engineering_toolbox] を選択します。

    2. [Restart] を選択します。

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

    /mcp

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

このセクションでは、前のセクションで QueryData が nighttime traffic という用語を認識しなかった問題に対処するため、コンテキスト セット ファイルで、5:00 PM と 7:00 PM の間で発生するトラフィックとしてこの用語を定義します。

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

  1. Antigravity CLI に次のプロンプトを入力します。

    Generate a template for the question: "Tell me flights that can help me beat nighttime traffic if traveling from New York" with the following SQL query:

SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
  ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  2. エージェントは、入力を特定の形式に変換し、幅広いユーザー クエリにわたってコンテキスト セットのパフォーマンスを向上させます。詳細については、コンテキスト セットの概要をご覧ください。

  3. 生成されたクエリ テンプレートを確認します。クエリ テンプレートは、新しいエージェント コンテキスト ファイルとして保存することも、既存のエージェント コンテキスト ファイルに追加することもできます。

  4. エージェントにテンプレートを保存するよう指示します。

    Save it to context_set.json.

    エージェントは、同じディレクトリに次の内容のファイルを作成します。

    {
  "templates": [
    {
      "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
      "parameterized": {
        "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
      }
    }
  ]
}

値検索コンテキストを生成する

このセクションでは、値検索コンテキストを生成します。これにより、コンテキスト セット ロジックは、文字列の類似性（トライグラム マッチング）を使用して、値フレーズをデータベース列に保存されている特定の値にマッピングできます。たとえば、ユーザーが「ヒューストン インターコンチネンタル」へのフライトをリクエストした場合、値検索はこれを「ジョージ ブッシュ インターコンチネンタル ヒューストン空港」という正確なデータベース値にマッピングできます。

値検索コンテキストを生成する手順は次のとおりです。

  1. エージェント ハーネスに次のプロンプトを入力します。

  2. 「spanner」と入力して、データベースとして Spanner を選択します。

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

  3. 生成された値検索定義を確認します。値検索定義は、新しいコンテキスト セット ファイルとして保存することも、既存のコンテキスト セット ファイルに追加することもできます。

  4. エージェントに Append the context to context_set.json を入力します。これにより、前のセクションで作成したコンテキスト ファイルに値検索定義が追加されます。

  5. コンテキスト セット ファイルが生成されたデータベース インスタンスとデータベース名を入力します。

    既存のコンテキスト ファイルが値検索定義で更新されます。内容は次のとおりです。

      {
"templates": [
  {
    "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
    "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
    "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
    "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
    "parameterized": {
      "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
    }
  }
],
"facets": [],
"value_searches": [
  {
    "query": "SELECT 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."
  }
]
}

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

このセクションでは、コンテキスト セット ファイルを QueryData にアップロードして、データベースに対する QueryData の SQL 生成機能を向上させます。

コンテキストをアップロードする手順は次のとおりです。

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

    Spanner に移動

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

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

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

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

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

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

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

このセクションでは、アップロードしたコンテキスト セット ファイルを使用して、自然言語で質問します。これにより、QueryData が nighttime traffic などの用語やその他の関連フレーズの定義を正しく理解して適用していることを確認できます。

SQL クエリを生成する手順は次のとおりです。

  1. [エクスプローラ] ペインで、コンテキスト セットの横にある [その他の操作（）] をクリックします。
  2. [テスト コンテキスト セット] をクリックします。
  3. クエリエディタで、[Generate SQL using QueryData with: flights-assistant] をクリックします。

  4. 次の自然言語の質問を入力して SQL クエリを生成し、[生成] をクリックします。

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

    生成された SQL クエリは次のようになります。

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

    これは、QueryData のコンテキストに追加したのと同じ質問です。QueryData が nighttime traffic という用語を正確に解釈できるようになったことを確認します。

    コンテキストは特定の質問から生成されますが、QueryData はそれを使用して、さまざまな類似の質問に対する SQL 生成を強化します。

  5. [Generate SQL using QueryData with: flights-assistant] ウィンドウで、[編集] をクリックします。

  6. 次の類似した質問を入力して SQL クエリを生成し、[更新] をクリックします。

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

    この質問では、nighttime traffic という用語が類似の用語 evening traffic に置き換えられているため、QueryData は同じ解釈を適用して、この質問に対して一貫した回答を提供します。

    生成された SQL クエリは次のようになります。

    -- What are the flights that can help me avoid evening traffic if departing from Boston
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
ON
  f.departure_airport = a.iata
WHERE
  a.city = 'Boston'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  7. 次の質問を入力して SQL クエリを生成し、[更新] をクリックします。

    Show me the flight to Houston Intercontinental

    生成された SQL クエリは次のようになります。

    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 が、「Houston Intercontinental」がデータベース内の「George Bush Intercontinental Houston Airport」に関連していることを正確に解釈できるようになりました。

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

このセクションでは、フライト検索アプリケーション用のデータ エージェントを作成します。このデータ エージェントは、先ほど作成した flights テーブルと airports テーブルへの会話型インターフェースを提供します。また、Agent Development Kit（ADK）、Gemini Data Analytics QueryData MCP ツール、コンテキスト セットを使用して、このデータ エージェントを作成してアプリケーションに統合し、回答の品質を向上させる方法についても説明します。

  1. MCP ツールボックス バージョン 1.14.0 以降をダウンロードします。MCP ツールボックスは、アプリケーションが接続するためのツールとしてデータ エージェントを公開します。MCP ツールボックスは、コンテキストを生成する、先ほどインストールしたコンテキスト エンジニアリング エージェントとは異なります。

  2. アプリケーションのデフォルト認証情報（ADC）を設定します。

    gcloud auth application-default login

  3. 先ほど作成したコンテキスト セットの ID を確認します。コンテキスト セット ID を確認する方法については、コンテキスト セット ID を確認するをご覧ください。

  4. MCP ツールボックスを使用してデータ エージェントに接続するには、tools.yaml 構成に次のように追加します。詳細については、Gemini データ分析ソースと Gemini データ分析 QueryData ツールをご覧ください。

    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

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

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • REGION_ID: Spanner インスタンスのリージョン（例: us-central1）。
    • INSTANCE_ID: Spanner インスタンスの ID。
    • DATABASE_ID: 接続先のデータベースの名前。
    • CONTEXT_SET_ID: コンテキスト セット ID。コンテキスト セット ID を確認する方法については、コンテキスト セット ID を確認するをご覧ください。

  5. tools.yaml ファイルを使用して MCP ツールボックス サーバーを実行します。

    ./toolbox --config autoctx/tools.yaml

  6. MCP ツールボックスの Python SDK を使用して Gemini Data Analytics QueryData ツールを呼び出す ADK アプリケーションを作成します。MCP ツールボックスの Python SDK の使用方法について詳しくは、ツールボックスのクイックスタートをご覧ください。Python ADK については、ADK のクイックスタートをご覧ください。

    1. アプリケーションを保存するディレクトリ（flight-assistant-app など）を作成します。

    2. ディレクトリを flight-assistant-app ディレクトリに変更します。

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

    3. flight-assistant-app ディレクトリで次のコマンドを実行して、仮想環境を作成し、必要なコンポーネントをインストールします。

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

    4. ADK エージェントを設定します。

      1. ADK エージェントを作成します。

        uv run adk create my_agent

      2. gemini-3.8-flash モデル以降を選択します。

      3. [Google AI] を選択し、Gemini API キーを入力します。API キーを確認する方法の詳細については、Gemini API キーを使用するをご覧ください。（無料トライアルが不要な場合は、[Vertex AI] を選択して、課金が有効になっている Google Cloud プロジェクトを指定することもできます）。

    5. agent.py ファイルの内容を、次の Flight Data Assistant サンプル アプリケーション コードに置き換えます。

      from typing import cast

from google.adk.agents.llm_agent import Agent
from google.adk.agents.llm_agent import ToolUnion

from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = "http://127.0.0.1:5000"

INSTRUCTION = """
# ROLE
You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
- use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.

# OPERATIONAL CONSTRAINTS
- TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides.
- TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance.
- SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with.

# COMMUNICATION STYLE
- Be concise and scannable when listing answers.
- Maintain a helpful, professional persona.

=====

# QUERY DATA TOOL

Inputs:
1. query: A natural language formulation of a database query.

Outputs: (all optional)
1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
2. generated_query: The generated query for the user query.
3. intent_explanation: An explanation for why the tool produced `generated_query`.
4. query_result: The result of executing `generated_query`.
5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.

Usage guidance:
1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user.
3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning.
"""

client = ToolboxSyncClient(TOOLBOX_URL)

mcp_tool = client.load_tool("cloud_gda_query_tool")

root_agent = Agent(
    model="gemini-3.8-flash",  # Or newer.
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. flight-assistant-app ディレクトリで次のコマンドを実行して、アプリケーションを起動し、http://127.0.0.1:8000 で ADK ウェブサーバーにアクセスします。

    uv run adk web --port 8000

  8. hello などのテキストを入力して、エージェントとのやり取りを開始します。

    ADK エージェントは、一般的な質問に回答し、必要な MCP ツールを呼び出します。

  9. フライトに関する次の質問を入力します。

    How many flights depart from the west side?

    この質問に答えるために、MCP ツールが呼び出されます。ただし、the west という用語は曖昧で、空港が指定されていないため、MCP ツールは曖昧性除去の質問を返します。エージェントはこれを使用して回答を作成します。

    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. エージェント用に生成されたクエリ テンプレートの質問と同様の質問を入力します。

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

    MCP ツールは、先ほど追加した QueryData コンテキストに基づいて、evening traffic が午後 5 時から午後 7 時の間に発生することを認識します。MCP ツールは、エージェントがレスポンスの構築に使用する関連データを返します。

    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. QueryData エージェントのコンテキストに追加したコンセプト タイプに基づいて質問を入力します。

    Show me the flight to Houston Intercontinental

    先ほど追加した値検索コンテキストに基づいて、エージェントは「Houston Intercontinental」が「George Bush Intercontinental Houston Airport」（空港コード IAH）に関連していることを理解し、エージェントが回答の作成に使用する関連データを返します。

    Here are the flights heading to Houston Intercontinental (IAH):

* Flight UA 1285 departs from SFO and arrives at IAH on 2025-01-01 at 23:20:00Z.
* Flight F9 1056 departs from SFO and arrives at IAH on 2025-01-02 at 20:09:00Z.
* Flight UA 1722 departs from SFO and arrives at IAH on 2025-01-03 at 02:29:00Z.

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

ADK ウェブ UI を使用すると、Gemini Data Analytics QueryData MCP ツールからのリクエストとレスポンスを検査できます。このレスポンスを使用して、生成された SQL クエリ、結果セット、インテントの説明、曖昧性除去の質問、自然言語の回答などのツール レスポンスを確認し、エージェントのレスポンスの正確性を確認できます。

たとえば、先ほど入力した入力テキスト How many flights depart from the west side? の場合は、エージェントの吹き出しをクリックします。左側のナビゲーションの [Event] タブで、functionResponse を展開して次のレスポンスを確認します。

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

回答の精度を向上させる

追加のコンテキストを追加することで、Gemini データ分析 QueryData ツールからの回答の精度を継続的に向上させることができます。コンテキスト エンジニアリング エージェントを使用してコンテキストを生成し、更新されたコンテキスト セット ファイルを既存の flights-assistant データ エージェントにアップロードします。詳細については、Spanner Studio でコンテキスト セットを管理するをご覧ください。アップロードした新しいコンテキストは、コンソールにすぐに取り込まれます。これにより、アプリケーションのダウンタイムなしでエージェントの精度を向上させることができます。

複数のエージェント

開発環境では、tools.yaml ファイル内のツールに異なる名前を割り当てることで、複数のデータ エージェント コンテキストで A/B テストを実行できます。たとえば、cloud_gda_query_tool_v1 や cloud_gda_query_tool_v2 など、異なる名前の 2 つの cloud-gemini-data-analytics-query ツールを定義することで、一意の tools.yaml 構成を作成できます。この設定により、対応するツール名を選択して必要なコンテキスト バージョンをプログラムで選択するアプリケーション ロジックを実装できます。

次の例 tools.yaml は、データベース ソースに複数のデータ エージェントを設定する方法を示しています。

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

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

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • V1_YOUR_CONTEXT_SET_ID: バージョン 1 のコンテキスト セット ID。
  • V2_YOUR_CONTEXT_SET_ID: バージョン 2 のコンテキスト セット ID。

クリーンアップ

このチュートリアルを完了したら、作成したリソースを削除して、継続的な費用が発生しないようにする必要があります。以降のセクションでは、このようなリソースを削除する方法を説明します。

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

インスタンスを削除する前に、作成したコンテキスト セットを削除します。

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

    Spanner に移動

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

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

  4. [エクスプローラ] ペインで、コンテキスト セットの横にある [その他の操作（）] をクリックします。

  5. [コンテキスト セットを削除] ウィンドウで、確認ボックスに「flight-assistant」と入力します。

  6. [確認] をクリックします。

インスタンスの削除

始める前にで作成したインスタンスを削除すると、作成したすべてのオブジェクトも削除されます。

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

    Spanner に移動

  2. 「テスト インスタンス」など、削除するインスタンスの名前をクリックします。

  3. [インスタンスの削除] をクリックします。

  4. インスタンス名を入力し [削除] をクリックして、インスタンスの削除を確定します。

次のステップ