GENAI107

總覽

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

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

目標

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

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

設定和需求

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

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

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

需求條件

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

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。
• 已預留充足時間可完成實驗室。

注意：如果您擁有個人 Google Cloud 或專案，請勿用於本實驗室。

注意：如果您使用的是 Pixelbook，請在無痕視窗執行本實驗室。

如何開始研究室及登入 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 並設定環境

注意：建議在無痕模式瀏覽器視窗中開啟大多數 Qwiklabs 課程，以免分不清 Qwiklabs 學員帳戶和其他登入 Google Cloud 的帳戶。如果使用 Chrome，可以直接關閉所有無痕視窗，然後在本實驗室頂端的「Open console」按鈕上按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

啟用 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. 在 Cloud Shell 終端機中輸入下列指令，開啟 Cloud Shell 編輯器並前往主目錄：

   cloudshell workspace ~

6. 關閉畫面右側顯示的其他教學課程或 Gemini 面板，為程式碼編輯器提供更多視窗空間。
7. 在本實驗室的其餘環節，您可以將這個視窗當成 IDE，使用 Cloud Shell 編輯器和 Cloud Shell 終端機來操作。

下載並安裝本實驗室所需的 ADK 和程式碼範例

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

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk

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

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

3. 使用下列指令安裝其他實驗室需求：

   python3 -m pip install -r adk_to_agent_engine/requirements.txt

4. 執行下列指令，在 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={{{project_0.default_region| GCP_LOCATION}}} MODEL=gemini-2.5-flash EOF

5. 將 .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[adk,agent_engines]==1.110.0

6. 儲存檔案。

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

   adk deploy agent_engine transcript_summarization_agent \ --display_name "Transcript Summarizer" \ --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. 如要查看服務代理及其獲派的角色，請前往控制台的「身分與存取權管理：IAM」。

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. 在「區域」下拉式選單中，確認已選取本實驗室指定的位置 ()。

3. 畫面上會顯示已部署代理的顯示名稱。按一下即可進入監控資訊主頁。

4. 請注意「指標」和「工作階段」，這兩個分頁可幫助您深入瞭解代理使用情況。

5. 準備好刪除代理時，請從監控資訊主頁頂端選取「部署項目詳細資料」。

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

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

7. 從 Agent Engine 的「Deployment info」面板中，複製「名稱」欄位，格式如下：projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504。

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

9. 按下「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

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

11. 如要查看列出及刪除代理的簡易 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 技術方面的技能和專業知識。

使用手冊上次更新日期：2025 年 8 月 19 日

實驗室上次測試日期：2025 年 8 月 19 日

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