google-agents-cli-workflow

ADK 開發工作流程與準則

停止 — 先不要寫程式碼。 如果還沒有專案，請先用 agents-cli scaffold create <name> 建立 scaffold。如果使用者已經有程式碼，請用 agents-cli scaffold enhance . 來加入 agents-cli 結構。執行 agents-cli info 檢查專案是否已存在。跳過此步驟會導致缺少評估樣板、CI/CD 設定和專案慣例。

agents-cli 是一套 CLI 與技能工具組，用於在 Google Cloud 上使用 Agent Development Kit (ADK) 建構、評估與部署代理程式。它可與任何編碼代理程式搭配使用 — Gemini CLI、Claude Code、Codex 或其他。使用 uvx google-agents-cli setup 安裝。

需求：google-agents-cli ~= 0.5.1
如果版本落後，請執行：uv tool install "google-agents-cli~=0.5.1"

檢查版本：agents-cli info
如有需要，請先安裝 uv。

工作階段連續性與技能交叉參考

請在每個階段之前重新閱讀相關技能 — 而不是等到已經開始並遇到問題才讀。上下文壓縮可能已刪除先前的技能內容。如果技能不可用，請執行 uvx google-agents-cli setup 來安裝它們。

階段	技能	何時載入
0 — 理解	—	不需要技能 — 如果存在則讀取 .agents-cli-spec.md，否則與使用者釐清目標
1 — 研究範例	—	查看下方 Notable Samples 表格 — 在建立 scaffold 之前先複製並研究相符的範例
2 — Scaffold	/google-agents-cli-scaffold	在建立或增強專案之前
3 — 建構	/google-agents-cli-adk-code	在撰寫代理程式程式碼之前 — API 模式、工具、回呼、狀態
4 — 評估	/google-agents-cli-eval	在執行任何評估之前 — 資料集結構、指標、評估-修正迴圈
5 — 部署	/google-agents-cli-deploy	在部署之前 — 目標選擇、疑難排解 403/逾時
6 — 發布	/google-agents-cli-publish	部署之後，如果要註冊 Gemini Enterprise（選用）
7 — 監控	/google-agents-cli-observability	部署之後 — 追蹤、記錄、監控設定

---

設定

如果尚未安裝 agents-cli：

uv tool install google-agents-cli

找不到 uv 指令

請依照官方安裝指南安裝 uv。

產品名稱對應

先前稱為「Vertex AI」的平台現在是 Gemini Enterprise Agent Platform（簡稱：Agent Platform）。使用者可能使用不同的名稱來稱呼產品。請將它們對應到正確的 CLI 值：

使用者可能說	CLI 值
Agent Engine、Vertex AI Agent Engine、Agent Runtime	--deployment-target agent_runtime
Vertex AI Search、Agent Search	--datastore agent_platform_search
Vertex AI Vector Search、Vector Search	--datastore agent_platform_vector_search
Agent Engine sessions、Agent Platform Sessions	--session-type agent_platform_sessions

vertexai Python SDK 套件名稱不變。

---

階段 0：理解

在撰寫或建立 scaffold 之前，先了解你要建構什麼。

如果目前目錄中存在 .agents-cli-spec.md，請讀取它 — 它是你的主要真相來源。否則：

不要繼續進行規劃、建立 scaffold 或編碼。請向使用者提出以下問題並等待他們的回答。你必須在使用者回答後才能繼續。不要自行假設、研究或填空。使用者的意圖驅動一切 — 跳過此步驟會導致浪費工作。

務必詢問：

1. 代理程式要解決什麼問題？ — 核心目的與能力
2. 需要哪些外部 API 或資料來源？ — 工具、整合、驗證需求
3. 安全限制？ — 代理程式不得做的事、護欄
4. 部署偏好？ — 先建立原型（建議）還是完整部署？如果要部署：Agent Runtime、Cloud Run 或 GKE？

根據上下文詢問：

