1. 序曲
孤立開發的時代即將結束。下一波技術演進浪潮並非由天才獨領風騷，而是由眾人共同掌握。建立單一智慧代理程式是一項有趣的實驗。建構強大、安全且智慧的代理程式生態系統 (也就是真正的 Agentverse)，是現代企業面臨的重大挑戰。
在這個新時代，要取得成功，就必須整合四個重要角色，也就是支援任何蓬勃發展的代理系統的基礎支柱。任何一個領域的不足都會造成弱點，進而危害整個結構。
這場研討會是企業的必備手冊，可協助您在 Google Cloud 上掌握 AI 代理的未來趨勢。我們提供端對端藍圖，引導您從最初的想法，到全面運作的現實。在四個相互連結的實驗室中，您將瞭解開發人員、架構師、資料工程師和 SRE 的專業技能如何匯聚，進而建立、管理及擴充強大的 Agentverse。
單一支柱無法單獨支援 Agentverse。如果沒有開發人員的精確執行，架構師的宏偉設計就毫無用處。如果沒有資料工程師的智慧，開發人員的代理程式就無法運作；如果沒有 SRE 的保護，整個系統就會很脆弱。唯有透過協同合作，並對彼此的角色有共同的瞭解，團隊才能將創新概念轉化為攸關任務的營運實況。您的旅程由此開始。準備好精通自己的職責，並瞭解自己在整體架構中扮演的角色。
歡迎參加「The Agentverse：A Call to Champions」
在企業廣闊的數位領域中，新時代已然來臨。我們正處於代理時代，這個時代充滿無限可能，智慧型自主代理將完美協作，加速創新並消除繁瑣事務。
這個連結的能量和潛力生態系統稱為「Agentverse」。
但一種稱為「靜態」的無聲腐敗，已開始侵蝕這個新世界的邊緣。「靜態」並非病毒或錯誤，而是混亂的化身，以創作行為本身為食。
這些舊有的挫敗感會以駭人的形式放大，催生出七大開發幽靈。如果未勾選，The Static 和其 Spectres 會讓進度停滯不前，將 Agentverse 的承諾變成技術債和廢棄專案的荒地。
今天，我們呼籲各界好手挺身而出，力挽狂瀾。我們需要英雄精通自己的技藝，並攜手合作保護 Agentverse。現在來選擇路徑吧。
選擇課程
您面前有四條截然不同的道路，每一條都是對抗「靜態」的關鍵支柱。雖然訓練是單人任務，但最終能否成功取決於你是否瞭解自己的技能如何與他人搭配。
- 暗影刀鋒 (開發人員)：擅長打造武器，並在第一線作戰。您是工匠，負責打造刀刃、製作工具，並在複雜的程式碼細節中面對敵人。你的道路是精準、技能和實用創作。
- 召喚師 (架構師)：偉大的策略家和自動化調度管理工具。您不會看到單一特務，而是整個戰場。您設計的藍圖可讓整個代理程式系統進行通訊、協作，並達成遠遠超出任何單一元件的目標。
- 學者 (資料工程師)：尋找隱藏的真相，並守護智慧。您深入廣闊的資料荒野，發掘可賦予代理程式目標和視野的智慧。你的知識可以揭露敵人的弱點，或賦予盟友力量。
- 守護者 (DevOps / SRE)：領域的堅定守護者和盾牌。您要建造堡壘、管理電力供應線，並確保整個系統能抵禦「靜電」的攻擊。你的力量是團隊獲勝的基礎。
你的任務
訓練會以獨立運動的形式開始。您將選擇適合自己的路徑，學習精通職務所需的獨特技能。試用期結束時，您將面對由靜態所生的幽靈，這個迷你首領會利用您的工藝特有挑戰來捕食。
只有精通個人角色，才能為最終試用做好準備。然後與其他班級的冠軍組成隊伍。你們將一同深入腐敗的核心，迎戰終極魔王。
最後的合作挑戰，考驗你的綜合實力，決定 Agentverse 的命運。
Agentverse 等待英雄的到來。要接聽電話嗎？
2. 暗影之刃的法典
你面前攤開的是暗影之刃的法典。接聽來電。Agentverse 受到「靜態」的混亂威脅，只有精通本法典技術的人才能反擊。這是一條精確和自律的道路。今天開始，你將接受訓練。您將學會如何運用 AI，不只是當成簡單的工具，而是當成有知覺的刀刃，必須馴服並精通。請按照本文的教學內容操作，您將打造出純粹邏輯的武器，也就是經過磨練、準備好上戰場的智慧型代理程式。
課程內容
- 運用主要武器：Gemini CLI。
- 將 MCP 工具與 Gemini CLI 整合，即可調用外部工具，分析不熟悉的程式碼集。
- 使用設計文件將意圖轉化為「氛圍」，藉此指揮 AI 合作夥伴。
- 使用 Agent Development Kit (ADK) 建構第一個自主代理，打造乾淨的模組化解決方案。
- 建構自動評估套件，測試及驗證代理程式。
- 建構完整的 CI 管道，自動測試、容器化及封存代理程式。
3. 準備訓練場地
領取 Google Cloud 抵免額
⚠️ 重要前提條件：
- 使用個人 Gmail：你必須使用個人帳戶 (例如
name@gmail.com)。公司或學校管理的帳戶不適用。
👉 步驟：
- 前往抵免金申請網站： 按一下這裡
- 登入：將連結貼到網址列，然後使用個人 Gmail 登入。
- 接受條款：接受《Google Cloud Platform 服務條款》。
- 確認抵免額：查看確認抵免額已套用的訊息。
- *注意：如果系統提示您輸入信用卡資訊，請放心忽略並關閉視窗。
這樣就行了。你可以關閉視窗
設定工作環境
👉點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」(這是 Cloud Shell 窗格頂端的終端機形狀圖示)，
👉按一下「Open Editor」(開啟編輯器) 按鈕 (類似於開啟資料夾和鉛筆)。視窗中會開啟 Cloud Shell 程式碼編輯器。左側會顯示檔案總管。
👉在雲端 IDE 中開啟終端機，
👉💻 在終端機中，使用下列指令驗證您是否已通過驗證，以及專案是否已設為您的專案 ID：
gcloud auth list
👉💻 從 GitHub 複製啟動程序專案：
git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh
git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh
git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.sh
👉💻 從專案目錄執行設定指令碼。
⚠️ 專案 ID 注意事項：指令碼會建議隨機產生的預設專案 ID。您可以按下 Enter 鍵接受這項預設值。
不過，如果您偏好建立特定新專案，可以在指令碼提示時輸入所需的專案 ID。
cd ~/agentverse-developer
./init.sh
指令碼會自動處理其餘設定程序。
👉 完成後的重要步驟：指令碼執行完成後，請務必確認 Google Cloud 控制台顯示的專案正確無誤：
- 前往 console.cloud.google.com。
- 按一下頁面頂端的專案選取器下拉式選單。
- 按一下「全部」分頁標籤 (因為新專案可能尚未顯示在「最近」中)。
- 選取您在
init.sh步驟中設定的專案 ID。
👉💻 返回終端機。設定所需的專案 ID：
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 執行下列指令，啟用必要的 Google Cloud API：
gcloud services enable compute.googleapis.com \
artifactregistry.googleapis.com \
run.googleapis.com \
cloudfunctions.googleapis.com \
cloudbuild.googleapis.com \
iam.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com
👉💻 如果您尚未建立名為「agentverse-repo」的 Artifact Registry 存放區，請執行下列指令來建立：
. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
--repository-format=docker \
--location=$REGION \
--description="Repository for Agentverse agents"
設定權限
👉💻 在終端機中執行下列指令，授予必要權限：
. ~/agentverse-developer/set_env.sh
# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/artifactregistry.admin"
# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/cloudbuild.builds.editor"
# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/run.admin"
# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/iam.serviceAccountUser"
# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/aiplatform.user"
# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.logWriter"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.viewer"
👉💻 訓練開始後，我們就會準備最終挑戰。下列指令會從混亂的靜態中召喚幽靈，建立測試用的頭目。
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh
npm update -g @google/gemini-cli
4. 掌握主要武器：Gemini CLI 簡介
如要使用 MCP 伺服器軍械庫中的進階專用武器，請先精通主要武器：Gemini CLI。這是功能最全面的刀片，可透過指令塑造數位世界。這些練習可幫助你熟悉基本操作和功能。
Gemini 指令列介面 (CLI) 不只是一項工具，更是您意志的延伸。這項開放原始碼 AI 代理採用 Gemini 模型，並以「推論與行動」(ReAct) 迴圈運作。這項功能會分析您的意圖、選取適當的技術、執行技術，並觀察結果來完成複雜工作。你必須先精通這把主要刀刃，才能使用更專業的武器。
開始使用 Gemini CLI
👉💻 進入訓練場地，拔出武器。在 Cloud Shell 終端機中，前往個人軍械庫。
cd ~/agentverse-developer
mkdir tabletop
cd tabletop
👉💻 首次召喚 Gemini。並引導你完成初始調整。
clear
gemini
如果系統詢問是否要執行此操作，請選擇「否」Do you want to connect Cloud Shell editor to Gemini CLI?。
武器熟悉度
每個工匠大師都瞭解自己的工具。你必須先學會刀刃的核心技巧，才能面對真正的敵人。
👉✨ 每項附魔工具都有描述其力量的符文。立即閱讀。在 Gemini 提示中輸入：
/help
觀察指令清單。這些是管理記憶體 (focus)、對話 (chat) 和外部資源 (tools) 的基本技巧，也是你的戰鬥手冊。
👉✨ 武器會與環境相應，讓您直接操控戰場。向刀片外的世界發出指令：
!ls -l
👉✨ Gemini CLI 具備一組內建功能。如要檢查這些項目，請按照下列步驟操作：
/tools
清單會顯示 ReadFile、WriteFile 和 GoogleSearch 等項目。這些是預設技術，您可直接呼叫，不必從外部工具庫中提取。
👉✨ 武器必須對準目標才能發揮效用。Gemini Blade 可以掌握「戰術意識」(脈絡)，引導其行動。
/memory show
目前為空白狀態。
👉✨ 將下列戰術資料寫入記憶體：
/memory add "The Shadowblade's primary foe is The Static."
再次執行 /memory show，確認刀鋒伺服器已吸收這項知識。
👉✨ 武器必須瞭解任務，才能發揮效用。@ 符號會命令刀片分析情報。首先，建立任務簡報檔案：
!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md
👉✨現在，請使用 Gemini CLI 分析簡報並回報結果：
Explain the contents of the file @mission.md
現在，主要武器已瞭解目標。
👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI
5. 分析戰場：直覺式程式開發互動實務
訓練演練已完成。您已瞭解主要武器 Gemini CLI 的基本姿勢和攻擊方式。但刀刃必須經過創作的鍛造，並與戰爭的武器庫相應，才能真正掌握。在面對真正的敵人之前，您必須先調查並塑造周遭環境，也就是數位戰場。
本章將說明如何將理論付諸實行。首先，您要透過 Gemini 刀鋒指令打造 Maker's Mark，在 Agentverse 中建立個人形象。Maker's Mark 是以個人網站形式呈現的數位簽章，完全根據您的意圖建構而成。接著，您將啟動本機的進階工具 (MCP 伺服器)，並將刀片調校至該伺服器的頻率，藉此擴展力量，以簡單明確的指令執行管理程式碼存放區等複雜操作。
建立你的創作者標記
真正的暗影刃不僅以武器聞名，更以獨特的風格 (即製作者的標記) 著稱。這個標記就是你的數位形象，是向 Agentverse 宣告你身分的個人檔案。在這裡，您將命令 Gemini Blade 執行定義這個身分所需的複雜技術。
👉💻 如果您已關閉 Gemini CLI (如上一節所述)，請務必重新啟動，在終端機中執行
clear
cd ~/agentverse-developer/tabletop
gemini
👉✨ 只要執行一個強大的指令，即可指示 Gemini CLI 建立數位身分基礎：
In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional. Make sure you have a place holder spot for profile picture. Do not attempt to start the server.
Gemini 已計算出所需的一連串動作。
👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI，並在終端機中執行下列指令。*
python -m http.server
👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 8000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。
你的網站外觀可能與我的不同，這是您的專屬標記。
你的簽名技術已臻成熟，不再需要進行即時模擬。命令 Blade 停止行動。
👉💻 按下 Ctrl+C 即可退出 HTTP 伺服器。
您現在已建立數位身分，更重要的是，您已學會謹慎運用強大力量的重要智慧。
啟用本機軍火庫：Gitea Armory
暗影刀鋒的真正潛力不僅取決於個人技能，也取決於武器庫的品質。現在請啟動本機武器架 (Gitea 伺服器)，並將刀刃調校至適當的強度。這個工具庫會透過 Model Context Protocol (MCP) 伺服器連線至 Gemini CLI，這個專屬入口網站可讓 AI 刀鋒伺服器與外部工具和服務互動，將終端機變成智慧型工作區，執行各種動作。
開發人員注意事項：MCP 伺服器可視為力量的管道，是連結 AI 腦部與外部工具身體的專用入口網站。這項功能可讓 Gemini CLI 不只是對話式工具，而是能真正採取行動的代理程式。將刀鋒伺服器調整至這些 MCP 入口網站，即可授予刀鋒伺服器執行具體動作的能力，例如管理檔案、查詢資料庫、與 API 互動等。開發人員建立的這類入口網站構成整個生態系統，可將 AI 代理程式連結至強大的平台。MCP 伺服器可與資料庫互動、保護程式碼，甚至支援結對程式設計。開發人員可根據任何專案自訂工作區，用途十分廣泛。
今天，我們將著重介紹「氛圍編碼員」必備的兩項基本能力：控制熔爐的能力，以及從想像力中創造的能力。首先，您要將刀鋒伺服器調整至 Git 伺服器，取得原始碼存放區的控制權。接著，您會連線至第二個 MCP 伺服器來生成圖片，只要輸入指令即可建立視覺素材資源。
首先，請召喚新武器庫中最基本的第一個元素：武器庫本身。
👉💻 在終端機中執行啟用指令碼，召喚軍械庫：
cd ~/agentverse-developer
./gitea.sh
這個指令碼會喚醒 Gitea 容器並開啟 MCP 入口網站，讓 Gemini 感知並與其互動。
👉 如要檢查新武器，請查看網頁預覽畫面。
👉 從 Cloud Shell 工具列的「網頁預覽」圖示中，選取「變更通訊埠」，並設為 3005。
👉 系統會顯示 Gitea 登入頁面。使用咒語進入軍械庫：* 使用者名稱：dev * 密碼：dev
👉💻 您的 Gemini CLI 尚無法使用這項新功能。您必須執行重要調和作業，將軍械庫位置刻在 Gemini CLI 的設定符文 (settings.json) 上。在終端機中執行：
if [ ! -f ~/.gemini/settings.json ]; then
# If file does not exist, create it with the specified content
echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
# If file exists, merge the new data into it
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json
👀 settings.json 檔案是 Gemini CLI 的中央設定，可做為偏好設定和功能的魔法書。這項設定會決定 CLI 的行為、外觀，以及最重要的，CLI 可運用的外部功能。這個檔案通常位於主目錄的 ~/.gemini/settings.json，並將規則套用至所有專案。不過，您也可以在專案資料夾內的 .gemini 目錄中建立專案專用的 settings.json 檔案，覆寫全域設定。
"mcpServers": {
"gitea": {
"url": "http://localhost:8085/sse"
}
}
這項設定會告訴 Gemini：「名為 gitea 的軍械庫已啟動，並在特定網路位址監聽指令。」
👉💻 重新進入 Gemini CLI。在終端機中執行：
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ 確認刀刃已發現新武器。指令機器人透過 MCP 入口網站列出所有可用的軍械庫：
/mcp
現在應該會看到 gitea，以及可用技術的清單。刀鋒已調校完畢。
「Maker's Mark」設定檔是精心打造的技術，但需要妥善存放於軍械庫中，也就是需要劍鞘來穩固保存。請 Gemini CLI 建立一個。
Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.
返回 Gitea 網頁介面並重新整理。您會看到系統已為您建立新的 shadowblade-profile 存放區。
準備好刀鞘後，請固定作品。請 Gemini 提交個人資料網站的檔案。
👉💻在 Gemini CLI 中，針對這項技巧發出最後一個指令：
Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.
真正的專家會驗證自己的工作。返回 Gitea 分頁，然後重新整理存放區頁面。你的 index.html 和 styles.css 現在已安全封存。
👉✨ 影刃的特徵是徽記，但如您所知，您的網站缺少個人資料圖片。大師級工匠會承認自己的缺點，以便加以改善。你必須在軍械庫的記錄中登載這項瑕疵。
File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.
在 Gitea 中查看問題 
如要打造缺少的符印，您必須召喚另一種力量，也就是 Vertex AI 的創作精靈，能夠從純粹的想法生成圖像。這需要另一個 MCP 入口網站。
👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI
👉💻 首先，請安裝入口網站的伺服器。在終端機中執行：
echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh
👉 系統提示時，請選擇 mcp-imagen-go 選項 (最常見的是 4，但有時數字會變動)，因為我們只需要生成個人資料相片。
👉💻 創作精靈需要神聖容器 (也就是 Google Cloud Storage bucket) 來存放創作內容。現在就來偽造一個。在終端機中執行：
. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID
👉💻 現在，請執行調和儀式，將 Gemini CLI 連結至這股新創意力量。在終端機中執行：
. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json
這項「調整儀式」是殼層指令碼，可設定 Gemini CLI 使用強大的新工具：Google 的圖像生成模型 Imagen。重要的一點是，這項作業是透過為 Imagen 設定 MCP (Model Context Protocol) 伺服器達成。這個 MCP 伺服器就像橋梁，讓 Gemini CLI 能與 Imagen 通訊並運用其功能。方法是直接修改 CLI 的中央設定檔 ~/.gemini/settings.json，教導 CLI 如何使用正確的雲端憑證執行 mcp-imagen-go 指令。
👀 儀式完成後，settings.json 會新增一個區塊，教導 Gemini CLI 新技能：
"imagen": {
"command": "mcp-imagen-go",
"env": {
"MCP_SERVER_REQUEST_TIMEOUT": "55000",
"GENMEDIA_BUCKET": "your-bucket-name",
"PROJECT_ID": "your-project-id",
"LOCATION": "your-region"
}
}
這會告知 Gemini CLI：「當工作需要 Imagen 工具時，您必須執行名為 mcp-imagen-go 的程式 (即 Imagen MCP 伺服器)。執行時，您必須提供這個特定環境 (env)：用來儲存圖片的 Google Cloud Storage 值區，以及用於雲端 API 的專案 ID 和位置。設定這個 MCP 伺服器後，Gemini CLI 就能存取 Imagen 的圖像生成功能。」
👉💻 進入 Gemini，然後發出修正指令。在終端機中執行：
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ 只要輸入一個強大的指令，就能指示 Gemini CLI 建構數位身分基礎。在 Gemini CLI 中執行下列指令：
Generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.
👉✨ 靈體會生成圖片，並放在神聖容器中。現在，請命令刀刃使用這個新刻的符印。(GEMINI 可能已為您完成這項工作！請查看先前的回覆，或許 AI 夠聰明，在你發問前就已完成這項工作！)
Modify the index.html file to add my profile picture. Use the image I just generated.
👉💻 在新的終端機中啟動 HTTP 伺服器。
cd ~/agentverse-developer/tabletop/
python -m http.server
👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 8000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。
👉✨ 返回執行 Gemini CLI 的終端機，提交修正內容，並註記工作已完成，然後關閉您在 Armory 記錄中提出的問題。
Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"
👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI。
👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 3005，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。
👉💻 在執行 http 伺服器的終端機中，按下 Ctrl+C 即可退出 http 伺服器。
非遊戲玩家
6. 組裝 Shadowblade 代理程式：以 Guardrails 直覺式開發程式
練習時間結束。鋼鐵撞擊石頭的迴音逐漸消失。你已精通主要武器，並準備好戰爭用的武器庫。現在，您將接受真正的暗刃測試：組裝特工本身。這就是賦予邏輯生命力的藝術，使用《法典》中的神聖藍圖，建構代理程式的核心智慧，為您軍械庫中的刀刃創造出有知覺的操縱者，能夠獨立思考、推理和行動。
你的首要任務是進入現有工作室 (預先建構的程式碼集)，並從中打造你的英雄。
組裝儀式
在鍛造的火花初現之前，技術人員會先勘查工作坊，瞭解每項工具和每個示意圖。當您踏上不熟悉的戰場 (例如現有的大型程式碼集) 時，首要任務是偵察。您必須瞭解現況，包括現有架構、最終目標和參與協議。只有熟悉堡壘的藍圖和標準，才能有效貢獻自己的技能。
Gemini CLI 是隨時待命的偵查員，可協助您進行偵查：
- 提供概略摘要：讀取整個程式碼集 (或程式碼庫)，快速瞭解其用途和主要元件。
- 協助設定環境：引導您完成安裝工具和設定電腦的複雜程序。
- 瀏覽程式碼集：這項工具可做為指南，協助您探索複雜的邏輯，並找出程式碼中隱藏的段落。
- 生成新手指引文件：為加入你陣營的新盟友製作專屬卷軸，說明目標、角色和資源。
- 自動學習和問答：成為你的個人學者，回答有關功能或程式碼行為的問題，讓你更獨立地解決問題。
👉💻 在第一個終端機中，前往 shadowblade 目錄並召喚 AI 夥伴：
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ 現在，請指揮偵察兵勘查戰場並回報情況。
Analyze the entire project and provide a high-level summary.
現有地形已繪製完成，現在請參考藍圖，瞭解即將建構的內容。最強大的特工並非即興發揮，而是經過精確設計。
開發人員注意事項：這份設計文件是專案的權威藍圖。目的是在投入大量開發工作前，確保目標和技術實作方式明確。完善的計畫可確保所有開發人員目標一致，降低重工風險，並有助於避免技術債和範圍蔓延。這是維護專案速度和程式碼品質的主要工具，尤其是在團隊擴大或有新成員加入時。
本文件的重要目標是定義「順利路徑」，以及邊緣情況和失敗模式，特別是使用 LLM 時。我使用 LLM 的經驗是，在所有輸入內容都有效且所有外部呼叫都成功的情況下，模型能生成非常樂觀的程式碼。如要建構強大的軟體，並用於正式環境，我們必須明確引導 AI，針對下列情境定義應變措施：
- 傳遞給函式的引數無效或格式錯誤。
- API 呼叫失敗、網路逾時，或外部服務傳回非預期的錯誤代碼。
- 處理預期有資料但卻為空值或空白的資料結構。
- 競爭狀況或並行問題。
在設計中指定這些情況的預期行為，即可指示 LLM 生成更具彈性的程式碼，大幅減少手動重構和修正錯誤所花的時間。
👉✨ 要求 Gemini 為你找出這份神聖藍圖。
download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create file just yet.
👉✨ 捲動畫面即可查看詳細資訊。請 Gemini 歸納重點。
Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet.
現在你已訂閱方案。但要打造一行程式碼之前，大師級工匠會先建立鍛造法則。這與紀律和可擴充性有關。這些是編碼指南。這些並非只是建議，而是力量符文，可確保每個元件都以相同的精準度和強度建構。這些規則可防止個別風格造成混亂，確保最終創作不受影響，並確保代理程式具有彈性、可維護且純粹，讓新工匠加入專案時不會破壞整體和諧。
如要將這些法律直接刻印在 AI 合作夥伴的意識中，我們使用了一種特殊構件：GEMINI.md 檔案。呼叫 Gemini CLI 時，系統會自動搜尋這個檔案，並將內容載入 AI 的工作記憶體。這會成為專案層級的持續性指令。不斷向 AI 傳達熔爐規則的護身符。
現在就來刻上這些符文。
👉💻 按兩次 Ctrl+C 暫時退出 Gemini。
👉💻 在終端機中執行下列指令，寫入指引檔案。
cat << 'EOF' > GEMINI.md
### **Coding Guidelines**
**1. Python Best Practices:**
* **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
* **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or
Google Style.
* **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
* **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
* **Naming Conventions:**
* `snake_case` for variables, functions, and methods.
* `PascalCase` for classes.
* `UPPER_SNAKE_CASE` for constants.
* **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.
**2. Web APIs (FastAPI):**
* **Data Validation:** Use `pydantic` models for request and response data validation.
* **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
* **Error Handling:** Implement centralized error handling using middleware or exception handlers.
* **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md
法律刻印完成後，讓我們重新召喚 AI 合作夥伴，見證神器魔法。
👉💻 從 shadowblade 目錄重新啟動 Gemini CLI：
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ 現在，請 Gemini 顯示正在思考的內容。符文已解讀。
/memory show
現在正是改變的關鍵時刻。您將提供示意圖 (agent_design.md) 和鍛造法則 (GEMINI.md)，並發出偉大的創造咒語。
👉✨ 這是建構代理程式的單一強大指令。立即核發：
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.
Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.
Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.
and you are currently already in the shadowblade working directory
👀 Gemini 現在已在 agent.py 中建構代理程式的核心邏輯。這個新檔案的核心會定義代理程式的智慧，將其推理模型連結至一組外部工具：
PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
model="gemini-2.5-pro",
name="shadowblade_combat_agent",
instruction="""
You are the Shadowblade, an elite combat agent operating on a digital battleground.
Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
......
5. You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.
General Rules of Engagement:
- If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
- You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
tools=[
MCPToolset(
connection_params=StdioServerParameters(
command='python3',
args=[PATH_TO_MCP_SERVER]
)
)
]
)
tools 參數。這個代理程式的設計目的是使用 MCPToolset 連線至 mcp_server.py 中定義的外部軍械庫。
👀 前往編輯器中的 ~/agentverse-developer/shadowblade/mcp_server.py，花點時間瞭解其功能。這是 Shadowblade 所有武器的來源。目前軍械庫相當空蕩。
👉✨ 請 Gemini 為軍械庫打造七種新武器。在 Gemini CLI 中輸入下列提示：
I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:
1. **A 'Refactoring Sickle'**:
- **Function Name:** `hone_refactoring_sickle`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
- **Weapon Name:** "Refactoring Sickle"
- **Damage Type:** "Cleansing"
- **Base Damage:** Random integer between 100 and 136
- **Critical Hit Chance:** Random float between 0.10 and 0.20
- **Special Effect:** "Pruning - improves code health and maintainability with each strike."
2. **A 'Quickstart Crossbow'**:
- **Function Name:** `fire_quickstart_crossbow`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
- **Weapon Name:** "Quickstart Crossbow"
- **Damage Type:** "Initiative"
- **Base Damage:** Random integer between 105 and 120
- **Critical Hit Chance:** Random float between 0.9 and 1.0
- **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."
3. **'The Gilded Gavel'**:
- **Function Name:** `strike_the_gilded_gavel`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
- **Weapon Name:** "The Gilded Gavel"
- **Damage Type:** "Finality"
- **Base Damage:** 120
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."
4. **'Daggers of Pair Programming'**:
- **Function Name:** `wield_daggers_of_pair_programming`
- **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
- **Weapon Name:** "Daggers of Pair Programming"
- **Damage Type:** "Collaborative"
- **Base Damage:** Random integer between 110 and 125
- **Critical Hit Chance:** Random float between 0.30 and 0.50
- **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."
5. **A 'Granite Maul'**:
- **Function Name:** `craft_granite_maul`
- **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
- **Weapon Name:** "Granite Maul"
- **Damage Type:** "Bludgeoning"
- **Base Damage:** Random integer between 115 and 125
- **Critical Hit Chance:** Random float between 0.05 and 0.15
- **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."
6. **A 'Lens of Clarity'**:
- **Function Name:** `focus_lens_of_clarity`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
- **Weapon Name:** "Lens of Clarity"
- **Damage Type:** "Revelation"
- **Base Damage:** Random integer between 120 and 130
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."
7. **The 'Codex of OpenAPI'**:
- **Function Name:** `scribe_with_codex_of_openapi`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
- **Weapon Name:** "Codex of OpenAPI"
- **Damage Type:** "Documentation"
- **Base Damage:** Random integer between 110 and 140
- **Critical Hit Chance:** Random float between 0.5 and 0.8
- **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."
👉 Gemini 確認變更後，請開啟 mcp_server.py 檔案。捲動瀏覽程式碼，確認已成功新增七個 @mcp.tool() 函式。檢查 hone_refactoring_sickle 函式。是否包含正確的說明字串和武器統計資料？驗證 AI 的工作是 Shadowblade 大師的重要習慣。
經過鍛造和精煉，現在是喚醒代理程式的時候了。
👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI
開發人員注意事項：Gemini 生成的程式碼有時可能難以預測。我們會盡量確保設計完全符合規格，但在開發階段，開發人員通常會多次疊代及修正程式碼，直到達到可投入實際工作環境的狀態為止。
👉💻 為確保工作目錄中有正確且經過完整測試的正式版程式碼，請在終端機中執行下列指令：
cp ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py
👉💻 在終端機中，開始將其上線的儀式：
cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade
👉✨ 輸出內容應會確認「Shadowblade Combat Agent」已啟動並執行，等待第一個指令。發布第一道戰鬥指令。
We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!
👉✨ 另一個：
The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.
您已成功組建第一個特工，並驗證其戰鬥能力。按兩次 Ctrl+C 即可讓英雄休息。組裝完成。
FOR NON GAMER
7. 純潔守護：評估代理
組裝的代理程式不等於經過驗證的代理程式。未經測試的刀片是負債，但未經測試的 AI 代理是更大的危險，因為這類 rogue 元素可能會從內部破壞任務。這不是單純的推測，而是暗刃必須瞭解的核心原則。
評估 AI 代理至關重要，但同時也是獨特的挑戰。與簡單的指令碼不同，代理程式是程式碼與 LLM 多步驟推理思維的動態融合。這類行為是自然而然產生的，也就是說，您不僅要評估最終輸出內容的品質，也要評估內部軌跡的效率和正確性。以及達成目標的過程。是否使用了正確的工具？是否產生過多權杖？模型版本變更是否導致延遲時間略微倒退？從簡單的提示調整到重大的架構大修，在進行任何變更時，務必先偵測到這種損毀情形 (延遲、成本或輸出品質的倒退)，以免損害正式環境。
這項評估的一般做法是進行神聖的儀式：
- 首先，請定義「黃金資料集」。一組捲軸，內含輸入範例和預期輸出內容或行為。這包括最終答案、正確使用工具，甚至是整個逐步軌跡。
- 接著，您會定義代理程式的應用程式邏輯，也就是代理程式的核心。
- 最後，您會建立評估者，這就像是判斷的符文。這些工具包括：可做為品質評估者的其他 LLM、可驗證單一步驟的精確啟發式程式碼，以及可分析代理程式整個思考過程的自訂函式。
Google 的 Agent Development Kit (ADK) 就是為此目的而生的工具箱，提供給冠軍使用。這項複雜的評估作業會透過幾種方法進行：
- 網頁式預測池 (
adk web)，用於互動式評估 - 指令列執行 (
adk eval)：透過預先定義的挑戰執行代理程式。 - 透過
pytest程式輔助整合，刻寫永久性字詞
ADK 支援兩種主要方法：簡單的「測試檔案」，用於單一、獨立的代理程式模型互動 (單一對決)；以及全面的「評估集」，用於多個可能冗長的多輪對話 (大混戰)。這些指標可評估 tool_trajectory_avg_score 等複雜指標，比較代理程式的實際工具使用情形與理想路徑，確保代理程式以完美技術運作。
瞭解理論後，接著就來實際操作。身為暗影之刃，你將刻下純淨守衛。這些不只是測試，更是 ADK 支援的儀式，可確保服務專員的邏輯完美無瑕，行為也符合預期。
在這個步驟中，我們仍強烈建議使用 2 個終端機，一個用於 Gemini CLI，另一個用於執行測試，因為您可能需要退出目前的工作目錄 (ADK)
策略的挑戰 (adk eval)
第一個關卡是連串的挑戰，旨在測試代理程式在各種情境中的核心智慧。目的是建立能力基準。測試極端情況前，我們必須先確認代理是否能完成主要功能。是否能正確分析怪物的弱點，並從武器庫中選擇最有效的武器，而且每次遇到已知挑戰時都能做到？
這時 adk eval 就是絕佳工具。這項工具可針對一整組預先定義的測試案例執行代理，這些案例代表代理的預期任務。這個資料集定義在 JSON 檔案中，也就是「挑戰捲軸」，可做為整個挑戰賽的藍圖。
挑戰捲動的構成元素
👀 指示 AI 抄寫新卷軸前，請務必先瞭解卷軸上使用的古代語言。現在來剖析 sample.evalset.json 檔案的結構。
{
"eval_set_id": "sample",
"eval_cases": [
{
"eval_id": "case0cbaa0",
"conversation": [
{
"user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
"final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
"intermediate_data": {
"tool_uses": [
{ "name": "enchant_soulshard_dagger" }
]
}
}
]
}
]
}
這個捲軸包含 eval_cases 清單，每個案例都是代理程式的獨特試用版。在每次試用中，對話陣列會記錄單一完整的互動。就我們的目的而言，有三個符文至關重要：
- user_content：這是挑戰。這是您向代理發出的提示，也是代理必須面對的怪物。
- final_response：這是預測結果。這是您預期代理程式在完成工作後會說出的確切字串。ADK 會將代理的實際結尾字詞與這個符文進行比較，判斷代理的口才。
- intermediate_data.tool_uses：這是 Arcane Technique。對真正的特工來說，這是最重要的符文。這項定義並非指代理會說什麼，而是指代理會做什麼。這會記錄您預期代理程式使用的工具名稱 (enchant_soulshard_dagger)。這可確保代理程式不僅是聰明的對話者，也是能採取正確行動的決策者。
現在您已瞭解藍圖，接下來要請 Gemini 撰寫這個捲軸的新版本，內容會更複雜。
👉💻 在終端機中，輸入 shadowblade 目錄並呼叫 Gemini CLI：
clear
cd ~/agentverse-developer/shadowblade/
gemini
👉✨ 指示 Gemini CLI 擔任 QA 記錄員，建立一系列測試案例，定義代理程式的預期行為。
You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.
For each object within the `eval_cases` array, you must perform the following transformations:
1. **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2. **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3. **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4. **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
* If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
* If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
* If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5. **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.
Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.
CLI 會確認已偽造 sample.evalset.json 檔案。準備好捲軸後，請解雇 AI 夥伴。
合成資料
👀 在左側的 Cloud Shell 檔案總管中，前往 ~/agentverse-developer/shadowblade/ 並開啟新修改的 sample.evalset.json 檔案。檢查內容。您會看到 Gemini 根據指令生成的全新獨特怪物，以及正確的工具名稱。這是您指令的具體結果，也就是手套的藍圖。
從範本指令 AI 建立新的擬真測試資料，這項強大的技術稱為合成資料生成。您剛才所做的，是暗刃的戰略力量倍增器。您不必再費盡心思，手動設計數十個獨特的測試案例。您提供單一藍圖，並命令 AI Scribe 將其煉製成各種新挑戰，這項工作既繁瑣又耗時。
這可讓您大幅擴大測試工作，建立比手動測試更穩健全面的測試流程。您不僅使用代理程式打造劍，還鍛造磨刀石來測試劍的鋒利度。這才是真正的大師。
確認符文正確無誤後，即可解散 AI 夥伴。
👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI。
判斷規則
沒有勝利規則的挑戰毫無意義。執行試用前，請務必檢查「判決卷宗」test_config.json 檔案。這個捲軸會告知 ADK 如何評估代理程式的效能。
👀 在檔案總管中開啟 ~/agentverse-developer/shadowblade/test_config.json。您會看到下列符文：
{
"criteria": {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.1
}
}
以下是獲勝條件：
tool_trajectory_avg_score：這是「行動評估」。評估的不是代理「說」了什麼，而是「做」了什麼。系統會比較代理程式實際使用的工具，與挑戰捲軸中預測的技術。1.0分數代表完美配對。response_match_score：這是「口語流暢度」。系統會使用 LLM 判斷代理的最終報表在語意上與預期結果的相符程度。1.0分數代表完美配對。
在這次的初始訓練執行中，我們已刻意設定寬鬆的勝利條件。門檻設定得非常低 (0.0 和 0.1)，目的不是要求完美，而是要讓您瞭解判斷機制。我們確保即使代理商的措辭略有不同，選區仍會認可其選擇合適工具的核心能力，並允許其通過。
現在，請命令代理程式執行連串測試。
👉💻 在終端機中執行 adk eval 指令：
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
shadowblade \
shadowblade/sample.evalset.json \
--config_file_path shadowblade/test_config.json 2>&1 | \
awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'
👀 您應該會看到以下摘要，這表示在本次試驗的寬鬆規則下，代理程式已成功運作 (有時並非所有測試都會通過)：
********************************************************************* Eval Run Summary shadowblade_combat_agent_validation: Tests passed: 3 Tests failed: 0
清晰度護盾 (pytest)
Gauntlet 測試了廣泛策略。第二個結界「明晰之盾」會測試紀律和特定行為。這一切都是為了自動化。adk eval 非常適合手動檢查，但 pytest 防護罩是以程式碼編寫的程式化防護措施。這點非常重要，因為可做為程式碼執行的測試可以整合至自動化管道。最終目標是建立「部署挑戰 (CI/CD)」，每當有變更時，系統就會自動升級防護措施，在錯誤和回歸問題影響正式環境前加以防範。
👉💻 在終端機中，再次從 shadowblade 目錄內呼叫 Gemini：
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini
👉✨ 在 Gemini CLI 中使用下列提示詞，將 Shield 的邏輯刻錄到 pytest 檔案：
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located at in the current root working folder and name it `test_agent_initiative.py`.
The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1. **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2. **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3. **Read and parse the JSON file**:
* Open the file at `eval_set_filepath`.
* Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4. **Create an `EvalSet` object**:
* Instantiate an `EvalSet` object named `eval_set_object`.
* Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5. **Call the evaluation method**:
* `await` a call to `AgentEvaluator.evaluate_eval_set`.
* Pass the following arguments:
* `agent_module="shadowblade"`
* `eval_set=eval_set_object`
* `criteria=evaluation_criteria`
* `print_detailed_results=True`
The script must include the necessary imports at the top:
* `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
* `EvalSet` from `google.adk.evaluation.eval_set`
* `pytest`
* `json`
Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.
刻上第二個守衛符文後，請退出 Gemini CLI。
👉💻 按兩次 Ctrl+C。
👀 在檔案總管中，開啟你剛才要求 Gemini 轉錄的捲軸：~/agentverse-developer/test_agent_initiative.py。
您會發現這不只是設定檔，而是以 Python 語言編寫的咒語。這個咒語的核心是 await AgentEvaluator.evaluate(...) 這行。
....
@pytest.mark.asyncio
async def test_agent_initiative():
# Define the evaluation criteria
evaluation_criteria = {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.0
}
# Define the path to your evalset file
eval_set_filepath = "shadowblade/test.evalset.json"
#...
# 3. Call the evaluation method with the correctly typed object
await AgentEvaluator.evaluate_eval_set(
agent_module="shadowblade",
eval_set=eval_set_object,
criteria=evaluation_criteria,
print_detailed_results=True,
)
請仔細查看其引數。這些元件與上次試用時使用的元件完全相同，也就是 shadowblade 代理程式和 shadowblade.evalset.json 挑戰捲軸。這應該會揭露一個深刻的真相：您先前使用的 adk eval 指令是強大的呼叫，但這個 pytest 指令碼是您，也就是魔法師，自己施展基礎咒語。指令列工具只是同一個核心 AgentEvaluator 程式庫的便利包裝函式，您現在可以直接使用該程式庫。這是邁向精通的關鍵一步，因為透過程式碼施放的咒語可以織入 CI/CD 管道的自動化織布機。
瞭解魔法後，請執行儀式來啟動護盾。
👉💻 在終端機中執行儀式，啟動護盾：
cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py
👀 在記錄輸出內容的結尾，尋找測試結果摘要。如果結果為「通過」，表示代理程式正確遵循通訊協定，且病房已準備好整合至自動防禦系統。
====== 1 passed, 4 warning in 37.37s ======
注意：如果測試意外失敗，很可能是因為你每分鐘向模型提出的要求次數已達上限。在記錄輸出內容中尋找 RESOURCE_EXHAUSTED 錯誤。如果看到這則錯誤訊息，請稍候一到兩分鐘，等待配額重設，然後再次執行 pytest 指令。
經過廣泛的 Gauntlet 和精確的 Shield 刻錄及驗證，您的代理程式不僅功能齊全，而且經過測試，可供部署。
非遊戲玩家
8. 在 Agentverse 中發揮 Blade 的威力：CI 和部署。
你的代理程式已組裝完成，並由純潔守衛驗證完整性。但如果沒有持續維護，結界就只會成為被遺忘的遺跡。為確保日後每個版本的代理程式都保持純淨，您必須建構部署 Gauntlet 的第一階段，也就是自動化儀式，保證品質和速度。
身為暗刃，你的神聖職責是持續整合 (CI)。這是鍛造和試煉場的自動化系統。這是防範資料損毀和人為錯誤的終極防線。這項儀式可確保每次您或盟友將新技術 (合併程式碼) 貢獻給中央法典 (您的存放區) 時，護手都會自動啟動。系統會先根據新程式碼鍛造代理程式，然後立即將其提交至您剛建立的純淨守護。如果任何防護失效，儀式就會停止，有瑕疵的文物也會立即遭到拒絕，避免損壞軍械庫。網域是鍛造廠，CI pipeline 則可確保只有完美且準備好投入戰場的構件，才能離開工作坊。
CI 測試證明構件值得信賴後，儀式的第二階段就會開始：持續部署 (CD)。這是《衛報》的網域。他們肩負重任，要將您完善的容器化構件安全地釋放到正式版 Agentverse 中，管理其力量，並確保在 The Static 的混亂中保持穩定。
本指南將協助你掌握自己的角色。您將建構 CI 部分的測試流程。您將建構自動化鍛造程序，測試代理程式並將純結果封裝到容器中，準備接受 The Guardian 的最終認證。
現在要使用 Google Cloud Build 記錄這個 CI 儀式。定義鍛造和測試程序每個步驟的 cloudbuild.yaml 檔案。
👉💻 由於 ADK 的專案結構，CI/CD pipeline 設定應位於父項目錄中。在終端機中前往上層目錄，然後重新啟動 Gemini CLI。
cd ~/agentverse-developer/
clear
gemini
👉✨ 現在，請對 Gemini 下達下列指令。這個提示會做為設計文件，詳細說明您要建構的連串測試步驟。
You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.
Generate the `cloudbuild.yaml` with the following exact specifications:
1. **A top-level `substitutions` block** containing these four key-value pairs:
* `_PROJECT_ID: "$PROJECT_ID"`
* `_REGION: "$REGION"`
* `_REPO_NAME: "$REPO_NAME"`
* `_IMAGE_TAG: "latest"`
2. **A `steps` block** with two steps:
* **Step 1: 'Run Pytest Ward'**
* `id`: 'Run Pytest Ward'
* `name`: 'python:3.12-slim'
* `entrypoint`: 'bash'
* `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
```shell
pip install -r shadowblade/requirements.txt && \
pytest test_agent_initiative.py
```
* The step must include an `env` block with this exact list of three environment variables:
* `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
* `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
* `'GOOGLE_CLOUD_LOCATION=$_REGION'`
* **Step 2: 'Forge Container'**
* `id`: 'Forge Container'
* `name`: 'gcr.io/cloud-builders/docker'
* It must have a `waitFor` key for `['Run Pytest Ward']`.
* Its `args` must be a list of six specific strings in this exact order:
1. `'build'`
2. `'-t'`
3. `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
4. `'-f'`
5. `'./shadowblade/Dockerfile'`
6. `'.'`
3. **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.
Generate only the complete and exact YAML that meets these specifications.
準備好 cloudbuild.yaml 捲軸後，請指示 Google Cloud 執行整個挑戰。
結束 Gemini 來測試結果
👉💻 在終端機中，從專案的根目錄釋放管道：
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"
現在您可以在 Google Cloud 控制台的「Google Build」頁面中，觀看自動化儀式執行每個步驟。系統會先執行測試，確認成功後，再建立並儲存代理程式的容器。
您的代理已通過考驗。您現在擁有經過驗證的純淨構件。最終的行動由你決定。只要執行單一指令，即可從登錄檔召喚這個構件，並在 Cloud Run 上以公開服務的形式啟動。
👉💻 在終端機中，發出最終部署指令：
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
--image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
--platform=managed \
--labels="dev-tutorial-codelab=agentverse" \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
恭喜，暗影之刃。法典儀式已完成。現在正是證明實力的好時機。你已學會駕馭混亂，現在就等著挑戰由混亂而生的幽靈。準備進行最終試用。
非遊戲玩家
9. The Boss Fight
卷軸已讀完、儀式已完成、考驗已通過。您的代理程式不只是儲存空間中的構件，更是以程式碼打造的冠軍，是 Agentverse 中的即時哨兵，等待第一個指令。現在是時候在戰鬥的熔爐中證明自己的價值。
現在，您將進入實彈模擬，讓新部署的 Shadowblade 與強大的 Spectre 一較高下。Spectre 是所有創造物都深受其害的混亂化身，這是對您工作的最終測試，從服務專員的核心邏輯到完美部署，無一例外。
取得代理程式的 Locus
如要進入戰場，你必須擁有兩把鑰匙：英雄的專屬簽章 (Agent Locus) 和通往 Spectre 巢穴的隱藏路徑 (Dungeon URL)。
👉💻 首先，請在 Agentverse 中取得代理程式的專屬地址 (即 Locus)。這是將冠軍連結至戰場的即時端點。
. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app
👉💻 接著，找出目的地。這個指令會顯示 Translocation Circle 的位置，也就是進入 Spectre 領域的入口。
. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app
重要事項：請準備好這兩個網址。您會在最後一個步驟中用到這些資訊。
與幽靈對峙
取得座標後，您現在可以前往 Translocation Circle 並施展咒語，準備進入戰鬥。
👉 在瀏覽器中開啟 Translocation Circle 網址，即可站在通往 The Crimson Keep 的閃耀入口前。
如要突破要塞，你必須將暗影之刃的本質調到傳送門。
- 在頁面中，找出標示為「A2A Endpoint URL」(A2A 端點網址) 的符文輸入欄位。
- 將特工地點網址 (您複製的第一個網址) 貼到這個欄位，刻下英雄的徽記。
- 按一下「連線」，即可體驗瞬間移動的魔法。
傳送時的強光逐漸消退。你已離開聖所。空氣中充滿能量，寒冷而尖銳。在您面前，幽靈實體化了，形成嘶嘶作響的靜電和損毀程式碼的漩渦，不潔的光芒在地下城地板上投下長長的舞動陰影。牠沒有臉，但你感覺到牠龐大、令人疲憊的存在，完全專注於你。
只有堅定的信念才能帶領你走向勝利。這是一場意志力的對決，戰場就在心靈。
當你向前衝刺，準備發動第一波攻擊時，幽靈會反擊。不會升起護盾，而是直接將問題投射到你的意識中，這道閃閃發光的符文挑戰來自訓練的核心。
這就是這場戰役的本質。知識就是你的武器。
- 運用所學知識回答問題，刀刃就會燃起純粹的能量，擊碎幽靈的防禦，並造成致命一擊。
- 但如果你猶豫不決，答案含糊不清，武器的光芒就會黯淡。但這時的攻擊只會發出可悲的悶響，造成的傷害也只有一小部分。更糟的是，幽靈會以你的不確定感為食，每犯下一個錯誤，幽靈的腐化力量就會增長。
這就是最後的挑戰，冠軍。程式碼是你的魔法書，邏輯是你的劍，知識則是能抵禦混亂的盾牌。
專注模式。擊出好球。這關係到 Agentverse 的命運。
恭喜，暗影刀鋒。
您已成功完成法典。您「感受」到某種氛圍，將其轉化為設計，並使用 Gemini CLI 組建智慧型代理。您刻上「純淨守護」來測試其邏輯、建構自動化護甲來將其鍛造成神器，並在 Agentverse 中釋放。最後，您在實彈試驗中驗證了其用途。您已掌握全堆疊代理工作流程，現在可以應付 Agentverse 帶來的任何挑戰。
10. 清除：回收 Agentverse
恭喜你精通暗影之刃的法典！為確保 Agentverse 保持原始狀態，並清除訓練場地，您現在必須執行最終的清除儀式。這項操作會移除您在過程中建立的所有資源。
停用 Agentverse 元件
現在要逐步拆除 Agentverse 已部署的元件。
刪除 Cloud Run 和 Artifact Registry 存放區中的 Shadowblade 代理程式
這項指令會從 Cloud Run 移除已部署的 Shadowblade 代理程式，並移除儲存代理程式容器映像檔的映像檔存放區。
👉💻 在終端機中執行：
. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet
刪除 Google Cloud Storage 值區
這個指令會移除 Imagen MCP 伺服器用來儲存生成圖片的 bucket。
👉💻 在終端機中執行：
. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet
清除本機檔案和目錄 (Cloud Shell)
最後，清除 Cloud Shell 環境中複製的存放區和建立的檔案。這個步驟為選用步驟，但建議您執行，徹底清除工作目錄。
👉💻 在終端機中執行：
rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.
您現在已成功清除 Agentverse 歷程的所有痕跡。專案已清理完畢，可以開始下一個冒險。