adk-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADK Project Scaffolding Guide

ADK 项目脚手架指南

Use the

agent-starter-pack

CLI (via

uvx

) to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.

使用

agent-starter-pack

CLI（通过

uvx

）创建新的ADK Agent项目，或为现有项目添加部署、CI/CD及基础设施脚手架。

Step 1: Gather Requirements

步骤1：收集需求

Start with the use case, then ask follow-ups based on answers.

Always ask:

What problem will the agent solve? — Core purpose and capabilities
External APIs or data sources needed? — Tools, integrations, auth requirements
Safety constraints? — What the agent must NOT do, guardrails
Deployment preference? — Prototype first (recommended) or full deployment? If deploying: Agent Engine or Cloud Run?

Ask based on context:

If retrieval or search over data mentioned (RAG, semantic search, vector search, embeddings, similarity search, data ingestion) → Datastore? Use
```
--agent agentic_rag --datastore <choice>
```
:
- ```
vertex_ai_vector_search
```
  — for embeddings, similarity search, vector search
- ```
vertex_ai_search
```
  — for document search, search engine
If agent should be available to other agents → A2A protocol? Use
```
--agent adk_a2a
```
to expose the agent as an A2A-compatible service.
If full deployment chosen → CI/CD runner? GitHub Actions (default) or Google Cloud Build?
If Cloud Run chosen → Session storage? In-memory (default), Cloud SQL (persistent), or Agent Engine (managed).
If deployment with CI/CD chosen → Git repository? Does one already exist, or should one be created? If creating, public or private?

从用户场景入手，根据回答进行后续提问。

必须询问以下问题：

该Agent要解决什么问题？ — 核心用途与功能
是否需要调用外部API或数据源？ — 所需工具、集成方式及认证要求
有哪些安全约束？ — Agent绝对不能执行的操作、防护规则
部署偏好？ — 优先原型开发（推荐）还是直接完整部署？若选择部署：使用Agent Engine还是Cloud Run？

根据上下文追加提问：

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

Step 2: Write DESIGN_SPEC.md

步骤2：编写DESIGN_SPEC.md

Compose a detailed spec with these sections. Present the full spec for user approval before scaffolding.

markdown

undefined

撰写包含以下章节的详细规格文档。在执行脚手架生成前，需提交完整规格文档供用户确认。

markdown

undefined

DESIGN_SPEC.md

Overview

概述

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

2-3段文字描述Agent的用途及工作原理。

Example Use Cases

示例场景

3-5 concrete examples with expected inputs and outputs.

3-5个具体示例，包含预期输入与输出。

Tools Required

所需工具

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

每个工具的用途、API细节及认证需求。

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.


The spec should be thorough enough for another developer to implement the agent without additional context.

---

至少3-5个Agent需能优雅处理的场景。


规格文档需足够详尽，确保其他开发者无需额外上下文即可实现该Agent。

---

Step 3: Create or Enhance the Project

步骤3：创建或优化项目

Create a New Project

创建新项目

bash

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

Constraints:

Project name must be 26 characters or less, lowercase letters, numbers, and hyphens only.
Do NOT
```
mkdir
```
the project directory before running
```
create
```
— the CLI creates it automatically. If you mkdir first,
```
create
```
will fail or behave unexpectedly.
Auto-detect the guidance filename based on the IDE you are running in and pass
```
--agent-guidance-filename
```
accordingly.
When enhancing an existing project, check where the agent code lives. If it's not in
```
app/
```
, pass
```
--agent-directory <dir>
```
(e.g.
```
--agent-directory agent
```
). Getting this wrong causes enhance to miss or misplace files.

bash

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

约束条件：

项目名称必须不超过26个字符，仅包含小写字母、数字及连字符。
运行
```
create
```
命令前不要手动创建项目目录 — CLI会自动创建目录。若提前创建，
```
create
```
命令可能失败或出现异常行为。
根据当前运行的IDE自动检测指南文件名，并相应传入
```
--agent-guidance-filename
```
参数。
优化现有项目时，需检查Agent代码的存放位置。若不在
```
app/
```
目录下，需传入
```
--agent-directory <目录>
```
（例如：
```
--agent-directory agent
```
）。参数错误会导致优化过程遗漏或错误放置文件。