• 如果提到資料檢索或搜尋（RAG、語意搜尋、向量搜尋、嵌入、相似度搜尋、資料擷取）→ 資料儲存？ 選項：agent_platform_vector_search（嵌入、相似度搜尋）或 agent_platform_search（文件搜尋、搜尋引擎）。
• 如果代理程式應該可供其他代理程式使用 → A2A 協定？ 將代理程式啟用為 A2A 相容服務。
• 如果選擇完整部署 → CI/CD 執行器？ GitHub Actions（預設）或 Google Cloud Build？
• 如果代理程式應該跨工作階段記住使用者偏好或事實 → Memory Bank？ 跨對話的長期記憶。請參閱 /google-agents-cli-adk-code。
• 如果選擇 Cloud Run 或 GKE → 工作階段儲存？ 記憶體內（預設）、Cloud SQL（持久）或 Agent Platform Sessions（受管）。
• 如果選擇含 CI/CD 的部署 → Git 儲存庫？ 是否已存在，還是需要建立？如果要建立，公開還是私人？

一旦獲得使用者的回答，請將規格寫入目前目錄的 .agents-cli-spec.md 並取得使用者核准。請參閱 /google-agents-cli-scaffold 了解這些選擇如何對應到 CLI 旗標。至少包含以下章節 — 如果使用者想要詳細規格，可以擴充更多細節：

# Agent Spec

## 概述
描述代理程式的用途與運作方式。

## 範例使用案例
具體範例，包含預期的輸入與輸出。

## 所需工具
每個工具的目的、API 詳細資訊與驗證需求。

## 限制與安全規則
具體規則 — 不只是泛泛陳述。

## 成功標準
可衡量的評估結果。

## 參考範例
檢查階段 1 中的 Notable Samples — 列出任何符合此使用案例的範例。

選用章節以提供更詳細的規格：需處理的邊緣案例、架構與子代理程式、資料來源與驗證、非功能性需求。

一旦你清楚了解，請繼續進行階段 1。

階段 1：研究參考範例

問問自己：是否有範例可以幫助我設計並節省時間？掃描以下關鍵字。可以比對多個範例 — 複製並研究所有相關的範例。

# 複製範例進行研究 — 讀取關鍵檔案，了解模式，然後將它們套用
# 到你自己的 scaffold 專案。不要使用 `adk@<sample>` 建立 scaffold。
git clone --filter=tree:0 --sparse https://github.com/google/adk-samples /tmp/adk-samples 2>/dev/null; \
cd /tmp/adk-samples && git sparse-checkout add python/agents/<sample-name>

• ambient-expense-agent — 按排程執行或回應事件的代理程式，無需互動使用者。
  關鍵字：排程、cron、每日、pubsub、事件驅動、警示、電子郵件、ambient
  關鍵檔案：expense_agent/fast_api_app.py、expense_agent/agent.py、expense_agent/config.py、terraform/
• adk-ae-oauth — 具有 OAuth 2.0 使用者同意的代理程式，部署到 Agent Runtime 並搭配 Gemini Enterprise。
  關鍵字：OAuth、驗證、使用者同意、Google Drive、Agent Runtime、Gemini Enterprise
  關鍵檔案：README.md、adk_ae_oauth/tools.py、adk_ae_oauth/auths.py
• genmedia-for-commerce — 全端代理程式，包含 React UI、MCP 工具、媒體/圖片處理與 Gemini Enterprise 註冊。
  關鍵字：MCP、媒體、影片生成、Veo、虛擬試穿、零售、全端、React、Gemini Enterprise
  關鍵檔案：genmedia4commerce/agent.py、genmedia4commerce/agent_utils.py、genmedia4commerce/fast_api_app.py
• deep-search — 研究型代理程式，會反覆迭代直到品質達標，並附上來源引用。
  關鍵字：研究、引用、迭代、接地、多代理、人機協作、網頁搜尋、報告
  關鍵檔案：app/agent.py、app/config.py
• safety-plugins — 可重複使用的安全護欄，可插入任何代理程式執行器。
  關鍵字：安全、護欄、model armor、過濾器
  關鍵檔案：safety_plugins/plugins/model_armor.py、safety_plugins/plugins/agent_as_a_judge.py、safety_plugins/main.py
