使用 ADK 建構 AI 代理：資料分析師代理

1. 事前準備

歡迎來到「使用 ADK 建構 AI 代理」系列文章的第四部分！在本實作程式碼研究室中，您將結合先前課程所學內容，建立資料分析師代理程式。這個代理程式會分析資料、產生寶貴的洞察資訊，並自動執行資料分析工作流程的重要環節。

您可以使用 ADK 內含的強大工具，讓代理程式探索上傳的檔案，並連結至 Google Cloud BigQuery 等企業級資料庫。

您也可以透過這個縮短網址存取程式碼研究室：goo.gle/adk-data-analyst

必要條件

對生成式 AI 概念有基本瞭解
熟悉 Python 程式設計的基本操作，且能輕鬆使用指令列。
熟悉本系列先前程式碼研究室中的概念：「基礎」和「善用工具」。

課程內容

如何使用 ADK 框架建構實用的資料分析師代理。
讓代理程式分析上傳文件資料的方法。
瞭解如何將代理程式連結至 BigQuery 資料庫，進行企業級資料分析。
定義代理程式核心邏輯的技巧，包括用途和指令。

軟硬體需求

可正常運作的電腦和穩定的網際網路連線。
瀏覽器 (例如 Chrome)，用來存取 Google Cloud 控制台
好奇心和學習熱忱。

2. 簡介

在現今資料導向的環境中，快速準確地分析大量資訊的能力比以往更重要。不過，要從資料中擷取有意義的洞察資料，通常需要 SQL 等領域的深厚技術專業知識，這會造成瓶頸，進而拖慢決策速度。如果能彌合這道鴻溝，像對話一樣輕鬆與複雜的資料集互動，該有多好？

AI 代理正可望改變現況。AI 代理程式可做為您與資料之間的智慧介面，瞭解自然語言問題、將問題轉譯為技術查詢，並在幾秒內提供可執行的洞察資料。

在本程式碼研究室中，您將使用 Agent Development Kit (ADK) 建構實用的資料分析師代理，搶先體驗資料分析的未來。我們會先建立基礎代理程式，然後逐步提升其功能。首先，您要教導代理程式分析上傳文件中的非結構化資料。接著，您會將其連結至功能強大的企業級資料倉儲 Google Cloud BigQuery，查詢及分析大規模的真實醫療保健資料集。

在本教學課程結束時，您不僅會擁有可運作的 AI 助理，還會深入瞭解如何建構代理程式，自動執行例行資料工作、加快分析速度，以及為您和團隊提供重要洞察資料。

3. 設定 Google Cloud 服務

建立 Google Cloud 專案

為確保本程式碼研究室的所有工作井然有序，並與其他專案區隔，請先建立新的 Google Cloud 專案。

前往 console.cloud.google.com/projectcreate
輸入必要資訊：

專案名稱 - 您可以輸入任何想要的名稱 (例如 genai-workshop)
位置 - 保持「沒有機構」
帳單帳戶：如果顯示這個選項，請選取「Google Cloud Platform 試用帳單帳戶」，或視需要選取自己的帳單帳戶。如果沒有看到這個選項，請繼續下一個步驟。

複製產生的專案 ID，後續步驟將會用到。

如果一切正常，請按一下「建立」按鈕

設定 Cloud Shell

專案建立完成後，請按照下列步驟設定 Cloud Shell。

1. 啟動 Cloud Shell

前往 shell.cloud.google.com。如果出現要求授權的彈出式視窗，請按一下「Authorize」(授權)。

2. 設定專案 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. 安裝 adk 頁面

uv pip install google-adk --no-cache

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. 啟動開發網路伺服器

建立代理程式後，請執行下列指令啟動開發網路伺服器：

adk web

