GENAI107

總覽

在本實驗室中，您將學習如何將 ADK 代理部署至 Agent Engine，為代理式工作流程建立可擴充的全代管環境。

如此一來，您就能專注於代理的邏輯，將基礎架構的分配和擴充作業交給系統自動完成。

目標

本實驗室的學習內容包括：

• 將代理部署至 Agent Engine 的優點
• 如何將必要角色授予 Reasoning Engine 服務代理
• 如何使用 ADK 指令列介面將代理部署至 Agent Engine
• 如何向部署至 Agent Engine 的代理提出查詢
• 如何監控部署的代理
• 如何刪除代理

設定和需求

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

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

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

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

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

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

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

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

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

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

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

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

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

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

Agent Engine

Vertex AI Agent Engine 過去稱為 LangChain on Vertex AI 或 Vertex AI Reasoning Engine，是 Google Cloud 全代管的服務，開發人員能利用這項服務在正式環境中部署、管理及擴大使用 AI 代理。

如要進一步瞭解這項服務的優點，請參閱 Vertex AI Agent Engine 說明文件。

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

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

啟用 Vertex AI 建議的 API

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

準備 Cloud Shell 編輯器分頁

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

下載並安裝這個實驗室要使用的 ADK 和程式碼範例

1. 將下列指令貼入 Cloud Shell 終端機，從 Cloud Storage bucket 複製檔案並解壓縮，建立這個實驗室的程式碼專案目錄：

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_to_agent_engine .

2. 在 Cloud Shell 終端機執行下列指令，更新 PATH 環境變數並安裝 ADK。

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_to_agent_engine/requirements.txt

3. 執行下列指令，在 adk_to_agent_engine 目錄建立 .env 檔案。請注意，如要查看開頭為半形句號的隱藏檔案，可以在 Cloud Shell 編輯器選單依序點選「View」>「Toggle Hidden Files」來啟用這項功能：

   cd ~/adk_to_agent_engine cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=us-central1 MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

4. 將 .env 檔案複製到代理目錄，讓代理在部署完畢後取得必要的驗證設定：

   cp .env transcript_summarization_agent/.env

工作 2：使用指令列 deploy 方法部署至 Agent Engine

ADK 的指令列介面提供捷徑，方便將代理部署至 Agent Engine、Cloud Run 和 Google Kubernetes Engine (GKE)。使用下列基本指令，即可部署至上述服務：

• adk deploy agent_engine (指令列引數說明請參閱 @deploy.command("agent_engine") 裝飾器部分)
• adk deploy cloud_run (指令列引數說明請參閱 @deploy.command("cloud_run") 裝飾器部分)
• adk deploy gke (指令列引數說明請參閱 @deploy.command("gke") 裝飾器部分)

adk deploy agent_engine 指令會將代理包裝在 reasoning_engines.AdkApp 類別中，並將這個應用程式部署至 Agent Engine 的代管執行階段，準備接收代理查詢。

AdkApp 部署至 Agent Engine 時，會自動使用 VertexAiSessionService 管理工作階段，並確保工作階段資料持續存在，無須額外設定，就能享有多輪對話記憶。進行本機測試時，應用程式預設會使用暫時的 InMemorySessionService。

如要使用 adk deploy agent_engine 部署 Agent Engine 應用程式，請完成下列步驟：

1. 在 adk_to_agent_engine/transcript_summarization_agent 目錄中，按一下 agent.py 檔案，查看這個簡單摘要代理的操作說明。

2. 如要部署代理，必須提供相關需求。在 Cloud Shell 編輯器中，在 transcript_summarization_agent 目錄上按一下滑鼠右鍵 (您可能需要按一下「允許」，才能啟用右鍵選單)。

3. 選取「New File...」。

4. 依照 Python 需求檔標準命名檔案，例如 requirements.txt。

5. 將下列內容貼入檔案：

   google-cloud-aiplatform[agent_engines,adk]>=1.112

6. 儲存檔案。

7. 在 Cloud Shell 終端機執行部署指令：

   adk deploy agent_engine transcript_summarization_agent \ --display_name "Transcript Summarizer" \ --region us-central1 \ --staging_bucket gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket

   您可以從指令的輸出內容連結至記錄檔，藉此追蹤狀態。部署期間執行的步驟如下：

   1. 系統會在本機產生一組構件，當中含有：
      • *.pkl：對應 local_agent 的 pickle 檔案。
      • requirements.txt：這是代理資料夾內的檔案，用於定義套件需求。
      • dependencies.tar.gz：包含額外套件的 tar 檔案。
   2. 為了暫存構件，這個檔案包會上傳至 Cloud Storage (如果已指定，便會使用定義的目錄)。
   3. 各個構件的 Cloud Storage URI 會在 PackageSpec 中指定。
   4. Vertex AI Agent Engine 服務會接收要求、建構容器，並在後端啟動 HTTP 伺服器。

   注意：部署作業約需 10 分鐘，但您可以在部署期間繼續本實驗室的課程。

   在代理部署期間測驗一下

   每個 adk deploy ... 指令都需要設定特定引數。如要查看最新引數，請按一下這項工作頂端清單中連結的指令，然後尋找標示為「必要」的引數。

   --project 和 --region 等部分必要引數來自 adk deploy agent_engine 部署流程，如果代理的 .env 檔案存在，可從該檔案載入值。

   根據 adk deploy agent_engine 的引數，回答下列問題：

   預期輸出內容重點摘要：

   正在複製代理原始碼... 代理原始碼複製完畢。 正在啟動 Vertex AI... [...] 正在建立 AgentEngine 建立 AgentEngine 備份 LRO：projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480/operations/2777364189918789632 查看進度和記錄：https://console.cloud.google.com/logs/query?project=qwiklabs-gcp-04-f71a2270bd79 AgentEngine 已建立。資源名稱：projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480 在另一個工作階段使用這個 AgentEngine： agent_engine = vertexai.agent_engines.get('projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480') 正在清理暫存資料夾：/tmp/agent_engine_deploy_src/20250813_175223

