AI Skills
google-agents-cli-scaffold

google-agents-cli-scaffold

热门

当用户想要“创建 Agent 项目”、“启动新的 ADK 项目”、“帮我构建一个新 Agent”、“为项目添加 CI/CD”、“添加部署配置”、“增强现有项目”或“升级项目”时，应当使用此 Skill。 本 Skill 属于 Google ADK（Agent Development Kit）Skill 套件的一部分。 涵盖 `agents-cli scaffold create`、`scaffold enhance` 和 `scaffold upgrade` 命令、模板选项、部署目标以及原型优先（prototype-first）工作流。 请勿用于编写 Agent 代码（请使用 google-agents-cli-adk-code）或部署运维操作（请使用 google-agents-cli-deploy）。

3081Star
487Fork
更新于 2026/6/22
获取 Skill源代码

相关 Skills

cmux-backend2.5万tmux39万sherpa-onnx-tts38万
SKILL.md
只读
名称
google-agents-cli-scaffold
描述

当用户想要“创建 Agent 项目”、“启动新的 ADK 项目”、“帮我构建一个新 Agent”、“为项目添加 CI/CD”、“添加部署配置”、“增强现有项目”或“升级项目”时，应当使用此 Skill。 本 Skill 属于 Google ADK（Agent Development Kit）Skill 套件的一部分。 涵盖 `agents-cli scaffold create`、`scaffold enhance` 和 `scaffold upgrade` 命令、模板选项、部署目标以及原型优先（prototype-first）工作流。 请勿用于编写 Agent 代码（请使用 google-agents-cli-adk-code）或部署运维操作（请使用 google-agents-cli-deploy）。

ADK 项目脚手架指南

前置依赖： agents-cli（执行 uv tool install google-agents-cli）——如尚未安装 uv，请先参考 安装 uv。

使用 agents-cli 命令行工具新建 ADK Agent 项目，或为现有项目补充部署、CI/CD 及基础设施脚手架。

前置要求：明确需求（新项目强制执行）

在生成新项目脚手架之前，必须先加载 /google-agents-cli-workflow 并完成阶段 0（Phase 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 Runner --cicd-runner <github_actions|google_cloud_build>
会话持久化存储 --session-type <in_memory|cloud_sql|agent_platform_sessions>

产品名称映射说明

原名为“Vertex AI”的平台现已更名为 Gemini Enterprise Agent Platform（简称 Agent Platform）。用户可能会使用旧称或不同说法，请将其映射到正确的 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

Python SDK 的包名 vertexai 保持不变。

步骤 2：创建或增强项目

创建新项目

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

约束条件与注意事项：

  • 项目名称长度不得超过 26 个字符，且仅能包含小写字母、数字和连字符（-）。
  • 切勿在运行 create 命令之前手动创建项目目录（mkdir）——CLI 会自动创建目录。如果提前 mkdir，会导致 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）。如果路径不正确，增强过程可能会漏掉或放错文件。

参考文档

文件 内容说明
references/flags.md create 与 enhance 命令的完整参数参考文档

增强现有项目

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

请在项目根目录下运行上述命令（或使用具体路径替代 .）。

升级项目

将现有项目升级至较新的 agents-cli 版本，在保留自定义改动的同时智能应用升级：

agents-cli scaffold upgrade                # 升级当前目录的项目
agents-cli scaffold upgrade <project-path> # 升级指定路径的项目
agents-cli scaffold upgrade --dry-run      # 预览升级变更（不实际应用）
agents-cli scaffold upgrade --auto-approve  # 自动应用无冲突的更新

执行模式

CLI 默认采用严格编程式模式（strict programmatic mode）——所有必需参数必须通过 CLI flag 显式传入，否则会抛出 UsageError。无需确认标志，直接显式传入全部必需参数即可。

常见工作流

在运行以下命令前，务必先询问用户。 列出所有可选配置（如 CI/CD Runner、部署目标等），获得用户确认后再执行。

# 为已有原型添加部署配置（严格编程式模式）
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 带数据导入流水线的 RAG

部署选项

部署目标 描述
agent_runtime Google 托管服务（Vertex AI Agent Runtime）。自动处理 Session。
cloud_run 基于容器的部署。掌控度更高，需要 Dockerfile。
gke 基于 GKE Autopilot 的容器部署。具备完整的 Kubernetes 控制能力。
none 不生成部署脚手架，仅保留代码。

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