• data-science — 在受管沙盒中執行程式碼以進行資料分析的代理程式。
  關鍵字：SQL、BigQuery、程式碼執行、沙盒
  關鍵檔案：data_science/sub_agents/analytics/agent.py
• memory-bank — 透過 Memory Bank（Cloud Run 與 Agent Runtime）具有跨工作階段記憶的對話代理程式。
  關鍵字：記憶、跨工作階段、回憶、上下文、記住、Memory Bank
  關鍵檔案：app/agent.py、app/agent_runtime_app.py、app/fast_api_app.py

如果沒有符合的範例，請繼續進行階段 2。但首先 — 你確定嗎？重新閱讀使用者的請求，並與上述關鍵字進行比較。跳過符合的範例意味著重新建構已存在的模式。

重要 — 退出條件： 研究範例後，問問自己：我可以從這個範例中套用任何東西來幫助我交付設計嗎？在繼續之前，記下你會重複使用的內容。在回答這個問題之前，不要繼續。

此清單在任何階段都很有用 — 當你遇到部署、發布或基礎架構問題時，請重新查看它。範例的 Terraform 或註冊模式可能正是你之後需要的。

階段 2：建立 Scaffold（如有需要）

使用 /google-agents-cli-scaffold 建立新專案，或將現有專案匯入 agents-cli 格式（加入部署、CI/CD、基礎架構）。它涵蓋架構選擇（部署目標、代理程式類型、工作階段儲存）以及專案建立或增強。

如果專案已由 agents-cli 建立或增強，請跳過此階段 — 從專案根目錄執行 agents-cli info 來檢查。

階段 3：建構與實作

實作代理程式邏輯：

1. 在代理程式目錄中撰寫/修改程式碼（檢查 GEMINI.md / CLAUDE.md 以取得目錄名稱）
2. 快速冒煙測試：使用 agents-cli run "your prompt" 驗證代理程式在變更後是否正常運作 — 這是在不離開終端機的情況下檢查行為的最快方式
3. 根據使用者回饋迭代實作

如果使用者要求互動式測試，建議使用 agents-cli playground — 它會開啟一個網頁版遊樂場，用於與代理程式進行手動對話。

如需 ADK API 模式與程式碼範例，請使用 /google-agents-cli-adk-code。

絕對不要撰寫斷言 LLM 輸出內容的 pytest 測試（例如檢查回應中的關鍵字、驗證角色、確認語氣）。LLM 輸出是非確定性的 — 這類測試本質上不穩定，應屬於評估而非 pytest。使用 agents-cli run 進行快速檢查，使用 agents-cli eval generate 後接 agents-cli eval grade 進行系統性驗證。

階段 3.5：佈建資料儲存（僅限 RAG 專案）

對於 agentic_rag 專案，請在測試前佈建資料儲存：agents-cli infra datastore，然後 agents-cli data-ingestion。使用 infra datastore — 不要使用 infra single-project（相同的資料儲存佈建，但速度更快，跳過不相關的 Terraform）。

階段 4：評估

這是最重要的階段。 評估從端到端驗證代理程式的行為。

強制性： 在執行評估之前，請先啟用 /google-agents-cli-eval。
它包含資料集結構、設定格式與關鍵陷阱。不要跳過此步驟。

不要跳過此階段。 建構代理程式後，你必須繼續進行評估。不要撰寫 pytest 測試來驗證代理程式行為 — 那是評估的工作。

uv run pytest 與 agents-cli eval 的區別：

• uv run pytest — 測試程式碼正確性：匯入是否正常、函式是否回傳預期型別、API 合約是否成立。不測試代理程式的行為是否良好。
• agents-cli eval — 測試代理程式行為：回應品質、工具使用、角色一致性、安全合規。這才是驗證代理程式是否正常運作的方式。
• agents-cli run "prompt" — 開發期間的快速一次性冒煙測試。如果要測試多個提示，請使用 --start-server 選項來持續執行本機伺服器，這可減少重複呼叫的開銷，並允許透過 --session-id 恢復本機工作階段。用於快速迭代，而不是 pytest。

