為 ADK 代理提供工具

Create a data store and search app

Check my progress

/ 25

Use a LangChain Tool

Check my progress

/ 25

Use a function as a custom tool

Check my progress

/ 25

Use a Google-provided tool

Check my progress

/ 25

This lab may incorporate AI tools to support your learning.

GENAI105

總覽

本實驗室介紹如何在 Agent Development Kit 代理中使用各種工具。

無論是 Google 提供的強大工具 (例如 Google 搜尋和 Vertex AI Search)，還是 LangChain 生態系統中豐富多樣的工具，都能輕鬆上手。

此外，只要寫好 docstring，就能將函式轉成自訂工具！

本實驗室假設您熟悉「開始使用 Agent Development Kit (ADK)」實驗室涵蓋的 ADK 基礎知識。

目標

在本實驗室，您將瞭解 ADK 代理適用的工具生態系統，以及如何將函式提供給代理當做自訂工具。

完成本實驗室後，您將能夠：

將 Google 或 LangChain 預建工具提供給代理
瞭解在編寫代理工具函式時，結構化 docstring 與型別標註的重要性
為代理編寫專屬工具函式

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始研究室及登入 Google Cloud 控制台

點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：
- 「Open Google Cloud console」按鈕
- 剩餘時間
- 必須在這個研究室中使用的臨時憑證
- 完成這個實驗室所需的其他資訊 (如有)
點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

提示：您可以在不同的視窗中並排開啟分頁。
注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。
如有必要，請將下方的 Username 貼到「登入」對話方塊。
{{{user_0.username | "Username"}}}
您也可以在「Lab Details」窗格找到 Username。
點選「下一步」。
複製下方的 Password，並貼到「歡迎使用」對話方塊。
{{{user_0.password | "Password"}}}
您也可以在「Lab Details」窗格找到 Password。
點選「下一步」。
重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。
按過後續的所有頁面：
- 接受條款及細則。
- 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
- 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。「導覽選單」圖示和搜尋欄位

搭配使用 Agent Developer Kit 和工具

善用工具是智慧型代理與基本模型的主要差異。工具是一段程式碼 (如函式或方法)，可執行特定動作，例如與資料庫互動、發出 API 要求，或叫用其他外部服務。

工具可讓代理與其他系統互動，並執行超出核心推理和生成能力範圍的動作。請務必注意，這些工具是獨立運行，與代理的 LLM 無關，也就是說，工具不會自動具備自己的推理能力。

Agent Development Kit 為開發人員提供多種工具：

預建工具：可直接使用的功能，例如 Google 搜尋、程式碼執行及檢索增強生成 (RAG) 工具。
第三方工具：完美整合 LangChain 等外部程式庫的工具
自訂工具：使用程式語言特定的語法結構，以及「代理即工具」機制，建立符合特定需求的專屬工具。SDK 也透過 Long Running Function Tools 提供非同步功能。

在本實驗室，您將瞭解這些類別，並實作其中一種類別。

Google 提供的預先建構工具

Google 為代理提供多種實用工具，包括：

Google 搜尋 (google_search)：允許代理使用 Google 搜尋執行網頁搜尋，只要將 google_search 新增至代理的工具即可。

執行程式碼 (built_in_code_execution)：這項工具可讓代理執行程式碼，進行計算、操縱資料，或以程式輔助方式與其他系統互動。您可以使用預先建構的 VertexCodeInterpreter，或是實作 BaseCodeExecutor 介面的任何程式碼執行器。

檢索 (retrieval)：這組工具可從各種來源擷取資訊。

Vertex AI Search 工具 (VertexAiSearchTool)：這項工具與 Google Cloud 的 Vertex AI Search 服務整合，可讓代理搜尋 AI 應用程式資料儲存庫。

工作 1：安裝 ADK 並設定環境

注意：建議在無痕模式瀏覽器視窗中開啟大多數 Qwiklabs 課程，以免分不清 Qwiklabs 學員帳戶和其他登入 Google Cloud 的帳戶。如果是使用 Chrome，您可以直接關閉所有無痕視窗，在本實驗室頂端的「Open Google Cloud 控制台」按鈕上按一下滑鼠右鍵，然後選取「在無痕視窗中開啟連結」。

