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
Enable the APIs
/ 10
Deploy the Agent
/ 90
在本實驗室中,您將著重學習使用 Agent Development Kit (ADK) 實作及部署用戶端代理服務,建構可串連遠端工具 (如 MCP 伺服器) 的 AI 代理。本實驗室展示「關注點分離」這項關鍵架構原則,也就是讓獨立的推理層 (代理) 和工具層 (MCP 伺服器),透過安全的 API 互相通訊。
本實驗室已預先部署 MCP 伺服器,為大型語言模型 (可透過 Gemini CLI 互動) 提供虛構動物園的動物資料。在本實驗室中,您將為虛構動物園建構以 Python 應用程式為基礎的導覽員代理。這個代理會透過 MCP 伺服器存取園內動物的詳細資料,並運用維基百科打造最佳導覽體驗。
最後,您會將導覽員代理部署至 Google Cloud Run,讓所有動物園遊客都能使用,而不只是在本機執行。
在本實驗室中,您將瞭解如何執行下列工作:
Cloud Run 是無伺服器平台,非常適合用來託管 ADK 代理。您只需要專心編寫程式碼,不必管理基礎架構,相關作業交由 Cloud Run 代勞即可。
這個平台好比快閃店,只有在顧客 (要求) 到來時才需要營業及使用資源;沒有顧客時,商店會完全關閉,您不需為閒置店面付費。
請詳閱以下操作說明。實驗室活動會計時,且中途無法暫停。點選「Start Lab」後就會開始計時,顯示可使用 Google Cloud 資源的時間。
您將在真正的雲端環境完成實作實驗室活動,而不是模擬或示範環境。為此,我們會提供新的暫時憑證,供您在實驗室活動期間登入及存取 Google Cloud。
為了順利完成這個實驗室,請先確認:
Cloud Shell 是搭載多項開發工具的虛擬機器,提供永久的 5 GB 主目錄,而且在 Google Cloud 中運作。Cloud Shell 提供指令列存取權,方便您使用 Google Cloud 資源。
點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」圖示 。
系統顯示視窗時,請按照下列步驟操作:
連線建立完成即代表已通過驗證,而且專案已設為您的 Project_ID:
gcloud 是 Google Cloud 的指令列工具,已預先安裝於 Cloud Shell,並支援 Tab 鍵自動完成功能。
輸出內容:
輸出內容:
gcloud 的完整說明,請前往 Google Cloud 參閱 gcloud CLI 總覽指南。
在這項工作中,您將啟用相關 API 並建立專案資料夾,用來儲存 Python 專案部署作業的原始碼。
進行本實驗室的後續步驟時,請將這個視窗做為 IDE,搭配上方的 Cloud Shell 編輯器和下方的 Cloud Shell 終端機一起使用。
關閉畫面右側顯示的其他教學課程或 Gemini 面板,為程式碼編輯器騰出更多視窗空間。
在終端機輸入下列指令,設定專案:
預期輸出內容: 終端機應會輸出訊息,確認屬性已更新。
執行下列指令,啟用所有必要服務:
預期輸出內容: 終端機應會輸出訊息,確認作業已順利完成。
點選「Check my progress」,確認目標已達成。
執行下列指令,在實驗室中建立主要資料夾,用來存放代理的原始碼:
接著執行下列指令,建立虛擬環境:
執行下列指令來啟用虛擬環境:
現在,您可以建立
requirements.txt 檔案了,該檔案會列出動物園代理所需的 Python
程式庫。
執行下列指令,在 zoo_guide_agent 目錄中建立檔案,接著在 Cloud Shell 編輯器中啟動檔案,以利編輯:
將下列指令新增至 requirements.txt 檔案,然後按下 Ctrl+S
鍵儲存變更:
在終端機中執行下列指令,要求 uv 套件管理工具安裝 Python
套件:
使用下列指令,為目前的專案、區域和使用者設定變數:
執行下列指令,建立並開啟 .env 檔案,以驗證
zoo_guide_agent 目錄中的代理:
內含 .env 檔案的目錄會在 Cloud Shell 編輯器中開啟。
將下列指令新增至 .env 檔案,然後儲存變更:
在本節中,您將與遠端 MCP 伺服器建立連線。
請返回 Cloud Shell 終端機執行下列指令,授予 Cloud Run 服務身分呼叫遠端 MCP 伺服器的權限:
執行下列指令,將 MCP 伺服器網址儲存至環境變數:
接著建立 __init__.py 檔案,用來告訴 Python
zoo_guide_agent 目錄是套件:
在開啟的 Cloud Shell 編輯器中,將下列程式碼加到
__init__.py 並儲存變更:
在這項工作中,您將設定動物園導覽員代理的工作流程。首先,您需要匯入相關程式庫以進行初始設定。接著,您會定義動物園代理的功能 (要使用的工具) 和專用代理,然後定義工作流程代理,最後整合主要工作流程。
agent.py 檔案
返回 Cloud Shell 終端機並執行下列指令,建立主要的
agent.py 檔案,並在 Cloud Shell
編輯器中開啟該檔案。您會在後續步驟中於該處貼上多代理系統的完整程式碼:
下方程式碼區塊的第一段,會從 ADK 和 Google Cloud
匯入所有必要程式庫、設定記錄功能,以及從
.env 檔案載入環境變數,這些是存取模型和伺服器網址的關鍵。
將以下程式碼新增至 agent.py 檔案:
代理的實用度取決於所使用的工具。在本節中,您將定義代理的所有功能,包括儲存資料的自訂函式、連線至安全 MCP 伺服器的 MCP 工具,以及維基百科工具。
將下列程式碼新增至 agent.py 底部:
add_prompt_to_state:📝
這項工具會記住動物園遊客提出的問題。當遊客詢問「獅子在哪一區?」時,此工具會將問題儲存到代理的記憶體中,這樣工作流程中的其他代理就知道要研究什麼問題。
運作機制:Python 函式會將遊客的提示詞寫入共用的
tool_context.state
字典。這個工具情境可以視為代理在單一對話中的短期記憶。工作流程中的下一個代理,可以讀取前一個代理儲存至狀態的資料。
MCPToolset:🦁
這個工具可以將導覽員代理,連線至本實驗室預先部署的動物園 MCP
伺服器。這個伺服器具備特殊工具,可查詢園內動物的特定資訊,例如名稱、年齡和圈養園區。
運作機制:此工具會以安全的方式連線至動物園的私人伺服器網址,並透過
get_id_token 自動取得安全「金鑰卡」(服務帳戶 ID
權杖),以證明自己的身分並取得存取權。
LangchainTool:🌍
這個導覽員代理具備一般世界知識。當遊客提出動物園資料庫未收錄的問題時,例如「獅子在野外吃什麼?」,這項工具會指示代理前往維基百科搜尋答案。
運作機制:這項工具擔任中介轉換的角色,讓代理使用 LangChain 程式庫中預先建構的 WikipediaQueryRun 工具。
參考資源:
在本節中,您將定義「研究人員」和「回覆生成」這兩個專用代理。「研究人員代理」是這項作業的「大腦」,它會從共用的
State 取得使用者的提示詞、綜覽可運用的強大工具 (動物園的 MCP
伺服器工具和維基百科工具),然後決定要使用哪些工具來搜尋答案。
「回覆生成代理」的角色是呈現資訊。這個代理不會使用任何工具尋找新資訊,而是會擷取「研究人員」代理收集的原始資料 (透過 State 傳遞),並運用大型語言模型的語言組織能力,將資料轉換成親切的對話式回覆。
將下列程式碼新增至 agent.py 底部:
工作流程代理好比動物園導覽員的「後勤」經理,負責接收研究要求,確保您在步驟 3 中定義的兩個代理按正確順序工作:先研究,再生成回覆。這樣一來,回答動物園遊客的問題時,就有一套可預測且可靠的程序能遵循。
運作機制:工作流程代理會使用
SequentialAgent,這是一種不會自行思考的特殊代理。他只負責按照固定順序執行
sub_agents 清單中的子代理
(研究人員和回覆生成),自動將共用記憶體從一個子代理傳遞給下一個。
請將下列程式碼區塊新增至 agent.py 底部:
主要工作流程由 root_agent 指定,ADK
架構會將這個代理做為所有新對話的起點。這個代理的主要任務是協調所有程序,並擔任初始控管者,管理對話的第一輪。
請將最後一段程式碼區塊新增至 agent.py 底部,然後儲存變更:
agent.py 檔案現已建構完成!
透過這種方式建構代理,您將能瞭解每個元件 (工具、作業代理和管理代理) 在打造最終智慧型系統時所扮演的角色。接著是部署時間!
本機環境就緒後,下一步是準備 Google Cloud 專案,以利部署動物園導覽員代理。
您將對代理的檔案結構進行最後一次檢查,確保與部署指令相容。此外,您也會設定必要的 IAM 權限,供已部署的 Cloud Run 服務代替您呼叫 Agent Platform 模型。完成這個步驟即可備妥雲端環境,確保代理順利執行。
請返回 Cloud Shell 終端機執行下列指令,將變數載入殼層工作階段:
執行下列指令,將 Agent Platform 使用者角色授予服務帳戶,以利服務帳戶進行預測及呼叫 Google 的模型:
本機程式碼和 Google Cloud 專案就緒後,就可以部署代理了。
在這項工作中,您會使用
adk deploy cloud_run
指令,輕鬆將整個部署工作流程自動化。這個單一指令會封裝程式碼、建構容器映像檔、將映像檔推送至
Artifact Registry,並在 Cloud Run 上啟動服務,讓使用者透過網路存取。
執行下列指令來部署應用程式:
如果系統詢問是否要繼續操作,以及是否允許未經驗證就叫用
[zoo-tour-guide],請在每次詢問時輸入
Y,然後按下 Enter 鍵。
執行下列指令,修改現有 Cloud Run 服務的設定:
代理成功部署至 Cloud Run 後,請按住 Ctrl 鍵並點按輸出內容中的服務網址,在新瀏覽器分頁開啟。
服務網址輸出內容格式應如下所示:
由於您在部署至 Cloud Run 時使用了 --with_ui 旗標,因此應該會看到
ADK 開發人員 UI。
點選「Check my progress」,確認目標已達成。
現在代理已於 Cloud Run 上線,在這項工作中,您將測試代理是否部署成功且正常運作。您將使用公開服務網址存取 ADK 的網頁介面,並與代理互動。
在網路瀏覽器中,開啟前一個工作輸出內容中的公開 Cloud Run 服務網址,或點按輸出內容中的網址 (應會在新的瀏覽器分頁中開啟)。系統會開啟 ADK 開發人員 UI。
在 ADK 工具列的右上方,將「詞元串流」切換為「開啟」。
現在您可以與動物園導覽員代理互動了。
在提示詞輸入框中輸入 hello,然後按下 Enter
鍵,即可開始新對話。
請查看結果,代理應會迅速回覆標準問候語:
現在,請與動物園導覽員代理互動。輸入下列查詢來展開新對話:
您應該會收到類似以下的回覆:
您的系統就像一個智慧型多代理團隊,會按明確程序執行作業,確保使用者從提出問題到獲得最終詳細解答的過程順暢有效率。
1. 動物園迎賓員 (迎賓櫃台)
整個流程從迎賓代理開始。
用途:展開對話。這個代理會問候使用者,並詢問他們想瞭解哪種動物。
使用的工具:當使用者回覆時,迎賓代理會使用 add_prompt_to_state 工具完整擷取輸入的文字 (例如「介紹一下獅子」),並儲存在系統記憶體中。
轉接:儲存提示詞後,迎賓代理會立即將控制權轉給子代理 tour_guide_workflow。
2. 全方位研究人員 (超級研究人員)
這是主要工作流程的第一步,也是整個作業的「大腦」。您不必仰賴龐大的團隊,只要一個技能高超的代理就能存取所有可用資訊。
用途:分析使用者的問題,並聰明擬定計畫。這個代理會運用強大的語言模型,判斷是否需要:
執行動作:執行必要工具,收集所有需要的原始資料。舉例來說,如果遊客問「園內的獅子幾歲?牠們在野外吃什麼?」,模型會呼叫 MCP 伺服器取得年齡資訊,並呼叫維基百科工具取得飲食資訊。
3. 回覆生成 (資訊呈現者)
全方位研究人員收集所有事實後,就會交由最後的代理來呈現。
用途:擔任友善的動物園導覽員,將原始資料 (可能來自一個或兩個來源) 整理成實用回覆。
執行動作:將所有資訊統整成單一、連貫且實用的答案。這個代理會按照指示,先提供該動物園的具體資訊,再補充有趣的一般知識。
最終結果:代理會生成完整詳細的文字答案,並顯示在對話視窗中。
請參閱下列資源,進一步瞭解如何建構代理:
在這項工作中,您將刪除於本實驗室建立的 Cloud 資源,以免產生後續費用。
請返回 Cloud Shell 終端機分頁執行下列指令:
在本實驗室中,您學會使用 ADK 指令列介面,建構要部署的 Python 專案、實作多代理工作流程、連線至遠端 MCP 伺服器來取用工具、整合 Wikipedia API 等外部工具以擴充內部資料,以及將代理做為無伺服器容器部署至 Cloud Run。
使用手冊上次更新日期:2025 年 10 月 13 日
實驗室上次測試日期:2025 年 10 月 13 日
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