google-agents-cli-scaffold

Name: google-agents-cli-scaffold
Author: google

ADK 專案腳手架指南

前置需求： agents-cli (uv tool install google-agents-cli) — 若需要請先安裝 uv。

使用 agents-cli CLI 工具建立新的 ADK Agent 專案，或為現有專案擴充部署設定、CI/CD 與基礎架構腳手架。

前置步驟：明確需求（新建專案必做）

在產生新專案骨架前，請先載入 /google-agents-cli-workflow 並完成 Phase 0 — 在執行任何 scaffold create 指令前，先與使用者確認需求。詢問 Agent 應該具備什麼功能、需要哪些工具/API，以及需要的是原型還是完整部署。

步驟 1：選擇架構

將使用者的選擇對應至 CLI 旗標：

需求對應	CLI 旗標
搭配向量搜尋的 RAG	`--agent agentic_rag --datastore agent_platform_vector_search`
搭配文件搜尋的 RAG	`--agent agentic_rag --datastore agent_platform_search`
A2A 協定	`--agent adk_a2a`
原型（不含部署）	`--prototype`
部署目標	`--deployment-target <agent_runtime\|cloud_run\|gke>`
CI/CD 執行器	`--cicd-runner <github_actions\|google_cloud_build>`
Session 儲存機制	`--session-type <in_memory\|cloud_sql\|agent_platform_sessions>`

產品名稱對應

原名 "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 套件名稱保持不變。

步骤 2：建立或擴充專案

建立新專案

agents-cli scaffold create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype

限制事項：

專案名稱必須在 26 個字元以內，僅能包含小寫英文字母、數字與連字號 (-)。
請勿在執行 create 前手動 mkdir 建立專案目錄 — CLI 會自動建立。如果先建立了目錄，create 可能會失敗或出現預期之外的行為。
根據目前執行的 IDE 自動偵測指引檔名，並傳入對應的 --agent-guidance-filename 參數（Gemini CLI 使用 GEMINI.md、Claude Code 使用 CLAUDE.md、OpenAI Codex 或其他工具使用 AGENTS.md）。
在擴充現有專案時，請檢查 Agent 程式碼放置位置。若非存放在 app/ 目錄中，請傳入 --agent-directory <dir>（例如 --agent-directory agent）。如果設錯目錄，增強程序會找不到或放錯檔案。

參考文件

檔案	內容描述
`references/flags.md`	`create` 與 `enhance` 指令的完整旗標參考文件

擴充現有專案

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

請在專案目錄內執行（或傳入專案路徑代替 .）。

升級專案

將現有專案升級至較新的 agents-cli 版本，智慧套用更新的同時保留你的客製化修改：

agents-cli scaffold upgrade                # 升級目前目錄的專案
agents-cli scaffold upgrade <project-path> # 升級指定路徑的專案
agents-cli scaffold upgrade --dry-run      # 預覽變更而不實際套用
agents-cli scaffold upgrade --auto-approve  # 自動套用無衝突的變更

執行模式

CLI 預設使用嚴格程式化模式 (strict programmatic mode) — 所有必需的參數都必須透過 CLI 旗標指定，否則會拋出 UsageError。無需傳入確認旗標，所有必要參數請明確指定。

常見工作流程

執行這些指令前務必先詢問使用者。 列出所有選項（例如 CI/CD 執行器、部署目標等）並經使用者確認後再執行。

# 為現有的原型新增部署設定（嚴格程式化模式）
agents-cli scaffold enhance . --deployment-target agent_runtime

# 新增 CI/CD 管線（先詢問：GitHub Actions 或 Cloud Build？）
agents-cli scaffold enhance . --cicd-runner github_actions

範本選項

範本名稱	部署目標	說明
`adk`	Agent Runtime, Cloud Run, GKE	標準 ADK Agent（預設）
`adk_a2a`	Agent Runtime, Cloud Run, GKE	Agent 對 Agent 協調架構（A2A 協定）
`agentic_rag`	Agent Runtime, Cloud Run, GKE	包含資料載入管線的 RAG 範本

部署選項

部署目標	說明
`agent_runtime`	由 Google 全託管 (Vertex AI Agent Runtime)。自動處理 Session 狀態。
`cloud_run`	基於容器的部署。掌控度更高，需要提供 Dockerfile。
`gke`	在 GKE Autopilot 上進行容器部署。擁有完整的 Kubernetes 控制權。
`none`	不產生部署腳手架，僅產生程式碼。

