使用 ADK 建立多代理系統、在 Agent Engine 中部署，並開始使用 A2A 通訊協定

1. 本實驗室的目標

在本實作實驗室中，您將使用 ADK (Agent Development Kit) 建構多代理應用程式，根據提示生成圖片，並根據提示評估圖片。如果生成的圖片不符合提示中的規定，智慧助理會持續生成圖片，直到生成符合規定的圖片為止。本實作實驗室中的每個代理程式都有單一用途，這些代理程式會互相合作，以達成整體目標。您將瞭解如何在本機測試應用程式，並在 Vertex AI Agent Engine 中部署。

課程內容

• 瞭解 ADK (Agent Development Kit) 的基本概念，並學習如何建立多代理系統。
• 瞭解如何輕鬆在 Vertex AI Agent Engine 中部署及使用代理程式。
• 瞭解 A2A 通訊協定的基本概念
• 瞭解如何搭配使用 A2A 通訊協定和 ADK (Agent Development Kit) ，建立開放式代理。

2. 專案設定

您可以取得 Google Cloud 抵免額來執行這項實驗室。按這裡即可取得抵免額。請參閱這篇文章，瞭解如何申請 Google Cloud 抵免額。

• 如果沒有可用的專案，請在 GCP 主控台中建立新專案。
• 在本實驗室中，我們將使用 GCP Cloud Shell 執行工作。開啟 Cloud Shell，並使用 Cloud Shell 設定專案。
• 按一下這裡開啟 GCP Cloud Shell 。如果看到「Authorize Shell」(授權 Shell) 彈出式視窗，請點選授權 Cloud Shell 編輯器。
• 您可以在 Cloud Shell 終端機中執行下列指令，檢查專案是否已通過驗證。

gcloud auth list

• 在 Cloud Shell 中執行下列指令，確認專案

gcloud config list project

• 複製專案 ID，然後使用下列指令設定

gcloud config set project <YOUR_PROJECT_ID>

• 我們需要啟用一些服務才能執行本實驗室。在 Cloud Shell 中執行下列指令。

gcloud services enable aiplatform.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com

3. Agent Development Kit 簡介

Agent Development Kit 為需要建構代理應用程式的開發人員帶來多項關鍵優勢：

1. 多代理系統：可在階層結構中組合多個專用代理，建構出可擴充的模組化應用程式，藉以執行複雜的協調和委派作業。
2. 豐富的工具生態系統：為代理提供多元功能，像是使用預先建構的工具 (搜尋、程式碼執行等)、建立自訂函式、整合第三方代理框架的工具 (LangChain、CrewAI)，甚至還可以使用其他代理做為工具。
3. 彈性的自動化調度管理功能：使用工作流程代理 (SequentialAgent、ParallelAgent 和 LoopAgent) 來定義可預測的管道工作流程，或透過使用 LLM 的動態轉送功能 (LlmAgent 轉移)，創造靈活應變的代理。
4. 整合式開發人員體驗：使用功能強大的 CLI 和互動式開發 UI，在本機開發、測試及偵錯，逐步檢查事件、狀態和代理執行作業。
5. 內建評估功能：與預先定義的測試案例比較，評估最終回覆品質和逐步執行軌跡，有系統地判斷代理效能。
6. 可隨時部署：將代理容器化並部署至任何位置，無論是在本機執行、透過 Vertex AI Agent Engine 擴充，或使用 Cloud Run/Docker 整合至自訂基礎架構都沒問題。

雖然其他生成式 AI SDK 或代理框架同樣能查詢模型，甚至為模型提供工具，但您必須投入大量心力，在多個模型間靈活調度。

相較之下，Agent Development Kit 比上述工具更加高階，您可以輕鬆相互連結多個代理，建立複雜但方便維護的工作流程。

圖 1：ADK (Agent Development Kit) 的定位

4. Vertex AI Agent Engine 簡介

Vertex AI Agent Engine 是全代管服務，可在 Google Cloud 中部署代理程式。開發人員可透過 Vertex AI Agent Engine，在 Vertex AI 上開發、自訂、部署、提供及管理 OSS AI 代理( ADK (Agent Development Kit) 、LangChain、LangGraph、CrewAI、AutoGen 等！)。

Agent Engine 也提供服務來處理使用者資料，也就是所謂的代理程式記憶體。目前提供兩種記憶體服務。