建议先使用 --prototype 选项，跳过 CI/CD 和 Terraform 配置。前期专注于把 Agent 的核心逻辑跑通，后续再通过 scaffold enhance 追加部署配置：

# 步骤 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。如果代码中设置了 session_type，请将其清除——Agent Runtime 会直接覆盖该配置。

步骤 3：加载开发工作流

脚手架创建完成后，请立即加载 /google-agents-cli-workflow——其中包含了实现 Agent 时必须遵循的开发工作流、编码规范及操作准则。

需自定义的核心文件： app/agent.py（指令、工具集、模型）、app/tools.py（自定义工具函数）、.env（项目 ID、Region 位置、API Key）。
需保留勿动的文件： agents-cli-manifest.yaml（CLI 依赖此文件）、deployment/ 目录下的部署配置、Makefile、app/__init__.py（其中的 App(name=...) 必须与目录名保持一致，默认即为 app）。

RAG 项目（agentic_rag）——需优先创建数据存储：
在运行 agents-cli playground 或测试 RAG Agent 之前，必须先创建数据存储基础设施并导入数据：

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

请使用 infra datastore——不要使用 infra single-project。虽然二者都能创建数据存储，但 infra datastore 会跳过无关的 Terraform 流程，速度更快。如果不执行此步骤，Agent 将无法检索到数据。

Vector Search 区域设置： vector_search_location 默认值为 us-central1，与主 region（如 us-east1）相互独立。它同时决定 Vector Search Collection 和 BQ 导入数据集的区域，二者同地域放置以避免跨区域数据传输。可在每次调用时添加 --vector-search-location <region> 进行覆盖。

验证 Agent 是否正常工作： 使用 agents-cli run "测试提示词" 进行快速冒烟测试，接着通过 agents-cli eval generate 和 agents-cli eval grade 进行系统化评估验证。切勿编写对 LLM 返回内容进行常规断言的 pytest 测试——此类验证应放在 eval 评估流程中。

脚手架参考模式

当你需要某些具体文件（如 Terraform 配置、CI/CD 工作流、Dockerfile），但又不希望直接在当前项目中生成脚手架时，可以在 /tmp/ 目录下创建一个临时参考项目：

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

查看生成的文件，提取所需部分并按需修改后复制到实际项目中。完成后删除该临时参考项目。

适用于以下场景：

  • enhance 无法处理的非标准项目结构
  • 挑选提取特定的基础设施文件
  • 在正式引入前预览并了解 CLI 会生成哪些配置文件

核心硬性规则

  • 严禁跳过需求澄清：在运行 scaffold create 前，必须先加载 /google-agents-cli-workflow 阶段 0 并明确用户意图。
  • 严禁擅自修改模型：除非用户明确要求，否则切勿修改已有代码中的 model 设置。
  • 严禁提前创建目录：不要在 create 之前手动 mkdir——CLI 会自行创建目录；提前创建会导致 CLI 误识别为 enhance 模式而非 create 模式。
  • 未经确认严禁创建/推送到 Git 远程仓库：必须先向用户确认仓库名称、公开/私有属性以及是否确实需要创建仓库。
  • 选择 CI/CD Runner 时必须先询问：明确列出 GitHub Actions 与 Cloud Build 供用户选择，切勿默默使用默认项。
  • Agent Runtime 会清空 session_type：若部署目标为 agent_runtime，请从代码中移除任何 session_type 配置。
  • 优先使用 --prototype 开启快速迭代：先跑通原型，后续再通过 enhance 补充部署配置。
  • 项目命名限制：名称长度不得超过 26 个字符，且仅支持小写字母、数字和连字符。
  • 严禁从头手写 A2A 代码：A2A 的 Python API 接口（导入路径、AgentCard schema、to_a2a() 签名等）较为复杂且随版本演进。构建 A2A 项目时务必使用 --agent adk_a2a 脚手架。

示例

将脚手架作为参考范例：
用户需求：“我的项目结构是非标准的，需要一个 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 逻辑。

常见问题排查

找不到 agents-cli 命令

请参阅 /google-agents-cli-workflow 中的 Setup（环境配置） 章节。

相关 Skill

  • /google-agents-cli-workflow — 开发工作流、编码规范及构建-评估-部署的全生命周期管理
  • /google-agents-cli-adk-code — 用于编写 Agent 代码的 ADK Python API 快速参考
  • /google-agents-cli-deploy — 部署目标平台、CI/CD 流水线及生产环境工作流
  • /google-agents-cli-eval — 评估方法论、数据集 Schema 以及“评估-修复”闭环迭代