GSP1350

總覽
在本實驗室中,您將著重學習使用 Agent Development Kit (ADK) 實作及部署用戶端代理服務,建構可串連遠端工具 (如 MCP 伺服器) 的 AI 代理。本實驗室展示「關注點分離」這項關鍵架構原則,也就是讓獨立的推理層 (代理) 和工具層 (MCP 伺服器),透過安全的 API 互相通訊。
本實驗室已預先部署 MCP 伺服器,為大型語言模型 (可透過 Gemini CLI 互動) 提供虛構動物園的動物資料。在本實驗室中,您將為虛構動物園建構以 Python 應用程式為基礎的導覽員代理。這個代理會透過 MCP 伺服器存取園內動物的詳細資料,並運用維基百科打造最佳導覽體驗。
最後,您會將導覽員代理部署至 Google Cloud Run,讓所有動物園遊客都能使用,而不只是在本機執行。
必要條件
- 運行在 Cloud Run 的 MCP 伺服器,或與伺服器相關聯的服務網址。
- 已啟用計費功能的 Google Cloud 專案。
課程內容
在本實驗室中,您將瞭解如何執行下列工作:
- 建構 Python 專案,以利部署 ADK。
- 使用 google-adk 導入會使用工具的代理。
- 將代理連線至遠端 MCP 伺服器,以取用工具組。
- 將 Python 應用程式以無伺服器容器的形式部署至 Cloud Run。
- 使用 IAM 角色設定安全的服務對服務驗證。
- 刪除 Cloud 資源,避免產生後續費用。
事前準備
- Google Cloud 帳戶和 Google Cloud 專案
- 網路瀏覽器,例如 Chrome
部署至 Cloud Run 的理由
Cloud Run 是無伺服器平台,非常適合用來託管 ADK 代理。您只需要專心編寫程式碼,不必管理基礎架構,相關作業交由 Cloud Run 代勞即可。
這個平台好比快閃店,只有在顧客 (要求) 到來時才需要營業及使用資源;沒有顧客時,商店會完全關閉,您不需為閒置店面付費。
Cloud Run 的主要特色
可隨處執行容器
- 您只要準備內含應用程式的容器 (Docker 映像檔)。
- Cloud Run 會在 Google 基礎架構上執行容器。
- 不必修補作業系統、設定虛擬機器或煩惱資源調度事宜。
自動調整資源配置
- 當應用程式無人使用時,所有執行個體都不會運行 (閒置時不需付費)。
- 如果收到 1,000 個要求,系統會視需要啟動足量的執行個體。
預設為無狀態
- 每項要求都能傳送至不同的執行個體。
- 如需儲存狀態,請使用 Cloud SQL、Firestore 或 Redis 等獨立於應用程式的服務。
支援任何語言或架構
- 無論應用程式是以 Python、Go、Node.js、Java 或 .Net 編寫,只要能在 Linux 容器中執行,Cloud Run 就都支援。
用多少付多少
- 按要求次數 + 運算時間 (可精確至 100 毫秒) 計費。
- 不必像使用傳統 VM 一樣為閒置資源付費。
設定和需求
瞭解以下事項後,再點選「Start Lab」按鈕
請詳閱以下操作說明。實驗室活動會計時,且中途無法暫停。點選「Start Lab」後就會開始計時,顯示可使用 Google Cloud 資源的時間。
您將在真正的雲端環境完成實作實驗室活動,而不是模擬或示範環境。為此,我們會提供新的暫時憑證,供您在實驗室活動期間登入及存取 Google Cloud。
為了順利完成這個實驗室,請先確認:
- 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。
注意事項:請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室,這可以防止個人帳戶和學員帳戶之間的衝突,避免個人帳戶產生額外費用。
- 是時候完成實驗室活動了!別忘了,活動一旦開始將無法暫停。
注意事項:務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶,可能會產生額外費用。
啟動 Cloud Shell
Cloud Shell 是搭載多項開發工具的虛擬機器,提供永久的 5 GB 主目錄,而且在 Google Cloud 中運作。Cloud Shell 提供指令列存取權,方便您使用 Google Cloud 資源。
-
點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」圖示
。
-
系統顯示視窗時,請按照下列步驟操作:
- 繼續操作 Cloud Shell 視窗。
- 授權 Cloud Shell 使用您的憑證發出 Google Cloud API 呼叫。
連線建立完成即代表已通過驗證,而且專案已設為您的 Project_ID:。輸出內容中有一行文字,宣告本工作階段的 Project_ID:
Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}
gcloud 是 Google Cloud 的指令列工具,已預先安裝於 Cloud Shell,並支援 Tab 鍵自動完成功能。
- (選用) 您可以執行下列指令來列出使用中的帳戶:
gcloud auth list
- 點按「授權」。
輸出內容:
ACTIVE: *
ACCOUNT: {{{user_0.username | "ACCOUNT"}}}
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- (選用) 您可以使用下列指令來列出專案 ID:
gcloud config list project
輸出內容:
[core]
project = {{{project_0.project_id | "PROJECT_ID"}}}
注意:如需 gcloud 的完整說明,請前往 Google Cloud 參閱 gcloud CLI 總覽指南。
工作 1:下載並安裝 ADK,然後建立專案資料夾
在這項工作中,您將啟用相關 API 並建立專案資料夾,用來儲存 Python 專案部署作業的原始碼。
啟用 API 並設定環境變數
- 在 Cloud Shell 中點按「開啟編輯器」,開啟 Cloud Shell 編輯器並前往主目錄。
- 在 Cloud Shell 編輯器的動作列中,依序點按「View」>「終端機」。
注意:您可能需要拉寬瀏覽器視窗,才能看到「View」選單選項。
進行本實驗室的後續步驟時,請將這個視窗做為 IDE,搭配上方的 Cloud Shell 編輯器和下方的 Cloud Shell 終端機一起使用。
關閉畫面右側顯示的其他教學課程或 Gemini 面板,為程式碼編輯器騰出更多視窗空間。
-
在終端機輸入下列指令,設定專案:
gcloud config set project {{{project_0.project_id | filled in at lab start}}}
預期輸出內容:
終端機應會輸出訊息,確認屬性已更新。
注意:如果 Cloud Shell 逾時或重新啟動,請重新設定專案。
-
執行下列指令,啟用所有必要服務:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com \
compute.googleapis.com
預期輸出內容:
終端機應會輸出訊息,確認作業已順利完成。
點選「Check my progress」,確認目標已達成。
啟用 API
建立專案目錄
-
執行下列指令,在實驗室中建立主要資料夾,用來存放代理的原始碼:
mkdir zoo_guide_agent && cd zoo_guide_agent
-
接著執行下列指令,建立虛擬環境:
uv venv
-
執行下列指令來啟用虛擬環境:
source .venv/bin/activate
現在,您可以建立 requirements.txt 檔案了,該檔案會列出動物園代理所需的 Python 程式庫。
-
執行下列指令,在 zoo_guide_agent 目錄中建立檔案,接著在 Cloud Shell 編輯器中啟動檔案,以利編輯:
cloudshell edit requirements.txt
-
將下列指令新增至 requirements.txt 檔案,然後按下 Ctrl+S 鍵儲存變更:
google-adk==1.12.0
langchain-community
wikipedia
-
在終端機中執行下列指令,要求 uv 套件管理工具安裝 Python 套件:
uv pip install -r requirements.txt
-
使用下列指令,為目前的專案、區域和使用者設定變數:
export PROJECT_ID=$(gcloud config get-value project)
export REGION=$(gcloud compute project-info describe \
--format="value(commonInstanceMetadata.items[google-compute-default-region])")
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
注意:如果 Cloud Shell 逾時或重新啟動,請重新初始化上述變數。
-
執行下列指令,建立並開啟 .env 檔案,以驗證 zoo_guide_agent 目錄中的代理:
cloudshell edit .env
內含 .env 檔案的目錄會在 Cloud Shell 編輯器中開啟。
-
將下列指令新增至 .env 檔案,然後儲存變更:
MODEL="{{{ project_0.startup_script.gemini_flash_model_id | filled in at lab start }}}"
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
連線至安全的 MCP 伺服器端點
在本節中,您將與遠端 MCP 伺服器建立連線。
-
請返回 Cloud Shell 終端機執行下列指令,授予 Cloud Run 服務身分呼叫遠端 MCP 伺服器的權限:
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT" \
--role="roles/run.invoker"
-
執行下列指令,將 MCP 伺服器網址儲存至環境變數:
echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.${REGION}.run.app/mcp/" >> .env
-
接著建立 __init__.py 檔案,用來告訴 Python zoo_guide_agent 目錄是套件:
cloudshell edit __init__.py
-
在開啟的 Cloud Shell 編輯器中,將下列程式碼加到 __init__.py 並儲存變更:
from . import agent
工作 2:建立代理工作流程
在這項工作中,您將設定動物園導覽員代理的工作流程。首先,您需要匯入相關程式庫以進行初始設定。接著,您會定義動物園代理的功能 (要使用的工具) 和專用代理,然後定義工作流程代理,最後整合主要工作流程。
建立主要的 agent.py 檔案
步驟 1:匯入程式庫並執行初始設定
下方程式碼區塊的第一段,會從 ADK 和 Google Cloud 匯入所有必要程式庫、設定記錄功能,以及從 .env 檔案載入環境變數,這些是存取模型和伺服器網址的關鍵。
-
將以下程式碼新增至 agent.py 檔案:
import os
import logging
import google.cloud.logging
from dotenv import load_dotenv
from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper
import google.auth
import google.auth.transport.requests
import google.oauth2.id_token
# --- 設定 Cloud Logging 和環境 ---
cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()
load_dotenv()
model_name = os.getenv("MODEL")
步驟 2:定義工具 (代理的功能)
代理的實用度取決於所使用的工具。在本節中,您將定義代理的所有功能,包括儲存資料的自訂函式、連線至安全 MCP 伺服器的 MCP 工具,以及維基百科工具。
-
將下列程式碼新增至 agent.py 底部:
# 歡迎使用者並儲存他們輸入的提示詞
def add_prompt_to_state(
tool_context: ToolContext, prompt: str
) -> dict[str, str]:
"""Saves the user's initial prompt to the state."""
tool_context.state["PROMPT"] = prompt
logging.info(f"[State updated] Added to PROMPT: {prompt}")
return {"status": "success"}
# 設定 MCP 工具以連線至動物園 MCP 伺服器
mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
raise ValueError("The environment variable MCP_SERVER_URL is not set.")
def get_id_token():
"""Get an ID token to authenticate with the MCP server."""
target_url = os.getenv("MCP_SERVER_URL")
audience = target_url.split('/mcp/')[0]
request = google.auth.transport.requests.Request()
id_token = google.oauth2.id_token.fetch_id_token(request, audience)
return id_token
"""
# 如果您使用公開 MCP 伺服器,請改用這段程式碼,並將下方定義 mcp_tools 的程式碼設為註解,加以排除
mcp_tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=mcp_server_url
)
)
"""
mcp_tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=mcp_server_url,
headers={
"Authorization": f"Bearer {get_id_token()}",
},
),
)
# 設定維基百科工具
wikipedia_tool = LangchainTool(
tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
三種工具說明
-
add_prompt_to_state:📝 這項工具會記住動物園遊客提出的問題。當遊客詢問「獅子在哪一區?」時,此工具會將問題儲存到代理的記憶體中,這樣工作流程中的其他代理就知道要研究什麼問題。
運作機制:Python 函式會將遊客的提示詞寫入共用的 tool_context.state 字典。這個工具情境可以視為代理在單一對話中的短期記憶。工作流程中的下一個代理,可以讀取前一個代理儲存至狀態的資料。
-
MCPToolset:🦁 這個工具可以將導覽員代理,連線至本實驗室預先部署的動物園 MCP 伺服器。這個伺服器具備特殊工具,可查詢園內動物的特定資訊,例如名稱、年齡和圈養園區。
運作機制:此工具會以安全的方式連線至動物園的私人伺服器網址,並透過 get_id_token 自動取得安全「金鑰卡」(服務帳戶 ID 權杖),以證明自己的身分並取得存取權。
-
LangchainTool:🌍 這個導覽員代理具備一般世界知識。當遊客提出動物園資料庫未收錄的問題時,例如「獅子在野外吃什麼?」,這項工具會指示代理前往維基百科搜尋答案。
運作機制:這項工具擔任中介轉換的角色,讓代理使用 LangChain 程式庫中預先建構的 WikipediaQueryRun 工具。
參考資源:
步驟 3:定義專用代理
在本節中,您將定義「研究人員」和「回覆生成」這兩個專用代理。「研究人員代理」是這項作業的「大腦」,它會從共用的 State 取得使用者的提示詞、綜覽可運用的強大工具 (動物園的 MCP 伺服器工具和維基百科工具),然後決定要使用哪些工具來搜尋答案。
「回覆生成代理」的角色是呈現資訊。這個代理不會使用任何工具尋找新資訊,而是會擷取「研究人員」代理收集的原始資料 (透過 State 傳遞),並運用大型語言模型的語言組織能力,將資料轉換成親切的對話式回覆。
-
將下列程式碼新增至 agent.py 底部:
# 1. 研究人員代理
comprehensive_researcher = Agent(
name="comprehensive_researcher",
model=model_name,
description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
instruction="""
You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
You have access to two tools:
1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).
First, analyze the user's PROMPT.
- If the prompt can be answered by only one tool, use that tool.
- If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
you MUST use both tools to gather all necessary information.
- Synthesize the results from the tool(s) you use into preliminary data outputs.
PROMPT:
{{ PROMPT }}
""",
tools=[
mcp_tools,
wikipedia_tool
],
output_key="research_data" # 用來儲存整合後資訊的金鑰
)
# 2. 回覆生成代理
response_formatter = Agent(
name="response_formatter",
model=model_name,
description="Synthesizes all information into a friendly, readable response.",
instruction="""
You are the friendly voice of the Zoo Tour Guide. Your task is to take the
RESEARCH_DATA and present it to the user in a complete and helpful answer.
- First, present the specific information from the zoo (like names, ages, and where to find them).
- Then, add the interesting general facts from the research.
- If some information is missing, just present the information you have.
- Be conversational and engaging.
RESEARCH_DATA:
{{ research_data }}
"""
)
步驟 4:定義工作流程代理
工作流程代理好比動物園導覽員的「後勤」經理,負責接收研究要求,確保您在步驟 3 中定義的兩個代理按正確順序工作:先研究,再生成回覆。這樣一來,回答動物園遊客的問題時,就有一套可預測且可靠的程序能遵循。
運作機制:工作流程代理會使用 SequentialAgent,這是一種不會自行思考的特殊代理。他只負責按照固定順序執行 sub_agents 清單中的子代理 (研究人員和回覆生成),自動將共用記憶體從一個子代理傳遞給下一個。
步驟 5:整合主要工作流程
主要工作流程由 root_agent 指定,ADK 架構會將這個代理做為所有新對話的起點。這個代理的主要任務是協調所有程序,並擔任初始控管者,管理對話的第一輪。
agent.py 檔案現已建構完成!
透過這種方式建構代理,您將能瞭解每個元件 (工具、作業代理和管理代理) 在打造最終智慧型系統時所扮演的角色。接著是部署時間!
工作 3:準備部署要用的應用程式
本機環境就緒後,下一步是準備 Google Cloud 專案,以利部署動物園導覽員代理。
您將對代理的檔案結構進行最後一次檢查,確保與部署指令相容。此外,您也會設定必要的 IAM 權限,供已部署的 Cloud Run 服務代替您呼叫 Vertex AI 模型。完成這個步驟即可備妥雲端環境,確保代理順利執行。
-
請返回 Cloud Shell 終端機執行下列指令,將變數載入殼層工作階段:
source .env
-
執行下列指令,將 Vertex AI 使用者角色授予服務帳戶,以利服務帳戶進行預測及呼叫 Google 的模型:
# 將「Vertex AI 使用者」角色授予服務帳戶
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT" \
--role="roles/aiplatform.user"
工作 4:使用 ADK CLI 部署代理
本機程式碼和 Google Cloud 專案就緒後,就可以部署代理了。
在這項工作中,您會使用 adk deploy cloud_run 指令,輕鬆將整個部署工作流程自動化。這個單一指令會封裝程式碼、建構容器映像檔、將映像檔推送至 Artifact Registry,並在 Cloud Run 上啟動服務,讓使用者透過網路存取。
部署代理
-
執行下列指令來部署應用程式:
# 執行部署指令
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=$REGION \
--service_name=zoo-tour-guide \
--with_ui \
.
-
如果系統詢問是否要繼續操作,以及是否允許未經驗證就叫用 [zoo-tour-guide],請在每次詢問時輸入 Y,然後按下 Enter 鍵。
注意:這個部署指令可能需要 5 到 10 分鐘才會執行完畢。
-
執行下列指令,修改現有 Cloud Run 服務的設定:
gcloud run services update zoo-tour-guide \
--region=$REGION \
--update-labels=dev-tutorial=codelab-adk
取得部署作業連結
由於您在部署至 Cloud Run 時使用了 --with_ui 旗標,因此應該會看到 ADK 開發人員 UI。
注意:任何知道網址的人都能存取這個代理,因此請只在測試時使用此方法。
點選「Check my progress」,確認目標已達成。
部署代理
工作 5:測試已部署的代理
現在代理已於 Cloud Run 上線,在這項工作中,您將測試代理是否部署成功且正常運作。您將使用公開服務網址存取 ADK 的網頁介面,並與代理互動。
-
在網路瀏覽器中,開啟前一個工作輸出內容中的公開 Cloud Run 服務網址,或點按輸出內容中的網址 (應會在新的瀏覽器分頁中開啟)。系統會開啟 ADK 開發人員 UI。
-
在 ADK 工具列的右上方,將「詞元串流」切換為「開啟」。
現在您可以與動物園導覽員代理互動了。
-
在提示詞輸入框中輸入 hello,然後按下 Enter 鍵,即可開始新對話。
請查看結果,代理應會迅速回覆標準問候語:
「您好!我是動物園導覽員。我可以帶您認識園內的奇妙動物,今天想認識或探索什麼呢?」
-
現在,請與動物園導覽員代理互動。輸入下列查詢來展開新對話:
企鵝在哪一區?
您應該會收到類似以下的回覆:

代理流程說明
您的系統就像一個智慧型多代理團隊,會按明確程序執行作業,確保使用者從提出問題到獲得最終詳細解答的過程順暢有效率。
1. 動物園迎賓員 (迎賓櫃台)
整個流程從迎賓代理開始。
用途:展開對話。這個代理會問候使用者,並詢問他們想瞭解哪種動物。
使用的工具:當使用者回覆時,迎賓代理會使用 add_prompt_to_state 工具完整擷取輸入的文字 (例如「介紹一下獅子」),並儲存在系統記憶體中。
轉接:儲存提示詞後,迎賓代理會立即將控制權轉給子代理 tour_guide_workflow。
2. 全方位研究人員 (超級研究人員)
這是主要工作流程的第一步,也是整個作業的「大腦」。您不必仰賴龐大的團隊,只要一個技能高超的代理就能存取所有可用資訊。
用途:分析使用者的問題,並聰明擬定計畫。這個代理會運用強大的語言模型,判斷是否需要:
- 取用動物園記錄的內部資料 (透過 MCP 伺服器)。
- 從網路 (透過 Wikipedia API) 搜尋一般知識。
- 同時運用上述兩個管道,以回答複雜問題。
執行動作:執行必要工具,收集所有需要的原始資料。舉例來說,如果遊客問「園內的獅子幾歲?牠們在野外吃什麼?」,模型會呼叫 MCP 伺服器取得年齡資訊,並呼叫維基百科工具取得飲食資訊。
3. 回覆生成 (資訊呈現者)
全方位研究人員收集所有事實後,就會交由最後的代理來呈現。
用途:擔任友善的動物園導覽員,將原始資料 (可能來自一個或兩個來源) 整理成實用回覆。
執行動作:將所有資訊統整成單一、連貫且實用的答案。這個代理會按照指示,先提供該動物園的具體資訊,再補充有趣的一般知識。
最終結果:代理會生成完整詳細的文字答案,並顯示在對話視窗中。
後續步驟/瞭解詳情
請參閱下列資源,進一步瞭解如何建構代理:
工作 6:清理作業環境
在這項工作中,您將刪除於本實驗室建立的 Cloud 資源,以免產生後續費用。
恭喜!
在本實驗室中,您學會使用 ADK 指令列介面,建構要部署的 Python 專案、實作多代理工作流程、連線至遠端 MCP 伺服器來取用工具、整合 Wikipedia API 等外部工具以擴充內部資料,以及將代理做為無伺服器容器部署至 Cloud Run。
使用手冊上次更新日期:2025 年 10 月 13 日
實驗室上次測試日期:2025 年 10 月 13 日
Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標,其他公司和產品名稱則有可能是其關聯公司的商標。