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：收集需求

Ask these questions in two rounds. Start with the use case, then move to architecture.

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 <dir>
```
参数（例如
```
--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

bash

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

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

）。

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与session_type

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与session_type

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`
命令未找到