使用 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 Billing 帳戶。如果還沒有，請按照下列步驟兌換試用帳單帳戶：

  1. 在瀏覽器中開啟無痕視窗
  2. 前往這個兌換入口網站
  3. 使用個人 Gmail 帳戶登入
  4. 按照入口網站的逐步說明操作

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，後續步驟將會用到。

c3988d2f9ea7b7c3.png

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

設定 Cloud Shell

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

1. 啟動 Cloud Shell

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

d5e271ec814f5769.png

2. 設定專案 ID

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

gcloud config set project <your-project-id>

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

a596b7d3cb052d07.png

3. 啟用必要的 API

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

gcloud services enable aiplatform.googleapis.com

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

4. 建立 Python 虛擬環境

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

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

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

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

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

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

aa915af1d8379132.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 資料夾
  • 按一下「確定」。

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

733f215484b2ee7d.png

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

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

  • 前往頂端的選單列，
  • 按一下「查看」，然後
  • 選取「切換隱藏檔案」。

a3a4e5587e8ed302.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]: 
...

請與服務專員進行即時通訊！輸入「你好。「你有哪些功能？」，系統應該會回覆。

...
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 試用帳單帳戶」

ac71beafc7f645e.png

61c3fca79c772230.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

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

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

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 代理程式：運用工具提升效能」，瞭解如何完成這項程序。