將 QueryData 整合至應用程式

本教學課程說明如何使用 Cloud de Confiance 控制台，在 PostgreSQL 適用的 Cloud SQL 中設定及使用 QueryData，並將其整合至應用程式。瞭解如何建構內容集檔案、建立使用內容集檔案的內容集、使用 MCP Toolbox 呼叫 QueryData API，為自然語言問題生成 SQL 查詢，並將其整合至應用程式。

詳情請參閱「QueryData 總覽」。

目標

  • 建立資料庫表格並填入資料。
  • 使用 Gemini CLI 和 MCP 工具箱建構脈絡集檔案。
  • 建立內容集並上傳內容集檔案。
  • 在 Studio 中測試 QueryData 並產生 SQL 查詢。
  • 使用 MCP Toolbox 中的 Gemini Data Analytics QueryData 工具，將 QueryData 整合至應用程式。
  • 使用值搜尋查詢，為 LLM 回覆內容建立基準。

費用

在本文件中，您會使用下列 Cloud de Confiance by S3NS的計費元件：

您可以使用 Pricing Calculator 根據預測用量估算費用。

初次使用 Cloud de Confiance by S3NS 的使用者可能符合免費試用期資格。

如要避免繼續計費，請在完成本文中的工作後，刪除您建立的資源。詳情請參閱「清理」一節。

事前準備

建立內容集之前，請先完成下列先決條件。

啟用必要服務

為專案啟用下列服務：

準備 Cloud SQL 執行個體

請確認您有權存取現有的 Cloud SQL 執行個體，或建立新的執行個體。 詳情請參閱「建立 Cloud SQL 執行個體」。

本教學課程需要您在 Cloud SQL 執行個體中建立資料庫。詳情請參閱「在 Cloud SQL 執行個體上建立資料庫」一文。

必要角色和權限

  • 將 IAM 使用者或服務帳戶新增至執行個體。詳情請參閱「使用 Cloud SQL 的 IAM 資料庫驗證機制管理使用者」。
  • 在專案層級將 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色授予 IAM 使用者。詳情請參閱「為專案新增 IAM 政策繫結」。
  • 您也必須以具有超級使用者權限 (例如 postgres 使用者) 的身分登入，然後授予 IAM 使用者或服務帳戶資料庫唯讀權限。

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;

    將 USER_NAME 替換為使用者的電子郵件地址。由於電子郵件地址含有特殊字元 (「@」和「.」)，因此必須加上引號。

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

授予 Cloud SQL 執行個體 executesql 權限

如要將 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： 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. 按一下「驗證」。「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 "public"."flights" LIMIT 10;
SELECT * FROM "public"."airports" LIMIT 10;

在 Studio 中建立情境集

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

  1. 前往 Cloud de Confiance by S3NS 控制台的 Cloud SQL 頁面。

    前往 Cloud SQL

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

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

  4. 使用 IAM 驗證登入 Studio。

  5. 在「Explorer」窗格中，點選「Context sets」(內容集) 旁邊的「View actions」(查看動作)。

  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. 在「Generate SQL using QueryData with: flights-assistant」(使用 QueryData 生成 SQL 查詢：flights-assistant) 視窗中，按一下「Edit」(編輯)。

  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」(使用 QueryData 生成 SQL 查詢：flights-assistant) 視窗中，按一下「Edit」(編輯)。

  8. 輸入下列自然語言問題來生成 SQL 查詢，然後按一下「更新」。

    flight to disney world

    情境設定邏輯會產生查詢，找出名稱中含有「迪士尼世界」的機場。由於資料庫中沒有這類機場或城市，查詢不會傳回任何資料列。

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
INNER JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."name" ILIKE '%Disney World%';

為內容集生成背景資訊

在本節中，您將建立結構定義檔案，協助提升內容集的查詢功能。

設定環境

開始產生內容前，請先準備環境。

如要設定環境，請執行下列步驟：

  1. 安裝 Gemini CLI。詳情請參閱 Gemini CLI 快速入門指南。
  2. 安裝 gcloud CLI。

  3. 設定應用程式預設憑證 (ADC)。在終端機中執行下列指令，驗證及選取專案：

    gcloud auth application-default login

  4. 安裝 DB Context Enrichment 擴充功能，其中包含產生背景資訊的工作流程。

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

    確認版本為 0.4.2 以上。如要更新 DB Context Enrichment 擴充功能，請執行下列指令：

    gemini extensions update mcp-db-context-enrichment

  5. 如要更新 DB Context Enrichment 擴充功能或取代 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 Toolbox 支援，並定義在 tools.yaml 設定檔中。

    如要在目前目錄中建立 tools.yaml 設定檔，請輸入 Help me set up the database connection 等提示詞，然後按照技能提供的操作說明執行。如要進一步瞭解 tools.yaml 檔案，請參閱 MCP Toolbox 說明文件。

  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. 輸入 postgresql，選取 Cloud SQL 做為資料庫引擎。

  3. 輸入值搜尋設定，如下所示：

    Table: airports
Column: city
Concept: Airport City
Match Function: SEMANTIC_SIMILARITY_MATCH

  4. 確認是否要產生值搜尋定義。

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

  6. 選取要附加至現有脈絡集檔案的選項。這會將值搜尋定義新增至先前建立的結構定義檔案。

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

    現有的結構定義檔案會更新為值搜尋定義。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 = $1 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"
        }
      }
    ],
    "value_searches": [
      {
          "query": "/* Requires extensions: vector, google_ml_integration */ WITH SemanticMetrics AS (    SELECT T.city AS original_value, (        (google_ml.embedding('gemini-embedding-001', $value)::vector <=>          google_ml.embedding('gemini-embedding-001', T.city)::vector) / 2.0    ) AS normalized_dist     FROM airports T     WHERE T.city IS NOT NULL) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, ''::text AS context FROM SemanticMetrics",
          "concept_type": "Airport City",
          "description": "Semantic search for airport city name"
      }
  ]
  }