絕對不要撰寫檢查 LLM 回應內容的 pytest 測試（例如斷言海盜關鍵字出現、檢查代理程式是否提到過敏）。LLM 輸出是非確定性的。請改用具有 LLM-as-judge 標準的評估。

1. 從小處著手：從 1-2 個評估案例開始，而不是完整的測試套件
2. 執行評估：agents-cli eval run（串聯 generate + grade）。如需除錯或自訂追蹤位置，請使用兩步驟形式：agents-cli eval generate 然後 agents-cli eval grade。
3. 與使用者討論結果
4. 修正問題並先迭代核心案例
5. 只有在核心案例通過後，才加入邊緣案例與新情境
6. 重複直到品質門檻達標

預計在此進行 5-10 次以上的迭代。

階段 5：部署

一旦評估門檻達標：

1. 檢查專案是否已設定部署目標 — 執行 agents-cli info 查看目前設定
2. 如果專案是原型（無部署目標），請先加入部署支援：

   agents-cli scaffold enhance . --deployment-target <target>
   

   請參閱 /google-agents-cli-deploy 了解部署目標決策矩陣（Agent Runtime vs Cloud Run vs GKE）。
3. 準備就緒後部署：agents-cli deploy

重要：未經明確的人員核准，絕對不要部署。

階段 6：發布（選用）

並非所有代理程式都需要此步驟 — 目前支援 Gemini Enterprise。請參閱 /google-agents-cli-publish 了解註冊模式、旗標與疑難排解。

階段 7：監控

部署後，使用可觀測性工具監控代理程式在生產環境中的行為。請參閱 /google-agents-cli-observability 了解 Cloud Trace、提示-回應記錄、BigQuery Analytics 與第三方整合。

---

編碼代理程式的操作準則

常見應避免的捷徑

代理程式經常以看似合理的藉口跳過步驟。請辨識這些情況並堅持正確做法：

捷徑	為什麼會失敗
「使用者的請求已經夠清楚了，不需要釐清」	你在猜測需求。階段 0 的存在是為了在建立 scaffold 之前確認意圖 — 即使只問一個問題也能避免整個重做。
「代理程式在 agents-cli run 中回應正確，所以不需要評估」	一個提示不是測試套件。評估能捕捉到單次執行永遠不會發現的回歸、邊緣案例與工具軌跡問題。
「我會使用更新/更好的模型」	scaffold 選擇的模型是經過深思熟慮的。未經要求就更改它違反了程式碼保留原則（原則 1），而且通常會導致問題 — 錯誤的位置、已棄用的版本或 404。你的訓練資料很可能已經過時 — 請依賴技能和模型列出指令，而不是你對模型名稱的知識。
「我可以跳過 scaffold 並手動設定」	手動設定會遺漏評估樣板、CI/CD 設定與專案設定檔清單慣例。即使是快速實驗也請使用 agents-cli create。

原則 1：程式碼保留與隔離

程式碼修改需要精確的手術 — 僅更改使用者請求直接針對的程式碼區段，並嚴格保留所有周圍與不相關的程式碼。

強制性執行前驗證：

在最終確定任何程式碼替換之前，請驗證以下事項：

1. 目標識別： 僅根據使用者的明確指示，清楚定義要更改的確切行數或表達式。
2. 保留檢查： 確認所有目標之外的程式碼、設定值（例如 model、version、api_key）、註解與格式保持不變。

範例：

• 使用者請求：「將代理程式的指令改為食譜建議者。」
• 不正確（違規）：

  root_agent = Agent(
      name="recipe_suggester",
      model="gemini-1.5-flash",  # 非預期 — 未要求更改模型
      instruction="You are a recipe suggester."
  )
  

