コンテキスト セットをアプリケーションと統合する

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

詳細については、コンテキスト セットの概要をご覧ください。

目標

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

費用

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

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

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

引き続き課金されないようにするには、このドキュメントのタスクを完了したら、作成したリソースを削除します。詳細については、クリーンアップをご覧ください。

始める前に

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

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

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

Cloud SQL インスタンスを準備する

必要なロールと権限

Cloud SQL インスタンスに executesql 権限を付与する

Cloud SQL インスタンスに executesql 権限を付与し、Cloud SQL Data API を有効にするには、次のコマンドを実行します。 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
次のように置き換えます。
  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • INSTANCE_ID: Cloud SQL インスタンスの ID。
このチュートリアルの手順を行うには、Cloud de Confiance by S3NS にログインし、IAM 認証を使用してデータベースに対する認証を行います。

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

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

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

    Cloud SQL に移動

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

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

  4. Identity and Access Management 認証を使用して Studio にログインします。

  5. [認証] をクリックします。[エクスプローラ] ペインに、データベースにあるオブジェクトのリストが表示されます。

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

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

    CREATE TABLE IF NOT EXISTS airports (
  id INT PRIMARY KEY,
  iata TEXT,
  name TEXT,
  city TEXT,
  country TEXT
  );

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

    CREATE TABLE IF NOT EXISTS flights (
  id INT PRIMARY KEY,
  airline VARCHAR(10),
  flight_number INT,
  departure_airport VARCHAR(5),
  arrival_airport VARCHAR(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate VARCHAR(10),
  arrival_gate VARCHAR(10)
);

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

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

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

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

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

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

値検索用にデータベースを準備する

セマンティック検索とトライグラム値検索を使用するには、ベクトル エンベディングと n グラム インデックス登録をサポートするように Cloud SQL for MySQL インスタンスを構成する必要があります。

  1. Cloud SQL for MySQL インスタンスでセマンティック値検索を実行できるようにするには、次のフラグを有効にする必要があります。

    1. cloudsql_vector フラグを有効にします。

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. enable-google-ml-integration フラグを有効にして、Cloud SQL for MySQL インスタンスを Vertex AI と統合できるようにします。

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. 都市エンベディングを格納するベクトル列を作成する

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. 都市名のベクトル エンベディングを生成して保存する

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Cloud SQL for MySQL インスタンスでトライグラム値の検索を実行できるようにするには、次の操作を行います。

    1. ngram_token_size フラグを有効にします。

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. 空港名のトライグラム マッチング用の FULLTEXT インデックスを作成する

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

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

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

  1. Cloud de Confiance by S3NS コンソールで、[Cloud SQL] ページに移動します。

    Cloud SQL に移動

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

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

  4. IAM 認証を使用して Studio にログインします。

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

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

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

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

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

このセクションでは、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. [QueryData を使用して SQL を生成: 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. [QueryData を使用して SQL を生成: flights-assistant] ウィンドウで、[編集] をクリックします。

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

    Find flights heading into Manhattan

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

    SELECT
  `skybot`.`flights`.*
FROM
  `skybot`.`flights`
JOIN
  `skybot`.`airports`
ON
  `skybot`.`flights`.`arrival_airport` = `skybot`.`airports`.`iata`
WHERE
  `skybot`.`airports`.`city` = 'Manhattan';

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

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

環境の設定

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

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

  1. Gemini CLI をインストールします。詳細については、Gemini CLI クイックスタートをご覧ください。
  2. gcloud CLI をインストールします。

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

    gcloud auth application-default login

  4. コンテキスト生成のワークフローを含む DB コンテキスト拡充拡張機能をインストールします。

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

    バージョンが 0.4.2 以降であることを確認します。DB コンテキスト拡充拡張機能を更新するには、次のコマンドを実行します。

    gemini extensions update mcp-db-context-enrichment

  5. DB コンテキスト拡充拡張機能を更新するか、GEMINI_API_KEY を置き換えるには、次のコマンドを実行します。

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    GEMINI_API_KEY は、実際の Gemini API キーに置き換えます。

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

    gemini

  7. Gemini CLI 認証を設定します。

  8. データベース接続を設定します。この拡張機能では、コンテキスト生成にデータベース接続が必要です。これは MCP ツールボックスでサポートされており、tools.yaml 構成ファイル内で定義されています。

    現在のディレクトリに tools.yaml 構成ファイルを作成するには、Help me set up the database connection などのプロンプトを入力し、スキルから提供される手順に沿って操作します。tools.yaml ファイルの詳細については、MCP ツールボックスのドキュメントをご覧ください。

  9. tools.yaml ファイルの作成後に構成を再読み込みするには、Gemini CLI で次のコマンドを実行します。

    /mcp reload

  10. MCP ツールボックスとデータベース拡充拡張機能が接続され、使用可能な状態であることを確認します。

    /mcp list

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

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

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

  1. /generate_targeted_templates コマンドを実行し、ワークフローに沿って操作します。

    /generate_targeted_templates

  2. クエリ テンプレートに追加する自然言語クエリをターミナルで指定します。

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

  3. クエリ テンプレートに追加する対応する SQL クエリを指定します。このクエリ テンプレートは、nighttime という用語が 5:00 PM と 7:00 PM の間に発生すると定義します。

    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;

  4. Enter キーを押すと、Gemini は、入力内容を特定の形式に変換し、幅広いユーザー クエリでコンテキスト セットのパフォーマンスを向上させます。詳細については、コンテキスト セットの概要をご覧ください。

    必要に応じて、/generate_bulk_templates ワークフローを実行して、Gemini CLI がデータベース スキーマをスキャンし、関連するコンテキストを提案することで、より多くのコンテキストを生成できるようにします。

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

  6. 新しいエージェント コンテキスト ファイルを作成するオプションを選択します。Gemini は、同じディレクトリに INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.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 ?"
      }
    }
  ]
}

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