你可以按住 Ctrl 鍵並點選或按住 Cmd 鍵並點選連結 (即 http://localhost:8000) 終端機中，或

按一下「網頁預覽」按鈕
選取「變更通訊埠」。
輸入通訊埠編號 (例如 8000)
按一下「變更並預覽」

瀏覽器隨即會顯示類似即時通訊應用程式的使用者介面。

4. 與虛擬服務專員對話

請透過這個介面與代理程式對話！說出「你好，你會做什麼？」等問句。

6. 分析文件中的資料

在本節中，您將上傳文件至代理程式，並提出有關文件內容的問題。

1. 製作文件重點摘要

請按照下列步驟取得文件摘要：

下載檔案，瞭解 Google 的醫療保健策略。
在代理程式的使用者介面中，按一下「上傳檔案」按鈕，然後選取剛下載的檔案。
在對話介面中，要求服務專員提供檔案摘要：「請提供這個檔案的摘要」
按下 Enter 鍵。

您應該會收到文件內容的簡明摘要。

2. 提出更詳細的問題

現在，請嘗試提出更詳細的問題，深入瞭解文件內容：

Google 目前的 AI 和資料計畫主要針對哪些疾病？
Google 計畫如何提升醫療照護資料互通性，並打破資料孤島？
Google Cloud 如何支援醫療保健企業和研究人員？
Google 可能會探索哪些新的疾病領域 (例如慢性阻塞性肺病、癌症、心理健康)？

3. 提出後續問題

你也可以提出後續問題，例如找出頁面參考編號，以利進一步調查：

您在哪裡看到糖尿病相關資訊？
請將我導向疾病的相關頁面。
有哪些有趣的圖表值得參考？

挑戰：找出要讓代理程式分析的文件，然後上傳。向虛擬服務專員詢問內容相關問題。

7. 結合文件洞察資料和即時網路搜尋結果

現在，這個代理程式已成為文件專家，但強大的分析師也需要存取最新的外部資訊。現在要讓代理程式具備搜尋網路的能力。

在 Cloud Shell 終端機中，按下 Ctrl+C 停止網路伺服器。
執行下列指令，在 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
    ]
)

儲存檔案並重新啟動網路伺服器：在終端機中輸入 adk web
在代理程式 UI 中重新上傳 GoogleHealthStrategy.pdf 檔案。
現在，提出問題，要求 AI 根據文件內容和外部資訊回答：

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 等企業系統中。

目前，開發人員建構代理程式應用程式時，通常必須自行建構及維護自訂工具。這個手動流程緩慢、有風險，且會造成大量額外負擔。這會迫使開發人員處理驗證到錯誤處理等所有事項，而無法專注於創新。

Agent Development Kit (ADK) 包含用於 BigQuery 互動的第一方工具。在這項特定分析中，我們會使用醫療保險和醫療補助服務中心 (CMS) 提供的醫療保險使用情況資料集。

首先，將代理程式連結至龐大的公共醫療保健資料集。

在 Cloud Shell 終端機中，按下 Ctrl+C 鍵停止網路伺服器。
在終端機中執行下列指令，開啟 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
    ],
)

儲存檔案並重新啟動網路伺服器：在終端機中輸入 adk web
現在，您可以要求代理程式分析公開的 Medicare 資料集。首先，請探索資料：

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) 的「重大關節置換」平均總付款金額是多少？
哪個州的平均給付費用最高？

本程式碼研究室到此結束。您只發掘了冰山一角，企業資料系統支援的資料代理程式還有更多潛力。如有任何關於 cms_medicare 資料集的問題，歡迎隨時向服務專員提出。

挑戰：在 BigQuery 中尋找其他公開資料集，並使用代理程式探索該資料集。您也可以使用自己的資料建立資料集，並私下分析。

9. 清理 (選用)

如要避免產生後續費用，請刪除本程式碼研究室中使用的資源。

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. 結語

恭喜！您已成功使用 Agent Development Kit (ADK) 架構建構資料分析師代理。這個代理程式可以分析各種來源的資料、產生洞察資訊，並協助自動執行部分資料分析工作流程。

如要繼續學習，請參閱下列資源：

閱讀官方網誌文章：隆重推出 AI 代理程式專用的 BigQuery 工具組
查看說明文件：如要瞭解新功能和進階指南，請參閱官方 Agent Development Kit (ADK) 說明文件。
瀏覽程式碼：查看 ADK GitHub 存放區。
探索更多資料：瀏覽 Google Cloud 公開資料集目錄。