• 短期記憶：透過 Agent Engine 工作階段，您可以在單一工作階段中儲存、管理及擷取進行中的對話記錄 (狀態)，做為短期記憶。
• 長期記憶：透過 Agent Engine 記憶庫儲存、轉換及擷取記憶 (狀態)，特別是跨多個工作階段的長期記憶。

您也可以在 Cloud Run 或 GKE 等其他 Google Cloud 服務中部署 Agent，但建議在下列用途中使用 Vertex AI Agent Engine。

• 具狀態的全代管執行階段：如要為代理程式部署作業使用具狀態的全代管執行階段，建議選用 Vertex AI Agent Engine，因為這項服務會將常見工作 (例如工作階段管理、AI 代理的持續性) 抽象化。
• 程式碼執行：如果 Agent 需要執行在使用者工作階段期間動態生成的程式碼，Agent Engine 會提供安全的沙箱，供您執行程式碼。
• 彈性的長期記憶：如果需要為代理提供彈性的長期記憶，可搭配 Vertex AI Agent Engine 使用的 Vertex AI Memory Bank，就能彈性記憶使用者資訊，並在不同工作階段中使用。

您也可以將 Vertex AI Agent Engine 與 Cloud Run 等其他執行階段結合，建立彈性的應用程式架構。以下是使用各種服務建構代理程式的參考架構範例。

圖 2：使用多項服務建構 Agent 的參考架構範例。

5. A2A 簡介

Agent2Agent (A2A) 通訊協定是開放標準，旨在讓不同架構、供應商和網域的自主 AI 代理，能夠順暢安全地通訊及協作。

1. 普遍互通性：A2A 可讓代理協同運作，不受底層技術限制，進而打造真正的多代理生態系統。也就是說，不同公司在不同平台上建構的代理程式可以通訊及協調。
2. 功能探索：代理可以使用「代理資訊卡」(JSON 文件) 宣傳功能，說明身分、支援的 A2A 功能、技能和驗證需求。這樣一來，其他代理程式就能探索並選取最適合特定工作的代理程式。
3. 預設安全：安全性是核心原則。A2A 採用企業級驗證和授權機制，並使用 HTTPS/TLS、JWT、OIDC 和 API 金鑰等標準，確保互動安全無虞，並保護機密資料。
4. 不限模式：通訊協定支援各種通訊模式，包括文字、音訊和影片串流，以及互動式表單和嵌入式 iframe。代理程式可彈性地以最適合工作和使用者的格式交換資訊。
5. 結構化工作管理：A2A 會明確定義工作委派、監控和完成的通訊協定。這項功能支援將相關工作分組，並使用不重複的工作 ID，在不同代理之間管理工作。工作可以經歷定義的生命週期 (例如已提交、處理中、已完成)。
6. 不透明的執行作業：這項功能非常重要，因為代理程式不需要向其他代理程式揭露內部推理程序、記憶體或特定工具。這些服務只會公開可呼叫的服務，有助於提升模組化程度和隱私權。
7. 以現有標準為基礎：A2A 採用 HTTP、伺服器推送事件 (SSE) 即時串流和 JSON-RPC 結構化資料交換等成熟的網路技術，因此更容易與現有 IT 基礎架構整合。
8. 非同步通訊：通訊協定的設計主要考量非同步通訊，可促進彈性工作進度，即使連線並非持續維持，也能啟用更新的推播通知。

6. 代理程式架構

在本實驗室中，您將建立多代理程式應用程式，根據規格生成圖片，並在向您顯示圖片前進行評估。

系統架構包含一個名為 image_scoring 的主要代理程式，負責協調整個程序。這個主要代理有一個名為 image_generation_scoring_agent 的子代理，而這個子代理本身也有自己的子代理，負責執行更具體的任務。這會建立階層式關係，主代理會將工作委派給子代理。

圖 3：整體代理程式流程。

所有代理程式的清單

