google-agents-cli-scaffold

项目脚手架指南

需要： agents-cli（uv tool install google-agents-cli）——如有需要，请先安装 uv。

使用 agents-cli CLI 创建新的 Agent 项目，或为现有项目添加部署、CI/CD 和基础设施脚手架。

---

前置步骤：明确需求（新项目必做）

在为新项目搭建脚手架之前，加载 /google-agents-cli-workflow 并完成 Phase 0——在运行任何 scaffold create 命令前，先明确用户的需求。询问 Agent 应执行什么任务、需要哪些工具/API，以及用户想要的是原型还是完整部署。

---

第 1 步：选择架构

将用户的选择映射到 CLI 标志：

选择	CLI 标志
检索/RAG、沙箱执行、跨会话记忆、OAuth 授权、护栏、定时运行	无标志——这些功能来自克隆并研究示例方案。**ADK Python：**参阅 /google-agents-cli-adk-code 中的主题索引 → references/samples.md；对于其他框架，请参阅框架模板附带的示例索引
A2A 协议	已内置于生成脚手架的应用中——正常搭建脚手架（ADK Python：--agent adk，默认值；ADK Go：--agent adk_go）
原型（不部署）	--prototype
部署目标	--deployment-target <agent_runtime|cloud_run|gke>
CI/CD 运行器	--cicd-runner <github_actions|google_cloud_build>
会话存储	--session-type <in_memory|cloud_sql|agent_platform_sessions>

产品名称映射

当前名称（以及用户可能提到的旧名称）→ CLI 值（vertexai SDK 包名保持不变）：

• Gemini platform 中的 Agent Runtime（Agent Engine / Vertex AI Agent Engine / Agent Runtime）→ --deployment-target agent_runtime
• Gemini platform 中的 Sessions（Agent Engine sessions / Agent Platform Sessions）→ --session-type agent_platform_sessions
• Gemini platform 中的 Search / Vector Search（Vertex AI Search / Vertex AI Vector Search）/ RAG → 克隆并研究示例方案，而非使用标志

已移除的标志。 --datastore、agentic_rag 模板以及 agents-cli infra datastore / agents-cli data-ingestion 均已不存在。如果你正准备使用其中任一项，应该改用示例方案。

---

第 2 步：创建或增强项目

创建新项目

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

限制：

• 项目名称不得超过 26 个字符，且只能包含小写字母、数字和连字符。
• 运行 create 前不要 mkdir 项目目录——CLI 会自动创建该目录。如果先运行 mkdir，create 将会失败或出现异常行为。
• 根据当前使用的 IDE 自动检测指导文件名，并相应传入 --agent-guidance-filename（Antigravity CLI 使用 GEMINI.md，Claude Code 使用 CLAUDE.md，OpenAI Codex/其他工具使用 AGENTS.md）。
• 增强现有项目时，检查 Agent 代码所在位置。如果代码不在 app/ 中，请传入 --agent-directory <dir>（例如 --agent-directory agent）。设置错误会导致 enhance 遗漏文件或将文件放错位置。

参考文件

文件	内容
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                # Upgrade current directory
agents-cli scaffold upgrade <project-path> # Upgrade specific project
agents-cli scaffold upgrade --dry-run      # Preview changes without applying
agents-cli scaffold upgrade --auto-approve  # Auto-apply non-conflicting changes
agents-cli scaffold upgrade --force        # Overwrite scaffolding files when smart-merge fails
agents-cli scaffold upgrade --force --dry-run  # List what --force would overwrite

--force 是智能合并失败时的备用选项。如果创建项目时使用的 agents-cli 版本不在 PyPI 上，智能合并也会停止，因为它需要该版本的模板；此时也请使用 --force。它会用新模板覆盖脚手架文件，并保留 Agent 代码、配置文件、README.md、Agent 指南文件、评估数据集和配置。它不会删除依赖项或新模板中已移除的文件（例如已移除的 CI 工作流），因此请手动删除不再使用的内容。之后，请检查导入并运行测试。先使用 --dry-run 查看哪些文件会发生变化。

