使用 ADK 建構 AI 代理：基礎知識

1. 事前準備

歡迎來到「使用 ADK 建構 AI 代理」系列的第一部分！在本實作程式碼研究室系列中，您將踏上精彩旅程，使用 Google 的 Agent Development Kit (ADK) 建立專屬的智慧型 AI 代理。

我們會從最基本的概念開始，引導您設定開發環境，並打造基礎的對話式代理程式。完成本程式碼研究室後，您將建構出第一個互動式 AI，並在後續的系列課程中，將其擴展為複雜的多代理程式系統 (MAS)。

您可以在本機環境或 Google Cloud 中完成本程式碼研究室。為獲得最一致的體驗，建議使用 Google Cloud 環境的 Cloud Shell。Cloud Shell 也會在 $HOME 目錄中提供 5 GB 的永久儲存空間。這項功能可儲存指令碼、設定檔或複製的存放區。

必要條件

課程內容

  • 如何設定 Python 環境
  • 如何使用 ADK 建立簡單的個人助理代理
  • 如何執行、測試及偵錯代理程式

軟硬體需求

  • 可正常運作的電腦和穩定的 Wi-Fi
  • 瀏覽器 (例如 Chrome)，用來存取 Google Cloud Console
  • 啟用計費功能的 Google Cloud 專案
  • 好奇心和學習意願

2. 簡介

生成式 AI (GenAI) 領域發展迅速，AI 代理程式目前是熱門話題。AI 代理程式是智慧型電腦程式，可代表您執行動作，就像個人助理一樣。這類模型可以感知數位環境、做出決策，並採取行動來達成特定目標，不需直接的人為控制。這項功能就像是主動自主的實體，能夠學習和適應，以完成工作。

AI 代理會以大型語言模型 (LLM) 做為「大腦」，負責理解和推論。因此可以處理文字、圖片和聲音等多種來源的資訊。然後，代理程式會根據這項理解制定計畫，並執行一連串工作，以達成預先定義的目標。

現在您可以使用 Agent Development Kit (ADK) 等現成架構，輕鬆建構自己的 AI 代理，即使沒有深厚的專業知識也能上手。我們將從建構個人助理代理程式開始，協助您完成工作。我們馬上開始！

3. 設定 Google Cloud 服務

建立 Google Cloud 專案

本程式碼研究室假設您已建立啟用計費功能的 Google Cloud 專案。如果還沒有專案，請按照下列步驟建立專案：

選取或建立 Google Cloud 專案

  • 前往 Google Cloud 控制台。
  • 按一下頂端的專案選取器下拉式選單 (Google Cloud 標誌旁)
  • 選擇現有專案或建立新專案。

啟用計費功能

  • 確認所選 Google Cloud 專案已啟用計費功能。
  • 如要瞭解如何檢查專案是否已啟用帳單功能，請按照 Google Cloud 帳單說明文件中的操作說明進行。

設定 Cloud Shell

現在，請確認您已在 Cloud Shell 中正確設定，這是 Google Cloud 控制台內建的實用指令列介面。

啟動 Cloud Shell

在 Google Cloud 控制台的右上角，您會看到類似終端機的圖示 (>_)。按一下該圖示即可啟用 Cloud Shell。

8e234ad9973e49d4.png

授予存取權

如果系統提示您授權，請按一下「授權」，授予 Cloud Shell 與 Google Cloud 專案互動的必要權限。

d5e271ec814f5769.png

驗證帳戶：

Cloud Shell 載入完成後，請確認您使用的是正確的 Google Cloud 帳戶。執行下列指令：

gcloud auth list

終端機應會顯示類似的指令輸出內容：

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

切換帳戶 (如有必要)：

如果目前使用的帳戶不是您要用於本程式碼實驗室的帳戶，請使用下列指令切換至正確的帳戶，並將 <your_desired_account@example.com> 替換為您要用於本實驗室的實際電子郵件地址：

gcloud config set account <your_desired_account@example.com

確認專案

接著，請確認 Cloud Shell 已設定為使用正確的 Google Cloud 專案。執行作業：

gcloud config list project

畫面上會顯示設定清單。找到 [core] 區段，並確認專案值與您要用於本程式碼研究室的 Google Cloud 專案 ID 相符：

[core]
project = <current-project-id>

設定專案 (如有必要)

如果 project ID 值不正確，請使用下列指令將其設為所需專案：

gcloud config set project <your-desired-project-id>

啟用必要的 API

如要使用 Google Cloud 服務，必須先為專案啟用對應的 API。在 Cloud Shell 終端機中執行下列指令，即可啟用本程式碼研究室所需的所有服務：

gcloud services enable aiplatform.googleapis.com

如果作業成功，終端機就會顯示 Operation/... finished successfully。

4. 建立 Python 虛擬環境