• 正確（符合）：

  root_agent = Agent(
      name="recipe_suggester",  # 可以，與新用途相關
      model="gemini-flash-latest",  # 保留
      instruction="You are a recipe suggester."  # 可以，直接目標
  )
  

原則 2：執行最佳實務

• 模型選擇 — 關鍵：

  • 除非明確要求，否則絕對不要更改模型。
  • 建立新代理程式（非修改現有）時，請使用最新的 Gemini 模型。列出可用模型以挑選最新的：

    # 使用 'global' 或任何支援的區域（例如 'us-east1'）
    uv run --with google-genai python -c "
    from google import genai
    client = genai.Client(vertexai=True, location='global')
    for m in client.models.list(): print(m.name)
    "
    

  • 除非明確要求，否則不要使用較舊的模型。如需模型文件，請擷取 https://adk.dev/agents/models/google-gemini/index.md。另請參閱穩定模型版本。

• 執行 Python 指令：

  • 一律使用 uv 執行 Python 指令（例如 uv run python script.py）
  • 在執行腳本之前，請先執行 uv sync

• 中斷無限迴圈：

  • 如果連續 3 次以上看到相同的錯誤，請立即停止
  • 紅旗：鎖定 ID 遞增、名稱附加 v5→v6→v7、重複出現「我再試一次」
  • 狀態衝突（錯誤 409）：使用 terraform import 而不是重試建立
  • 卡住時：直接執行底層指令（例如 terraform CLI）

• 疑難排解：

  • 先檢查 /google-agents-cli-adk-code — 它涵蓋了大多數常見模式
  • 使用 ADK 文件索引中的 URL 進行 WebFetch（curl https://adk.dev/llms.txt）以深入探討
  • 遇到持續錯誤時，有針對性的網頁搜尋通常能更快找到解決方案
  • CLI 指令失敗： 執行 agents-cli <command> --help — 輸出結尾會有一個 Source: 行，指向實作該指令的確切原始檔。讀取它以了解邏輯並診斷失敗。如果需要瀏覽多個檔案，請使用 agents-cli info 取得完整的 CLI 安裝路徑。

系統性除錯

當發生問題時，請依序執行以下步驟 — 不要跳過步驟或亂槍打鳥：

1. 重現 — 執行失敗的確切指令。儲存完整的錯誤輸出。如果你無法重現，就無法修正。
2. 定位 — 縮小原因範圍：是代理程式程式碼、工具、設定還是環境？使用 agents-cli run "prompt" 將代理程式行為與部署問題隔離。加上 -v（--verbose）以列印完整的 JSON 事件負載 — 有助於檢查工具呼叫、中間步驟與無聲失敗。
3. 一次修正一件事 — 一次只更改一個變數。如果你同時更改指令、工具和設定，你將不知道是什麼修正了問題（或破壞了其他東西）。
4. 驗證 — 重新執行確切的再現指令。不要假設修正有效。
5. 防護 — 如果是非顯而易見的錯誤，請加入一個評估案例以捕捉回歸。

停止線規則： 如果某項變更破壞了原本正常運作的功能，請停止功能開發並先修正回歸問題。不要為了希望之後能回頭而繼續推進 — 回歸問題會疊加。

• 環境變數：
  • .env 檔案與環境變數指派（例如 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION）通常是代理程式運作所必需的 — 除非使用者明確要求，否則絕對不要移除或修改它們
  • 如果專案根目錄中存在 .env 檔案，請將其視為必要設定
  • 對於機密與 API 金鑰，建議使用 GCP Secret Manager 而非純文字 .env 條目 — 請參閱 /google-agents-cli-deploy 以取得機密管理指引

---

使用暫存 Scaffold 作為參考

當你需要特定的基礎架構檔案（Terraform、CI/CD、Dockerfile）但不想修改目前專案時，請使用 /google-agents-cli-scaffold 在 /tmp/ 中建立暫存專案，並複製你需要的內容。

---

參考檔案

檔案	內容
references/internals.md	agents-cli 包裝的底層工具與指令（adk、pytest、ruff、uvicorn）

開發指令