啟用 Vertex AI 建議的 API

在本實驗室環境中，Vertex AI API 已啟用。如要在專案中執行這些步驟，請前往 Vertex AI，然後按照提示啟用。

準備 Cloud Shell 編輯器分頁

選取 Google Cloud 控制台視窗，然後依序按下鍵盤上的 G 和 S 鍵，開啟 Cloud Shell。或者，您也可以點選 Cloud 控制台右上方的「啟用 Cloud Shell」按鈕。
點選「繼續」。
系統提示您授權 Cloud Shell 時，點按「授權」。
點按 Cloud Shell 終端機面板右上角的「在新視窗開啟」按鈕。
點按窗格頂端的「開啟編輯器」鉛筆圖示，即可查看檔案。
點按左側導覽選單頂端的「探索工具」圖示 ()，開啟檔案探索工具。
點按「開啟資料夾」按鈕。
「開啟資料夾」對話方塊出現後，點按「確定」，選取 Qwiklab 學員帳戶的主資料夾。
關閉畫面右側的其他教學課程或 Gemini 面板，為程式碼編輯器騰出更多空間。
操作本實驗室其餘步驟時，您可以全程將這個視窗當成 IDE 使用，搭配 Cloud Shell 編輯器和 Cloud Shell 終端機作業。

下載並安裝本實驗室的 ADK 和程式碼範例

將下列指令貼到 Cloud Shell 終端機，從 Cloud Storage bucket 下載本實驗室的程式碼：
gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_tools .
在 Cloud Shell 終端機執行下列指令，更新 PATH 環境變數、安裝 ADK，並安裝本實驗室所需的其他項目。
export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_tools/requirements.txt

工作 2：建立搜尋應用程式，根據自有資料建立回覆基準

在後續工作中，您將使用 Google 提供的 Vertex AI Search 工具，根據 AI 應用程式資料儲存庫中的資料建立回覆基準。由於資料儲存庫擷取資料需要時間，因此現在要先完成設定，以便在後續工作中根據您的資料建立回覆基準。

在剛才開啟 Cloud 控制台的瀏覽器分頁中，於頂端搜尋「AI 應用程式」並前往該頁面 (此時可關閉分頁底部的 Cloud Shell 終端機，或右側的教學面板)。
勾選條款及細則核取方塊，然後按一下「繼續並啟用 API」。
選取左側導覽選單中的「資料儲存庫」。
選取「建立資料儲存庫」。
找到「Cloud Storage」資訊卡，點按其中的「選取」。
在「匯入非結構化資料 (文件搜尋和 RAG)」下方，選取「文件」。
範例文件已為您上傳至 Cloud Storage。這些文件與假想的行星「Persephone」有關。本例中使用的是虛構行星，因此模型在訓練期間不可能學到任何與該行星相關的知識。

如果是 GCS 路徑，請輸入 -bucket/planet-search-docs。
按一下「繼續」。
將「位置」維持「全域」。
在「資料儲存庫名稱」欄位輸入 Planet Search。
按一下「繼續」。
在提示選取計費模式時，請保留預設設定，然後點選「建立」。
按一下左側導覽列中的「應用程式」。
按一下「建立新的應用程式」。
找到「自訂搜尋 (一般)」應用程式的資訊卡，然後按一下「建立」。
將應用程式命名為 Planet Search。
將「公司名稱」設為 Planet Conferences。
按一下「繼續」。
勾選「Planet Search」資料儲存庫旁的核取方塊。
保留預設定價條款，選取「建立」。
建立應用程式後，按一下左上方的「AI 應用程式」，即可返回應用程式資訊主頁。
在「應用程式」表格中複製應用程式 ID。請將這個值儲存在文字文件中，稍後會使用這個值。

目前，資料儲存庫需要一些時間來擷取資料。稍後您需要將搜尋應用程式提供給代理，做為回應的依據。

點選「Check my progress」，確認目標已達成。建立資料儲存庫和搜尋應用程式。

工作 3：使用 LangChain 社群的第三方工具

ADK 支援使用 LangChain 等第三方 AI 框架的工具。LangChain 社群已開發大量工具整合項目，可用於存取多種資料來源、串接各種網路產品，以及處理許多作業。使用 ADK 內的社群工具，可避免重複編寫他人已建立的工具。

