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

1. 事前準備

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

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

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

您也可以透過這個縮短網址存取程式碼研究室：goo.gle/adk-foundation。

必要條件

課程內容

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

軟硬體需求

2. 簡介

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

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

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

3. 設定 Google Cloud 服務

建立 Google Cloud 專案

首先，請建立新的 Google Cloud 專案，確保本程式碼研究室的活動只會在這個新專案中進行。

  1. 前往 console.cloud.google.com/projectcreate
  2. 輸入必要資訊：
  • 專案名稱 - 您可以輸入任何想要的名稱 (例如 genai-workshop)
  • 位置 - 保持「沒有機構」
  • 帳單帳戶 - 如果看到這個選項，請選取「Google Cloud Platform 試用帳單帳戶」。如果沒有看到這個選項，請別擔心，請繼續執行下一步。
  1. 複製產生的專案 ID，後續步驟將會用到。

9cc4a060b8c46fb0.png

  1. 如果一切正常，請按一下「建立」按鈕

設定 Cloud Shell

專案建立完成後，請按照下列步驟設定 Cloud Shell。

1. 啟動 Cloud Shell

前往 shell.cloud.google.com，如果看到要求授權的彈出式視窗，請點選「Authorize」(授權)。

186bc51f8f3ae589.png

2. 設定專案 ID

在 Cloud Shell 終端機中執行下列指令，設定正確的專案 ID。將 <your-project-id> 替換為您在上述專案建立步驟中複製的實際專案 ID。

gcloud config set project <your-project-id>

現在，您應該會在 Cloud Shell 終端機中看到已選取正確的專案。所選專案 ID 會以黃色醒目顯示。

479ae540d1828559.png

3. 啟用必要的 API

如要使用 Google Cloud 服務，必須先為專案啟用對應的 API。在 Cloud Shell 終端機中執行下列指令，為本 Codelab 啟用服務：

gcloud services enable aiplatform.googleapis.com

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

4. 建立 Python 虛擬環境

開始任何 Python 專案前，建議您先建立虛擬環境。這樣一來，專案的依附元件就會與其他專案或系統的全域 Python 套件隔離，避免發生衝突。

1. 建立專案目錄並前往該目錄：

mkdir -p ai-agents-adk
cd ai-agents-adk

2. 建立並啟動虛擬環境：

uv venv --python 3.12
source .venv/bin/activate

終端機提示會顯示 (ai-agents-adk) 前置字元，表示虛擬環境已啟動。

6512ff43e8f5aa04.png

3. 安裝 adk 頁面

uv pip install google-adk

5. 建立代理程式

環境就緒後，就可以開始建立 AI 代理的基礎。ADK 需要幾個檔案來定義代理的邏輯和設定：

  • agent.py：包含代理程式的主要 Python 程式碼，定義代理程式的名稱、使用的 LLM 和核心指令。
  • __init__.py：將目錄標示為 Python 套件，協助 ADK 探索及載入代理定義。
  • .env：儲存機密資訊和設定變數，例如 API 金鑰、專案 ID 和位置。

這個指令會建立名為 personal_assistant 的新目錄，其中包含三個必要檔案。

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

接著，請確認方括號 [...] 顯示的專案 ID 是否設定正確。如果是，請按下 Enter 鍵。如果不是，請在下列提示中輸入正確的專案 ID：

Enter Google Cloud project ID [your-project-id]:

最後，在下一個問題中按下 Enter 鍵，將 us-central1 設為這個程式碼研究室的區域。

Enter Google Cloud region [us-central1]:

終端機中應該會顯示類似下方的輸出內容。

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

6. 探索代理程式碼

如要查看建立的檔案，請在 Cloud Shell 編輯器中開啟 ai-agents-adk 資料夾。

  • 按一下頂端選單中的「File」>「Open Folder...」。
  • 找出並選取 ai-agents-adk 資料夾
  • 按一下「確定」。

如果沒有看到頂端選單列，也可以按一下資料夾圖示，然後選擇「開啟資料夾」。

8d092e1c07966b24.png

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

.env 檔案通常預設為隱藏。如要在 Cloud Shell 編輯器中顯示該檔案，請按照下列步驟操作：

  • 前往頂端的選單列，
  • 按一下「查看」，然後
  • 選取「Toggle Hidden Files」。