Create Flags

创建命令参数

Flag	Short	Default	Description
`--agent`	`-a`	`adk`	Agent template (see template table below)
`--deployment-target`	`-d`	`agent_engine`	Deployment target ( `agent_engine` , `cloud_run` , `none` )
`--region`		`us-central1`	GCP region
`--prototype`	`-p`	off	Skip CI/CD and Terraform (recommended for first pass)
`--cicd-runner`		`skip`	`github_actions` or `google_cloud_build`
`--datastore`	`-ds`	—	Datastore for data ingestion ( `vertex_ai_search` , `vertex_ai_vector_search` )
`--session-type`		`in_memory`	Session storage ( `in_memory` , `cloud_sql` , `agent_engine` )
`--auto-approve`	`-y`	off	Skip confirmation prompts
`--skip-checks`	`-s`	off	Skip GCP/Vertex AI verification checks
`--agent-directory`	`-dir`	`app`	Agent code directory name
`--google-api-key`	`-k`	—	Use Google AI Studio instead of Vertex AI
`--agent-guidance-filename`		`GEMINI.md`	Guidance file name ( `CLAUDE.md` , `AGENTS.md` )
`--debug`		off	Enable debug logging for troubleshooting

参数	简写	默认值	描述
`--agent`	`-a`	`adk`	Agent模板（见下方模板表格）
`--deployment-target`	`-d`	`agent_engine`	部署目标（ `agent_engine` 、 `cloud_run` 、 `none` ）
`--region`		`us-central1`	GCP区域
`--prototype`	`-p`	关闭	跳过CI/CD与Terraform配置（首次开发推荐使用）
`--cicd-runner`		`skip`	CI/CD运行器（ `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代码目录名称
`--google-api-key`	`-k`	—	使用Google AI Studio替代Vertex AI
`--agent-guidance-filename`		`GEMINI.md`	指南文件名（ `CLAUDE.md` 、 `AGENTS.md` ）
`--debug`		关闭	启用调试日志用于故障排查

Enhance an Existing Project

优化现有项目

bash

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

Run this from inside the project directory (or pass the path instead of

). Remember that enhance creates new files (

.github/

deployment/

tests/load_test/

, etc.) that need to be committed.

bash

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

需在项目目录内运行该命令（或传入项目路径替代

）。注意优化操作会创建新文件（

.github/

、

deployment/

、

tests/load_test/

等），需提交这些文件到版本控制。

Enhance Flags

优化命令参数

All create flags are supported, plus:

Flag	Short	Default	Description
`--name`	`-n`	directory name	Project name for templating
`--base-template`	`-bt`	—	Override base template (e.g. `agentic_rag` to add RAG)
`--dry-run`		off	Preview changes without applying
`--force`		off	Force overwrite all files (skip smart-merge)

支持所有创建命令的参数，额外新增：

参数	简写	默认值	描述
`--name`	`-n`	目录名称	用于模板渲染的项目名称
`--base-template`	`-bt`	—	覆盖基础模板（例如：使用 `agentic_rag` 添加RAG功能）
`--dry-run`		关闭	预览变更但不实际执行
`--force`		关闭	强制覆盖所有文件（跳过智能合并）

Common Workflows

常见工作流

Always ask the user before running these commands. Present the options (CI/CD runner, deployment target, etc.) and confirm before executing.

bash

undefined

执行以下命令前必须先询问用户。提供选项（CI/CD运行器、部署目标等）并得到确认后再执行。

bash

undefined

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?)

添加CI/CD流水线（询问：使用GitHub Actions还是Cloud Build？）

uvx agent-starter-pack enhance . --cicd-runner github_actions -y

Add RAG with data ingestion

添加带数据导入的RAG功能

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

---

uvx agent-starter-pack enhance . --deployment-target cloud_run --dry-run -y

---

Template Options

模板选项

Template	Deployment	Description
`adk`	Agent Engine, Cloud Run	Standard ADK agent (default)
`adk_a2a`	Agent Engine, Cloud Run	Agent-to-agent coordination (A2A protocol)
`agentic_rag`	Agent Engine, Cloud Run	RAG with data ingestion pipeline

模板	部署支持	描述
`adk`	Agent Engine、Cloud Run	标准ADK Agent（默认）
`adk_a2a`	Agent Engine、Cloud Run	支持Agent间协作（A2A协议）
`agentic_rag`	Agent Engine、Cloud Run	带数据导入流水线的RAG Agent

Deployment Options

部署选项

Target	Description
`agent_engine`	Managed by Google (Vertex AI Agent Engine). Sessions handled automatically.
`cloud_run`	Container-based deployment. More control, requires Dockerfile.
`none`	No deployment scaffolding. Code only.

目标	描述
`agent_engine`	由Google托管（Vertex AI Agent Engine），自动处理会话。
`cloud_run`	基于容器的部署，提供更多控制权，需要Dockerfile。
`none`	仅生成代码，不包含部署脚手架。

"Prototype First" Pattern (Recommended)

“优先原型开发”模式（推荐）

Start with

--prototype

to skip CI/CD and Terraform. Focus on getting the agent working first, then add deployment later with

enhance

bash

undefined

使用

--prototype

参数跳过CI/CD与Terraform配置，先专注于实现Agent核心功能，后续再通过

enhance

命令添加部署配置：

bash

undefined

Step 1: Create a prototype

步骤1：创建原型

uvx agent-starter-pack create my-agent --agent adk --prototype -y

Step 2: Iterate on the agent code...

步骤2：迭代开发Agent代码...

Step 3: Add deployment when ready

步骤3：准备就绪后添加部署配置

uvx agent-starter-pack enhance . --deployment-target agent_engine -y

undefined

uvx agent-starter-pack enhance . --deployment-target agent_engine -y

undefined

Agent Engine and session_type

Agent Engine与会话类型

When using

agent_engine

as the deployment target, Agent Engine manages sessions internally. If your code sets a

session_type

, clear it — Agent Engine overrides it.

当使用

agent_engine

作为部署目标时，Agent Engine会在内部管理会话。若代码中设置了

session_type

，需将其清除 — Agent Engine会覆盖该配置。

Step 4: Save DESIGN_SPEC.md and Load Dev Workflow

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

After scaffolding, save the approved spec from Step 2 to the project root as

DESIGN_SPEC.md

Then immediately load
/adk-dev-guide
— it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent.

脚手架生成完成后，将步骤2中确认的规格文档保存到项目根目录，命名为

DESIGN_SPEC.md

。

随后立即加载
/adk-dev-guide
— 其中包含开发工作流、编码规范及Agent开发必须遵循的操作规则。

Scaffold as Reference

脚手架参考用法

When you need specific files (Terraform, CI/CD workflows, Dockerfile) but don't want to scaffold the current project directly, create a temporary reference project in

/tmp/

bash

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

Inspect the generated files, adapt what you need, and copy into the actual project. Delete the reference project when done.

This is useful for:

Non-standard project structures that
```
enhance
```
can't handle
Cherry-picking specific infrastructure files
Understanding what ASP generates before committing to it

当需要特定文件（Terraform配置、CI/CD工作流、Dockerfile）但不想直接对当前项目进行脚手架生成时，可在

/tmp/

目录下创建临时参考项目：

bash

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

查看生成的文件，提取所需内容并适配到实际项目中。使用完成后删除临时项目。

该方法适用于：

```
enhance
```
命令无法处理的非标准项目结构
选择性提取特定基础设施文件
在正式生成前了解ASP工具的输出内容

Critical Rules

关键规则

NEVER change the model in existing code unless explicitly asked
NEVER
mkdir
before
create
— the CLI creates the directory; pre-creating it causes enhance mode instead of create mode
NEVER create a Git repo or push to remote without asking — confirm repo name, public vs private, and whether the user wants it created at all
Always ask before choosing CI/CD runner — present GitHub Actions and Cloud Build as options, don't default silently
Agent Engine clears session_type — if deploying to
```
agent_engine
```
, remove any
```
session_type
```
setting from your code
Start with
--prototype
for quick iteration — add deployment later with
```
enhance
```
Project names must be ≤26 characters, lowercase, letters/numbers/hyphens only

除非明确要求，否则绝不要修改现有代码中的模型
运行
create
命令前绝不要手动创建目录 — CLI会自动创建目录；提前创建会触发优化模式而非创建模式
未经询问绝不要创建Git仓库或推送到远程 — 确认仓库名称、公开/私有属性，以及用户是否需要创建仓库
选择CI/CD运行器前必须询问用户 — 提供GitHub Actions与Cloud Build选项，不要默认选择
Agent Engine会清除session_type配置 — 若部署到
```
agent_engine
```
，需从代码中移除所有
```
session_type
```
设置
优先使用
--prototype
参数进行快速迭代 — 后续通过
```
enhance
```
命令添加部署配置
项目名称必须≤26个字符，仅包含小写字母、数字及连字符

Examples

示例

Using scaffold as reference: User says: "I need a Dockerfile for my non-standard project" Actions:

Create temp project:

uvx agent-starter-pack create /tmp/ref --agent adk --deployment-target cloud_run -y

Copy relevant files (Dockerfile, etc.) from /tmp/ref
Delete temp project Result: Infrastructure files adapted to the actual project

脚手架参考用法示例：用户需求：“我需要为非标准项目生成Dockerfile” 操作步骤：

创建临时项目：

uvx agent-starter-pack create /tmp/ref --agent adk --deployment-target cloud_run -y

从/tmp/ref目录复制相关文件（如Dockerfile）
删除临时项目结果：基础设施文件适配到实际项目中

Troubleshooting

故障排查

uvx

command not found

uvx

命令未找到

Install

uv

curl -LsSf https://astral.sh/uv/install.sh | sh

uv

is not an option, use pip instead:

bash

undefined

安装

uv

：

curl -LsSf https://astral.sh/uv/install.sh | sh

若无法使用

uv

，可使用pip安装：

bash

undefined

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> ...

undefined

python -m venv .venv && .venv\Scripts\activate

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

undefined

adk-scaffold

Original

Translation

ADK Project Scaffolding Guide

ADK 项目脚手架指南

Step 1: Gather Requirements

步骤1：收集需求

Step 2: Write DESIGN_SPEC.md

步骤2：编写DESIGN_SPEC.md

DESIGN_SPEC.md

DESIGN_SPEC.md

Overview

概述

Example Use Cases

示例场景

Tools Required

所需工具

Constraints & Safety Rules

约束与安全规则

Success Criteria

成功标准

Edge Cases to Handle

需要处理的边缘场景

Step 3: Create or Enhance the Project

步骤3：创建或优化项目

Create a New Project

创建新项目

Create Flags

创建命令参数

Enhance an Existing Project

优化现有项目

Enhance Flags

优化命令参数

Common Workflows

常见工作流

Add deployment to an existing prototype

为现有原型添加部署配置

Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)

添加CI/CD流水线（询问：使用GitHub Actions还是Cloud Build？）

Add RAG with data ingestion

添加带数据导入的RAG功能

Preview what would change (dry run)

预览即将发生的变更（试运行）

Template Options

模板选项

Deployment Options

部署选项

"Prototype First" Pattern (Recommended)

“优先原型开发”模式（推荐）

Step 1: Create a prototype

步骤1：创建原型

Step 2: Iterate on the agent code...

步骤2：迭代开发Agent代码...

Step 3: Add deployment when ready

步骤3：准备就绪后添加部署配置

Agent Engine and session_type

Agent Engine与会话类型

Step 4: Save DESIGN_SPEC.md and Load Dev Workflow

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

Scaffold as Reference

脚手架参考用法

Critical Rules

关键规则

Examples

示例

Troubleshooting

故障排查

uvx command not found

uvx命令未找到

macOS/Linux

macOS/Linux

Windows

Windows

`uvx`
command not found

`uvx`
命令未找到