执行模式

CLI 默认采用严格编程模式——必须通过 CLI 标志提供所有必需参数，否则会引发 UsageError。无需审批标志。请显式传入所有必需参数。

常见工作流

运行这些命令前，务必先询问用户。 展示各项选项（CI/CD 运行器、部署目标等），并在执行前确认。

# Add deployment to an existing prototype (strict programmatic)
agents-cli scaffold enhance . --deployment-target agent_runtime

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
agents-cli scaffold enhance . --cicd-runner github_actions

---

模板选项

模板	语言	部署	说明
adk	Python	Agent Runtime、Cloud Run、GKE	标准 ADK Agent（默认）；内置 A2A 协议
adk_go	Go	Agent Runtime、Cloud Run、GKE	标准 ADK Go Agent；内置 A2A 协议

adk 和 adk_go 是仅有的内置模板。 adk 是默认模板，因此 Go 项目 需要显式指定 --agent adk_go。 其他框架以模板仓库的形式提供，可直接从中搭建脚手架： --agent google/agents-cli/extensions/langchain/[email protected]，无需安装任何内容。第一方 LangChain 模板位于 agents-cli 仓库中的 extensions/langchain/template/；如需发布自己的模板，请参阅 /google-agents-cli-workflow → references/extension.md。超出模板范围的功能——检索、沙盒化执行、记忆、OAuth、防护措施—— 是用于克隆和学习的方案，而非模板。ADK Python： 请参阅 /google-agents-cli-adk-code → references/samples.md 中的主题索引。

实时和语音 Agent： 没有对应模板。请搭建 adk 脚手架，然后按照 /google-agents-cli-adk-code 中的转换检查清单操作（references/adk-python-live.md，“将已搭建脚手架的 项目转换为 Live”）。模型替换是五项修改之一。

---

部署选项

目标	说明
agent_runtime	由 Google 管理（Agent Runtime）。基于容器——Agent Runtime 会构建项目的 Dockerfile。会话自动处理。
cloud_run	基于容器的部署。控制力更强；由你构建并部署 Dockerfile。
gke	在 GKE Autopilot 上进行基于容器的部署。可全面控制 Kubernetes。
none	不包含部署脚手架。仅代码（仍包含 Dockerfile）。

“先做原型”模式（推荐）

先使用 --prototype 跳过 CI/CD 和 Terraform。首先专注于让 Agent 正常运行，之后再通过 scaffold enhance 添加部署：

# Step 1: Create a prototype
agents-cli scaffold create my-agent --agent adk --prototype

# Step 2: Iterate on the agent code...

# Step 3: Add deployment when ready
agents-cli scaffold enhance . --deployment-target agent_runtime

Agent Runtime 和 session_type

将 agent_runtime 用作部署目标时，Agent Runtime 会在内部管理会话。如果代码设置了 session_type，请将其清除——Agent Runtime 会覆盖该设置。

---

第 3 步：加载开发工作流

完成脚手架搭建后，立即加载 /google-agents-cli-workflow — 其中包含实现 Agent 时必须遵循的开发工作流、编码指南和操作规则。

根据语言不同，需要编辑的内容也不同；/google-agents-cli-adk-code 中的 references/adk-python.md 和 references/adk-go.md 提供了各语言的注释版目录树。

• ADK Python（--agent adk） — 自定义 app/agent.py 和 app/tools.py。
• ADK Go（--agent adk_go） — 自定义 app/agent.go。

.env 由你负责。请保留模板生成的其他所有内容 — 它们负责配置服务、会话和内置的 A2A 界面。

调整示例方案： 将其中的 app/、infra/terraform/ 以及任何数据导入或配置内容复制到已搭建脚手架的项目中，然后运行该示例方案自带的 Makefile 进行配置（例如 make setup-infra）。从其 AGENTS.md 开始。