開始任何 Python 專案前，建議您先建立虛擬環境。這樣一來，專案的依附元件就會與其他專案或系統的全域 Python 套件區隔開來，避免發生衝突。由於 Agent Development Kit (ADK) 需要 Python 3.9 以上版本，我們會使用 uv 等工具管理虛擬環境，並確保使用正確的 Python 版本。

uv 是一款新穎、快速且有效率的工具，可管理 Python 專案和環境，並結合傳統工具 (例如 pip、venv、pip-tools 和 pipx) 的功能。這項工具是以 Rust 編寫，因此速度很快。

Cloud Shell 已提供 uv，因此我們可以立即開始。

確認 uv 安裝正確無誤

uv --version

為 AI 代理程式建立新的專案資料夾

uv init ai-agents-adk
cd ai-agents-adk

使用 Python 3.12 建立虛擬環境

uv venv --python 3.12

在虛擬環境中安裝 Google ADK 程式庫

uv add google-adk

確認是否已成功安裝 google-adk 套件

uv pip list | grep google-adk

如果看到包含 google-adk 和其版本的輸出行，即可繼續下一個步驟。

5. 建立代理程式

開發環境設定完成後，就可以開始為 AI 代理程式奠定基礎。Agent Development Kit (ADK) 可簡化這個程序，您只需幾個必要檔案，即可定義代理程式的核心邏輯和設定。

這三個檔案會共同運作，讓代理程式可供探索、執行及設定：

  • agent.py：這是代理程式的核心。其中包含定義代理程式行為的主要 Python 程式碼，包括代理程式名稱、做為「大腦」的大型語言模型 (LLM)，以及引導回覆的核心指令。
  • __init__.py：在 Python 中，__init__.py 檔案會將目錄標示為 Python 套件。對 ADK 而言，這項功能至關重要，因為它有助於架構從 agent.py 探索及載入代理程式定義。在簡單的 ADK 專案中，這通常包含匯入 agent 模組的單行程式碼，讓 ADK 執行器可存取代理程式。
  • .env：這個檔案 (簡稱「環境」) 用於儲存代理程式需要的機密資訊和設定變數，例如 API 金鑰、專案 ID 和地理位置。將這些詳細資料放在個別的 .env 檔案中，是確保安全性和可攜性的最佳做法，因為這樣可避免直接將機密資料硬式編碼到程式碼中。此外，您也可以輕鬆變更設定，不必修改主要代理程式邏輯。

使用下列指令，在個人助理代理程式的專屬資料夾中建立這些檔案：

uv run adk create personal_assistant

執行指令後，系統會要求你選擇幾個選項來設定代理程式。首先，請選擇選項 1，使用 gemini-2.5-flash 模型。這個模型快速有效率，非常適合對話工作。

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

在第二個步驟中，請選擇 Vertex AI (選項 2)，這是 Google Cloud 強大的代管式 AI 平台，可做為後端服務供應商。

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

最後，系統會要求您確認 Google Cloud 專案 ID 和區域。如果預先填入的值 (current-project-id 和 current-region) 符合您的需求，只要針對每個問題按下 Enter 鍵即可。

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

終端機應會顯示類似的輸出內容。

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

現在，請按一下 Cloud Shell 視窗頂端的「Open Editor」(開啟編輯器) 按鈕。按一下該按鈕會開啟「編輯器」視窗，方便您探索檔案內容。切換作業可能需要一些時間。如果載入畫面停滯超過幾分鐘，請嘗試重新整理瀏覽器。

331da4cf37a1e8a4.png

編輯器視窗完全載入後，請前往「personal-assistant」資料夾。您會看到上述必要檔案 (agent.py、__init__.py 和 .env)。現在來探索內容。

如果資料夾中沒有 .env 檔案，請前往頂端的選單列，按一下「顯示」，然後選取「切換隱藏檔案」。這是常見的設定，因為 .env 檔案通常預設為隱藏，以免意外曝光。

ad3a52aebdae6142.png

現在來看看每個檔案的內容。

agent.py

這個檔案會使用 google.adk.agents 程式庫的 Agent 類別，例項化您的代理程式。

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)
  • from google.adk.agents import Agent：這行會從 ADK 程式庫匯入必要的 Agent 類別。
  • root_agent = Agent(...)：您要在此建立 AI 代理程式的執行個體。
  • name="personal_assistant"：代理程式的專屬 ID。ADK 會以這個名稱辨識及參照代理。
  • model="gemini-2.5-flash"：這個重要參數會指定代理使用的基礎「大腦」大型語言模型 (LLM)，用於理解、推論及生成回覆。gemini-2.5-flash 是快速有效率的模型，適合用於對話工作。
  • description="..."：簡要說明代理程式的用途或功能。描述主要是為了方便人類瞭解，或是讓多代理程式系統中的其他代理程式瞭解這個特定代理程式的功能。這項功能通常用於記錄、偵錯，或顯示代理程式的相關資訊。
  • instruction="..."：這是引導代理程式行為並定義其角色的系統提示。這段說明會告知 LLM 應如何行動，以及主要用途。在本例中，這段說明會將代理程式設為「實用助理」。這項指令是決定 AI 代理人對話風格和能力的重要因素。