このセクションでは、値検索コンテキストを生成して、コンテキスト セットのロジックが値のフレーズをデータベース列に保存されている特定の値にマッピングできるようにします。たとえば、ユーザーが「マンハッタン行きのフライト」をリクエストすると、まずマンハッタンが値句として抽出され、セマンティック類似性検索によってマンハッタンが airports.city 列に保存されている「ニューヨーク」に関連付けられます。

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

  1. /generate_targeted_value_searches コマンドを実行します。

    /generate_targeted_value_searches

  2. mysql と入力して、データベースとして MySQL を選択します。

  3. 使用する MySQL のバージョンを入力します。default を選択して MySQL 8.0 を選択します。

  4. 値検索の構成を次のように入力します。

    Table: airports
Column: name
Concept: airport name
Match Function: TRIGRAM_STRING_MATCH

  5. セマンティック マッチについても同じプロセスを繰り返します。

    Table: airports
Column: city
Concept: airport city
Match Function: SEMANTIC_STRING_MATCH
Column Embedding: city_embedding

  6. 値検索定義を生成するかどうかを確認します。

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

  8. 既存のコンテキスト セット ファイルに追加するオプションを選択します。これにより、値検索定義が前のセクションで作成したコンテキスト ファイルに追加されます。

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

    既存のコンテキスト ファイルが値検索定義で更新されます。Gemini は、同じディレクトリに INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.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 ?"
    }
  }
],
"facets": [],
"value_searches": [
  {
    "query": "SELECT * FROM (  WITH TrigramMetrics AS (    SELECT T.`name` AS original_value,     MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) AS raw_score     FROM `airports` AS T     WHERE MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) > 0     ORDER BY raw_score DESC LIMIT 10  ),   NormalizationParams AS (    SELECT MAX(raw_score) AS max_score     FROM TrigramMetrics  )   SELECT original_value AS value, 'name' AS `columns`,   'airport city' AS concept_type,   (CASE WHEN n.max_score > 0 THEN (1 - (m.raw_score / n.max_score)) ELSE 0 END) AS distance,   JSON_OBJECT() AS context   FROM TrigramMetrics m, NormalizationParams n) AS wrapped_query ",
    "concept_type": "airport city",
    "description": null
  },
  {
    "query": "SELECT * FROM (  WITH search_embedding AS (    SELECT mysql.ml_embedding('text-embedding-005', $value) AS val  )   SELECT T.`city` AS value, 'city' AS `columns`,   'airport name' AS concept_type,   COSINE_DISTANCE(T.`city_embedding`, search_embedding.val) AS distance,   JSON_OBJECT() AS context   FROM `airports` AS T, search_embedding   WHERE T.`city_embedding` IS NOT NULL) AS wrapped_query ",
    "concept_type": "airport name",
    "description": null
  }
]
}

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

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

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

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

    Cloud SQL に移動

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

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

  4. Identity and Access Management 認証を使用して Studio にログインします。

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

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

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

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

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

