基于 Vertex AI 与 Google ADK 的 BigQuery 对话式智能体：六大陷阱
使用 Google ADK 和 Gemini 构建自然语言 BigQuery 智能体，将其部署到 Vertex AI Agent Engine，从而避开 Python、依赖项、计费及 IAM 相关的难题。
来源: Building a BigQuery Conversational Agent on Vertex AI with ADK and the traps nobody warns you about
问题：简单的查询却卡在处理队列中
业务团队始终需要数据仓库中已有的数据。上个月发出了多少订单？哪种产品最畅销？每一个问题都会变成一张工单，随后需要手动提取数据，再经过一轮又一轮的沟通协调，往往要耗费数小时甚至数天时间，而实际上答案就在 BigQuery 中只需一次查询即可获得。
另一种解决方案是使用对话式智能体。用户用通俗的英语输入问题，智能体会自行生成 SQL 语句，在 BigQuery 中执行并返回结果。无需工单、无需数据提取，也不需要任何 SQL 技能。在笔记本电脑上实现这一功能还算容易，但要在 Google Cloud 上正确部署它时，才会出现各种隐藏问题，包括 Python 版本冲突、未声明的依赖项，以及只有在智能体在云端运行时才会显现的 IAM 相关问题。
此构建的堆栈由四部分组成：
- Google ADK，即用于协调智能体运行的代理开发工具包框架。
- 作为推理引擎的Gemini 2.5 Flash on Vertex AI。
- ADK附带的The BigQuery工具集，用于检查模式及执行SQL语句。
- 用于部署的托管运行时——Vertex AI Agent Engine。
项目设置
以已安装ADK的全新Python项目作为基础，理论上只需三步操作：创建虚拟环境、激活该环境，然后使用pip安装相关包。
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk
陷阱1：Python版本问题。ADK需要Python 3.10或更高版本。那些仍使用系统自带的Python 3.9的Mac在代理程序启动前看似一切正常，但一旦启动就会输出大量FutureWarning警告信息，随后出现错误提示，指出MCP需要Python 3.10或更高版本。在macOS上，应避免与系统解释器发生冲突，而是通过Homebrew安装一个干净的Python版本，具体方法见下文。
brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install google-adk
使用 python --version 检查版本，确保为 3.12.x，并确认命令行提示符以 (.venv) 开头。之后，通过 ADK 命令行生成代理框架结构。
adk create bq_agent_app
陷阱2：文件夹名称。代理的文件夹名必须是有效的Python标识符，即只能包含字母、数字和下划线。像bq-agent-app这样的带连字符的名称会导致部署失败，并出现无效的代理名称错误。而使用下划线形式的bq_agent_app则是可行的。这虽是个小细节，却可能轻易耗费十分钟时间。
将整个代理功能置于一个文件中
这正是ADK的优势所在。原本需要数百行编排代码才能实现的逻辑，现在只需一个声明式文件即可完成。该文件开头会导入Google认证相关模块、Agent类、BigQuery工具集以及相关的凭证和工具配置类。
import google.auth
from google.adk.agents import Agent
from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig
from google.adk.tools.bigquery.config import BigQueryToolConfig
其余部分会重用应用程序默认凭据，构建凭据配置，设置工具集，并定义代理本身，包括其模型、指令及工具过滤器。
# Reuse your Application Default Credentials
application_default_credentials, project = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
credentials=application_default_credentials
)# Google's first-party BigQuery toolset
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # bills the query jobs
),
tool_filter=[
"list_dataset_ids",
"get_dataset_info",
"list_table_ids",
"get_table_info",
"execute_sql",
],
)root_agent = Agent(
model="gemini-2.5-flash",
name="bq_data_assistant",
description="Answers natural-language questions over BigQuery data.",
instruction=(
"You are a data assistant for business teams. "
"When asked a question, first inspect the schema of the relevant "
"tables (get_table_info) BEFORE writing any SQL, so you use real "
"column names and never invent them. "
"You always run your query jobs in the configured billing project, "
"but you CAN read data from any accessible dataset, including public "
"ones. Reading a public dataset from your billing project is normal "
"and allowed, never refuse for that reason. "
"Write standard BigQuery SQL, execute it with execute_sql, then "
"return a clear answer with the number and, in one line, the query used. "
"If a question is ambiguous, ask for clarification before running."
),
tools=[bigquery_toolset],
)
该文件中的三点体现了智能体的真正内涵。
首先，思考与行动是分离的。Gemini负责推理，但它本身并不了解你的数据，也无法直接访问BigQuery。BigQueryToolset则提供了相应的工具，即模型可以决定调用的功能，比如检查数据结构或执行查询。整个过程以循环形式运行：模型先分析问题并选择工具，ADK负责执行该工具，得到结果后模型再决定下一步行动，直到能够给出答案。正是这种循环构成了智能体与聊天机器人的区别——聊天机器人只是进行对话，而智能体则能在受控的循环中在你的系统中执行操作。
其次，指令是核心控制手段。要求智能体在编写SQL之前先检查模式结构的指令，能够防止其随意创建列名。智能体的行为是通过提示词而非代码来塑造的，这一点的重要性远超表面所见。
第三，tool_filter用于实现最小权限控制，仅暴露智能体真正需要的工具。在处理敏感数据的生产环境中，应将其设置为只读模式，这样智能体虽然可以执行查询，但无法修改任何内容。
在本地运行
ADK提供了两种运行智能体的方式。adk run bq_agent_app会打开一个普通的终端聊天界面，而adk web则会启动一个包含聊天区域以及显示每次工具调用记录的“事件”面板的本地网页界面。虽然网页界面更美观，但由于adk run会明确显示错误信息而非默默失败，因此在故障排查时更为合适。
陷阱3：工具集从未声明的依赖项
在这一阶段问题确实会出现，而且这类问题的解决需要最多的反复尝试。虽然BigQuery工具集被描述为内置在ADK中，但实际上它却依赖于google-adk并未安装的包。首次启动时会遇到ModuleNotFoundError: No module named 'google.cloud'的错误。安装google-cloud-bigquery又会引发另一个错误：cannot import name 'dataplex_v1'，随后还会出现对db-dtypes的依赖问题。这样接连出现了三个错误，每个错误都是由于工具集假定存在但从未列出的包所导致的。
解决办法是提前安装这三个包，从而避免这种循环问题。
pip install google-cloud-bigquery google-cloud-dataplex db-dtypes
然后启动网页界面。
adk web
打开本地URL，选择代理，然后提出一个简单的问题来验证连接状况。
List the tables in bigquery-public-data.thelook_ecommerce
测试数据为 thelook_ecommerce，这是谷歌公开发布的合成电商数据集。其中包含客户、产品及订单信息，非常适合用于测试业务问题处理代理，且不涉及任何真实数据。如果能够返回表格列表，说明设置正确。请关注“事件”面板，那里会显示代理如何将 get_table_info 与 execute_sql 相结合。该面板最能清晰展现代理的行为，非常适合在演示中使用。
陷阱4：计费项目
在确认基础功能正常后，可以尝试提出真实问题。
What is the most sold product?
该代理礼貌地拒绝了请求。它表示没有权限在 bigquery-public-data 项目中创建任务，随后展示了本应执行的 SQL 语句，并请求指引到一个它有权限使用的项目。这看似是配置错误，但实际上并非如此。这是 BigQuery 中一个事后看来显而易见、但最初却让几乎所有人犯错的概念。
bigquery-public-data 是由谷歌拥有的只读项目。你可以读取其中的表，但无法在其中执行查询，因为执行查询会创建一个任务，而任务必须计费到你有权限使用的项目中。谷歌不会允许任何人将其项目的计算费用转嫁出去。因此，读取数据和执行查询是两个独立的操作，分别关联到两个不同的项目：一个负责存储数据，另一个负责支付计算费用。
该修复方案指示工具集在从公共数据集读取数据的同时，在您自己的项目中运行任务。相关设置名为compute_project_id，位于BigQueryToolConfig中，因此需要先导入该配置文件。
from google.adk.tools.bigquery.config import BigQueryToolConfig
然后使用该配置构建工具集，并添加注释标明哪些任务会在您的项目中运行并产生费用。
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # jobs run and bill here
),
tool_filter=[...],
)
重新部署后，会出现第二道更为有趣的“障碍”。该智能体现在知道要为您的项目计费，但它认为根本无法读取公共数据集，因而再次拒绝。这次它的判断是错误的，因为从自己的计费项目读取公共数据集是正常且被允许的，它只是过于谨慎了。
这正是利用指令作为杠杆来解决问题的时刻。问题出在提示词而非代码上，因为智能体自行推导出了一个并不存在的规则。在指令中加入一句明确的说明即可解决问题。该句应规定：查询任务始终在配置好的计费项目中进行，任何可访问的数据集（包括公共数据集）的数据都可以被读取，而且从计费项目读取公共数据集是正常行为，绝不应成为拒绝的理由。
经过另一次重新部署后，代理会检查模式结构、编写连接逻辑并执行该逻辑，随后返回最佳产品结果及其所使用的查询语句。这个示例表明，即便代理拥有必要的技术访问权限，若指令模糊不清，仍可能表现不佳。恰当的指令表述是此项工程工作的一部分，而非额外的技能。
部署到 Agent Engine
在笔记本电脑上运行只是基础，而真正让代理发挥作用的是在谷歌的基础设施上独立运行。Vertex AI Agent Engine 是专为 ADK 代理设计的托管运行时环境：你只需将代理交付给谷歌，由他们负责运行、扩展并维持其正常运转，无需自行管理服务器。
部署过程首先是从启用若干 API 开始，然后创建一个暂存桶，ADK 会将打包好的代码存储到该桶中。
gcloud services enable aiplatform.googleapis.com storage.googleapis.com
gcloud storage buckets create gs://your-project-id-adk-staging --location=us-central1
接着是部署命令，它需要项目名称、区域以及预发布存储桶信息。
adk deploy agent_engine \
--project=your-project-id \
--region=us-central1 \
--staging_bucket=gs://your-project-id-adk-staging \
bq_agent_app
这需要几分钟时间，因为后台会构建一个容器，而下一个陷阱就存在于该容器中。
陷阱5：容器对您的笔记本电脑一无所知
Agent Engine的首次运行会因同样的cannot import name 'dataplex_v1'错误而崩溃，看似问题已解决。部署环境无法查看开发人员机器上安装了什么，它只知道agent文件夹中requirements.txt文件里列出的包。因此笔记本电脑上存在依赖项，而容器中却没有。这一教训适用于所有GCP服务，无论是Cloud Functions、Cloud Run还是Agent Engine。在本地测试通过与在生产环境运行通过是两回事，明确的依赖项列表才能将二者联系起来。
解决办法就是明确列出所有包的名称。
# requirements.txt
google-adk
google-cloud-bigquery
google-cloud-dataplex
db-dtypes
重新部署后，容器会安装其所需的组件。
陷阱6：代理已不再是你本人
最后一个陷阱最能体现生产环境中的代理机制。部署虽然成功，但在云测试环境中输入的查询因缺乏bigquery.jobs.create权限而被BigQuery拒绝。这并非漏洞，而是IAM按设计正常运作的结果。
在笔记本电脑上，代理以你的身份运行，拥有你所有的权限。而部署后它则在服务账户下运行，本质上相当于一个机器人身份，该身份最初并不具备BigQuery的权限。正是这种设计使得代理在处理敏感数据时更加安全——代理无法超越其身份所允许的范围，没有任何信息被隐藏，IAM对其的限制与对任何人的限制相同。
服务账户需要两个角色，一个用于执行查询，另一个用于读取数据。第一个配置块授予 roles/bigquery.jobUser 权限。
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.jobUser"
第二个授权授予 roles/bigquery.dataViewer。
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.dataViewer"
稍等片刻，让变更生效后再在 Playground 中尝试。此时智能体会在云端响应，完全依靠谷歌的基础设施运行，而笔记本电脑则保持关闭状态。
构建过程中的经验教训
- 智能体并非聊天机器人。两者的区别在于智能体的思考循环：它会进行推理、调用工具、查看结果，然后重复这一过程直至能够给出答案。
- 指令承担了大部分实际工作。相同的代码和访问权限，由于指令表述的不同会导致截然不同的行为；而避免编造列名以及不必要的拒绝，都是通过优化提示词实现的。
- 内置并不等同于已安装。虽然 ADK 已包含 BigQuery 工具集，但它仍依赖于
google-cloud-bigquery、google-cloud-dataplex和db-dtypes，因此需先安装这些依赖项。
requirements.txt中列出的权限，这两种环境之间的差异都有明确的处理方式。一个最初只是关于如何从 BigQuery 中获取自然语言答案的课题，最终发展成了一个完全部署好的 Vertex AI 智能体，它无需使用 SQL 也不需要手动提取数据即可回答业务问题。整个解决方案均基于 GCP 的原生技术，因此已经在使用 BigQuery 的团队无需更换技术栈，只需将 Gemini 添加到他们现有的工具中即可。相关教程并未提及这些潜在问题：Python 版本不匹配、未声明的依赖项、计费项目混淆以及权限不足的服务账户。了解这些隐患能节省大量时间，因此建议从小规模开始尝试，故意制造问题并查看错误信息。
相关阅读
- Bedrock Agents：内存摘要、版本化约束机制与知识库 — 由Terraform驱动的Bedrock智能体功能：支持自定义摘要提示的内存管理、采用“检测后阻断”策略的版本化约束机制，以及基于S3的RAG技术。
- 实用指南：Google ADK详解——如何构建多智能体系统 — 该指南为希望采用此架构的团队提供了详细操作步骤，包括相关契约、校验规则以及可直接插入代码的模块。