init.py

Python 必須有這個檔案，才能將 personal-assistant 視為套件，ADK 才能正確匯入 agent.py 檔案。

from . import agent
  • from . import agent：這一行會執行相對匯入作業，告知 Python 在目前的套件 (personal-assistant) 中尋找名為 agent 的模組 (對應至 agent.py)。這個簡單的程式碼行可確保 ADK 嘗試載入 personal-assistant 代理程式時，能夠找到並初始化 agent.py 中定義的 root_agent。即使是空白檔案，只要有 __init__.py，目錄就會成為 Python 套件。

.env

這個檔案包含特定環境的設定和敏感憑證。

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
  • GOOGLE_GENAI_USE_VERTEXAI：這會告知 ADK，您打算使用 Google 的 Vertex AI 服務進行生成式 AI 作業。這對於運用 Google Cloud 的代管服務和進階模型至關重要。
  • GOOGLE_CLOUD_PROJECT：這個變數會保留 Google Cloud 專案的專屬 ID。ADK 需要這項資訊，才能正確將代理程式與雲端資源建立關聯，並啟用帳單。
  • GOOGLE_CLOUD_LOCATION：指定 Vertex AI 資源所在的 Google Cloud 區域 (例如 us-central1)。使用正確位置可確保代理程式能與該區域的 Vertex AI 服務有效通訊。

6. 在終端機上執行代理程式

備妥這三個檔案後，您就可以直接從終端機執行代理程式。如要執行這項操作，請開啟終端機視窗。在選單列中按一下「Terminal」(終端機)，然後選擇「New Terminal」(新增終端機) 即可！

77e87c904f45d1b2.png

終端機可用後，您可以使用 adk run 指令啟動代理程式。由於這是新的終端機視窗，且我們使用 uv，因此您必須先前往 ai-agent-adk 資料夾，然後在 adk run 指令前面加上 uv run。

在終端機中輸入下列指令：

cd ai-agents-adk
uv run adk run personal_assistant

如果一切設定正確，終端機中會顯示類似的輸出內容。

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

請與服務專員聯絡！你會發現輸出內容有時會以 Markdown 格式設定，這在終端機中可能難以閱讀。在下一個步驟中，我們會使用開發 UI，提供更豐富的體驗，類似於聊天應用程式。

7. 在開發 UI 中執行代理程式

Agent Development Kit 也提供便利的方式，讓您使用開發 UI 將代理發布為即時通訊應用程式。只要使用 adk web 指令取代 adk run. 即可

如果仍處於上一個工作階段，只要在終端機中輸入 exit 即可關閉。關閉上一個工作階段後，在終端機中輸入下列指令：

uv run adk web

終端機應會顯示類似下列的輸出內容：

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

您可以透過兩種方式存取開發使用者介面：

  1. 透過「終端機」開啟
  • 按住 Ctrl 鍵並點選或按住 Cmd 鍵並點選網址 (例如 http://localhost:8000) 從終端機。
  1. 透過網頁預覽開啟
  • 按一下「網頁預覽」按鈕，
  • 選取「變更通訊埠」。
  • 輸入通訊埠編號 (例如 8000)
  • 按一下「變更並預覽」

9af437bf60562635.png

瀏覽器隨即會顯示類似即時通訊應用程式的使用者介面。歡迎透過這個介面與個人助理對話！您會發現 Markdown 格式現在可以正確顯示，而且這個 UI 也可讓您偵錯及調查每個訊息事件、服務專員的狀態、使用者要求等。祝你聊天愉快！

7b779b9601941a12.png

8. 清除

由於本程式碼研究室不涉及任何長時間執行的產品，因此只要在終端機中按下 Ctrl + C，停止執行中的代理程式工作階段 (例如終端機中的 adk web 執行個體) 即可。

刪除代理商專案資料夾和檔案

如要從 Cloud Shell 環境中移除程式碼，請使用下列指令：

cd ~
rm -rf ai-agents-adk

停用 Vertex AI API

如要停用先前啟用的 Vertex AI API，請執行下列指令：

gcloud services disable aiplatform.googleapis.com

關閉整個 Google Cloud 專案

如要完全關閉 Google Cloud 專案，請參閱官方指南，瞭解詳細操作說明。

9. 結語

恭喜！您已使用 Agent Development Kit (ADK) 成功建構簡單的個人助理代理。

如您所見，這個個人助理代理程式的能力還不夠強大 (例如無法存取網際網路來取得最新資訊)。在本「使用 ADK 建構 AI 服務專員」系列下一個程式碼研究室中，您將瞭解如何為個人助理服務專員提供函式和工具。到時見！