验证 Agent 是否正常运行： 使用 agents-cli run "test prompt" 进行快速冒烟测试，然后使用 agents-cli eval run 进行系统验证。不要编写断言大模型响应内容的 pytest 测试；这类验证应通过 eval 完成。

---

将脚手架用作参考

如果需要特定文件（Terraform、CI/CD 工作流、Dockerfile），但不想直接为当前项目搭建脚手架，可以在 /tmp/ 中创建一个临时参考项目：

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

检查生成的文件，按需调整并复制到实际项目中。完成后删除参考项目。

以下情况适用：

• enhance 无法处理的非标准项目结构
• 选择性复制特定基础设施文件
• 在确定采用 CLI 方案之前，了解 CLI 会生成哪些内容

---

关键规则

• 绝不跳过需求澄清 — 加载 /google-agents-cli-workflow 的第 0 阶段，并在运行 scaffold create 前澄清用户意图
• 除非明确提出要求，否则绝不更改现有代码中的模型
• 绝不在 create 前运行 mkdir — CLI 会创建目录；预先创建目录会导致进入 enhance 模式而非 create 模式
• 未经询问，绝不创建 Git 仓库或推送到远程仓库 — 确认仓库名称、设为公开还是私有，以及用户是否希望创建仓库
• 选择 CI/CD 运行器前务必先询问 — 提供 GitHub Actions 和 Cloud Build 选项，不要擅自默认
• Agent Runtime 会清除 session_type — 如果部署到 agent_runtime，请从代码中移除所有 session_type 设置
• 快速迭代时从 --prototype 开始 — 之后再通过 enhance 添加部署功能
• 项目名称不得超过 26 个字符，且只能包含小写字母、数字和连字符
• 绝不从头编写 A2A 代码 — A2A 已内置于搭建脚手架生成的应用中（adk 和 adk_go 模板以及框架模板均如此）；各语言的 A2A 界面（导入路径、AgentCard 架构等）并不简单，且会随版本变化。正常搭建脚手架；切勿手动编写 A2A 界面。（唯一允许手动修改 A2A 的情况是：Live Agent 无法通过 A2A 提供服务，因此移除生成的接线配置 — 参见 /google-agents-cli-adk-code、references/adk-python-live.md。）

示例

以 scaffold 为参考： 用户说：“我需要为我的非标准项目编写一个 Dockerfile” 操作：

1. 创建临时项目：agents-cli scaffold create ref --output-dir /tmp --agent adk --deployment-target cloud_run
2. 从 /tmp/ref 复制相关文件（Dockerfile 等）
3. 删除临时项目 结果：根据实际项目调整基础设施文件

---

A2A 项目： 用户说：“帮我构建一个通过 A2A 对外提供服务并部署到 Cloud Run 的 Python Agent” 操作：

1. 遵循标准流程（了解需求、选择架构、搭建脚手架）
2. agents-cli scaffold create my-a2a-agent --agent adk --deployment-target cloud_run --prototype 结果：有效的 A2A 导入语句和 Dockerfile——无需手动编写 A2A 代码。

---

Go 项目： 用户说：“帮我构建一个部署到 Cloud Run 的 Go Agent” 操作：

1. 遵循标准流程（了解需求、选择架构、搭建脚手架）
2. agents-cli scaffold create my-go-agent --agent adk_go --deployment-target cloud_run --prototype 结果：Go 项目包含 app/agent.go、main.go 中的启动器，以及位于根目录的 A2A 卡片。

---

故障排除

找不到 agents-cli 命令

请参阅 /google-agents-cli-workflow → 设置部分。

---

相关技能

• /google-agents-cli-workflow — 开发工作流、编码指南以及构建-评估-部署生命周期
• /google-agents-cli-adk-code — 编写 Agent 代码的 ADK API 速查，包括图工作流 API
• /google-agents-cli-deploy — 部署目标、CI/CD 流水线和生产工作流
• /google-agents-cli-eval — 评估方法、数据集架构以及评估-修复循环