點選「Check my progress」，確認目標已達成。 部署代理。

工作 3：取得部署至 Agent Engine 的代理並提出查詢

如要向代理提出查詢，需要先授權代理透過 Vertex AI 呼叫模型。

1. 如要查看服務代理及其獲派的角色，請前往控制台的「身分與存取權管理」。

2. 勾選「Include Google-provided role grants」核取方塊。

3. 找到 AI 平台 Reasoning Engine 服務代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com)，然後點選這個服務代理列中的編輯鉛筆圖示。

4. 點選「+ 新增其他角色」。

5. 在「選取角色」欄位中，輸入「Vertex AI 使用者」。如果部署的代理會使用工具存取其他資料，您也必須授權此服務代理存取這些系統。

6. 點選「儲存」儲存變更。

7. 返回 Cloud Shell 編輯器，在 adk_to_agent_engine 目錄中開啟 query_agent_engine.py 檔案。

8. 查看程式碼和註解，瞭解程式碼的作用。

9. 查看傳送給代理的文字記錄，評估生成的摘要是否適當。

10. 在 Cloud Shell 終端機中，從 adk_to_agent_engine 目錄執行檔案，使用的指令如下：

    cd ~/adk_to_agent_engine/transcript_summarization_agent python3 query_agent_engine.py

    輸出內容範例 (您看到的結果可能略有差異)：

    [遠端回覆] 使用者想買一艘船，在被問及船隻大小後，詢問 $50,000 美元能買到多大的船。虛擬代理回答 $50,000 美元可以買到「非常棒的船」，於是使用者同意繼續操作。

點選「Check my progress」，確認目標已達成。 向代理提出查詢。

工作 4：查看及刪除部署至 Agent Engine 的代理

1. 代理部署完畢之後，請返回開啟 Cloud 控制台的瀏覽器分頁，然後在控制台頂端搜尋並選取「Agent Engine」，前往該頁面。

2. 在「區域」下拉式選單，確認已選取區域「us-central1」。

3. 您會看見已部署代理的顯示名稱，點選即可進入監控資訊主頁。

4. 請留意「執行階段指標」、「追蹤記錄」和「工作階段」的分頁，內含代理使用情形的洞察資料。

5. 請留意「Playground」，您可以在這裡與已部署的代理對話。

6. 準備好刪除代理時，請在 Agent Engine 控制台頂端選取「服務設定」，然後選取「詳細部署資料」分頁標籤。

7. 返回執行 Cloud Shell 終端機的瀏覽器分頁，貼上下列指令，「但先不要執行」：

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

8. 從 Agent Engine 的「詳細部署資料」面板中，複製「資源名稱」欄位，格式如下：projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504。

9. 返回 Cloud Shell 終端機，將指令結尾的 REPLACE_WITH_AE_ID 替換為您複製的資源名稱。

10. 按下「Return」執行刪除指令。

    輸出內容範例：

    正在刪除 AgentEngine 資源：projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696 刪除 AgentEngine 備份 LRO：projects/1029886909158/locations/us-central1/operations/2884525977596067840 AgentEngine 資源已刪除：projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696

11. 返回 Cloud 控制台的「Agent Engine」資訊主頁，確認代理已刪除。

12. 如要查看列出及刪除代理的簡易 Python SDK 程式碼，請參閱 adk_to_agent_engine/agent_engine_utils.py 檔案內容。

點選「Check my progress」，確認目標已達成。 列出及刪除代理。

恭喜！

您已在本實驗室中瞭解：

• 將代理部署至 Agent Engine 的優點
• 如何將必要角色授予 Reasoning Engine 服務代理
• 如何使用 ADK 指令列介面將代理部署至 Agent Engine
• 如何向部署至 Agent Engine 的代理提出查詢
• 如何監控部署的代理
• 如何刪除代理

後續步驟

如要進一步瞭解如何使用 Agent Development Kit 建構代理，可以前往本系列的其他實驗室學習：

• 為 ADK 代理提供工具
• 使用 ADK 建構多代理系統
• 將 ADK 代理部署至 Agent Engine

Google Cloud 教育訓練與認證

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

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

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

Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。