返回顯示 Cloud Shell 編輯器的瀏覽器分頁，並使用左側的檔案總管前往 adk_tools/langchain_tool_agent 目錄。
在 Cloud Shell 終端機中執行下列指令，即可在代理目錄中建立 .env 檔案，提供驗證詳細資料：
cd ~/adk_tools cat << EOF > langchain_tool_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF
執行下列指令，將 .env 檔案複製到本實驗室會使用的其他代理目錄：
cp langchain_tool_agent/.env function_tool_agent/.env cp langchain_tool_agent/.env vertexai_search_tool_agent/.env
點選 langchain_tool_agent 目錄中的 agent.py 檔案。
請留意 LangchainTool 類別的匯入作業。此為 wrapper 類別，支援在 Agent Development Kit 中直接使用 LangChain 工具。
在 agent.py 檔案的指定位置加入下列程式碼，將 LangChain 的 Wikipedia 工具加入代理。這樣一來，代理就能搜尋維基百科的資訊：
tools = [ # Use the LangchainTool wrapper... LangchainTool( # to pass in a LangChain tool. # 在本例中為 WikipediaQueryRun 工具， # 該工具需要 WikipediaAPIWrapper # 才能正常運作。 tool=WikipediaQueryRun( api_wrapper=WikipediaAPIWrapper(), handle_tool_error=True, ) ), ]

在 Cloud Shell 終端機中切換至 adk_tools 專案目錄，並執行下列指令，啟動 Agent Development Kit 開發人員 UI：
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
輸出內容
INFO: Started server process [2434] INFO: Waiting for application startup. +-------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +-------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
點選終端機輸出內容中的 http://127.0.0.1:8000 連結，在新分頁開啟網頁介面。
系統會開啟新的瀏覽器分頁，顯示 ADK 開發人員使用者介面。
在左側的「選取代理」下拉式選單中，選取「langchain_tool_agent」。
使用下列內容查詢代理：
葛麗絲霍普是誰？
輸出內容：
點按代理聊天泡泡旁的代理圖示 ()，即可查看代理是否使用了 Wikipedia 工具。
請注意，內容包含 functionCall，其中含有維基百科的查詢。
點按分頁頂端的前進按鈕，即可前往下一個事件。
探索這個事件，您會看到系統從維基百科擷取，用來生成模型回覆的結果。
向這個代理提問完畢後，關閉開發人員使用者介面瀏覽器分頁。
選取 Cloud Shell 終端機面板，然後按下 CTRL + C 鍵停止伺服器。

點選「Check my progress」，確認目標已達成。使用 LangChain 工具。

工作 4：將函式做為自訂工具

如果預先建構的工具無法完全滿足特定需求，您可以自行建立工具，以便使用自訂功能，例如連線至專屬資料庫或實作獨特的演算法。

想要建立新工具，最簡單的方法是編寫標準 Python 函式，並以標準格式撰寫 docstring，然後傳遞至模型當做工具。這個方法具有彈性，且可快速整合。

撰寫做為工具使用的函式時，請留意下列幾點：

參數：函式可接受任意數量的參數，每個參數可以是任何可序列化為 JSON 的類型 (例如字串、整數、清單、字典)。請務必避免為參數設定預設值，因為大型語言模型 (LLM) 目前不支援解讀這些值。
傳回類型：Python 函式工具偏好的傳回類型為字典。您可以用鍵/值組合建構回覆，為 LLM 提供背景資訊和明確性。舉例來說，與其傳回數字錯誤代碼，不如傳回含有 "error_message" 鍵的字典，提供人類可讀的說明。最佳做法是在傳回的字典中加入 "status" 鍵，指出整體執行結果 (例如 "success"、"error"、"pending")，讓 LLM 能明確掌握作業狀態。
docstring：函式的 docstring 會做為工具說明，並傳送至 LLM。因此，撰寫詳盡的 docstring 至關重要，有助於 LLM 瞭解如何有效使用工具。請清楚說明函式的用途、參數的意義，以及預期的傳回值。

如要定義函式並將其當做工具使用，請完成下列步驟：

使用 Cloud Shell 編輯器的檔案總管，前往 adk_tools/function_tool_agent 目錄。
在 function_tool_agent 目錄中，點選 agent.py 檔案。
檢查函式 get_date() 和 write_journal_entry() 的 docstring 格式是否正確，ADK 代理可據此瞭解使用時機和方式，包括：
- 清楚說明每個函式的用途
- Args: 區段，說明函式的輸入參數和可序列化為 JSON 的類型
- Returns: 區段，說明函式傳回的內容，並以 dict 做為偏好的回覆類型
如要將函式傳遞給代理當做工具使用，請在 agent.py 檔案中的指定位置新增下列程式碼：
tools=[get_date, write_journal_entry]

您將使用開發人員使用者介面執行這個代理，瞭解如何透過工具輕鬆查看工具要求和回覆。在 Cloud Shell 終端機中，切換至 adk_tools 專案目錄並執行下列指令，重新啟動開發 UI (如果伺服器仍在執行，請先按下 Ctrl + C 鍵停止執行，再以下列指令重新啟動)：
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
點按終端機輸出內容中的 http://127.0.0.1:8000 連結。
系統會開啟新的瀏覽器分頁，顯示 ADK 開發人員使用者介面。
在左側的「選取代理」下拉式選單中，選取「function_tool_agent」。
使用下列內容與代理開始對話：
hello
代理應會詢問您今天過得如何。請用一句話說明您今天過得如何 (例如「It's been a good day.I did a cool ADK lab)，代理就會為您撰寫日記。

輸出內容範例：
請注意，代理會顯示自訂工具要求和回覆的按鈕。點按各個按鈕即可查看不同事件的詳細資訊。
關閉開發人員使用者介面分頁。
在 Cloud Shell 編輯器中，您可以在 adk_tools 目錄找到以日期為名的日記檔案 (建議您使用 Cloud Shell 編輯器的選單，啟用「查看」 >「換行」，就能查看完整文字，不用進行大量水平捲動)。
點按 Cloud Shell 終端機面板，然後按下 CTRL + C 鍵，停止伺服器。
撰寫函式做為工具的最佳做法包括：
- 參數越少越好：盡量減少參數的數量，降低複雜度。
- 使用簡易資料類型：盡可能使用原始資料類型 (如 str 和 int)，而非自訂類別。
- 使用有意義的名稱：函式和參數的名稱會大幅影響 LLM 解讀及使用工具的方式。選用的名稱應清楚反映函式的用途和輸入內容的意義。
- 拆解複雜函式：與其使用單一的 update_profile(profile: Profile) 函式，不如改為設計多個獨立函式，例如 update_name(name: str)、update_age(age: int) 等。
- 傳回狀態：在傳回字典中加入 "status" 鍵，指出整體執行結果 (例如 "success"、"error"、"pending")，讓 LLM 能清楚判斷作業狀態。

點選「Check my progress」，確認目標已達成。將函式做為自訂工具。

工作 5：將 Vertex AI Search 做為工具，以自有資料建立基準

在這項工作中，您將瞭解如何使用 Agent Development Kit 代理，搭配內建的 Google Vertex AI Search 工具，以及先前建立的 AI 應用程式資料儲存庫，輕鬆部署 RAG 應用程式。

返回「Cloud Shell 編輯器」分頁，然後選取「adk_tools/vertexai_search_tool_agent」目錄。
在 vertexai_search_tool_agent 目錄中，點選 agent.py 檔案。
在匯入項目底部的指定位置，新增 VertexAiSearchTool 類別的匯入項目：
from google.adk.tools import VertexAiSearchTool
更新程式碼，將 VertexAiSearchTool 例項化。在傳遞至 search_engine_id 的路徑中，將 YOUR_PROJECT_ID 更新為，並將 YOUR_SEARCH_APP_ID 更新為您在先前工作中複製的搜尋應用程式 ID。
在代理定義中的指定位置新增下列程式碼，為代理提供工具：
tools=[vertexai_search_tool]
如要確認資料儲存庫是否已可供使用，請在控制台的「AI 應用程式」>「資料儲存庫」頁面中選取資料儲存庫名稱。

「活動」和「文件」分頁會顯示文件匯入和建立索引作業的狀態。「活動」分頁顯示「匯入完成」時，資料儲存庫應已可供查詢。
在 Cloud Shell 終端機中執行下列指令，從 adk_tools 專案目錄啟動指令列介面。指令中須加入 --reload_agents 旗標，讓開發 UI 能在您做出變更時，自動重新載入代理。
adk web --allow_origins "regex:https://.*\.cloudshell\.dev" --reload_agents 注意：如未結束先前的 adk web 工作階段，請切換至執行指令的 Cloud Shell 終端機面板，按下 Ctrl + C 鍵。如果找不到先前使用的 Cloud Shell 終端機分頁，導致預設的 8000 通訊埠遭到占用，您也可以改用 adk web --port 8001 指令，透過新通訊埠啟動開發 UI。
點按 http://127.0.0.1:8000 開啟 ADK 開發人員使用者介面。
在左側的「選取代理」下拉式選單中，選取「vertexai_search_tool_agent」。
使用下列指令，向代理查詢 Cloud Storage 文件中所述的虛構行星：
Is the new planet Persephone suitable for habitation?
輸出內容範例 (可能與您的輸出內容略有不同)
Based on the "Persephone Survey: What we Know So Far" document, Persephone exhibits several characteristics that suggest it could be habitable: - Location: It orbits within the habitable zone of its star. - Temperature: The average surface temperature is estimated to be around 18°C (64°F). ...

使用 AgentTool 將搜尋工具與其他工具整合

搜尋工具的實作限制在於，您無法在同一個代理中混用搜尋工具和非搜尋工具。如要解決這個問題，您可以使用 AgentTool 將代理包裝成搜尋工具，然後使用該代理做為工具，與其他工具一起執行搜尋。

如要查看實際運作情況，請按照下列步驟操作：

確認您已開啟 adk_tools/vertexai_search_tool_agent/agent.py 檔案。
更新 root_agent 的 tools 參數，加入 get_date 函式工具：
tools=[vertexai_search_tool, get_date]

在 ADK 開發人員使用者介面中詢問代理：
What is today's date?
預期輸出內容：
返回 adk_tools/vertexai_search_tool_agent/agent.py 檔案，將下列程式碼貼到 root_agent 上方。這個代理專用於操作搜尋工具，內含工具本身與相關使用指令：
vertexai_search_agent = Agent( name="vertexai_search_agent", model=Gemini(model=os.getenv("MODEL"), retry_options=RETRY_OPTIONS), instruction="Use your search tool to look up facts.", tools=[vertexai_search_tool] )

將 root_agent 的工具參數替換成下列內容，使用 AgentTool() 包裝在上一個步驟中建立的代理：
tools=[ AgentTool(vertexai_search_agent, skip_summarization=False), get_date ]
現在您可以查詢代理，並同時接收搜尋結果和使用 get_date() 函式。

返回 ADK 開發人員使用者介面瀏覽器分頁，然後按一下「+ 新工作階段」。
再問一次以下問題：
What is today's date?
代理應會回覆正確日期。
提出以下問題來叫用搜尋工具：
When is the PlanetCon conference?
預期輸出內容：
The PlanetCon: Persephone conference is scheduled for October 26th - 28th, 2028.
歡迎向代理提出更多問題，瞭解這顆新行星和即將公布這項發現的研討會。取得滿意的結果後，關閉開發人員使用者介面分頁。
向這個代理提問完畢後，請關閉瀏覽器分頁，選取執行伺服器的 Cloud Shell 終端機視窗，然後按下 CTRL + C 鍵停止伺服器。

點選「Check my progress」，確認目標已達成。使用 Google 提供的工具。

恭喜！

在本實驗室中，您已瞭解如何：

將 Google 和 LangChain 預建工具提供給代理
自訂代理專用的工具函式
就編寫代理的工具函式，討論結構化 docstring 和型別指派的重要性

後續步驟

想進一步瞭解如何使用 Agent Development Kit 建構及部署代理，請參閱下列實驗室：

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2026 年 2 月 3 日

實驗室上次測試日期：2026 年 2 月 3 日

Checkpoints

GENAI105

總覽

目標