ff4c617fa62e2da2.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="root_agent"：代理程式的專屬 ID。ADK 會透過這個名稱辨識及參照您的代理。
  • model="gemini-2.5-flash"：這個重要參數會指定代理使用的基礎大型語言模型 (LLM)，做為理解、推論和生成回覆的「大腦」。gemini-2.5-flash 是快速有效率的模型，適合用於對話工作。
  • description="..."：簡要說明代理程式的用途或功能。說明主要是供人類瞭解，或供多代理系統中的其他代理瞭解這個特定代理的功能。這項功能通常用於記錄、偵錯，或顯示代理程式的相關資訊。
  • instruction="..."：這是系統提示，可引導代理的行為並定義其角色。這段說明會告知 LLM 代理應如何運作，以及主要用途。在本例中，這段說明會將代理設定為「實用助理」。這項指令是決定代理對話風格和能力的重要因素。

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 服務有效通訊。

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

備妥這三個檔案後，您就可以直接從終端機執行代理程式。如要這麼做，請在終端機中執行下列 adk run 指令：

adk run personal_assistant

如果一切設定正確，終端機就會顯示類似的輸出內容。只要看到 [user]:，就可以繼續操作，暫時不必理會警告。

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

請直接與代理程式對話！輸入「你好。What can you do for me?」(你能為我做什麼？)，系統應該會回覆。

...
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，享受更豐富的體驗，就像使用聊天應用程式一樣。

疑難排解

必須啟用計費功能，才能使用這個 API 方法

如果收到「{‘message': ‘This API method requires billing to be enabled'}」訊息，請按照下列步驟操作：

  1. 檢查 .env 檔案中使用的專案 ID 是否正確
  2. 前往連結的帳單帳戶頁面，確認帳單帳戶是否已連結
  3. 如果沒有，請從選項中選擇「Google Cloud Platform 試用帳單帳戶」

d9eb6361fd573427.png

f304212def88d3a3.png

專案未使用 Vertex AI API

如果收到含有 {'message': 'Vertex AI API has not been used in project...'} 的錯誤訊息，請在終端機中輸入下列指令，啟用 Vertex AI API：

gcloud services enable aiplatform.googleapis.com

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

其他錯誤

如果收到上述未提及的其他錯誤，請嘗試重新載入瀏覽器中的 Cloud Shell 分頁 (並在系統提示時重新授權)。

8. 在開發網頁版 UI 中執行代理程式

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

如果終端機仍在執行 adk run，請先輸入 exit 關閉終端機，再輸入指令。

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

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

...
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)

您可以使用下列兩種方法存取開發 UI：

  1. 直接透過終端機：對提供的連結使用 Ctrl + 按一下 (或 Cmd + 按一下)，例如 http://localhost:8000。
  2. 使用網頁預覽功能：
  • 按一下「網頁預覽」按鈕。
  • 選取「變更通訊埠」。
  • 輸入通訊埠編號 (例如 8000)。
  • 按一下「變更並預覽」。

43b8b9beedbb1766.png

瀏覽器隨即會顯示類似即時通訊應用程式的使用者介面。透過這個介面與個人助理對話吧！

你會發現 Markdown 格式現在可以正確顯示，而且這個 UI 也可讓你偵錯及調查每個訊息事件、代理程式狀態、使用者要求等。祝你聊天愉快！

e845ab685af1ad90.png

9. 清除 (選用)

由於本程式碼研究室不涉及任何長時間執行的產品，因此只要在終端機中按下 Ctrl + C 或 Cmd + 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 專案，請參閱官方指南，瞭解詳細操作說明。

10. 結語

恭喜！您已使用 Agent Development Kit (ADK) 成功建構簡單的個人助理代理。您現在已具備紮實的基礎，瞭解 ADK 代理程式的核心元件。

接下來，您可以為代理提供工具，讓代理存取即時資訊及與外部服務互動，大幅擴展代理的功能。如要繼續學習，請參閱本系列下一個程式碼研究室「使用 ADK 建構 AI 代理：加入工具」，瞭解如何完成這項程序。