Agent	Purpose	子代理程式
圖片評分 (主要代理程式)	這是管理整體工作流程的根代理程式。並在迴圈中反覆執行 image_generation_scoring_agent 和 checker_agent，直到符合終止條件為止。	image_generation_scoring_agent checker_agent_instance
image_generation_scoring_agent (image_scoring 的子代理)	這個代理負責生成及評估圖片的核心邏輯。為此，這項工具會依序執行三個子代理。	image_generation_prompt_agent image_generation_agent scoring_images_prompt
checker_agent_instance (image_scoring 的子代理程式)	這個代理程式會檢查是否應繼續或終止圖片評分程序。這項工具會使用 check_tool_condition 工具評估終止條件。	-
checker_agent_instance (image_scoring 的子代理程式)	這個代理程式擅長建立圖像生成提示，這項工具會根據輸入文字生成詳細提示，供圖像生成模型使用。	-
image_generation_prompt_agent (image_generation_scoring_agent 的子代理程式)	這個代理程式擅長建立圖像生成提示，這項工具會根據輸入文字生成詳細提示，供圖片生成模型使用。	-
scoring_images_prompt (image_generation_scoring_agent 的子代理程式)：	這個代理程式擅長根據各種條件評估圖片並給予分數。並為生成的圖片評分。	-

使用的所有工具清單

工具	說明	使用者代理程式
check_tool_condition	這項工具會檢查是否符合迴圈終止條件，或是否已達到疊代次數上限。如果符合任一條件，迴圈就會停止。	checker_agent_instance
generate_images	這項工具會使用 Imagen 3 模型生成圖片。也可以將生成的圖片儲存至 Google Cloud Storage bucket。	image_generation_agent
get_policy	這項工具會從 JSON 檔案擷取政策，image_generation_prompt_agent 會使用這項政策建立圖片生成提示，scoring_images_prompt 則會使用這項政策為圖片評分。	image_generation_agent
get_image	這項工具會載入生成的圖像構件，以便評分。	scoring_images_prompt
set_score	這項工具會在工作階段狀態中設定生成圖片的總分。	scoring_images_prompt

7. 安裝 ADK 並設定環境

在本實作實驗中，我們將使用 Cloud Shell 執行工作。

準備 Cloud Shell 編輯器分頁

1. 按一下這個連結，直接前往 Cloud Shell 編輯器
2. 按一下「繼續」。
3. 系統提示您為 Cloud Shell 提供授權時，按一下「授權」。
4. 在本實驗室的其餘部分，您可以透過這個視窗，使用 Cloud Shell 編輯器和 Cloud Shell 終端機做為 IDE。
5. 在 Cloud Shell 編輯器中，依序點選「Terminal」(終端機) >「New Terminal」(新增終端機)，開啟新的終端機。下列所有指令都會在這個終端機上執行。

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

1. 執行下列指令，從 GitHub 複製所需來源，並安裝必要程式庫。在 Cloud Shell 編輯器中開啟的終端機中執行指令。

#create the project directory
mkdir ~/imagescoring
cd ~/imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

2. 我們會使用 uv 建立 Python 環境 (在 Cloud Shell 編輯器終端機中執行)：

#Install uv if you do not have installed yet
pip install uv

#Create the virtual environment
uv venv .adkvenv

source .adkvenv/bin/activate

#go to the project directory
cd ~/imagescoring/multiagenthandson

#install dependencies
uv pip install -r pyproject.toml

3. 如果沒有雲端儲存空間值區，請在 Google Cloud Storage 中建立新的值區。您也可以使用 gsutil 指令建立 bucket。授予 Agent Engine Google Cloud Storage 存取權 (在 Cloud Shell 編輯器終端機中執行)。

# First, make sure your PROJECT_ID variable is set
PROJECT_ID=$(gcloud config get-value project)

# Now, create the bucket with a unique name
# We'll use the project ID to help ensure uniqueness
gsutil mb gs://${PROJECT_ID}-imagescoring-bucket

#Now lets give Agent Engine the permission to access Cloud Storage
# 1. Get the current Project ID (text) and Project Number (numeric)
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# 2. Construct the Reasoning Engine Service Account email
SA_EMAIL="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
# 3. Create Agent Engine Service account if not already created
gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_NUMBER}

# 3. Grant GCS Access
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/storage.objectUser" --condition=None

4. 在編輯器中，依序前往「View」->「Toggle hidden files」。在 image_scoring 資料夾中，建立含有下列內容的 .env 檔案。新增必要詳細資料，例如專案名稱和 Cloud Storage bucket (在 Cloud Shell 編輯器終端機中執行)。

#go to image_scoring folder
cd ~/imagescoring/multiagenthandson/image_scoring

cat <<EOF>> .env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=$(gcloud config get-value project)-imagescoring-bucket
GCS_BUCKET_NAME=$(gcloud config get-value project)-imagescoring-bucket
SCORE_THRESHOLD=40
IMAGEN_MODEL="imagen-3.0-generate-002"
GENAI_MODEL="gemini-2.5-flash"
EOF