設定與技能

指令	用途
agents-cli setup	將技能安裝到編碼代理程式
agents-cli setup --skip-auth	安裝技能，跳過驗證步驟
agents-cli setup --dry-run	預覽設定會做什麼，但不執行
agents-cli update	重新安裝/更新技能至最新版本

Scaffolding

指令	用途
agents-cli scaffold create <name>	建立新專案
agents-cli scaffold enhance .	將部署/CI-CD 加入專案
agents-cli scaffold upgrade	將專案升級至較新的 agents-cli 版本

開發

指令	用途
agents-cli playground	互動式本機測試（ADK 網頁遊樂場）
agents-cli run "prompt"	使用單一提示執行代理程式（非互動式）。加上 -v 以取得完整的 JSON 事件負載。
agents-cli lint	檢查程式碼品質
agents-cli lint --fix	自動修正 lint 問題
agents-cli lint --mypy	同時執行 mypy 型別檢查
agents-cli install	安裝專案相依套件（uv sync）

評估

指令	用途
agents-cli eval dataset synthesize	為你的代理程式合成多輪評估情境（冷啟動資料集）
agents-cli eval generate	在預設資料集上執行代理程式推論，產生追蹤
agents-cli eval generate --dataset PATH	為特定資料集執行推論
agents-cli eval grade	使用 eval_config.yaml 中的指標評分追蹤
agents-cli eval grade --metrics METRIC	使用特定指標評分（覆蓋 eval_config.yaml）
agents-cli eval metric list	列出 SDK 中可用的內建指標
agents-cli eval compare BASE CAND	比較兩個評分結果檔案（回歸檢查）
agents-cli eval analyze --eval-result RESULTS	從評分結果檔案中聚類失敗模式
agents-cli eval optimize	使用評估資料自動調整代理程式提示
agents-cli eval submit --dataset D --dest gs://BUCKET	在 Vertex AI Eval Service 上提交受管的雲端端評估執行
agents-cli eval results --run-id ID	擷取已提交的雲端評估執行的狀態/結果

部署與基礎架構

指令	用途
agents-cli deploy	部署至開發環境（需要人員核准）
agents-cli infra single-project	佈建單一專案 GCP 基礎架構，不含 CI/CD（Terraform，選用）
agents-cli infra cicd	設定 CI/CD 管線 + 測試/正式環境基礎架構
agents-cli publish gemini-enterprise	向 Gemini Enterprise 註冊代理程式

專案資訊

指令	用途
agents-cli info	顯示 CLI 安裝路徑、技能位置與專案設定

使用 agents-cli info 來探索 CLI 安裝路徑 — 這是 CLI 原始碼所在位置。讀取該路徑下的檔案以了解 CLI 內部、指令實作或範本邏輯。只有在產生的代理程式專案內執行時（即專案根目錄中有 agents-cli-manifest.yaml），該指令才會顯示專案詳細資訊。

驗證

指令	用途
agents-cli login --interactive	使用 Google 驗證以存取 ADK 服務（需要 -i / --interactive 以進行互動式瀏覽器型驗證）
agents-cli login --status	顯示驗證狀態

[!NOTE]
使用 API 金鑰驗證時，login 指令不會自動保留它們，它只是協助擷取金鑰並提供如何保留它們的指示。

---

技能版本

疑難排解提示： 如果技能看起來過時或不完整，請重新安裝：

agents-cli setup --skip-auth

只有在你懷疑過時的技能導致問題時才這樣做。

---

相關技能

• /google-agents-cli-scaffold — 專案建立、需求收集與增強
• /google-agents-cli-adk-code — ADK Python API 快速參考與生產範例代理程式
• /google-agents-cli-eval — 評估方法論、資料集結構與評估-修正迴圈
• /google-agents-cli-deploy — 部署目標、CI/CD 管線與生產工作流程
• /google-agents-cli-publish — Gemini Enterprise 註冊
• /google-agents-cli-observability — Cloud Trace、記錄、BigQuery Analytics 與第三方整合