Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 ADK 构建 AI 智能体：数据分析师智能体

1. 准备工作

欢迎观看“使用 ADK 构建 AI 智能体”系列的第四部分！在此 Codelab 中，您将通过实操练习，将之前课程中所学的知识融会贯通，创建一个数据分析师代理。该智能体将用于分析数据、生成有价值的数据洞见，并自动执行数据分析工作流的关键方面。

您将使用 ADK 中包含的强大工具，让智能体能够探索已上传的文件，并将其连接到 Google Cloud BigQuery 等企业级数据库。

您还可以通过以下缩短的网址访问此 Codelab：goo.gle/adk-data-analyst

前提条件

对生成式 AI 概念有基础的了解
基本掌握 Python 编程，并能熟练使用命令行。
熟悉本系列之前 Codelab 中的概念：“基础”和“利用工具赋能”。

学习内容

如何使用 ADK 框架构建功能齐全的数据分析师智能体。
用于使代理能够分析上传文档中的数据的方法。
如何将代理连接到 BigQuery 数据库以进行企业级数据分析。
用于定义智能体核心逻辑（包括其用途和指令）的技巧。

所需条件

一台可正常运行的计算机和可靠的互联网连接。
浏览器（例如 Chrome），用于访问 Google Cloud 控制台
好奇心和求知欲。

2. 简介

在当今这个数据驱动的世界，快速准确地分析海量信息的能力比以往任何时候都更加重要。不过，提取有意义的分析洞见往往需要具备 SQL 等方面的深厚技术专业知识，这会形成瓶颈，从而减慢决策速度。如果可以弥合这一差距，像对话一样轻松地与复杂的数据集互动，会怎么样？

而 AI 智能体正在改变这一局面。AI 代理充当您与数据之间的智能界面，能够理解自然语言问题，将其转换为技术查询，并在几秒钟内提供可据以采取行动的分析洞见。

在此 Codelab 中，您将使用智能体开发套件 (ADK) 构建实用的数据分析师智能体，从而迈入数据分析的未来。您将从创建基础代理开始，然后逐步增强其功能。您将首先教导代理分析上传文档中的非结构化数据。然后，您将它与功能强大的企业级数据仓库 Google Cloud BigQuery 相关联，以查询和分析大规模的真实医疗保健数据集。

在本教程结束时，您不仅会拥有一个可正常运行的 AI 助理，还会深入了解如何构建可自动执行日常数据任务、加快分析速度并为您和您的团队提供关键数据洞见的智能体。

3. 配置 Google Cloud 服务

创建 Google Cloud 项目

为了让您在此 Codelab 中的所有工作井井有条，并与其他项目分开，您将首先创建一个新的 Google Cloud 项目。

如需打开项目创建页面，请点击：

在项目创建页面上，输入所需信息：

项目名称：输入您选择的名称，例如 genai-workshop。长度必须介于 4 到 30 个字符之间，并且只能包含字母、数字、英文单引号、连字符、空格或英文感叹号。
位置：将此项设置为未选择任何组织。
结算账号：如果系统提示，请选择 Google Cloud Platform 试用结算账号（或您首选的有效结算账号）。如果未显示该选项，请继续操作。

记下生成的 项目 ID，稍后您会用到。

如果一切正常，请点击创建按钮。

配置 Cloud Shell

Cloud Shell 是一个预配置的环境，其中包含本 Codelab 所需的所有工具。成功创建项目后，请按以下步骤设置 Cloud Shell。

启动 Cloud Shell

如需启动 Cloud Shell，请点击：

如果系统弹出授权提示，请点击授权。

设置项目 ID

将 replace-with-your-project-id 替换为上述项目创建步骤中的实际项目 ID。在 Cloud Shell 终端中执行以下命令，以设置正确的项目 ID。

gcloud config set project replace-with-your-project-id

现在，您应该会在 Cloud Shell 终端中看到已选择正确的项目。所选项目 ID 会以黄色突出显示。

3. 启用必需的 API

如需使用 Google Cloud 服务，您必须先为项目启用其各自的 API。在 Cloud Shell 终端中运行以下命令，以启用此 Codelab 的服务：

gcloud services enable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

如果操作成功，您会在终端中看到 Operation/... finished successfully 消息。

4. 创建 Python 虚拟环境

接下来，创建一个独立的 Python 环境来管理项目的依赖项。

mkdir -p ai-agents-adk && cd ai-agents-adk