5. 查看原始碼中的代理程式結構，從 agent.py 開始。這個代理程式包含將連結至其他代理程式的根代理程式。
6. 返回終端機中的頂層目錄 multiagenthandson，然後執行下列指令，在本機執行代理程式 (在 Cloud Shell 編輯器終端機中執行)。

#go to the directory multiagenthandson
cd ~/imagescoring/multiagenthandson
# Run the following command to run agents locally
adk web

圖 4

在終端機上顯示的 http:// 網址上按 Ctrl + 滑鼠左鍵 (MacOS 則為按 CMD + 滑鼠左鍵)，開啟 ADK 的瀏覽器型 GUI 用戶端。畫面應如圖 2 所示

7. 選取左上側下拉式選單中的「image_scoring」(請參閱圖 5)。現在來生成一些圖片！您應該也會在 Google Cloud Storage bucket 中找到圖片。請嘗試使用下列提示，或自行輸入提示。
8. 日落時分寧靜的山景
9. 騎自行車的貓

圖 5：輸出範例

8. 部署至 Agent Engine

現在，我們要將代理部署至 Agent Engine。Agent Engine 是一項全代管服務，可在 GCP 中部署代理程式。Agent Engine 與 ADK (Agent Development Kit) 相容，因此以 ADK (Agent Development Kit) 建構的代理可部署在 Agent Engine 中。

1. 使用 Poetry 建立 requirements.txt 檔案。Poetry 會使用 pyproject.toml 建立 requirements.txt 檔案。執行指令後，請檢查是否已建立 requirements.txt 檔案 (在 Cloud Shell 編輯器終端機中執行)。

# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson

# install poetry-plugin-export
uv pip install poetry-plugin-export

#Create requirements.txt file
python3 -m poetry export -f requirements.txt --output requirements.txt --without-hashes

2. 建立套件。我們需要將應用程式打包成 .whl Python 套件。我們會使用 Poetry 執行這項操作。執行指令後，請確認是否已建立 dist 資料夾，且該資料夾包含 .whl 檔案 (在 Cloud Shell 編輯器終端機中執行)。

# Go to the parent folder containing pyproject.toml file
cd ~/imagescoring/multiagenthandson

#Create python package, to create whl file
python3 -m poetry build

3. 接著準備部署指令碼。部署指令碼會部署圖片評分代理或代理引擎服務。請確認 deploy 資料夾內的 deploy.py 內容如下 (使用 Cloud Shell 編輯器側邊窗格尋找檔案)。

import vertexai
from image_scoring.agent import root_agent
import os
import glob # To easily find the wheel file
from dotenv import load_dotenv

# Load environment variables from image_scoring/.env
env_path = os.path.join(os.path.dirname(__file__), "..", "image_scoring", ".env")
load_dotenv(env_path)

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")
STAGING_BUCKET = f"gs://{os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}"

from vertexai import agent_engines

client=vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)
remote_app = client.agent_engines.create(
    agent=root_agent,
    config={
        "display_name": "image-scoring",
        "staging_bucket": STAGING_BUCKET,
        "requirements": open(os.path.join(os.getcwd(), "requirements.txt")).readlines() + ["./dist/image_scoring-0.1.0-py3-none-any.whl"],
        "extra_packages": [
            "./dist/image_scoring-0.1.0-py3-none-any.whl",
        ],     "env_vars":{"GCS_BUCKET_NAME":os.getenv('GOOGLE_CLOUD_STORAGE_BUCKET')}
    }
)
print(f"DEBUG: AgentEngine attributes: {dir(remote_app)}")
try:
    print(remote_app.api_resource.name)
except AttributeError:
    print("Could not find resource_name, check DEBUG output above.")

4. 現在可以執行部署指令碼。首先，請前往頂層資料夾 multiagenthandson (在 Cloud Shell 編輯器終端機中執行)。

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

#run deploy script from the parent folder containing deploy.py
python3 -m deploy.deploy

部署完成後，您應該會看到類似下方的內容：

圖 6：輸出內容範例

5. 現在來測試已部署的代理程式。如要測試遠端部署的代理程式引擎，請先從終端機的部署輸出內容複製代理程式位置。格式應類似：projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680。
   前往 testclient 資料夾，在 Cloud Shell 編輯器中開啟 remote_test.py 檔案，然後編輯下列幾行。

REASONING_ENGINE_ID = "projects/xxx/locations/us-central1/reasoningEngines/xxx"  # TODO: Change this