「原型優先 (Prototype First)」模式（推薦）

建議先加上 --prototype 旗標以跳過 CI/CD 與 Terraform。初期專注於讓 Agent 正常運作，後續再透過 scaffold enhance 追加部署設定：

# 步驟 1：建立原型專案
agents-cli scaffold create my-agent --agent adk --prototype

# 步驟 2：疊代開發與調整 Agent 程式碼...

# 步驟 3：準備就緒後新增部署設定
agents-cli scaffold enhance . --deployment-target agent_runtime

Agent Runtime 與 session_type

當使用 agent_runtime 作為部署目標時，Agent Runtime 會在內部自動管理 Session。若你的程式碼中有設定 session_type，請將其清除 — 因為 Agent Runtime 會覆蓋該設定。

步驟 3：載入開發工作流程

腳手架建置完成後，請立即載入 /google-agents-cli-workflow — 其中包含實作 Agent 時必須遵循的開發流程、程式碼規範與操作規則。

需客製化的核心檔案： app/agent.py（System Instruction、Tools、Model）、app/tools.py（自訂工具函式）、.env（Project ID、Location、API Key）。
需保留的檔案： agents-cli-manifest.yaml（CLI 讀取用）、deployment/ 下的部署設定檔、Makefile、app/__init__.py（其中的 App(name=...) 名稱必須與目錄名一致 — 預設為 app）。

RAG 專案 (agentic_rag) — 必須先建置 Datastore：
在執行 agents-cli playground 或測試 RAG Agent 之前，必須先建置 Datastore 並載入資料：

agents-cli infra datastore   # 建立 Datastore 基礎架構
agents-cli data-ingestion    # 將資料載入至 Datastore

請使用 infra datastore — 而非 infra single-project。兩者皆可建置 Datastore，但 infra datastore 速度更快，因為它會跳過無關的 Terraform。若未執行此步驟，Agent 將無法搜尋到資料。

Vector Search 位置設定： vector_search_location 預設為 us-central1，與 region (us-east1) 獨立開來。它同時決定了 Vector Search Collection 位置與 BQ Ingestion Dataset 的位置，放在同一區塊以避免跨區域資料傳輸。若需修改可在每次執行時以 agents-cli data-ingestion --vector-search-location <region> 覆蓋。

驗證 Agent 是否正常運作： 先使用 agents-cli run "test prompt" 進行快速冒煙測試 (smoke test)，接著使用 agents-cli eval generate 和 agents-cli eval grade 進行系統化的評測驗證。請勿撰寫直接斷言 LLM 回覆內容的 pytest 單元測試 — 這類測試應屬於 eval 範疇。

將腳手架作為參考範例

當你只需要特定檔案（如 Terraform、CI/CD 工作流、Dockerfile），但不想直接在目前專案套用腳手架時，可以在 /tmp/ 建立臨時參考專案：

agents-cli scaffold create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run

檢視產生的檔案，節錄所需部分並複製到實際專案中。完成後刪除臨時專案即可。

此做法適用於以下情境：

enhance 無法處理的非標準專案結構
只需要挑選特定基礎架構檔案 (Cherry-picking)
在正式採用前想先了解 CLI 會產生哪些內容

關鍵規則

絕不可以跳過需求確認 — 執行 scaffold create 前必須先載入 /google-agents-cli-workflow Phase 0 與使用者確認意圖
絕對不可修改既有程式碼中的模型，除非使用者明確要求
絕不可在 create 前執行 mkdir — 目錄應由 CLI 建立；預先建立目錄會導致 CLI 判斷為 enhance 模式而非 create 模式
未經詢問絕不可建立 Git 儲存庫或 Push 到遠端 — 務必先確認儲存庫名稱、公開/私有屬性，以及使用者是否真的需要建立
選擇 CI/CD 執行器前務必先詢問 — 主動提供 GitHub Actions 與 Cloud Build 選項供選擇，切勿預設靜默決定
Agent Runtime 會覆蓋 session_type — 若部署至 agent_runtime，請從程式碼中移除所有 session_type 設定
優先使用 --prototype 開始以進行快速疊代 — 後續再透過 enhance 新增部署設定
專案名稱長度必須 ≤ 26 個字元，全小寫，僅限字母、數字與連字號 (-)
絕不可從頭手寫 A2A 程式碼 — A2A 的 Python API 介面（匯入路徑、AgentCard schema、to_a2a() 簽署）相當複雜且會隨版本更迭。請一律使用 --agent adk_a2a 建立 A2A 專案腳手架。