將脈絡集檔案上傳至 QueryData

在本節中，您會將內容集檔案上傳至 QueryData，以提升 QueryData 在資料庫中生成 SQL 的能力。

如要上傳內容，請按照下列步驟操作：

  1. 前往 Cloud de Confiance 控制台的 Cloud SQL 頁面。

    前往 Cloud SQL

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

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

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

  5. 在「Explorer」窗格中，點選「Context sets」旁邊的「Actions」 () 圖示。

  6. 按一下「編輯情境集」。

  7. 選用：編輯「Context set description」(情境集說明)。

  8. 按一下「Upload context set file」(上傳內容集檔案) 專區中的「Browse」(瀏覽)，然後選取先前產生的內容集檔案。

  9. 按一下 [儲存]。

使用 QueryData 生成 SQL 查詢

在本節中，您將使用上傳的內容集檔案，以自然語言提問。這項功能可讓您確認 QueryData 能正確解讀及套用 nighttime traffic 等字詞和其他相關片語的定義，並將值搜尋對應至資料庫欄位中儲存的特定值 (例如將「迪士尼世界」對應至「奧蘭多」)

如要生成 SQL 查詢，請執行下列步驟：

  1. 在「Explorer」窗格中，點選內容集旁邊的「查看動作」。
  2. 按一下「測試內容集」。
  3. 在查詢編輯器中，按一下「Generate SQL using QueryData with: flights assistant」(使用 QueryData 生成 SQL 查詢：航班助理)。

  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」(使用 QueryData 生成 SQL 查詢：flights-assistant) 視窗中，按一下「Edit」(編輯)。

  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. 在「Generate SQL using QueryData with: flights-assistant」(使用 QueryData 生成 SQL 查詢：flights-assistant) 視窗中，按一下「Edit」(編輯)。

  8. 輸入下列問題來生成 SQL 查詢，然後按一下「更新」。

    flights to disney world

    生成的 SQL 查詢大致如下：

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."city" = 'Orlando';

    請注意，QueryData 現在可以準確解讀「disney world」與「Orlando」城市相關。

將 QueryData 與應用程式整合

在本節中，您將為航班搜尋應用程式建立 QueryData 代理程式。這個 QueryData 代理程式提供對話式介面，可與您先前建立的 flights 和 airports 資料表互動。此外，本文也說明如何使用 Agent Development Kit (ADK)、Gemini Data Analytics QueryData MCP 工具，以及設定脈絡資料，在應用程式中建立及整合這個 QueryData 代理，進而提升回應品質。

  1. 下載 MCP Toolbox 0.31.0 以上版本。MCP 工具箱會將 QueryData 代理公開為應用程式可連線的工具。MCP 工具箱與您先前安裝的 MCP 工具箱 Gemini CLI 擴充功能不同，後者會產生內容。

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

    gcloud auth application-default login

  3. 找出內容集 ID。如要進一步瞭解如何找出內容集 ID，請參閱「找出內容集 ID」。

  4. 使用 MCP 工具箱建立 tools.yaml 設定，連線至 QueryData 代理程式。詳情請參閱「Gemini Data Analytics 來源」和 Gemini Data Analytics 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: "POSTGRESQL"
        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 伺服器。

    ./toolbox --config "tools.yaml"

  6. 使用 MCP Toolbox 的 Python SDK，建立會叫用 Gemini Data Analytics QueryData 工具的 ADK 應用程式。如要進一步瞭解如何使用 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 目錄下執行下列指令，建立虛擬環境並安裝必要元件。

      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. 根據您在 QueryData 代理脈絡中新增的概念類型，輸入問題。

    Get me flights to disney world

    根據先前新增的值搜尋環境，QueryData 代理程式會瞭解 disney world 與城市 Orlando 相關，並傳回相關資料，供 QueryData 代理程式用於建構回覆。

    Here are the flights heading to Orlando, which is the location of Disney World:

* Flight UA 1249 departs from SFO and arrives at MCO on 2025-01-02 at 18:15:00Z.
* Flight UA 698 departs from SFO and arrives at MCO on 2025-01-02 at 22:33:00Z.
* Flight UA 292 departs from SFO and arrives at MCO on 2025-01-03 at 06:37:00Z.

反覆提升代理程式效能

您可以在 ADK 網頁版 UI 中檢查 Gemini Data Analytics 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 Data Analytics QueryData 工具回覆內容的準確率。使用 Gemini CLI 生成脈絡資料，然後將更新後的脈絡資料集檔案上傳至現有的 flights-assistant QueryData 代理。詳情請參閱「使用 Gemini CLI 建構脈絡」。上傳新內容後，控制台會立即擷取，讓您提升代理程式的準確度，不必擔心應用程式停機。

多個代理程式

在開發環境中，您可以為 tools.yaml 檔案中的工具指派不同名稱，對多個 QueryData 代理程式環境執行 A/B 測試。舉例來說，您可以定義兩個名稱不同的 cloud-gemini-data-analytics-query 工具 (例如 cloud_gda_query_tool_v1 和 cloud_gda_query_tool_v2)，藉此建立不重複的 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. 在「Explorer」窗格中，點選內容集旁邊的「查看動作」。

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

  7. 按一下「確認」。

刪除執行個體

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

  1. 前往 Cloud de Confiance 控制台的 Cloud SQL 頁面。

    前往 Cloud SQL

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

  3. 按一下「Delete」(刪除)。

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

後續步驟