コンテキスト セットを使用して 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. [QueryData を使用して SQL を生成: 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. [QueryData を使用して SQL を生成: flights-assistant] ウィンドウで、[編集] をクリックします。

  8. [QueryData を使用して SQL を生成: flights-assistant] ウィンドウで、[編集] をクリックします。

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

    Find flights heading into Manhattan

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

    SELECT
  *
FROM `skybot`.`flights` AS t1
INNER JOIN `skybot`.`airports` AS t2
  ON t1.`arrival_airport` = t2.`iata`
WHERE t2.`city` = 'New York';

    QueryData は、セマンティック マッチングを使用して、「Manhattan」がデータベースの「New York」に関連していることを正確に解釈できるようになりました。

コンテキスト セットをアプリケーションと統合する

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

  1. MCP ツールボックス バージョン 0.31.0 以降をダウンロードします。MCP ツールボックスは、アプリケーションが接続するためのツールとして QueryData エージェントを公開します。MCP ツールボックスは、コンテキストを生成する MCP ツールボックス Gemini CLI 拡張機能とは異なります。

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

    gcloud auth application-default login

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

  4. MCP ツールボックスを使用して QueryData エージェントに接続する 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:
    cloudSqlReference:
      databaseReference:
        engine: "MYSQL"
        projectId: "PROJECT_ID"
        region: "REGION_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

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

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

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

    ./toolbox --config "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 ディレクトリで次のコマンドを実行して、仮想環境を作成し、必要なコンポーネントをインストールします。

      python3 -m venv .venv
source .venv/bin/activate
pip install toolbox-core
pip install google-genai
pip install google-adk

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

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

        adk create my_agent

      2. gemini-2.5-flash モデルを選択します。

      3. [Google AI] を選択し、Gemini API キーを入力します。API キーを確認する方法の詳細については、Gemini API キーを使用するをご覧ください。

    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-2.5-flash",
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

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

    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.

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

    Find flights heading into Manhattan

    エージェントは、先ほど追加した値検索コンテキストに基づいて、Manhattan が都市 New York に関連していることを理解し、関連するデータを返して、エージェントがレスポンスの作成に使用できるようにします。

    There are 6 flights heading into New York City, specifically arriving at JFK airport, which serves Manhattan.

Here are the details for these flights:

AA 24 from SFO, departing 2025-01-01 07:14:00 and arriving 2025-01-01 15:46:00.
UA 758 from SFO, departing 2025-01-02 07:07:00 and arriving 2025-01-02 15:53:00.
AA 24 from SFO, departing 2025-01-02 07:06:00 and arriving 2025-01-02 15:29:00.
DL 2040 from SFO, departing 2025-01-02 15:09:00 and arriving 2025-01-02 23:20:00.
DL 1370 from SFO, departing 2025-01-02 23:04:00 and arriving 2025-01-03 07:36:00.
CY 34 from SFO, departing 2025-01-02 23:15:00 and arriving 2025-01-03 07:54:00.

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

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

たとえば、先ほど入力した入力テキスト How many flights depart from the west side? の場合は、エージェント バブルをクリックします。左側のナビゲーションの [イベント] タブで、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 ツールからのレスポンスの精度を継続的に高めることができます。Gemini CLI を使用してコンテキストを生成し、更新されたコンテキスト セット ファイルを既存の flights-assistant QueryData エージェントにアップロードします。詳細については、Gemini CLI を使用してコンテキストを構築するをご覧ください。コンソールは、新しいコンテキストをアップロードするとすぐに取り込みます。これにより、アプリケーションのダウンタイムなしでエージェントの精度を高めることができます。

複数のエージェント

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

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

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: <var>PROJECT_ID</var>
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      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:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

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

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

クリーンアップ

以降のセクションでは、これらのリソースとオブジェクトを削除する方法について説明します。

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

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

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

    Cloud SQL に移動

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

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

  4. Identity and Access Management 認証を使用して Studio にログインします。

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

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

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

インスタンスの削除

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

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

    Cloud SQL に移動

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

  3. [削除] をクリックします。

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

次のステップ