範例

將腳手架作為參考範例：
使用者表示：「我的非標準專案需要一份 Dockerfile」
操作步驟：

建立臨時專案：agents-cli scaffold create /tmp/ref --agent adk --deployment-target cloud_run
從 /tmp/ref 複製相關檔案（如 Dockerfile 等）
刪除臨時專案
結果：順利將基礎架構檔案改編並套用至實際專案中

A2A 專案：
使用者表示：「幫我建立一個暴露 A2A 介面並部署到 Cloud Run 的 Python Agent」
操作步驟：

遵循標準流程（了解需求、選擇架構、建立腳手架）
agents-cli scaffold create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype
結果：獲得合法的 A2A 匯入與 Dockerfile — 全程無須手寫 A2A 程式碼。

疑難排解

找不到 `agents-cli` 指令

請參閱 /google-agents-cli-workflow → Setup 章節。

您可能也喜歡

geofeed-tuner

38Kdevops-cloud

Use this skill whenever the user mentions IP geolocation feeds, RFC 8805, geofeeds, or wants help creating, tuning, validating, or publishing a self-published IP geolocation feed in CSV format. Intended user audience is a network operator, ISP, mobile carrier, cloud provider, hosting company, IXP, or satellite provider asking about IP geolocation accuracy, or geofeed authoring best practices. Helps create, refine, and improve CSV-format IP geolocation feeds with opinionated recommendations beyond RFC 8805 compliance. Do NOT use for private or internal IP address management — applies only to publicly routable IP addresses.

github

獲取

runtime

37Kdevops-cloud

@copilotkit/runtime — mount a fetch-native CopilotRuntime on any JS server, wire middleware, pick an AgentRunner, instantiate BuiltInAgent (Factory Mode with TanStack AI is the preferred default) or plug in any of 12 external agent frameworks (Mastra, LangGraph, CrewAI Crews/Flows, PydanticAI, ADK, LlamaIndex, Agno, AWS Strands, MS Agent Framework, AG2, A2A), enable Intelligence mode for durable threads + websocket, register server-side tools via defineTool, and wire voice transcription. Uses the fetch-based createCopilotRuntimeHandler primitive — the Express/Hono adapters are discouraged. Load the reference under references/ that matches your task.

copilotkit

獲取

deployment-pipeline-design

38Kdevops-cloud

設計多階段 CI/CD 管線，包含核准關卡、安全檢查與部署編排。當您需要設計零停機部署管線、實作金絲雀發布策略、設定多環境提升工作流程，或除錯 CI/CD 中失敗的部署關卡時，請使用此技能。

wshobson

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新

google-agents-cli-scaffold

相關技能

ADK 專案腳手架指南

前置步驟：明確需求（新建專案必做）

步驟 1：選擇架構

產品名稱對應

步骤 2：建立或擴充專案

建立新專案

參考文件

擴充現有專案

升級專案

執行模式

常見工作流程

範本選項

部署選項

「原型優先 (Prototype First)」模式（推薦）

Agent Runtime 與 session_type

步驟 3：載入開發工作流程

將腳手架作為參考範例

關鍵規則

範例

疑難排解

找不到 `agents-cli` 指令

相關 Skills

您可能也喜歡

geofeed-tuner

runtime

deployment-pipeline-design

繼續探索

google-agents-cli-scaffold

相關技能

ADK 專案腳手架指南

前置步驟：明確需求（新建專案必做）

步驟 1：選擇架構

產品名稱對應

步骤 2：建立或擴充專案

建立新專案

參考文件

擴充現有專案

升級專案

執行模式

常見工作流程

範本選項

部署選項

「原型優先 (Prototype First)」模式（推薦）

Agent Runtime 與 session_type

步驟 3：載入開發工作流程

將腳手架作為參考範例

關鍵規則

範例

疑難排解

找不到 agents-cli 指令

相關 Skills

您可能也喜歡

geofeed-tuner

runtime

deployment-pipeline-design

繼續探索

找不到 `agents-cli` 指令