adk-scaffold

ADK 项目脚手架指南

使用 agent-starter-pack CLI（通过 uvx）创建新的 ADK Agent 项目，或为现有项目添加部署、CI/CD 和基础设施脚手架。

---

步骤 1：收集需求

从使用场景开始，然后根据回答提出后续问题。

务必询问：

1. Agent 要解决什么问题？ — 核心目的和功能
2. 需要哪些外部 API 或数据源？ — 工具、集成、身份验证要求
3. 有哪些安全约束？ — Agent 绝对不能做什么、护栏
4. 倾向于哪种部署方式？ — 先做原型（推荐）还是完整部署？如果要部署：Agent Engine、Cloud Run 还是 GKE？

根据具体情况询问：

• 如果提到了检索或数据搜索（RAG、语义搜索、向量搜索、嵌入、相似性搜索、数据摄取）→ 数据存储？ 使用 --agent agentic_rag --datastore <choice>：
  • vertex_ai_vector_search — 用于嵌入、相似性搜索、向量搜索
  • vertex_ai_search — 用于文档搜索、搜索引擎
• 如果 Agent 应该可供其他 Agent 使用 → A2A 协议？ 使用 --agent adk_a2a，将 Agent 公开为兼容 A2A 的服务。
• 如果选择了完整部署 → CI/CD 运行器？ GitHub Actions（默认）还是 Google Cloud Build？
• 如果选择了 Cloud Run 或 GKE → 会话存储？ 内存中（默认）、Cloud SQL（持久化）还是 Agent Engine（托管）。
• 如果选择了带 CI/CD 的部署 → Git 仓库？ 是否已存在仓库，还是需要新建？如果新建，选择公开还是私有？

---

步骤 2：编写 DESIGN_SPEC.md

撰写一份详细的规范，包含以下部分。在搭建脚手架之前，先向用户展示完整规范并征求批准。

# DESIGN_SPEC.md

## Overview
2-3 paragraphs describing the agent's purpose and how it works.

## Example Use Cases
3-5 concrete examples with expected inputs and outputs.

## Tools Required
Each tool with its purpose, API details, and authentication needs.

## Constraints & Safety Rules
Specific rules — not just generic statements.

## Success Criteria
Measurable outcomes for evaluation.

## Edge Cases to Handle
At least 3-5 scenarios the agent must handle gracefully.

规范应足够详尽，让其他开发者无需额外背景信息即可实现该 Agent。

---

步骤 3：创建或增强项目

创建新项目

uvx agent-starter-pack create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype \
  -y

约束：

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

Create 标志

标志	简写	默认值	描述
--agent	-a	adk	Agent 模板（参见下方模板表）
--deployment-target	-d	agent_engine	部署目标（agent_engine、cloud_run、gke、none）
--region		us-central1	GCP 区域
--prototype	-p	关闭	跳过 CI/CD 和 Terraform（推荐用于首次搭建）
--cicd-runner		skip	github_actions 或 google_cloud_build
--datastore	-ds	—	用于数据摄取的数据存储（vertex_ai_search、vertex_ai_vector_search）
--session-type		in_memory	会话存储（in_memory、cloud_sql、agent_engine）
--auto-approve	-y	关闭	跳过确认提示
--skip-checks	-s	关闭	跳过 GCP/Vertex AI 验证检查
--agent-directory	-dir	app	Agent 代码目录名称
--agent-guidance-filename		GEMINI.md	指导文件名（CLAUDE.md、AGENTS.md）
--debug		关闭	启用调试日志以便排查问题

默认情况下，脚手架生成的项目使用 Google Cloud 凭据（Vertex AI）。有关 API 密钥设置和模型配置，请参阅配置 Gemini 模型和支持的模型。

增强现有项目

uvx agent-starter-pack enhance . \
  --deployment-target <target> \
  -y

在项目目录中运行此命令（也可以传入路径，而不是 .）。请记住，enhance 会创建需要提交的新文件（.github/、deployment/、tests/load_test/ 等）。

Enhance 标志

支持所有 create 标志，此外还支持：

