1. Overture
孤立開發的時代即將結束。下一波技術演進浪潮並非天才的獨門絕技，而是協作的精髓。建立單一智慧代理程式是一項有趣的實驗。建構強大、安全且智慧的代理程式生態系統 (也就是真正的 Agentverse)，是現代企業面臨的重大挑戰。
在這個新時代，要取得成功，就必須整合四個重要角色，也就是支撐任何蓬勃發展的代理式系統的基礎支柱。任何一個領域的不足都會造成弱點，進而危害整個結構。
這場研討會是企業必備的實用指南，可協助您在 Google Cloud 上掌握 AI 代理的未來趨勢。我們提供端對端藍圖，引導您從最初的想法，到全面運作的現實。在四個相互連結的實驗室中，您將瞭解開發人員、架構師、資料工程師和 SRE 的專業技能如何匯聚，共同建立、管理及擴充強大的 Agentverse。
單一支柱無法單獨支援 Agentverse。如果沒有開發人員的精確執行，架構師的宏偉設計就毫無用處。如果沒有資料工程師的智慧，開發人員的代理程式就無法運作；如果沒有 SRE 的保護，整個系統就會很脆弱。唯有透過協同合作，並對彼此的角色有共同的瞭解，團隊才能將創新概念轉化為攸關任務的營運實務。您的旅程由此開始。準備好精通自己的角色，並瞭解自己如何融入整體架構。
歡迎參加「The Agentverse：A Call to Champions」
在企業廣闊的數位領域中，新時代已然來臨。我們正處於代理時代，這個時代充滿無限可能，智慧型自主代理能完美協作，加速創新並消除日常瑣事。
這個連結的生態系統充滿力量和潛力，我們稱之為「Agentverse」。
但一種稱為「靜態」的無聲腐敗，已開始侵蝕這個新世界的邊緣。「靜態」並非病毒或錯誤，而是混亂的化身，以創作行為本身為食。
這些舊有的挫敗感會以可怕的形式放大，進而催生出七大開發幽靈。如果未勾選，The Static 和其 Spectres 會讓進度停滯不前，將 Agentverse 的承諾變成技術債和廢棄專案的荒地。
今天，我們呼籲各界好手挺身而出，力挽狂瀾。我們需要英雄精通自己的技藝，並攜手合作保護 Agentverse。現在來選擇路徑吧。
選擇課程
您面前有四條截然不同的道路，每一條都是對抗「靜態」的關鍵支柱。雖然訓練是單人任務，但最終能否成功取決於你是否瞭解自己的技能如何與他人結合。
- 暗影刀鋒 (開發人員)：擅長打造武器，並在第一線作戰。您是工匠，負責打造刀刃、製作工具，並在複雜的程式碼細節中面對敵人。你的道路充滿精準、技能和實用創作。
- 召喚師 (架構師)：偉大的策略家和自動調度管理工具。您不會看到單一特務，而是整個戰場。您設計的藍圖可讓整個代理程式系統通訊、協作，並達成遠遠超出任何單一元件的目標。
- 學者 (資料工程師)：尋找隱藏的真相，並守護智慧。您深入廣闊的資料荒野，發掘可賦予代理程式目標和視野的智慧。你的知識可以揭露敵人的弱點，或賦予盟友力量。
- 守護者 (開發運作 / SRE)：領域的堅定守護者和盾牌。您要建造堡壘、管理電力供應線，並確保整個系統能抵禦「靜電」的攻擊。你的力量是團隊獲勝的基礎。
你的任務
訓練會以獨立運動的形式開始。您將選擇適合自己的路徑，學習精通職務所需的獨特技能。試用期結束時，您將面對由靜態所生的幽靈，這個迷你首領會利用您創作時遇到的特定挑戰。
只有精通個人角色，才能為最終試用做好準備。然後與其他班級的冠軍組成隊伍。你們將一同深入腐敗的核心，迎戰最終魔王。
最後的合作挑戰，將考驗你們的綜合實力，並決定 Agentverse 的命運。
Agentverse 等待英雄的到來。你會接聽電話嗎？
2. 暗影之刃的法典
你面前攤開的是暗影之刃的法典。接聽來電。靜態的混亂蔓延威脅著 Agentverse，只有精通本法典技術的人才能反擊。這是一條精準和自律的道路。今天起，你將開始接受訓練。您將學會如何運用 AI，不只是當成簡單的工具，而是當成有知覺的刀刃，必須馴服並精通。請按照本文的教導，打造純粹邏輯的武器，也就是經過磨練、準備好上戰場的智慧型代理程式。
課程內容
- 運用主要武器：Gemini CLI。
- 將 MCP 工具與 Gemini CLI 整合，即可呼叫外部工具，分析不熟悉的程式碼集。
- 使用設計文件將意圖轉化為「氛圍」，藉此指揮 AI 合作夥伴。
- 使用 Agent Development Kit (ADK) 建構第一個自主代理，打造乾淨的模組化解決方案。
- 建構自動化評估套件，測試及驗證代理程式。
- 建構完整的 CI 管道，自動測試、容器化及封存代理程式。
3. 準備訓練場地
👉點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」(這是 Cloud Shell 窗格頂端的終端機形狀圖示) 
👉按一下「Open Editor」(開啟編輯器) 按鈕 (類似於開啟資料夾和鉛筆的圖示)。這會在視窗中開啟 Cloud Shell 程式碼編輯器。左側會顯示檔案總管。
👉找出 Google Cloud 專案 ID：
- 開啟 Google Cloud 控制台：https://console.cloud.google.com
- 在頁面頂端的專案下拉式選單中，選取要用於本研討會的專案。
- 專案 ID 會顯示在資訊主頁的「專案資訊」資訊卡中
👉在雲端 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
👉💻 執行初始化指令碼，系統會提示您輸入 Google Cloud 專案 ID。並在 init.sh 指令碼提示時，輸入上一個步驟中找到的 Google Cloud 專案 ID。
cd ~/agentverse-developer
./init.sh
👉💻 設定所需的專案 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 --yolo
如果系統詢問 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 中建立自己的形象。接著，您將啟用本機的進階工具 (MCP 伺服器)，並將刀鋒伺服器調校至適當頻率，藉此擴展力量，以簡單明確的指令執行管理程式碼存放區等複雜操作。
建立你的創作者標記
真正的暗影刀鋒不僅以武器聞名，更以獨特的風格 (即製作者的標記) 著稱。這個標記就是你的數位形象，是向 Agentverse 宣告你身分的個人檔案。在這裡，您會命令 Gemini Blade 執行定義這個身分所需的複雜技術。
👉💻 如果您已關閉上一節的 Gemini CLI，請務必重新啟動，在終端機中執行
clear
cd ~/agentverse-developer/tabletop
gemini --yolo
👉✨ 只要一個強大的指令，就能指示 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.
Gemini 已計算出所需的一連串動作。
只有在實際情況中，才能看出技術的真正價值。下達指令給刀鋒伺服器，啟動本機模擬。
👉✨ 在 Gemini CLI 中發出模擬指令：
Use Python's built-in web server to start the Shadowblade Profile website you just created.
Gemini 會確認模擬功能已啟用。
👀 Gemini CLI 會遵守指令，確認模擬作業已啟動，且數位浮水印已上線：
The website is now being served on port 8000. You can access it at http://localhost:8000.
注意：刀片可能需要嘗試幾次才能正確執行這項操作。如果嘗試 3 到 4 次後問題仍未解決，請輸入 /quit 或按兩次 Ctrl+C 鍵，退出 Gemini CLI，然後在終端機中執行下列指令：👉💻
python3 -m http.server
👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 8000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。
你的網站可能與我的不同。這是您的專屬標記。
👉✨ 簽章技術現已改良，不再需要進行即時模擬。命令 Blade 停止行動。
Stop the Shadowblade Profile website
👉💻 注意：如果不是在 Gemini CLI 中執行這項操作，請按 Ctrl+C 鍵退出 http 伺服器。
您已成功指示 Gemini CLI 代表您執行一系列動作。但暗影刀鋒大師知道，真正的力量需要紀律和遠見。允許 AI 代理直接在環境中執行指令是一把雙面刃。如果指令不是啟動簡單的網頁伺服器，而是刪除重要檔案，一個不慎的指令就可能摧毀整個訓練場。
因此，最明智的工匠會在受保護的訓練場地 (也就是稱為沙箱的封閉維度) 中，練習最強大或未經測試的技術。
👉💻 按下 Ctrl+C 鍵兩次，即可退出 Gemini CLI
Gemini CLI 沙箱 (gemini --sandbox) 會為工作階段建立暫時的獨立容器。AI 執行的任何指令、寫入的任何檔案，以及啟動的任何程序，都只存在於該虛擬領域。無法觸及、變更或損壞實際的 Cloud Shell 環境。您可以在這裡測試強大的新工具、分析不熟悉的程式碼，或向 AI 提供複雜的指令，而不必擔心造成非預期的後果。體現了暗刃的謹慎。
👉💻 現在，請執行儀式，瞭解容器的力量。
clear
gemini --sandbox --yolo
- 如果系統要求您
Do you want to connect Cloud Shell editor to Gemini CLI?，請選擇「NO」。 - 如果系統提示登入，請按照指示操作，並務必使用 Google 帳戶登入
您現在已在獨立維度中作業。對 Gemini CLI 而言，一切都會看似正常。讓我們來證明。
👉💻 指示刀片執行與先前完全相同的技術：
Use the Python's built-in web server to start the Shadowblade Profile website, you just created.
Gemini 會回報成功，並認為已再次將網站帶回 8000 埠。但結界依然堅固。
👉 前往「網頁預覽」，嘗試透過通訊埠 8000 查看網站。
這次您會遇到錯誤。連線會失敗。無法存取網站。
這並非工具故障，而是沙箱功能強大的證明。網路伺服器「正在」執行，但執行位置是在容器維度內，與瀏覽器和外部世界完全隔離。結界運作正常。您已成功運用強大的技術，但對實際環境沒有任何影響。
👉💻 按兩次 Ctrl+C 即可結束 Gemini CLI。
您現在已建立數位身分，更重要的是，您已學會運用強大力量時，更要謹慎行事的關鍵智慧。
啟用本機軍械庫：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 的行為、外觀，以及最重要的，可運用的外部功能。這個檔案通常位於主目錄的 ~/.gemini/settings.json，並將規則套用至所有專案。不過，您也可以在專案資料夾內的 .gemini 目錄中建立專案專用的 settings.json 檔案，覆寫全域設定。
"mcpServers": {
"gitea": {
"url": "http://localhost:8085/sse"
}
}
這項設定會告訴 Gemini：「名為 gitea 的軍械庫已啟動，並在特定網路位址監聽指令。」
👉💻 重新進入 Gemini CLI。在終端機中執行：
clear
cd ~/agentverse-developer/tabletop/
gemini --yolo
👉✨ 確認刀刃已發現新武器。指令機器人透過 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 --yolo
👉✨ 只要一個強大的指令，就能指示 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.
👉✨ 最後一次啟動網站，欣賞完美的作品。
start the website with a simple HTTP server via Python
👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 8000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。
👉✨ 最後，請提交修正內容，註明工作已完成，並關閉您在軍械庫記錄中提出的問題。
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"
👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 3005，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。
👉✨ 在 Gitea 中確認圖片已更新，且問題已解決。你的工作已完成。關閉伺服器。
stop website server
👉💻 按兩次 Ctrl+C 即可退出。
非遊戲玩家
6. 組裝 Shadowblade Agent：以直覺方式開發程式，並使用 Guardrails
練習時間結束。鋼鐵撞擊石頭的迴音逐漸消失。您已精通主要武器，並準備好戰爭用的武器庫。現在，您將接受真正的暗刃測試：組裝特工本身。這就是賦予邏輯生命力的藝術，使用《法典》中的神聖藍圖建構代理程式的核心智慧，為武器庫中的刀刃創造出有知覺的持有者，讓他們能夠獨立思考、推理和行動。
你的首要任務是進入現有工作室 (預先建構的程式碼集)，並從中打造你的冠軍。
組裝儀式
在鍛造的火花初現之前，技術人員會先勘查工作坊，瞭解每項工具和每個示意圖。踏上陌生的戰場 (例如現有的大型程式碼集) 時，首要任務是偵察。您必須瞭解現有架構、最終目標和參與協議，才能掌握大局。只有熟悉堡壘的藍圖和標準，才能有效貢獻自己的技能。
Gemini CLI 是隨時待命的偵查兵，可協助您進行偵查：
- 提供概略摘要：讀取整個程式碼集 (或程式碼庫)，快速瞭解其用途和主要元件。
- 協助設定環境：可引導您完成安裝工具和設定電腦的複雜程序。
- 瀏覽程式碼集：這項功能可做為指南，協助您探索複雜的邏輯，並找出程式碼中隱藏的段落。
- 產生新成員加入文件：為新加入的盟友製作專屬卷軸，說明目標、角色和資源。
- 自動學習和問答：成為你的個人學者，回答有關功能或程式碼行為的問題，讓你更獨立地解決問題。
👉💻 在第一個終端機中，前往 shadowblade 目錄並召喚 AI 夥伴：
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --yolo
👉✨ 現在，請指揮偵察兵勘查戰場並回報情況。
Analyze the entire project and provide a high-level summary.
現有地形已繪製完成，現在請參考藍圖，瞭解接下來要建造的內容。最強大的特工並非即興發揮，而是經過精確設計。
開發人員注意事項：這份設計文件是專案的權威藍圖。目的是在投入大量開發工作前，確保目標明確，並清楚瞭解技術實作方式。完善的計畫可確保所有開發人員目標一致，降低重工風險，並有助於避免技術債和範圍蔓延。這是維護專案速度和程式碼品質的主要工具，尤其是在團隊擴大或新成員加入時。
本文件的重要目標是定義「順利路徑」，以及邊緣情況和失敗模式，特別是使用 LLM 時。如果所有輸入內容都有效，且所有外部呼叫都成功，我使用 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 --yolo
👉✨ 現在，請 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 輸出內容的注意事項：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 即可讓英雄休息。組裝完成。
適合非遊戲玩家
7. 純淨守護：評估代理程式
組裝的代理程式不等於經過驗證的代理程式。未經測試的刀片是負債，但未經測試的 AI 代理是更大的危險，因為這類代理可能會成為流氓元素，從內部破壞任務。這並非只是推測，而是暗刃必須瞭解的核心原則。
評估 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)
這個第一關是連串的挑戰，旨在測試 AI 代理程式在各種情境中的核心智慧。目的是建立能力基準。測試極端情況前，我們必須先確認代理能否完成主要功能。是否能正確分析怪物的弱點，並從武器庫中選出最有效的武器，而且每次遇到已知挑戰時都能做到？
這時 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 --yolo
👉✨ 指示 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 從範本建立新的擬真測試資料的行為，就是所謂的合成資料生成技術。您剛才所做的，是 Shadowblade 的戰略力量倍增器。不必再費盡心思手動製作數十個獨特的測試案例，您提供單一藍圖，並命令 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 --yolo
👉✨ 在 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. 將 Blade 釋放到 Agentverse：CI 和部署。
你的代理程式已組裝完成，並由純潔守衛驗證完整性。但如果沒有持續維護，結界就只會成為被遺忘的遺跡。為確保日後每個版本的代理程式都保持純淨，您必須建構部署 untlet 的第一階段，也就是自動化儀式，確保品質和速度。
身為暗刃，你的神聖職責是「持續整合 (CI)」。這是鍛造場和試煉場的自動化系統。這是防範資料損毀和人為錯誤的終極防禦措施。這項儀式可確保每次您或盟友將新技術 (合併程式碼) 貢獻給中央法典 (您的存放區) 時，護手都會自動啟動。系統會先根據新程式碼建立代理程式，然後立即將其納入您剛建立的純淨結界。如果任何防護失效，儀式就會停止，有瑕疵的文物也會立即遭到拒絕，避免損壞軍械庫。網域是鍛造廠，CI pipeline 則可確保只有完美無缺、準備好上戰場的構件能離開工作坊。
CI 測試證明構件值得信賴後，儀式的第二階段就會開始：持續部署 (CD)。這是《衛報》的網域。他們肩負重任，會將您完善的容器化構件安全地釋放到正式版 Agentverse 中，管理其力量，並確保在靜態混亂中維持穩定。
在本法典中，您將精通自己的角色。您將建構 CI 部分的測試流程。您將建構自動化鍛造廠，測試代理程式並將純粹結果封存到容器中，準備接受 The Guardian 的最終祝福。
現在要使用 Google Cloud Build，為這個 CI 儀式撰寫卷軸。定義鍛造和測試程序每個步驟的 cloudbuild.yaml 檔案。
👉💻 由於 ADK 的專案結構，CI/CD pipeline 設定應位於父項目錄中。在終端機中前往上層目錄，然後重新啟動 Gemini CLI。
cd ~/agentverse-developer/
clear
gemini --yolo
👉✨ 現在，對 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
恭喜，Shadowblade。法典儀式已完成。現在正是證明實力的好時機。你已學會駕馭混亂，現在就等著挑戰由混亂而生的幽靈。為最終試用做好準備。
非遊戲玩家
9. The Boss Fight
卷軸已讀完、儀式已完成、考驗已通過。您的代理程式不只是儲存空間中的構件，更是以程式碼打造的冠軍，是 Agentverse 中的即時守衛，等待第一個指令。現在是時候在戰鬥的嚴酷考驗中證明實力了。
現在你將進入實彈模擬，讓新部署的 Shadowblade 對抗強大的 Spectre，這個實體代表著困擾所有創造物的混亂。這是對您工作成果的最終測試，從服務專員的核心邏輯到完美部署，無一例外。
取得代理程式的軌跡
你必須擁有兩把鑰匙，才能進入戰場：英雄的專屬簽章 (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 端點網址) 的符文輸入欄位。
- 將特工地點網址 (您複製的第一個網址) 貼到這個欄位，即可刻上英雄的徽記。
- 按一下「連線」，即可體驗瞬間移動的魔力。
傳送時的強光逐漸消失。你已離開聖所。空氣中充滿能量，寒冷而尖銳。在您面前，幽靈實體化了，形成嘶嘶作響的靜電和損毀程式碼的漩渦，不潔的光芒在地下城地板上投下長長的舞動陰影。牠沒有臉，但你感覺到牠龐大、令人疲憊的存在感完全集中在你身上。
只有堅定信念，才能邁向勝利。這是一場意志力的較量，戰場就在心靈。
你向前衝刺，準備發動第一波攻擊，但幽靈卻反擊了。不會升起護盾，但會直接將問題投射到你的意識中，這道閃閃發光的符文挑戰來自訓練的核心。
這就是這場戰役的本質。知識就是你的武器。
- 運用所學知識回答問題，刀刃就會燃起純粹能量，擊碎幽靈的防禦並造成致命一擊。
- 但如果你猶豫不決，答案含糊不清，武器的光芒就會黯淡。但這時的攻擊只會發出微弱的聲響，造成的傷害也只有一小部分。更糟的是，Spectre 會以你的不確定感為食，每犯下一個錯誤，牠的腐化力量就會增長。
這就是最後的挑戰，冠軍。程式碼是你的魔法書，邏輯是你的劍，知識則是能抵擋混亂浪潮的盾牌。
專注。擊出好球。這關係到 Agentverse 的命運。
恭喜，Shadowblade。
您已成功完成法典。您從「氛圍」著手，將其轉譯為設計，並使用 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 Bucket
這個指令會移除 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 歷程的所有痕跡。專案已清理完畢，可以開始下一個冒險。