將 QueryData 整合至應用程式

本教學課程說明如何使用 Google Cloud 控制台，在 MySQL 適用的 Cloud SQL 中設定及使用 QueryData，並與應用程式整合。瞭解如何建構脈絡資料集檔案、建立使用脈絡資料集檔案的脈絡資料集、使用 MCP Toolbox 呼叫 Conversational Analytics API 中的 QueryData 方法，為自然語言問題生成 SQL 查詢，並將其整合至應用程式。

詳情請參閱「QueryData 總覽」。

目標

  • 建立資料庫並填入資料。
  • 使用脈絡工程代理建立脈絡資料集檔案。
  • 建立脈絡資料集並上傳脈絡資料集檔案。
  • 在 Cloud SQL Studio 中測試 QueryData 並生成 SQL 查詢。
  • 使用 MCP Toolbox 中的 Gemini 資料分析 QueryData 工具，將 QueryData 整合至應用程式。
  • 使用值搜尋查詢，為 LLM 回覆建立基準。

費用

在本文件中，您會使用下列 Google Cloud計費元件：

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後，請刪除建立的資源，避免繼續計費。詳情請參閱「清除所用資源」。

事前準備

建立情境集前，請先完成下列前置作業。

啟用必要服務

為專案啟用下列服務：

準備 Cloud SQL 執行個體

必要角色和權限

  • 在執行個體層級新增 IAM 使用者或服務帳戶。詳情請參閱「為使用者、服務帳戶或群組新增 IAM 政策繫結」。
  • 在專案層級，將 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色授予 IAM 使用者或服務帳戶。詳情請參閱「新增專案的 IAM 政策繫結」。
  • 如要建立、上傳及管理內容集，請在專案層級將 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色授予 IAM 使用者或服務帳戶。詳情請參閱「情境集權限」。
  • 您必須請具備特殊權限的使用者，將資料庫權限授予 IAM 使用者或服務帳戶。

    GRANT SELECT PRIVILEGES ON * TO "IAM_USERNAME";。

    詳情請參閱「將資料庫權限授予個別 IAM 使用者或服務帳戶」。

將 executesql 權限授予 Cloud SQL 執行個體

如要將 executesql 權限授予 Cloud SQL 執行個體，並啟用 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： Google Cloud 專案的 ID。
  • INSTANCE_ID：Cloud SQL 執行個體的 ID。
如要執行本教學課程中的步驟，請登入 Google Cloud，然後使用 IAM 驗證向資料庫進行驗證。

建立 flights 和 airports 結構定義與資料表

在本節中，您將為本教學課程建立 flights 和 airports 資料庫表格。

  1. 前往 Google Cloud 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 在導覽選單中，按一下「Cloud SQL Studio」。

  4. 使用 Identity and Access Management 驗證登入 Studio。

  5. 按一下「Authenticate」(驗證)。「Explorer」窗格會顯示資料庫中的物件清單。

  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;

準備資料庫以搜尋值

如要使用語意和三字母組合值搜尋，您必須設定 MySQL 適用的 Cloud SQL 執行個體，支援向量嵌入和 n-gram 索引。

  1. 如要讓 MySQL 適用的 Cloud SQL 執行個體執行語意值搜尋，請啟用下列標記。

    1. 啟用 cloudsql_vector 旗標。

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

    2. 啟用 enable-google-ml-integration 旗標，允許 MySQL 適用的 Cloud SQL 執行個體與 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. 如要讓 MySQL 適用的 Cloud SQL 執行個體執行三元值搜尋，請按照下列步驟操作。

    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;

在 Cloud SQL Studio 中建立情境集

在本節中，請建立名為 flights-assistant 的內容集。這個情境組合不含任何上傳的情境組合檔案。

  1. 前往 Google Cloud 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 按一下導覽選單中的「Cloud SQL Studio」。

  4. 使用 IAM 驗證機制登入 Studio。

  5. 在「Explorer」窗格中，點選「Context sets」旁的「更多動作」圖示 ()。

  6. 按一下「建立情境組合」。

  7. 在「Context set name」(脈絡資料集名稱) 中輸入 flights-assistant。

  8. 點選「建立」。

在 Studio 中測試 QueryData

在本節中，您將使用 flights-assistant 設定的背景資訊，透過自然語言問題生成 SQL 查詢。由於脈絡資料集未上傳任何脈絡資料集檔案，即使提出 nighttime traffic 等脈絡問題，QueryData 生成的查詢仍不盡理想。

  1. 在「Explorer」窗格中，點選情境集旁邊的「更多動作」圖示 。
  2. 按一下「測試脈絡資料集」。
  3. 在查詢編輯器中，點選「Generate SQL using QueryData with: flights-assistant」(使用 QueryData 生成 SQL，並搭配 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. 安裝 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 Toolbox 設定資料庫連線，以產生背景資訊。連線定義於 tools.yaml 設定檔中。

    如要在目前目錄中建立 tools.yaml 設定檔，請輸入類似下列的提示： 

    Help me set up a database connection.

    按照技能提供的指示操作。如要進一步瞭解 tools.yaml 檔案，請參閱 MCP Toolbox 說明文件。

  8. 建立 tools.yaml 檔案後，請在 Antigravity CLI 執行下列指令，並按照指示重新載入 Toolbox 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 ?"
      }
    }
  ]
}

生成值搜尋背景資訊

