ADK项目脚手架指南

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

使用

agents-cli

CLI创建新的ADK Agent项目，或为现有项目添加部署、CI/CD和基础设施脚手架以增强项目功能。

前置条件：明确需求（新项目必填）

在搭建新项目脚手架之前，请加载
/google-agents-cli-workflow
并完成第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\|cloud_build>`
会话存储	`--session-type <in_memory\|cloud_sql\|agent_platform_sessions>`

产品名称映射

原名为「Vertex AI」的平台现已更名为Gemini Enterprise Agent Platform（简称：Agent平台）。用户可能用不同名称指代产品，请将其映射为正确的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：创建或增强项目

创建新项目

bash

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

约束条件：

项目名称必须不超过26个字符，仅包含小写字母、数字和连字符。
运行
```
create
```
命令前请勿手动创建项目目录——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
```
）。参数错误会导致enhance模式遗漏或错误放置文件。

参考文件

文件	内容
`references/flags.md`	`create` 和 `enhance` 命令的完整参数参考

增强现有项目

bash

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

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

）。

升级项目

将现有项目升级到更新版本的agents-cli，智能应用更新同时保留你的自定义内容：

bash

agents-cli scaffold upgrade                # 升级当前目录
agents-cli scaffold upgrade <project-path> # 升级指定项目
agents-cli scaffold upgrade --dry-run      # 预览更改但不应用
agents-cli scaffold upgrade --auto-approve  # 自动应用无冲突的更改

执行模式

CLI默认使用严格编程模式——所有必填参数必须通过CLI标志提供，否则会抛出

UsageError

。无需确认标志，请显式传递所有必填参数。

常见工作流

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

bash

# 为现有原型添加部署（严格编程模式）
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间协作（A2A协议）
`agentic_rag`	Agent Runtime、Cloud Run、GKE	带数据 ingestion 流水线的RAG

部署选项

目标	描述
`agent_runtime`	由Google托管（Vertex AI Agent Runtime），会话自动处理。
`cloud_run`	基于容器的部署，可控性更强，需要Dockerfile。
`gke`	基于GKE Autopilot的容器部署，拥有完整Kubernetes控制权。
`none`	无部署脚手架，仅生成代码。

「原型优先」模式（推荐）

使用

--prototype

参数跳过CI/CD和Terraform，先专注于让Agent正常工作，之后再用

scaffold enhance

添加部署：

bash

# 步骤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_type

，请清除该设置——Agent Runtime会覆盖它。

步骤3：加载开发工作流

搭建完成后，如果项目根目录没有

DESIGN_SPEC.md

文件，请将其保存到根目录。

随后立即加载
/google-agents-cli-workflow
——其中包含开发工作流、编码规范以及实现Agent时必须遵循的操作规则。

需要自定义的关键文件：

app/agent.py

（指令、工具、模型）、

app/tools.py

（自定义工具函数）、

.env

（项目ID、区域、API密钥）。 需要保留的文件：

pyproject.toml

中的

[tool.agents-cli]

部分（CLI会读取该内容）、

deployment/

下的部署配置、

Makefile

、

app/__init__.py

（其中的

App(name=...)

必须与目录名称匹配——默认为

app

）。

RAG项目（
agentic_rag
）——先配置数据存储：在运行

agents-cli playground

或测试RAG Agent之前，必须先配置数据存储并导入数据：

bash

agents-cli infra datastore   # 配置数据存储基础设施
agents-cli data-ingestion    # 将数据导入数据存储

请使用

infra datastore

——不要使用

infra single-project

。两者都会配置数据存储，但

infra datastore

更快，因为它会跳过无关的Terraform步骤。不执行此步骤的话，Agent将没有可搜索的数据。

向量搜索区域：
vector_search_location
默认值为
us-central1
，与
region
（
us-east1
）分开设置。它会同时设置向量搜索集合区域和BQ导入数据集区域，保持同区域以避免跨区域数据传输。可通过
agents-cli data-ingestion --vector-search-location <region>
参数在每次调用时覆盖默认值。

验证Agent是否正常工作： 使用

agents-cli run "test prompt"

进行快速冒烟测试，然后使用

agents-cli eval run

进行系统性验证。请勿编写断言LLM响应内容的pytest测试——这类测试属于eval范畴。

将脚手架作为参考

当你需要特定文件（Terraform、CI/CD工作流、Dockerfile）但不想直接为当前项目搭建脚手架时，可以在

/tmp/

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

bash

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

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

这种方法适用于：

```
enhance
```
模式无法处理的非标准项目结构
挑选特定的基础设施文件
在决定使用CLI生成内容前，先了解其生成的内容

关键规则

绝对不要跳过需求明确步骤——加载
```
/google-agents-cli-workflow
```
第0阶段，在运行
```
scaffold create
```
前明确用户意图
绝对不要修改现有代码中的模型，除非用户明确要求
绝对不要在
create
前手动创建目录——CLI会创建目录；提前创建会触发enhance模式而非create模式
绝对不要未经询问就创建Git仓库或推送到远程——确认仓库名称、公私有属性以及用户是否需要创建仓库
选择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

→ 设置部分。

google-agents-cli-scaffold

NPX安装

标签

SKILL.md 内容（中文）

ADK项目脚手架指南

前置条件：明确需求（新项目必填）

步骤1：选择架构

产品名称映射

步骤2：创建或增强项目

创建新项目

参考文件

增强现有项目

升级项目

执行模式

常见工作流

模板选项

部署选项

「原型优先」模式（推荐）

Agent Runtime与session_type

步骤3：加载开发工作流

将脚手架作为参考

关键规则

示例

故障排除

`agents-cli`
命令未找到

相关技能

google-agents-cli-scaffold

NPX安装

标签

SKILL.md 内容（中文）

ADK项目脚手架指南

前置条件：明确需求（新项目必填）

步骤1：选择架构

产品名称映射

步骤2：创建或增强项目

创建新项目

参考文件

增强现有项目

升级项目

执行模式

常见工作流

模板选项

部署选项

「原型优先」模式（推荐）

Agent Runtime与session_type

步骤3：加载开发工作流

将脚手架作为参考

关键规则

示例

故障排除

agents-cli命令未找到

相关技能

`agents-cli`
命令未找到