Back to Details

google-agents-cli-scaffold

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADK Project Scaffolding Guide

ADK项目脚手架指南

Requires: 
agents-cli
(
uv tool install google-agents-cli
) — install uv first if needed.
Use the 
agents-cli
CLI to create new ADK agent projects or enhance existing ones with deployment, CI/CD, and infrastructure scaffolding.
要求： 
agents-cli
（
uv tool install google-agents-cli
）—— 如有需要，请先安装uv。
使用
agents-cli
CLI创建新的ADK Agent项目，或为现有项目添加部署、CI/CD和基础设施脚手架以增强项目功能。

Prerequisite: Clarify Requirements (MANDATORY for new projects)

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

Before scaffolding a new project, load 
/google-agents-cli-workflow
and complete Phase 0 — clarify the user's requirements before running any 
scaffold create
command. Ask what the agent should do, what tools/APIs it needs, and whether they want a prototype or full deployment.
在搭建新项目脚手架之前，请加载
/google-agents-cli-workflow
并完成第0阶段——在运行任何
scaffold create
命令之前，先明确用户的需求。询问Agent应实现的功能、所需的工具/API，以及用户需要原型还是完整部署版本。

Step 1: Choose Architecture

步骤1：选择架构

Mapping user choices to CLI flags:
ChoiceCLI flag
RAG with vector search
--agent agentic_rag --datastore agent_platform_vector_search
RAG with document search
--agent agentic_rag --datastore agent_platform_search
A2A protocol
--agent adk_a2a
Prototype (no deployment)
--prototype
Deployment target
--deployment-target <agent_runtime|cloud_run|gke>
CI/CD runner
--cicd-runner <github_actions|cloud_build>
Session storage
--session-type <in_memory|cloud_sql|agent_platform_sessions>
用户选择与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>

Product name mapping

产品名称映射

The platform formerly known as "Vertex AI" is now Gemini Enterprise Agent Platform (short: Agent Platform). Users may refer to products by different names. Map them to the correct CLI values:
User may sayCLI value
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
The 
vertexai
Python SDK package name is unchanged.
原名为「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包名称保持不变。

Step 2: Create or Enhance the Project

步骤2：创建或增强项目

Create a New Project

创建新项目

bash
agents-cli scaffold create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype
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 (
    GEMINI.md
    for Gemini CLI, 
    CLAUDE.md
    for Claude Code, 
    AGENTS.md
    for OpenAI Codex/other).
  • 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
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模式遗漏或错误放置文件。

Reference Files

参考文件

FileContents
references/flags.md
Full flag reference for 
create
and 
enhance
commands
文件内容
references/flags.md
create
和
enhance
命令的完整参数参考

Enhance an Existing Project

增强现有项目

bash
agents-cli scaffold enhance . --deployment-target <target>
agents-cli scaffold enhance . --cicd-runner <runner>
Run this from inside the project directory (or pass the path instead of 
.
).
bash
agents-cli scaffold enhance . --deployment-target <target>
agents-cli scaffold enhance . --cicd-runner <runner>
请在项目目录内运行该命令（或传递路径替代
.
）。

Upgrade a Project

升级项目

Upgrade an existing project to a newer agents-cli version, intelligently applying updates while preserving your customizations:
bash
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，智能应用更新同时保留你的自定义内容：
bash
agents-cli scaffold upgrade                # 升级当前目录
agents-cli scaffold upgrade <project-path> # 升级指定项目
agents-cli scaffold upgrade --dry-run      # 预览更改但不应用
agents-cli scaffold upgrade --auto-approve  # 自动应用无冲突的更改

Execution Modes

执行模式

The CLI defaults to strict programmatic mode — all required params must be supplied as CLI flags or a 
UsageError
is raised. No approval flags needed. Pass all required params explicitly.
CLI默认使用严格编程模式——所有必填参数必须通过CLI标志提供，否则会抛出
UsageError
。无需确认标志，请显式传递所有必填参数。

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 (strict programmatic)

为现有原型添加部署（严格编程模式）

agents-cli scaffold enhance . --deployment-target agent_runtime
agents-cli scaffold enhance . --deployment-target agent_runtime

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

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

agents-cli scaffold enhance . --cicd-runner github_actions

---
agents-cli scaffold enhance . --cicd-runner github_actions

---

Template Options

模板选项

TemplateDeploymentDescription
adk
Agent Runtime, Cloud Run, GKEStandard ADK agent (default)
adk_a2a
Agent Runtime, Cloud Run, GKEAgent-to-agent coordination (A2A protocol)
agentic_rag
Agent Runtime, Cloud Run, GKERAG with data ingestion pipeline
模板部署方式描述
adk
Agent Runtime、Cloud Run、GKE标准ADK Agent（默认）
adk_a2a
Agent Runtime、Cloud Run、GKEAgent间协作（A2A协议）
agentic_rag
Agent Runtime、Cloud Run、GKE带数据 ingestion 流水线的RAG

Deployment Options

部署选项

TargetDescription
agent_runtime
Managed by Google (Vertex AI Agent Runtime). Sessions handled automatically.
cloud_run
Container-based deployment. More control, requires Dockerfile.
gke
Container-based on GKE Autopilot. Full Kubernetes control.
none
No deployment scaffolding. Code only.
目标描述
agent_runtime
由Google托管（Vertex AI Agent Runtime），会话自动处理。
cloud_run
基于容器的部署，可控性更强，需要Dockerfile。
gke
基于GKE Autopilot的容器部署，拥有完整Kubernetes控制权。
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 
scaffold enhance
:
bash
undefined
使用
--prototype
参数跳过CI/CD和Terraform，先专注于让Agent正常工作，之后再用
scaffold enhance
添加部署：
bash
undefined