标志	简写	默认值	说明
--name	-n	目录名称	用于模板生成的项目名称
--base-template	-bt	—	覆盖基础模板（例如，使用 agentic_rag 添加 RAG）
--dry-run		关闭	预览更改，不应用更改
--force		关闭	强制覆盖所有文件（跳过智能合并）

常见工作流

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

# Add deployment to an existing prototype
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
uvx agent-starter-pack enhance . --cicd-runner github_actions -y

# Add RAG with data ingestion
uvx agent-starter-pack enhance . --base-template agentic_rag --datastore vertex_ai_search -y

# Preview what would change (dry run)
uvx agent-starter-pack enhance . --deployment-target cloud_run --dry-run -y

---

模板选项

模板	部署方式	说明
adk	Agent Engine、Cloud Run、GKE	标准 ADK Agent（默认）
adk_a2a	Agent Engine、Cloud Run、GKE	Agent 间协调（A2A 协议）
agentic_rag	Agent Engine、Cloud Run、GKE	带有数据摄取管道的 RAG

---

部署选项

目标	说明
agent_engine	由 Google 管理（Vertex AI Agent Engine）。自动处理会话。
cloud_run	基于容器的部署。控制力更强，但需要 Dockerfile。
gke	在 GKE Autopilot 上进行基于容器的部署。可全面控制 Kubernetes。
none	不生成部署脚手架。仅生成代码。

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

先使用 --prototype 跳过 CI/CD 和 Terraform。优先让 Agent 正常运行，之后再通过 enhance 添加部署配置：

# Step 1: Create a prototype
uvx agent-starter-pack create my-agent --agent adk --prototype -y

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

# Step 3: Add deployment when ready
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

Agent Engine 和 session_type

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

---

第 4 步：保存 DESIGN_SPEC.md 并加载开发工作流

搭建脚手架后，将第 2 步中获批的规格说明保存到项目根目录，文件名为 DESIGN_SPEC.md。

然后立即加载 /adk-dev-guide——其中包含开发工作流、编码指南，以及实现 Agent 时必须遵循的操作规则。

---

将脚手架用作参考

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

uvx agent-starter-pack create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run \
  --cicd-runner github_actions \
  -y

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

适用于以下情况：

• enhance 无法处理的非标准项目结构
• 只挑选特定的基础设施文件
• 在决定使用 ASP 前，先了解它会生成什么

---

关键规则

• 除非用户明确要求，否则绝不更改现有代码中的模型
• 绝不在 create 之前运行 mkdir——CLI 会创建目录；提前创建目录会导致进入 enhance 模式，而非 create 模式
• 未经询问，绝不创建 Git 仓库或推送到远程端——确认仓库名称、公开还是私有，以及用户是否希望创建仓库
• 选择 CI/CD 运行器前务必先询问——提供 GitHub Actions 和 Cloud Build 作为选项，不要默认选择
• Agent Engine 会清除 session_type——如果部署到 agent_engine，请从代码中移除任何 session_type 设置
• 快速迭代时从 --prototype 开始——之后再通过 enhance 添加部署配置
• 项目名称最多 26 个字符，只能包含小写字母、数字和连字符
• 绝不从头编写 A2A 代码——A2A Python API 的接口（导入路径、AgentCard 架构、to_a2a() 签名）并不简单，且会随版本变化。搭建 A2A 项目时，务必使用 --agent adk_a2a。

---

示例

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

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

---

A2A 项目： 用户说：“为我构建一个支持 A2A 并部署到 Cloud Run 的 Python Agent。” 操作：

1. 遵循标准流程（收集需求、DESIGN_SPEC、scaffold）
2. uvx agent-starter-pack create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype -y 结果：有效的 A2A 导入和 Dockerfile，无需手动编写 A2A 代码。

---

故障排除

找不到 uvx 命令

按照官方安装指南安装 uv。

如果无法使用 uv，请改用 pip：

# macOS/Linux
python -m venv .venv && source .venv/bin/activate
# Windows
python -m venv .venv && .venv\Scripts\activate

pip install agent-starter-pack
agent-starter-pack create <project-name> ...

如需查看所有可用选项，请运行 uvx agent-starter-pack create --help。