将上下文集与应用集成

本教程介绍了如何使用 Cloud de Confiance 控制台在 Cloud SQL for PostgreSQL 中设置和使用上下文集，以及如何将其与您的应用集成。了解如何构建上下文集文件、创建使用上下文集文件的上下文集、使用 MCP Toolbox 调用 QueryData API 以针对自然语言问题生成 SQL 查询，以及如何将其与应用集成。

如需了解详情，请参阅上下文集概览。

目标

  • 创建数据库表并使用数据填充这些表。
  • 使用 Gemini CLI 和 MCP 工具箱构建上下文集文件。
  • 创建上下文集并上传上下文集文件。
  • 在 Studio 中测试上下文集并生成 SQL 查询。
  • 使用 MCP Toolbox 中的 Gemini Data Analytics QueryData 工具将上下文集与应用集成。
  • 使用价值搜索查询为 LLM 回答添加接地。

费用

在本文档中，您将使用 Cloud de Confiance by S3NS的以下收费组件：

您可使用价格计算器根据您的预计使用量来估算费用。

新 Cloud de Confiance by S3NS 用户可能有资格申请免费试用。

为避免继续计费，请在完成本文档中的任务后删除您创建的资源。如需了解详情，请参阅清理。

准备工作

在创建上下文集之前，请完成以下前提条件。

启用必需服务

为您的项目启用以下服务：

准备 Cloud SQL 实例

确保您有权访问现有 Cloud SQL 实例或创建新实例。 如需了解详情，请参阅为 Cloud SQL 创建实例。

本教程要求您在 Cloud SQL 实例中拥有一个数据库。如需了解详情，请参阅在 Cloud SQL 实例上创建数据库。

所需的角色和权限

  • 向实例添加 IAM 用户或服务账号。如需了解详情，请参阅使用 Cloud SQL 的 IAM 数据库身份验证管理用户。
  • 在项目级层向 IAM 用户授予 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色。如需了解详情，请参阅为项目添加 IAM 政策绑定。
  • 您还必须以具有超级用户权限（例如 postgres 用户）的用户身份登录，向 IAM 用户或服务账号授予只读数据库权限。

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;

    将 USER_NAME 替换为用户的电子邮件地址。您必须使用英文引号将电子邮件地址括起来，因为它包含特殊字符（@ 和 .）。

    如需了解详情，请参阅向单个 IAM 用户或服务账号授予数据库权限。

向 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 "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. 在探索器窗格中，点击上下文集旁边的查看操作。

  6. 点击创建上下文集。

  7. 在上下文集名称中，输入 flights-assistant。

  8. 点击创建。

在 Studio 中测试设置的上下文

在此部分中，请在 flights-assistant 上下文中提出自然语言问题，以生成 SQL 查询。由于上下文集中未上传任何上下文集文件，即使在提出包含上下文的问题（例如 nighttime traffic）后，QueryData 生成的查询也不是最佳查询。

  1. 在探索器窗格中，点击上下文集旁边的查看操作。
  2. 点击测试上下文设置。
  3. 在查询编辑器中，点击使用 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 流量”一词。这可能会阻止 Gemini 生成 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 查询，然后点击更新。

    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 或更高版本。如需更新“数据库上下文丰富化”扩展程序，请运行以下命令：

    gemini extensions update mcp-db-context-enrichment

  5. 如需更新数据库上下文丰富化扩展程序或替换 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. 在探索器窗格中，点击上下文集旁边的操作 () 图标。

  6. 点击修改情境集。

  7. 可选：修改上下文集说明。

  8. 点击上传上下文集文件部分中的浏览，然后选择之前生成的上下文集文件。

  9. 点击保存。

使用设置的上下文生成 SQL 查询

在本部分中，您将使用上传的上下文设置文件提出自然语言问题。这样一来，您就可以验证 QueryData 是否正确理解并应用了 nighttime traffic 等术语和其他相关短语的定义，以及值搜索是否将值短语映射到数据库列中存储的特定值（例如，将“迪士尼世界”映射到“奥兰多”）

如需生成 SQL 查询，请执行以下步骤：

  1. 在探索器窗格中，点击上下文集旁边的查看操作。
  2. 点击测试上下文设置。
  3. 在查询编辑器中，点击使用 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. 在使用 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 查询，然后点击更新。

    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 代理可为之前创建的 flights 和 airports 表提供对话界面。本文还介绍了如何使用智能体开发套件 (ADK)、Gemini Data Analytics QueryData MCP 工具和上下文创建此 QueryData 智能体并将其集成到应用中，以提高回答质量。

  1. 下载 MCP Toolbox 0.31.0 版或更高版本。MCP Toolbox 将 QueryData 代理公开为供应用连接的工具。MCP Toolbox 与您之前安装的 MCP Toolbox Gemini CLI 扩展程序不同，后者用于生成上下文。

  2. 设置应用默认凭证 (ADC)。

    gcloud auth application-default login

  3. 查找上下文集 ID。如需详细了解如何查找上下文集 ID，请参阅查找上下文集 ID。

  4. 创建 tools.yaml 配置，以使用 MCP Toolbox 连接到 QueryData 代理。如需了解详情，请参阅 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: "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 文件的内容替换为以下飞行数据助理示例应用代码。

      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 Web 服务器。

    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 网页界面，您可以检查来自 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 数据分析 QueryData 工具回答的准确性。使用 Gemini CLI 生成上下文，然后将更新后的上下文集文件上传到现有的 flights-assistant QueryData 代理。如需了解详情，请参阅使用 Gemini CLI 构建上下文。上传新上下文后，控制台会立即注入这些上下文，以便您在无需停机的情况下提高代理的准确率。

多个代理

在开发环境中，您可以通过在 tools.yaml 文件中为工具分配不同的名称，对多个 QueryData 代理上下文执行 A/B 测试。例如，您可以通过定义两个具有不同名称（例如 cloud_gda_query_tool_v1 和 cloud_gda_query_tool_v2）的 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. 输入实例名称，然后点击删除，以确认您要删除该实例。

后续步骤