Before you begin
- Labs create a Google Cloud project and resources for a fixed time
- Labs have a time limit and no pause feature. If you end the lab, you'll have to restart from the beginning.
- On the top left of your screen, click Start lab to begin
Run the agent using the ADK's Web UI
/ 40
Run an agent programmatically
/ 40
Preview a multi-agent example
/ 20
Run the agent using the ADK's Web UI
/ 40
Run an agent programmatically
/ 40
Preview a multi-agent example
/ 20
想要建構複雜的代理應用程式,通常需要協調多種專用模型、整合管理工具,並對執行作業追蹤記錄進行偵錯,這些作業可能需要耗費大量人力,且難以調度資源。
Agent Development Kit (ADK) 可提供模組框架,協助建構、測試及部署多代理系統,解決上述難題。您可以透過 ADK,在階層結構中組合專用代理、為代理提供預先建構或自訂的工具,並運用可預測管道和動態 LLM 轉送功能,管理自動化調度工作流程。
在本實驗室中,您將使用 ADK 建構研究助理,運用
在本實驗室中,您將瞭解如何執行下列工作:
使用 ADK 建構代理應用程式,可以為開發人員帶來以下主要好處:
雖然其他 SDK 也可查詢模型,但 ADK 提供更高階的框架,可協助處理多種模型之間的複雜協調作業。
請詳閱以下操作說明。實驗室活動會計時,且中途無法暫停。點選「Start Lab」後就會開始計時,顯示可使用 Google Cloud 資源的時間。
您將在真正的雲端環境完成實作實驗室活動,而不是模擬或示範環境。為此,我們會提供新的暫時憑證,供您在實驗室活動期間登入及存取 Google Cloud。
為了順利完成這個實驗室,請先確認:
點選「Start Lab」按鈕。如果實驗室會產生費用,畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目:
點選「Open Google Cloud console」;如果使用 Chrome 瀏覽器,也能按一下滑鼠右鍵,選取「在無痕視窗中開啟連結」。
接著,實驗室會啟動相關資源,並開啟另一個分頁,顯示「登入」頁面。
提示:您可以在不同的視窗中並排開啟分頁。
如有必要,請將下方的 Username 貼到「登入」對話方塊。
您也可以在「Lab Details」窗格找到 Username。
點選「下一步」。
複製下方的 Password,並貼到「歡迎使用」對話方塊。
您也可以在「Lab Details」窗格找到 Password。
點選「下一步」。
按過後續的所有頁面:
Google Cloud 控制台稍後會在這個分頁開啟。
在這項工作中,您將設定 Cloud Shell 編輯器、初始化專案,並安裝 Agent Development Kit (ADK),為代理應用程式建構和測試作業準備環境。
在本實驗室環境,Vertex AI API 和 Telemetry API 已啟用。在您的專案中,您需要啟用這兩個 API 才能查詢模型,並將遙測資料傳送至 Cloud Logging。
在 Google Cloud 控制台標題列,點按「啟用 Cloud Shell」圖示 ()。
點按「繼續」。
系統提示您授權 Cloud Shell 時,點按「授權」。
在 Cloud Shell 終端機動作列中,點按「在新視窗開啟」圖示 。
在 Cloud Shell 編輯器中,點按動作列的「開啟編輯器」圖示 來檢視檔案。
點按左側窗格中的「Explorer」圖示 ,開啟檔案總管。
點按「開啟資料夾」。
系統顯示「開啟資料夾」對話方塊後,點按「確定」,選取 Google Skills 學員帳戶的主資料夾。
關閉畫面右側的其他教學課程或 Gemini 面板,為程式碼編輯器騰出更多空間。
操作這個實驗室其餘步驟時,您可以全程將這個視窗當成 IDE 使用,搭配 Cloud Shell 編輯器和 Cloud Shell 終端機作業。
將下列指令貼到 Cloud Shell 終端機,從 Cloud Storage bucket 複製含有本實驗室所需程式碼的專案目錄:
在 Cloud Shell 終端機執行下列指令,更新 PATH 環境變數,加入使用者本機環境並安裝 ADK (包括用於記錄和遙測的 OpenTelemetry (OTel) 外掛程式) 和其他實驗室所需項目:
檢視 ADK 的核心概念和基礎構成元素,包括代理、工具和自動調度管理模式,瞭解這些設計原則如何建構出高效率且富有彈性的多代理系統:
Session) 的背景資訊,包括對話記錄 (Events),以及代理保有的對話相關工作記憶 (State)。接下來,請檢視 ADK 專案的標準配置,瞭解這些概念的實際整合方式:
在 Cloud Shell 編輯器的檔案總管窗格,點按「adk_project」,開啟目錄。
請注意,adk_project 中有四個代理目錄:adk_utils、app_agent、llm_auditor 和 my_google_search_agent,每個分別代表不同的代理。將代理各自放在專案目錄對應的位置,即可提供組織架構,讓 ADK 瞭解有哪些代理。
點按「my_google_search_agent」,瀏覽代理目錄。
adk_project/my_google_search_agent 目錄。
點按「init.py」即可查看內容,請留意目錄中也有 agent.py 檔案。
您也會發現 init.py 檔案只有從 agent.py 檔案匯入的一行程式碼。ADK 會使用這行程式碼,將這個目錄指定為代理套件:
點按「agent.py」,查看搭載 Google 搜尋工具的簡易代理程式碼。
google.adk 匯入的項目包括 Agent 類別和 tools 模組中的 google_search 工具。將匯入的 google_search 工具傳遞給代理,即可使用這個工具。在 agent.py 檔案,找到 Agent 物件建立程式碼尾端的指定位置 (約第 34 行),並貼上下列程式碼:
儲存 agent.py 檔案。
代理可透過工具,執行生成文字以外的動作。在這個案例中,代理可透過 google_search 工具判斷何時可能需要訓練資料以外的資訊,然後編寫搜尋查詢、使用 Google 搜尋在網路尋找資訊,並根據搜尋結果回覆使用者。
模型擷取額外資訊做為回覆依據的程序,稱為「建立基準」,而這整個程序則稱為「檢索增強生成」(RAG)。
ADK 具備可在本機執行的開發 UI,可協助開發及測試代理。開發 UI 會提供各類圖表,方便您瞭解每個代理的活動,以及多個代理之間的互動情形。在這項工作中,您將探索開發 UI。
注意:執行代理時,ADK 必須知道是誰要求模型 API 呼叫。您可以透過下列兩種方式提供這項資訊:
在本實驗室中,您將採用第二種方式,透過 Vertex AI 專案進行驗證。
前往 Cloud Shell 終端機執行下列指令,寫入 .env 檔案來設定環境變數,指示代理使用您的專案和全域端點:
這些變數的用途如下:
GOOGLE_GENAI_USE_VERTEXAI=TRUE:表示您使用 Vertex AI 進行驗證,而非 Gemini API 金鑰。GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION:提供要與模型呼叫建立關聯的專案和位置。MODEL:這不是必要變數,存放在這裡的用途是做為環境變數供系統載入,方便您在不同部署環境嘗試不同模型。OTEL_SERVICE_NAME、OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED 和 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT:用於設定 OpenTelemetry (OTel),收集代理提供的 ADK 專屬遙測資料。ADK 開發 UI 和 CLI 對話介面會自動載入 .env 檔案的設定。如果沒有這類檔案,這些介面會使用名稱相符的系統環境變數。
在 Cloud Shell 終端機執行下列指令,確認您位於 adk_project 目錄,也就是代理子目錄所在位置:
透過下列指令推出 ADK 開發 UI,並加上一些實用標記。這個指令會執行下列動作:
輸出內容
系統最後會顯示 ADK 開發 UI 網址,因為開發 UI 目前正在執行中。
點按終端機輸出內容中的「http://127.0.0.1:8000」連結,在新分頁開啟網頁介面。系統會透過 Proxy,將您連結至這個在本機 Cloud Shell 執行個體執行的應用程式。您會看到開發 UI 在新分頁執作。
在左側的「選取代理」選單中,選取「my_google_search_agent」。
如要提示代理使用 Google Search 搜尋工具,請輸入以下問題:
請注意,代理會使用 Google 搜尋擷取即時資訊,略過預先訓練模型的知識截點。
請注意,左側窗格預設會顯示「追蹤記錄」分頁。點按上次的查詢文字 (我知道 2028 年會舉辦夏季奧運,請告訴我有哪些國家/地區會參加,以及會舉辦哪些賽事。),即可查看追蹤記錄,瞭解查詢各部分花了多少時間執行。
您可以根據記錄,對工具呼叫相關的複雜執行作業偵錯,瞭解各個程序與回覆延遲之間的關聯。
返回視窗的對話討論部分,再前往右側窗格,點按代理回覆旁的代理圖示 (),即可檢查代理傳回的事件,包括
content (傳回給使用者的內容) 以及 groundingMetadata (回覆所依據的搜尋結果詳細資訊)。
探索完 ADK 開發 UI 後,關閉這個瀏覽器分頁。
返回 Cloud Shell 終端機的瀏覽器分頁,點按終端機窗格。
按下 CTRL+C 鍵,停止網路伺服器。
點選「Check my progress」,確認目標已達成。
雖然 ADK 開發 UI 適合用來測試及偵錯,但在正式環境中,最好不要向多名使用者顯示您的代理。
如要在大型應用程式中執行代理,則必須在 agent.py 指令碼加入一些額外元件。在上一項工作中,這些元件是由網頁應用程式處理。請按照下列步驟,開啟並檢查含有這些元件的指令碼。
如果代理目錄中沒有 .env 檔案,即可為所有代理設定環境變數。在 Cloud Shell 終端機執行下列指令,匯出環境變數:
在 Cloud Shell 編輯器檔案瀏覽器中,點按「adk_project/app_agent」。
點按這個目錄中的「agent.py」檔案。
這個代理的用途是做為應用程式的一部分來執行,因此請詳閱 agent.py 的程式碼註解,並特別留意程式碼中的下列元件:
InMemoryRunner() (約第 68 行):可監督代理執行功能。Runner 程式碼會負責接收使用者查詢,並傳送給合適的代理,然後接收代理回覆事件、傳回呼叫應用程式或 UI,觸發後續事件。詳情請參閱 ADK 事件迴圈說明文件。runner.session_service.create_session() (約第 71 行):可查看對話歷史記錄和共用狀態。Session 元件可讓代理保留狀態,記住項目清單、工作目前的狀態或其他現有資訊。為簡單起見,本實驗室選擇建立本機工作階段服務,但在正式環境中,這項服務可由資料庫處理。types.Content() 和 types.Part() (約第 78 和 79 行):結構化多模態訊息功能。系統不會向代理傳遞簡單的字串,而是傳遞 Content 物件,其中可能包含多個 Part。如此一來,您就可以用特定順序,將包括文字和多模態內容的複雜訊息傳遞給代理。您會發現指令碼包含一個給代理的硬式編碼查詢 (約第 93 行),內容為「法國的首都在哪裡?」。
在 Cloud Shell 終端機執行下列指令,透過程式執行這個代理:
輸出內容節錄:
您也可以為代理指定特定的輸入和/或輸出內容結構定義,如下所示:
在第 28 行附近,為 Pydantic 結構定義類別「BaseModel」和「Field」新增下列匯入陳述式,藉此指定結構定義類別:
在 root_agent 的 Agent 定義中 (約第 62 行),設定 output_schema 參數,以便使用您在上方程式碼中指定的 CountryCapital 結構定義。
再次執行代理指令碼,查看 output_schema 後的回覆:
輸出內容節錄:
點選「Check my progress」,確認目標已達成。
您還可以在本機開發環境中,使用指令列介面與代理對話。開發代理時,這項功能可幫助您快速偵錯及測試。
與網頁介面相同,指令列介面也會建立代理的工作階段服務、構件服務和執行元件。
請按照下列步驟,使用指令列介面執行互動工作階段:
在 Cloud Shell 終端機執行下列指令:
輸出內容:
輸入下列訊息:
輸出內容範例 (可能會與您的輸出內容略有不同):
在指令列介面與代理對話完畢時,於後續的使用者提示詞輸入「exit」,即可結束對話。
在這項工作中,您將探索多代理系統,瞭解核心 ADK 功能。
這個代理系統會評估 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。使用 prompt.py 單獨管理複雜提示詞,再匯入 agent.py。複製您稍早建立的 .env 檔案,供這個代理使用,並在 Cloud Shell 終端機執行下列指令,再次啟動 ADK 開發 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 提出其他事實查核範例問題。例如,您可以嘗試再提出以下問題:
如要重設對話,請點按工作階段標題列的「新增工作階段」,即可重新啟動對話。
向這個代理提問完畢後,請關閉瀏覽器分頁,並在終端機中按下 CTRL + C 鍵停止伺服器。
注意:雖然這個範例使用 SequentialAgent 工作流程代理,但可以視為人機迴圈模式。
當 SequentialAgent 結束序列時,對話會返回上層代理 (在本例中為 llm_auditor),取得新的使用者輸入內容,再將對話傳回其他代理。
點選「Check my progress」,確認目標已達成。
您已順利完成 Agent Development Kit (ADK) 的基礎實驗室,除了分析代理和工具的核心架構、初始化標準化開發環境,還將
如要進一步瞭解 ADK,請參閱以下資源:
adk-docs 的 GitHub 存放區:adk-docs
協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法,讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程,並有隨選、線上和虛擬課程等選項,方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。
使用手冊上次更新日期:2026 年 4 月 15 日
實驗室上次測試日期:2026 年 4 月 15 日
Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標,其他公司和產品名稱則有可能是其關聯公司的商標。
This content is not currently available
We will notify you via email when it becomes available
Great!
We will contact you via email if it becomes available
One lab at a time
Confirm to end all existing labs and start this one
Complete this quick step to start your lab.