Step 1: Create a prototype

步骤1：创建原型

agents-cli scaffold create my-agent --agent adk --prototype
agents-cli scaffold create my-agent --agent adk --prototype

Step 2: Iterate on the agent code...

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

Step 3: Add deployment when ready

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

agents-cli scaffold enhance . --deployment-target agent_runtime
undefined
agents-cli scaffold enhance . --deployment-target agent_runtime
undefined

Agent Runtime and session_type

Agent Runtime与session_type

When using 
agent_runtime as the deployment target, Agent Runtime manages sessions internally. If your code sets a
session_type`, clear it — Agent Runtime overrides it.
当使用
agent_runtime
作为部署目标时，Agent Runtime会在内部管理会话。如果你的代码设置了
session_type
，请清除该设置——Agent Runtime会覆盖它。

Step 3: Load Dev Workflow

步骤3：加载开发工作流

After scaffolding, save 
DESIGN_SPEC.md
to the project root if it isn't there already.
Then immediately load 
/google-agents-cli-workflow
 — it contains the development workflow, coding guidelines, and operational rules you must follow when implementing the agent.
Key files to customize: 
app/agent.py
(instruction, tools, model), 
app/tools.py
(custom tool functions), 
.env
(project ID, location, API keys). Files to preserve: 
pyproject.toml
[tool.agents-cli]
section (CLI reads this), deployment configs under 
deployment/
, 
Makefile
, 
app/__init__.py
(the 
App(name=...)
must match the directory name — default 
app
).
RAG projects (
agentic_rag
) — provision datastore first: Before running 
agents-cli playground
or testing your RAG agent, you must provision the datastore and ingest data:
bash
agents-cli infra datastore   # Provision datastore infrastructure
agents-cli data-ingestion    # Ingest data into the datastore
Use 
infra datastore
— not 
infra single-project
. Both provision the datastore, but 
infra datastore
is faster because it skips unrelated Terraform. Without this step, the agent won't have data to search over.
Vector Search region: 
vector_search_location
defaults to 
us-central1
, separate from 
region
(
us-east1
). It sets both the Vector Search collection region and the BQ ingestion dataset region, kept colocated to avoid cross-region data movement. Override per-invocation with 
agents-cli data-ingestion --vector-search-location <region>
.
Verifying your agent works: Use 
agents-cli run "test prompt"
for quick smoke tests, then 
agents-cli eval run
for systematic validation. Do NOT write pytest tests that assert on LLM response content — that belongs in eval.
搭建完成后，如果项目根目录没有
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范畴。

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
agents-cli scaffold create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run
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 the CLI generates before committing to it
当你需要特定文件（Terraform、CI/CD工作流、Dockerfile）但不想直接为当前项目搭建脚手架时，可以在
/tmp/
目录下创建一个临时参考项目：
bash
agents-cli scaffold create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run
检查生成的文件，调整所需内容并复制到实际项目中。完成后删除参考项目。
这种方法适用于：
  • enhance
    模式无法处理的非标准项目结构
  • 挑选特定的基础设施文件
  • 在决定使用CLI生成内容前，先了解其生成的内容

Critical Rules

关键规则

  • NEVER skip requirements clarification — load 
    /google-agents-cli-workflow
    Phase 0 and clarify the user's intent before running 
    scaffold create
  • 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 Runtime clears session_type — if deploying to 
    agent_runtime
    , 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
  • NEVER write A2A code from scratch — the A2A Python API surface (import paths, 
    AgentCard
    schema, 
    to_a2a()
    signature) is non-trivial and changes across versions. Always use 
    --agent adk_a2a
    to scaffold A2A projects.
  • 绝对不要跳过需求明确步骤——加载
    /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项目。

Examples

示例

Using scaffold as reference: User says: "I need a Dockerfile for my non-standard project" Actions:
  1. Create temp project: 
    agents-cli scaffold create /tmp/ref --agent adk --deployment-target cloud_run
  2. Copy relevant files (Dockerfile, etc.) from /tmp/ref
  3. Delete temp project Result: Infrastructure files adapted to the actual project
A2A project: User says: "Build me a Python agent that exposes A2A and deploys to Cloud Run" Actions:
  1. Follow the standard flow (understand requirements, choose architecture, scaffold)
  2. agents-cli scaffold create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype
    Result: Valid A2A imports and Dockerfile — no manual A2A code written.
将脚手架作为参考： 用户说："我需要为我的非标准项目准备一个Dockerfile" 操作步骤：
  1. 创建临时项目：
    agents-cli scaffold create /tmp/ref --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_a2a --deployment-target cloud_run --prototype
    结果：生成有效的A2A导入代码和Dockerfile——无需手动编写A2A代码。

Troubleshooting

故障排除

agents-cli
command not found

agents-cli
命令未找到

See 
/google-agents-cli-workflow
→ Setup section.
请查看
/google-agents-cli-workflow
→ 设置部分。

Related Skills

相关技能

  • /google-agents-cli-workflow
    — Development workflow, coding guidelines, and the build-evaluate-deploy lifecycle
  • /google-agents-cli-adk-code
    — ADK Python API quick reference for writing agent code
  • /google-agents-cli-deploy
    — Deployment targets, CI/CD pipelines, and production workflows
  • /google-agents-cli-eval
    — Evaluation methodology, evalset schema, and the eval-fix loop
  • /google-agents-cli-workflow
    — 开发工作流、编码规范以及构建-评估-部署生命周期
  • /google-agents-cli-adk-code
    — 用于编写Agent代码的ADK Python API快速参考
  • /google-agents-cli-deploy
    — 部署目标、CI/CD流水线以及生产工作流
  • /google-agents-cli-eval
    — 评估方法、评估集schema以及评估-修复循环