准备工作
- 实验会创建一个 Google Cloud 项目和一些资源,供您使用限定的一段时间
- 实验有时间限制,并且没有暂停功能。如果您中途结束实验,则必须重新开始。
- 在屏幕左上角,点击开始实验即可开始
Run the agent using the ADK's Web UI
/ 25
Run an agent programmatically
/ 25
Chat with an agent via the command-line interface
/ 25
Preview a multi-agent example
/ 25
使用 Agent Development Kit 建構代理應用程式,可以為開發人員帶來以下主要好處:
SequentialAgent、ParallelAgent 和 LoopAgent) 來定義可預測的管道工作流程,或透過使用 LLM 的動態轉送功能 (LlmAgent 轉移),創造靈活應變的代理。雖然其他生成式 AI SDK 或代理框架同樣能查詢模型,甚至為模型提供工具,但您必須投入大量心力,在多個模型間靈活調度。
相較之下,Agent Development Kit 比上述工具更加高階,您可以輕鬆相互連結多個代理,建立複雜但方便維護的工作流程。
此外,您還能將複雜的代理系統部署至 Agent Engine 的全代管端點,讓自己只需專注在代理邏輯,把基礎架構配置和調度作業交由 ADK 處理即可。
在本實驗室,您將建立一個可使用搜尋工具的代理,然後使用 ADK 的瀏覽器 UI、CLI 對話介面和程式指令碼,測試這項代理。
本實驗室的學習內容包括:
請詳閱以下操作說明。實驗室活動會計時,中途無法暫停。點選「Start Lab」後就會開始計時,顯示可使用 Google Cloud 資源的時間。
您會在實際雲端環境中完成 Qwiklabs 實作實驗室活動,而非模擬或示範環境。為此,我們會提供新的暫時憑證,供您在實驗室活動期間登入及存取 Google Cloud。
為了順利完成這個實驗室,請先確認:
注意:如果您擁有個人 Google Cloud 或專案,請勿用於本實驗室。
注意:如果您使用的是 Pixelbook,請在無痕視窗執行本實驗室。
點選「Start Lab」按鈕。如果實驗室會產生費用,畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目:
點選「Open Google Cloud console」;如果使用 Chrome 瀏覽器,也能按一下滑鼠右鍵,選取「在無痕視窗中開啟連結」。
接著,實驗室會啟動相關資源,並開啟另一個分頁,顯示「登入」頁面。
提示:您可以在不同的視窗中並排開啟分頁。
如有必要,請將下方的 Username 貼到「登入」對話方塊。
您也可以在「Lab Details」窗格找到 Username。
點選「下一步」。
複製下方的 Password,並貼到「歡迎使用」對話方塊。
您也可以在「Lab Details」窗格找到 Password。
點選「下一步」。
按過後續的所有頁面:
Google Cloud 控制台稍後會在這個分頁開啟。
選取 Google Cloud 控制台視窗,然後在鍵盤上依序按下 G 和 S 鍵,開啟 Cloud Shell,或者點選 Cloud 控制台右上方的「啟用 Cloud Shell」按鈕 。
按一下「繼續」。
看到授權 Cloud Shell 的提示時,點選「授權」按鈕。
在 Cloud Shell 終端機面板右上角,按一下「在新視窗中開啟」按鈕 。
在 Cloud Shell 終端機中輸入下列指令,開啟 Cloud Shell 編輯器並前往主目錄:
在 Cloud Shell 終端機執行下列指令,更新 PATH 環境變數,並安裝 ADK。注意:您需要指定版本,確保安裝的 ADK 版本與本實驗室所用者相符:
將下列指令貼到 Cloud Shell 終端機,從 Cloud Storage bucket 複製檔案並解壓縮,建立本實驗室所需的程式碼專案目錄:
使用下列指令安裝其他實驗室所需項目:
Google ADK 有以下幾個核心設計概念,因此功能強大且靈活:
Session) 的背景資訊,包括對話記錄 (Events),以及代理保有的對話相關工作記憶 (State)。在 Cloud Shell 編輯器的檔案總管窗格,找出 adk_project 資料夾,然後點選並開啟資料夾。
這個目錄包含其他三個目錄:my_google_search_agent、app_agent 和 llm_auditor,每個分別代表不同的代理。將代理各自放在專案目錄對應的位置,即可提供組織架構,讓 Agent Development Kit 瞭解有哪些代理。
點按「my_google_search_agent」,探索代理目錄。
您會發現目錄中有 __init__.py 檔案和 agent.py 檔案。__init__.py 通常用來指定目錄做為 Python 套件,能以其他 Python 程式碼匯入。點按「init.py」檔案即可查看其中內容。
您也會發現 __init__.py 檔案只有從 agent.py 檔案匯入的一行程式碼。ADK 會使用這行程式碼,將這個目錄指定為代理套件:
現在點選 agent.py 檔案,其中有一個簡單的代理。您將為這個代理配備強大的搜尋工具,讓代理能使用 Google 搜尋,在網際網路尋找資訊。檔案有以下幾個重點:
google.adk 匯入的項目:Agent 類別和 tools 模組中的 google_search 工具將匯入的 google_search 工具傳遞給代理,即可使用這個工具。方法是在 agent.py 檔案中,將下列程式碼貼至建立的 Agent 物件結尾:
儲存檔案。
代理可透過工具,執行生成文字以外的動作。在這個案例中,代理可透過 google_search 工具判斷何時可能需要訓練資料以外的資訊,然後編寫搜尋查詢、使用 Google 搜尋在網路尋找資訊,並根據搜尋結果回覆使用者。模型擷取額外資訊做為回覆依據的程序,稱為「建立基準」,而這整個程序則稱為「檢索增強生成」(RAG)。
如要進一步瞭解如何搭配使用 ADK 與各種工具,請參閱「為 ADK 代理提供工具」實驗室。
ADK 具備可在本機執行的開發 UI,來協助開發及測試代理。開發 UI 會提供各類圖表,方便您瞭解每個代理的活動,以及多個代理之間的互動情形。在本工作中,您將探索這個介面。
執行代理時,ADK 必須知道是誰要求模型 API 呼叫。您可以透過下列兩種方式,提供這項資訊:
在本實驗室中,您將採用 Vertex AI 做法。
在 Cloud Shell 編輯器選單中,依序選取「View」>「Toggle Hidden Files」,即可顯示/取消顯示隱藏的檔案 (如果檔案名稱開頭為半形句號,大部分檔案系統都會預設隱藏)。您可能需要向下捲動選單,才能找到「Toggle Hidden Files」選項。
在 Cloud Shell 編輯器的檔案總管窗格中,前往 adk_project/my_google_search_agent 目錄。
選取 my_google_search_agent 目錄中的「.env」檔案。
貼入以下的值覆寫現有檔案內容,將您的專案 ID 更新至檔案中:
儲存檔案。
這些變數的作用如下:
GOOGLE_GENAI_USE_VERTEXAI=TRUE:表示您將使用 Vertex AI 執行驗證,而非 Gemini API 金鑰。GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION:提供要與模型呼叫建立關聯的專案和位置。MODEL:這不是必要變數,存放在這裡的用途是做為環境變數供系統載入,方便您在不同部署環境嘗試不同模型。使用 ADK 開發 UI 或指令列對話介面測試代理時,如果代理有「.env」檔案,系統就會載入並使用該檔案;如果沒有,系統就會尋找與這裡所設名稱相同的環境變數。
在 Cloud Shell 終端機執行下列指令,確認您位於 adk_project 目錄,也就是代理子目錄所在位置:
使用下列指令啟動 Agent Development Kit 開發 UI:
輸出內容
點按終端機輸出內容中的 http://127.0.0.1:8000 連結,在新分頁開啟網頁介面。系統會透過 Proxy,將您連結至這個在本機 Cloud Shell 執行個體執行的應用程式。
ADK 開發 UI 會在新的瀏覽器分頁開啟。
在左側的「選取代理」下拉式選單中,選取「my_google_search_agent」。
輸入以下問題,讓代理使用 Google 搜尋工具查詢:
從結果可看出,代理能使用 Google 搜尋取得最新資訊,而不是只提供模型訓練時的資料。
請注意,左側欄預設會顯示「追蹤記錄」分頁。點按上次的查詢文字 (What is some recent global news?),即可查看追蹤記錄,瞭解查詢各部分花了多少時間執行。您可以根據記錄,對工具呼叫相關的複雜執行作業偵錯,瞭解各個程序與回覆延遲之間的關聯。
點選代理回覆旁的代理圖示 () 或「事件」分頁列出的內容,即可檢查代理傳回的事件,包括
content (傳回給使用者的內容),以及 groundingMetadata (回覆所依據的搜尋結果詳細資訊)。
探索完開發 UI 後,請關閉這個瀏覽器分頁,然後返回 Cloud Shell 終端機的瀏覽器分頁,點選終端機窗格,並按下 CTRL + C 鍵停止網路伺服器。
點選「Check my progress」,確認目標已達成。
雖然開發 UI 適合用於測試及偵錯,但在正式環境中,最好不要向多名使用者顯示您的代理。
如要大型應用程式中執行代理,則必須在 agent.py 指令碼加入一些額外元件。在上一個工作中,這些元件是由網頁應用程式處理。請按照下列步驟,開啟並檢查含有這些元件的指令碼。
在 Cloud Shell 終端機執行下列指令,匯出環境變數。如果代理的目錄中沒有 .env 檔案,即可使用這種方法為所有代理設定環境變數:
在 Cloud Shell 編輯器的檔案瀏覽器中,選取「adk_project/app_agent」目錄。
選取這個目錄中的「agent.py」檔案。
這個代理的用途是做為應用程式的一部分來執行,因此請詳閱 agent.py 的程式碼註解,並特別留意程式碼中的下列元件:
| 元件 | 功能 | 說明 |
|---|---|---|
InMemoryRunner() |
監督代理執行作業 | Runner 程式碼負責接收使用者查詢、傳遞給適當的代理、接收代理的回覆事件並將傳回呼叫的應用程式/UI,然後觸發後續事件。詳情請參閱 ADK 事件迴圈說明文件。 |
runner.session_service.create_session() |
對話記錄和共用狀態 | Session 元件可讓代理保留狀態,記住項目清單、工作目前的狀態或其他現有資訊。為簡單起見,本實驗室選擇建立本機工作階段服務,但在正式環境中,這項服務可由資料庫處理。 |
types.Content() 和 types.Part()
|
結構化的多模態訊息 | 系統不會向代理傳遞簡單的字串,而是傳遞 Content 物件,其中可能包含多個 Part。如此一來,您就可以用特定順序,將包括文字和多模態內容的複雜訊息傳遞給代理。 |
您會發現指令碼包含一個給代理的硬式編碼查詢,內容為「What is the capital of France?」。
在 Cloud Shell 終端機執行下列指令,透過程式執行這個代理:
輸出內容節錄:
您也可以為代理定義特定的輸入和/或輸出內容結構定義。
現在您要在 Pydantic 結構定義類別「BaseModel」和「Field」新增匯入項目,並用來定義結構定義的類別。這個類別只有一個欄位,索引鍵為「capital」,字串值為國家/地區的首都名稱。新增其他匯入項目後,即可直接將下列程式碼貼至 app_agent/agent.py 檔案:
在 root_agent 的 Agent 定義中,新增下列參數來停用轉移功能 (這是使用輸出內容結構定義時的必要操作),並設定代理根據上方的 CountryCapital 結構定義生成輸出內容:
再次執行代理指令碼,查看 output_schema 後的回覆:
輸出內容節錄:
點選「Check my progress」,確認目標已達成。
您還可以在本機開發環境中,使用指令列介面與代理對話。開發代理時,這項功能可幫助您快速偵錯及測試。
與網頁介面相同,指令列介面也會建立代理的工作階段服務、構件服務和執行元件。
請按照下列步驟,使用指令列介面執行互動工作階段:
在 Cloud Shell 終端機執行下列指令:
輸出內容:
輸入下列訊息:
輸出內容範例 (可能會與您的輸出內容略有不同):
在指令列介面與代理對話完畢時,於後續的使用者提示詞輸入 exit,即可結束對話。
點選「Check my progress」,確認目標已達成。
「使用 ADK 建構多代理系統」實驗室課程會進一步解說如何建構多代理系統,但由於多代理能力是 Agent Development Kit 的核心服務,本課程將帶您預先探索這類系統。
這個代理系統會評估 LLM 是否以事實做為回覆基準,並加以改善。這個系統使用以下代理:
- critic_agent:可自動查核事實
- reviser_agent:如需根據驗證後的發現項目修正錯誤,會重新編寫回覆
請按照下列步驟探索代理:
透過 Cloud Shell 編輯器的檔案總管前往 adk_project/llm_auditor 目錄,瞭解這個多代理系統的程式碼。
選取 llm_auditor 目錄中的「agent.py」檔案。
這個多代理範例有幾項重點需要注意:
SequentialAgent 類別的匯入和使用方式。這個工作流程類別範例可在代理之間依序傳遞對話控管權限,無須使用者介入。因此執行代理時,您會發現系統不須等待使用者採取動作,critic_agent 和 reviser_agent 就會依序回應。sub_agents 目錄中對應的目錄匯入。__init__.py 和 agent.py 檔案,另外還有一個 prompt.py 檔案。這個檔案會提供專屬位置,存放完整且結構良好的提示詞,以便編輯後匯入 agent.py 檔案。為這個代理建立 .env 檔案,然後在 Cloud Shell 終端機執行下列指令,再次啟動開發 UI:
adk web 工作階段,系統會封鎖預設的通訊埠 8000。不過只要使用 adk web --port 8001 之類的指令,即可透過新通訊埠啟動開發 UI。
點按終端機輸出內容中的 http://127.0.0.1:8000 連結。ADK 開發 UI 會在新的瀏覽器分頁開啟。
在左側的「選取代理」下拉式選單中,選取「llm_auditor」。
輸入下列錯誤敘述展開對話:
您應該會在對話區看到代理的兩則回覆:
critic_agent 的詳細回覆。該代理會使用 Google 搜尋查核事實,然後根據結果確認敘述是否為真。reviser_agent 修正您輸入的錯誤敘述後,輸出的簡要敘述,例如「與火星相比,地球距離太陽更近」。點按每則回覆旁的代理圖示 (),即可開啟該回覆的事件面板,您也可以在「事件」面板找出並選取相應編號的事件。事件檢視畫面頂端會以圖表呈現這個多代理系統中,代理與工具之間的關係。系統會醒目顯示負責這則回覆的代理。
您可以進一步探索程式碼,或在開發 UI 提出其他事實查核範例問題。例如,您可以嘗試再提出以下問題:
如要重設對話,只要使用 ADK 開發 UI 右上方的「+ 新增工作階段」連結,即可重新開始對話。
向這個代理提問完畢後,請關閉瀏覽器分頁,並在終端機中按下 CTRL + C 鍵停止伺服器。
雖然這個範例使用 SequentialAgent 工作流程代理,但可以視為人機迴圈模式。當 SequentialAgent 結束序列,對話會返回上層代理 (在本例中為 llm_auditor),取得新的使用者輸入內容,再將對話傳回其他代理。
點選「Check my progress」,確認目標已達成。
在本實驗室中,您已瞭解:
如要進一步瞭解如何使用 Agent Development Kit 建構及部署代理,請參閱下列實驗室:
如要進一步瞭解 ADK,請參閱說明文件和 GitHub 存放區:
adk-docs:adk-docs
協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法,讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程,並有隨選、線上和虛擬課程等選項,方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。
使用手冊上次更新日期:2025 年 8 月 4 日
實驗室上次測試日期:2025 年 8 月 4 日
Copyright 2022 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標,其他公司和產品名稱則有可能是其關聯公司的商標。
此内容目前不可用
一旦可用,我们会通过电子邮件告知您
太好了!
一旦可用,我们会通过电子邮件告知您
一次一个实验
确认结束所有现有实验并开始此实验