在本節中，您將產生值搜尋內容，協助內容集邏輯將值片語對應至資料庫欄中儲存的特定值。舉例來說，如果使用者要求「飛往曼哈頓的航班」，系統會先擷取曼哈頓做為值詞組，然後語意相似度搜尋會將曼哈頓與「紐約」建立關聯，並儲存在 airports.city 欄中。

如要產生值搜尋內容，請按照下列步驟操作：

  1. 在代理程式架構中輸入下列提示詞：

  2. 輸入 mysql，選取 MySQL 做為資料庫。

  3. 輸入要使用的 MySQL 版本。選取 default 即可選取 MySQL 8.0。

    Generate a trigram value search on table "airports" for column "name" with concept "airport name". Then generate a semantic value search on table "airports" for column "city" with concept "airport city" using embedding column "city_embedding".

  4. 查看系統生成的價值搜尋定義。您可以將值搜尋定義儲存為新的內容集檔案，或附加至現有的內容集檔案。

  5. 對代理下達 Append the context to context_set.json 提示詞。這會將值搜尋定義新增至先前建立的結構定義檔案。

  6. 輸入產生內容集檔案的資料庫執行個體和資料庫名稱。

    現有的結構定義檔案會更新為值搜尋定義，內容如下：

      {
"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. 前往 Google Cloud 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 在導覽選單中，按一下「Cloud SQL Studio」。

  4. 使用 Identity and Access Management 驗證機制登入 Studio。

  5. 在「Explorer」窗格中，按一下「Context sets」旁邊的「Actions」圖示 。

  6. 按一下「Edit context set」。

  7. 按一下「Upload context set file」部分的「Browse」，然後選取先前產生的情境集檔案。

  8. 按一下 [儲存]。

使用 QueryData 生成 SQL 查詢

在本節中，您將使用上傳的情境集檔案，以自然語言提問。這樣您就能確認 QueryData 正確解讀並套用「nighttime traffic」等字詞和其他相關詞組的定義。

如要生成 SQL 查詢，請按照下列步驟操作：

  1. 在「Explorer」窗格中，按一下內容集旁邊的「更多動作」圖示 ()。
  2. 按一下「測試脈絡資料集」。
  3. 在查詢編輯器中，點選「Generate SQL using QueryData with: flights-assistant」(使用 QueryData 生成 SQL，並搭配 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. 輸入下列問題來生成 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 現在能透過語意比對，準確解讀「曼哈頓」與資料庫中的「紐約」相關。

將 QueryData 與應用程式整合

在本節中，您將為航班搜尋應用程式建立資料代理程式。這個資料代理提供對話式介面，可存取您先前建立的 flights 和 airports 資料表。此外，您也會瞭解如何使用 Agent Development Kit (ADK)、Gemini 資料分析 QueryData MCP 工具和脈絡資料集，建立這類資料代理並整合至應用程式，提升回覆品質。

  1. 下載 MCP Toolbox 1.14.0 以上版本。MCP Toolbox 會將資料代理公開為工具，供應用程式連線。MCP Toolbox 與您先前安裝的脈絡工程代理不同，後者會生成脈絡。

  2. 設定應用程式預設憑證 (ADC)。

    gcloud auth application-default login

  3. 找出您先前建立的情境集 ID。如要進一步瞭解如何找出情境集 ID，請參閱「找出情境集 ID」。

  4. 將下列內容附加至 tools.yaml 設定，以便使用 MCP Toolbox 連線至資料代理。詳情請參閱「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： Google Cloud 專案 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 伺服器。

    ./toolbox --config autoctx/tools.yaml

  6. 建立 ADK 應用程式，使用 MCP Toolbox 的 Python SDK 叫用 Gemini 資料分析 QueryData 工具。如要進一步瞭解如何使用 MCP Toolbox 的 Python SDK，請參閱 Toolbox 快速入門導覽課程。如要瞭解 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 檔案的內容，替換成下列「飛航資料助理」範例應用程式程式碼。

      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 目錄下執行下列指令，啟動應用程式並存取 ADK 網路伺服器 (http://127.0.0.1:8000)。

    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.

    根據先前新增的 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

    根據先前新增的值搜尋情境，代理理解「曼哈頓」與「紐約」市相關，並傳回相關資料，供代理用於建構回覆。

    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?，請點選代理程式泡泡。在左側導覽列的「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 資料代理。詳情請參閱「在 Cloud SQL Studio 中管理情境集」。上傳後，控制台會立即擷取新的背景資訊，讓您在不中斷應用程式的情況下，提高代理的準確度。

多個代理程式

在開發環境中，您可以為 tools.yaml 檔案中的工具指派不同名稱，對多個資料代理程式環境執行 A/B 測試。舉例來說，您可以定義兩個名稱不同的 cloud-gemini-data-analytics-query 工具 (例如 cloud_gda_query_tool_v1 和 cloud_gda_query_tool_v2)，建立不重複的 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 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 在導覽選單中，按一下「Cloud SQL Studio」。

  4. 使用 Identity and Access Management 驗證登入 Studio。

  5. 在「Explorer」窗格中，點選情境集旁邊的「更多動作」圖示 。

  6. 在「Delete context set」(刪除情境集) 視窗的確認方塊中，輸入 flight-assistant。

  7. 按一下「確認」。

刪除執行個體

刪除「事前準備」一節中建立的執行個體時，您建立的所有物件也會一併刪除。

  1. 前往 Google Cloud 控制台的「Cloud SQL」頁面。

    前往 Cloud SQL

  2. 從清單中選取執行個體。

  3. 點選「刪除」。

  4. 輸入執行個體名稱，然後按一下「刪除」，確認要刪除執行個體。

後續步驟