2. 创建并激活虚拟环境：

uv venv --python 3.12
source .venv/bin/activate

您会看到终端提示符带有 (ai-agents-adk) 前缀，表明虚拟环境处于有效状态。

3. 移除现有缓存

rm -rf ~/.cache

4. 安装 ADK 页面

uv pip install google-adk --no-cache

5. 将文件夹作为 Cloud Shell 工作区打开

cd ~
cloudshell workspace ai-agents-adk

5. 创建初始代理

准备好环境后，就可以使用简单的 ADK 命令创建 AI 智能体了。

1. 创建代理

在终端中，运行以下命令：

adk create data_analyst_agent

2. 配置代理

系统会提示您配置智能体。进行以下选择：

选择模型：选择 1. gemini-2.5-flash。
选择后端：选择 2。Vertex AI。
输入 Google Cloud 项目 ID：按 Enter 键确认项目 ID 正确无误。
输入 Google Cloud 区域：按 Enter 键可使用默认值 us-central1。

3. 启动开发 Web 服务器

创建代理后，运行以下命令来启动开发 Web 服务器：

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

您可以按 Ctrl + 点击或 Cmd + 点击链接（即 http://localhost:8000）在终端中，也可以

点击网页预览按钮
选择更改端口。
输入端口号（例如 8000）
点击更改并预览

然后，您会在浏览器中看到类似聊天应用的界面。

4. 与代理聊天

快来通过此界面与您的代理聊天吧！说“你好，你能做些什么？”等话语。

6. 分析文档中的数据

在本部分中，您将向代理上传文档并询问有关其内容的问题。

1. 总结文档内容

请按照以下步骤获取文档摘要：

下载有关 Google 医疗保健战略的文件。
点击代理界面中的上传文件按钮，然后选择您刚刚下载的文件。
在聊天界面中，要求代理总结文件：“请总结一下这份文件”
按 Enter 键。

您应该会收到一份简明扼要的文档内容摘要。

2. 提出更详细的问题

现在，尝试提出更详细的问题，以便更深入地了解文档：

Google 目前正通过其 AI 和数据计划重点关注哪些疾病？
Google 计划如何改进医疗保健数据互操作性并打破数据孤岛？
Google Cloud 如何用于为医疗保健企业和研究人员提供支持？
Google 接下来可能会探索哪些新的疾病领域（例如 COPD、癌症、心理健康）？

3. 追问

您还可以提出后续问题，例如查找网页参考编号以供进一步调查：

您是在哪里看到有关糖尿病的信息的？
将我引导至有关疾病的相关页面。
有哪些值得一看的有趣图表？

挑战：找到您希望代理分析的自有文档，然后上传该文档。向代理询问有关其内容的问题。

7. 将文档数据分析与实时网页搜索相结合

现在，该代理已成为文档方面的专家，但强大的分析师还需要访问最新的外部信息。我们来为智能体添加网页搜索功能。

在 Cloud Shell 终端中，按 Ctrl+C 停止 Web 服务器。
执行以下命令，在 Cloud Shell 编辑器中打开 data_analyst_agent/agent.py 文件：

cloudshell edit data_analyst_agent/agent.py

修改文件以导入并添加 google_search 工具：

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction="""
        First, check the uploaded files for an answer. 
        If the information is not in the files, use your tools to search the web. 
        Answer user questions to the best of your ability.
    """,
    tools=[
        google_search
    ]
)

在终端中输入以下命令，保存文件并重启 Web 服务器：

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

在代理界面中，重新上传 GoogleHealthStrategy.pdf 文件。
现在，提出一个问题，该问题需要同时使用文档的上下文和外部信息：

The document discusses Google's strategy in healthcare. What are three other major tech companies that are also investing heavily in healthcare AI, and what are their primary focus areas?

现在，智能体将整合文档和实时 Google 搜索中的信息，为您提供全面的答案。您可以尝试提出以下几个问题：

该文档提及了使用 AI 检测糖尿病视网膜病变。在过去一年中，FDA 批准了哪些最新技术？
文件提及了合作伙伴关系。您能找到有关 Google 在医疗保健领域的最新合作的任何近期新闻报道或新闻稿吗？

挑战：尝试向您自己的文档提出类似的问题。利用本地文档和互联网搜索结果。

8. 使用 BigQuery 分析医疗保健数据

上传单个文档无法实现规模化。在实际应用场景中，数据位于 Google Cloud BigQuery 等企业系统中。