6. 在頂層資料夾 multiagenthandson 中，執行下列指令。您應該會看到類似圖 4 的輸出內容。執行完畢後，您應該會看到 (在 Cloud Shell 編輯器終端機中執行)。

#go to multiagenthandson folder
cd ~/imagescoring/multiagenthandson

#execute remote_test.py
python3 -m testclient.remote_test

圖 7：輸出範例

9. 建立 A2A 代理程式

在本步驟中，我們將根據先前步驟中建立的代理程式，建立簡單的 A2A 代理程式。現有的 ADK (Agent Development Kit) 代理程式可透過 A2A 通訊協定發布。這個步驟的重點如下：

• 瞭解 A2A 通訊協定的基本概念。
• 瞭解 ADK 和 A2A 通訊協定如何搭配運作。
• 瞭解如何與 A2A 通訊協定互動。

在本實作練習中，我們將使用 image_scoring_adk_a2a_server 資料夾中的程式碼。開始工作前，請先將目錄變更為這個資料夾 (在 Cloud Shell 編輯器終端機中執行)。

#change directory to image_scoring_adk_a2a_server
cd ~/imagescoring/multiagenthandson/image_scoring_adk_a2a_server

#copy the env file
cp ~/imagescoring/multiagenthandson/image_scoring/.env remote_a2a/image_scoring

1. 建立 A2A 代理資訊卡

A2A 通訊協定需要代理資訊卡，其中包含代理的所有資訊，例如代理功能、代理使用指南等。部署 A2A 代理後，即可使用「.well-known/agent-card.json」連結查看代理資訊卡。客戶可以參考這項資訊，將要求傳送給服務專員。

在 remote_a2a/image_scoring 資料夾中，使用 Cloud Shell 編輯器確認是否有 agents.json，且內容如下。

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

2. 建立 A2A 代理

在根資料夾 image_scoring_adk_a2a_server 中，使用 Cloud Shell 編輯器側邊窗格確認是否有 a2a_agent.py 檔案，這是 A2A 代理的進入點。內容應如下所示：

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

3. 執行 A2A 代理程式

現在可以執行代理程式了！如要執行代理程式，請在頂層資料夾 image_scoring_adk_a2a_server 中執行下列指令 (在 Cloud Shell 編輯器終端機中執行)。

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

4. 測試 A2A 代理

代理程式執行後，我們就可以測試代理程式。首先，請檢查代理程式卡片。使用「Terminal」(終端機) >「New Terminal」(新增終端機) 開啟新的終端機，然後執行下列指令 (在開啟的 Cloud Shell 編輯器終端機中執行)。

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

執行上述指令後，應該會顯示 A2A 代理程式的代理程式資訊卡，主要內容是我們在上一個步驟中建立的 agent.json。

現在，讓我們傳送要求給代理程式。我們可以使用 curl 將要求傳送至代理程式 (在剛開啟的 Cloud Shell 編輯器終端機中執行)，

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

在上述要求中，您可以變更「Create an image of a cat」這一行，藉此變更提示。執行指令後，您可以在指定的 Google Cloud Storage 中查看輸出圖片。

10. 清除所用資源

現在來清除剛才建立的內容。

1. 刪除我們剛建立的 Vertex AI Agent Engine 伺服器。在 Google Cloud 控制台的搜尋列中輸入「Vertex AI」，前往 Vertex AI。按一下左側的「代理程式引擎」。按一下「刪除」即可刪除代理程式。

圖 8

2. 刪除 Cloud Shell 中的檔案

#Execute the following to delete the files
cd ~
rm -R ~/imagescoring

3. 刪除 bucket。前往 GCP 控制台的「Cloud Storage」，選取並刪除 bucket。

圖 9：刪除 bucket

11. 結語

恭喜！您已成功將多代理 ADK (Agent Development Kit) 應用程式部署至 Vertex AI Agent Engine。這項重大成就涵蓋現代雲端原生應用程式的核心生命週期，為您部署複雜的代理系統奠定穩固基礎。

重點回顧

在本實驗室中，您已學會如何：

• 使用 ADK (Agent Development Kit) 建立多代理應用程式
• 將應用程式部署至 Vertex AI Agent Engine
• 建立可使用 A2A 通訊協定通訊的代理。

實用資源

• 官方 ADK 說明文件
• Vertex AI Agent Engine
• A2A 通訊協定
• Cloud Run