目前，构建智能体应用的开发者通常必须构建和维护自己的自定义工具。这种手动流程速度慢、风险高，并且会产生大量开销。这会迫使开发者处理从身份验证到错误处理的所有事务，而无法专注于创新。

智能体开发套件 (ADK) 包含用于 BigQuery 交互的第一方工具。对于此特定分析，您将使用由联邦医疗保险和医疗补助服务中心 (CMS) 提供的公开可用的医疗保险使用情况数据集。

首先，我们将代理连接到庞大的公共医疗保健数据集。

在 Cloud Shell 终端中，按 Ctrl+C 停止 Web 服务器。
在终端中执行以下命令，在 Cloud Shell 编辑器中打开 data_analyst_agent/agent.py 文件：

cloudshell edit data_analyst_agent/agent.py

将该文件的全部内容替换为以下代码，以配置强大的 BigQueryToolset：

import google.auth
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.bigquery import (
    BigQueryToolset,
    BigQueryCredentialsConfig
)
from google.adk.tools.bigquery.config import (
    BigQueryToolConfig,
    WriteMode
)

# Automatically get credentials from the gcloud environment
application_default_credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
    credentials=application_default_credentials
)

# Configure the BigQuery tool
tool_config = BigQueryToolConfig(
    write_mode=WriteMode.ALLOWED,
    application_name='data_analyst_agent'
)

# Create the toolset with the specified configurations
bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config, bigquery_tool_config=tool_config
)

# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

# Define the final agent with its instructions and tools
root_agent = Agent(
    model="gemini-2.5-flash",
    name="bigquery_agent",
    description=(
        "Agent to answer questions about BigQuery data and execute SQL queries."
    ),
    instruction="""
        You are an expert data analyst agent with access to BigQuery tools.
        When a user asks about a dataset, first use your tools to understand its schema.
        Then, use this knowledge to construct and execute SQL queries to answer the user's questions.
        Always confirm with the user if their question is ambiguous (e.g., for which year?).
    """,
    tools=[
        AgentTool(google_search_agent),
        bigquery_toolset
    ],
)

在终端中输入以下命令，保存文件并重启 Web 服务器：

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

现在，您可以让智能体分析公共医疗保险数据集。首先，探索数据：

Look into the cms_medicare dataset in the bigquery-public-data project. What can you tell me about it?

代理将使用其工具检查数据集，并提供可用表的列表。然后，您可以提出具体的分析问题，进一步深入分析。代理可能会提出澄清问题，以确保其查询准确无误。

对于某些问题，您需要向代理提供项目 ID，以便代理使用该 ID 创建查询。例如：

以下是一些您可以尝试的分析提示示例：

根据 inpatient_charges_2015 表，按出院总数排名前 5 的程序（DRG 定义）是什么？
加利福尼亚州 (CA) “主要关节置换”的平均总付款是多少？
哪个州的相应手术的平均报销费用最高？

本 Codelab 到此结束。您仅仅是初步了解了由企业数据系统提供支持的数据智能体能实现的功能。欢迎随时向您的代理提出有关 cms_medicare 数据集的任何问题。

挑战：在 BigQuery 中查找另一个公共数据集，然后使用代理探索该数据集。您还可以使用自己的数据创建自己的数据集，并私下进行分析。

9. 清理（可选）

为避免日后产生费用，您可以删除本 Codelab 中使用的资源。

1. 停止代理

在 Cloud Shell 终端中，按 Ctrl+C 停止 adk web 进程。

2. 删除项目文件

如需从 Cloud Shell 环境中移除代理代码，请在终端中运行以下命令：

cd ~ && rm -rf ai-agents-adk

3. 停用 API

如需停用之前启用的 API，请在终端中运行以下命令：

gcloud services disable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

4. 关停项目

如果您想删除整个 Google Cloud 项目，请按照关停项目指南操作。

10. 总结

恭喜！您已成功使用智能体开发套件 (ADK) 框架构建了数据分析师智能体。该智能体能够分析来自各种来源的数据、生成数据洞见，并帮助自动执行部分数据分析工作流。

如需继续学习之旅，请探索以下资源：

阅读官方博文：推出适用于 AI 代理的 BigQuery 工具集
浏览文档：访问官方智能体开发套件 (ADK) 文档，了解新功能和高级指南。
浏览代码：查看 ADK GitHub 代码库。
发现更多数据：探索 Google Cloud 公共数据集目录。