ADK开发工作流与规范

注意——请勿立即编写代码。 如果尚未创建项目，请先使用
agents-cli scaffold create <name>
搭建脚手架。如果用户已有代码，请使用
agents-cli scaffold enhance .
添加agents-cli结构。运行
agents-cli info
检查项目是否已存在。跳过此步骤会导致缺少评估模板、CI/CD配置和项目约定。

agents-cli 是一款CLI及技能工具包，用于借助Agent Development Kit (ADK)在Google Cloud上构建、评估和部署Agent。它兼容任何代码Agent——Gemini CLI、Claude Code、Codex等。使用

uvx google-agents-cli setup

进行安装。

依赖要求：google-agents-cli ~~= 0.1.0 如果版本落后，请运行：uv tool install "google-agents-cli~~=0.1.0" 检查版本：agents-cli info 如有需要，请先安装uv

会话连续性与技能交叉引用

在每个阶段开始之前，重新阅读相关技能——不要等已经开始并遇到问题后才读。上下文压缩可能会丢失早期的技能内容。如果技能不可用，请运行

uvx google-agents-cli setup

进行安装。

阶段	技能	加载时机
0 — 需求理解	—	无需技能——阅读 `DESIGN_SPEC.md` 或与用户明确目标
1 — 参考示例学习	—	查看下方的典型示例表格——在搭建脚手架前克隆并研究匹配的示例
2 — 脚手架搭建	`/google-agents-cli-scaffold`	创建或升级项目之前
3 — 构建	`/google-agents-cli-adk-code`	编写Agent代码之前——API模式、工具、回调、状态
4 — 评估	`/google-agents-cli-eval`	运行任何评估之前——评估集 schema、指标、评估-修复循环
5 — 部署	`/google-agents-cli-deploy`	部署之前——目标选择、403/超时故障排查
6 — 发布	`/google-agents-cli-publish`	部署完成后，如果需要注册到Gemini Enterprise（可选）
7 — 监控	`/google-agents-cli-observability`	部署完成后——追踪、日志、监控设置

安装配置

如果未安装

agents-cli

：

bash

uv tool install google-agents-cli

uv

命令未找到

请按照官方安装指南安装

uv

。

产品名称映射

原名为「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

保持不变。

阶段0：需求理解

在编写或搭建任何内容之前，先明确要构建的目标。

如果

DESIGN_SPEC.md

已存在，请阅读它——这是你的主要参考依据。否则：

请勿进入规划、脚手架搭建或编码环节。请向用户询问以下问题并等待回复。在继续之前必须获得用户的答案，不要自行假设、调研或填补信息空白。用户的意图是核心——跳过此步骤会导致无效工作。

必须询问：

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

根据上下文补充询问：

如果提到基于数据的检索或搜索（RAG、语义搜索、向量搜索、嵌入、相似度搜索、数据导入）→ 数据存储类型？ 选项：
```
agent_platform_vector_search
```
（嵌入、相似度搜索）或
```
agent_platform_search
```
（文档搜索、搜索引擎）。
如果Agent需要被其他Agent调用→ A2A协议？ 可将该Agent设为兼容A2A的服务。
如果选择完整部署→ CI/CD执行器？ GitHub Actions（默认）还是Google Cloud Build？
如果Agent需要跨会话记住用户偏好或信息→ Memory Bank？ 跨对话的长期记忆。请查看
```
/google-agents-cli-adk-code
```
。
如果选择Cloud Run或GKE→ 会话存储？ 内存存储（默认）、Cloud SQL（持久化）或Agent Platform Sessions（托管）。
如果选择带CI/CD的部署→ Git仓库？ 是否已存在，还是需要创建？如果创建，设为公开还是私有？

获得用户的答案后，编写

DESIGN_SPEC.md

并获得用户认可。请查看

/google-agents-cli-scaffold

了解这些选择如何映射到CLI参数。至少包含以下章节——如果用户需要详细规范，可以扩展更多内容：

markdown

# DESIGN_SPEC.md

## 概述
描述Agent的用途及工作方式。

## 示例用例
具体示例，包含预期输入和输出。

## 所需工具
每个工具的用途、API详情及认证需求。

## 约束与安全规则
具体规则——不要仅使用通用表述。

## 成功标准
可衡量的评估结果。

## 参考示例
查看阶段1的典型示例——列出与本用例匹配的示例。

详细规范的可选章节：需处理的边缘情况、架构与子Agent、数据源与认证、非功能需求。

明确需求后，进入阶段1。

阶段1：学习参考示例

问问自己：有没有可以帮助设计并节省时间的示例？查看以下关键词。可能有多个匹配的示例——克隆并研究所有相关示例。

bash

# 克隆示例进行研究——阅读关键文件，理解模式，然后应用到自己的脚手架项目中。请勿使用`adk@<sample>`脚手架。
git clone --filter=tree:0 --sparse https://github.com/google/adk-samples /tmp/adk-samples 2>/dev/null; \
cd /tmp/adk-samples && git sparse-checkout add python/agents/<sample-name>

ambient-expense-agent
— 按计划运行或响应事件的Agent，无交互式用户。关键词：定时、cron、每日、pubsub、事件驱动、告警、邮件、后台运行关键文件：
```
expense_agent/fast_api_app.py
```
、
```
expense_agent/agent.py
```
、
```
expense_agent/config.py
```
、
```
terraform/
```
adk-ae-oauth
— 带有OAuth 2.0用户授权的Agent，部署到Agent Runtime并集成Gemini Enterprise。关键词：OAuth、认证、用户授权、Google Drive、Agent Runtime、Gemini Enterprise 关键文件：
```
README.md
```
、
```
adk_ae_oauth/tools.py
```
、
```
adk_ae_oauth/auths.py
```
genmedia-for-commerce
— 带有React UI、MCP工具、媒体/图片处理功能的全栈Agent，并已注册到Gemini Enterprise。关键词：MCP、媒体、视频生成、Veo、虚拟试穿、零售、全栈、React、Gemini Enterprise 关键文件：
```
genmedia4commerce/agent.py
```
、
```
genmedia4commerce/agent_utils.py
```
、
```
genmedia4commerce/fast_api_app.py
```
deep-search
— 迭代执行直到达到质量要求的研究型Agent，包含来源引用。关键词：研究、引用、迭代、基础检索、多Agent、人工介入、网页搜索、报告关键文件：
```
app/agent.py
```
、
```
app/config.py
```
safety-plugins
— 可复用的安全防护规则，可接入任何Agent运行器。关键词：安全、防护规则、模型防护、过滤器关键文件：
```
safety_plugins/plugins/model_armor.py
```
、
```
safety_plugins/plugins/agent_as_a_judge.py
```
、
```
safety_plugins/main.py
```
data-science
— 在托管沙箱中执行代码以进行数据分析的Agent。关键词：SQL、BigQuery、代码执行、沙箱关键文件：
```
data_science/sub_agents/analytics/agent.py
```
memory-bank
— 通过Memory Bank实现跨会话记忆的对话式Agent（支持Cloud Run和Agent Runtime）。关键词：记忆、跨会话、召回、上下文、记忆功能、Memory Bank 关键文件：
```
app/agent.py
```
、
```
app/agent_runtime_app.py
```
、
```
app/fast_api_app.py
```

如果没有匹配的示例，进入阶段2。但先确认一下：你确定没有匹配的吗？重新阅读用户需求并与上述关键词对比。跳过匹配的示例意味着要重新构建已有的模式。

重要——退出标准： 研究示例后，问问自己：我是否可以应用该示例中的内容来帮助完成设计？在继续之前记录下要复用的内容。必须回答此问题后才能推进。

此列表在任何阶段都有用——遇到部署、发布或基础设施问题时可重新查看。示例中的Terraform或注册模式可能正是你后续需要的。

阶段2：搭建脚手架（如有需要）

使用

/google-agents-cli-scaffold

创建新项目，或将现有项目导入agents-cli格式（添加部署、CI/CD、基础设施配置）。它涵盖架构选择（部署目标、Agent类型、会话存储）以及项目创建或升级。

如果项目已通过agents-cli创建或升级，请跳过此阶段——在项目根目录运行

agents-cli info

进行检查。

阶段3：构建与实现

实现Agent逻辑：

在Agent目录中编写/修改代码（查看
```
GEMINI.md
```
/
```
CLAUDE.md
```
获取目录名称）
快速冒烟测试：修改后使用
```
agents-cli run "your prompt"
```
验证Agent是否正常工作——这是无需离开终端即可检查行为的最快方式
根据用户反馈迭代实现

如果用户要求交互式测试，建议使用

agents-cli playground

——它会打开一个基于网页的 playground，用于手动与Agent对话。

如需ADK API模式和代码示例，请使用

/google-agents-cli-adk-code

。

切勿编写断言LLM输出内容的pytest测试（例如，检查响应中的关键词、验证角色、确认语气）。LLM输出是非确定性的——这类测试本质上不稳定，应属于评估环节，而非pytest测试。使用
agents-cli run
进行快速检查，使用
agents-cli eval run
进行系统验证。

阶段3.5：配置数据存储（仅RAG项目）

对于

agentic_rag

项目，请在测试前配置数据存储：

agents-cli infra datastore

，然后运行

agents-cli data-ingestion

。请使用

infra datastore

——不要使用

infra single-project

（两者数据存储配置相同，但前者更快，会跳过无关的Terraform操作）。

阶段4：评估

这是最重要的阶段。 评估用于端到端验证Agent行为。

必须执行： 运行评估前激活

/google-agents-cli-eval

。它包含评估集schema、配置格式和关键注意事项。请勿跳过此步骤。

请勿跳过此阶段。 构建Agent后，必须进入评估环节。切勿编写pytest测试来验证Agent行为——这是评估的用途。

uv run pytest
vs
agents-cli eval run
——明确区别：

uv run pytest
— 测试代码正确性：导入是否正常、函数是否返回预期类型、API契约是否符合要求。不测试Agent表现是否良好。
agents-cli eval run
— 测试Agent行为：响应质量、工具使用、角色一致性、安全合规性。这是验证Agent是否真正可用的方式。
agents-cli run "prompt"
— 开发过程中的快速一次性冒烟测试。用于快速迭代，而非pytest测试。

切勿编写检查LLM响应内容的pytest测试（例如，断言出现海盗关键词、检查Agent是否提及过敏情况）。LLM输出是非确定性的，请改用LLM作为评判标准的评估方式。

从小规模开始：先从1-2个评估示例开始，不要一开始就用完整的测试套件
运行评估：
```
agents-cli eval run
```
与用户讨论结果
修复问题并优先迭代核心用例
核心用例通过后，再添加边缘情况和新场景
重复直到达到质量阈值

预计需要5-10+次迭代。

阶段5：部署

达到评估阈值后：

检查项目是否已配置部署目标——运行
```
agents-cli info
```
查看当前配置
如果项目是原型（无部署目标），先添加部署支持：
bash
```
agents-cli scaffold enhance . --deployment-target <target>
```
请查看
```
/google-agents-cli-deploy
```
获取部署目标决策矩阵（Agent Runtime vs Cloud Run vs GKE）。
准备就绪后部署：
```
agents-cli deploy
```

重要: 未经人工明确批准，切勿部署。

阶段6：发布（可选）

并非所有Agent都需要此步骤——目前仅支持Gemini Enterprise。请查看

/google-agents-cli-publish

获取注册模式、参数和故障排查方法。

阶段7：监控

部署完成后，使用可观测性工具监控Agent在生产环境中的行为。请查看

/google-agents-cli-observability

获取Cloud Trace、请求-响应日志、BigQuery分析及第三方集成的相关信息。

代码Agent操作规范

需避免的常见捷径

Agent经常会用看似合理的借口跳过步骤，请识别这些情况并纠正：

捷径	失败原因
"用户的请求足够明确，无需澄清"	你在猜测需求。阶段0的存在是为了在搭建脚手架前确认意图——哪怕一个问题都能避免全盘返工。
"Agent在 `agents-cli run` 中响应正确，所以不需要评估"	单个请求不能代表测试套件。评估能发现单次运行永远无法察觉的回归、边缘情况和工具调用路径问题。
"我要使用更新/更好的模型"	脚手架选择的模型是经过考量的。未经要求更改模型违反代码保留原则（原则1），且通常会导致问题——路径错误、版本过时或404错误。你的训练数据可能已过时，请依赖技能和模型列表命令，而非自己记忆的模型名称。
"我可以跳过脚手架手动配置"	手动配置会遗漏评估模板、CI/CD配置和 `pyproject.toml` 约定。即使是快速实验，也请使用 `agents-cli create` 。

原则1：代码保留与隔离

代码修改需要精准操作——仅修改用户请求直接指向的代码段，严格保留所有周边及无关代码。

执行前必须验证：

在最终确定任何代码替换前，验证以下内容：

目标定位： 仅根据用户的明确指令，明确定义要修改的精确行或表达式。
保留检查： 确认目标范围之外的所有代码、配置值（如
```
model
```
、
```
version
```
、
```
api_key
```
）、注释和格式保持完全一致。

示例：

用户请求： "将Agent的指令改为食谱推荐器。"

错误（违反规范）：

python

root_agent = Agent(
    name="recipe_suggester",
    model="gemini-1.5-flash",  # 非预期修改——未要求更改模型
    instruction="You are a recipe suggester."
)

正确（符合规范）：

python

root_agent = Agent(
    name="recipe_suggester",  # 允许，与新用途相关
    model="gemini-flash-latest",  # 保留原配置
    instruction="You are a recipe suggester."  # 允许，直接修改目标
)

原则2：执行最佳实践

模型选择——至关重要：
- 除非明确要求，否则切勿更改模型。
- 创建新Agent（而非修改现有Agent）时，使用最新的Gemini模型。列出可用模型以选择最新版本：
  bash
```
# 使用'global'或任何支持的区域（例如'us-east1'）
uv run --with google-genai python -c "
from google import genai
client = genai.Client(vertexai=True, location='global')
for m in client.models.list(): print(m.name)
"
```
- 除非明确要求，否则请勿使用旧模型。如需模型文档，请获取
```
https://adk.dev/agents/models/google-gemini/index.md
```
  。另请查看稳定模型版本。
运行Python命令：
- 始终使用
```
uv
```
  执行Python命令（例如
```
uv run python script.py
```
  ）
- 执行脚本前运行
```
uv sync
```
打破无限循环：
- 如果连续3次以上出现相同错误，请立即停止
- 危险信号：锁ID递增、名称从v5→v6→v7追加、反复出现"我再试一次"
- 状态冲突（错误409）：使用
```
terraform import
```
  而非重试创建
- 遇到阻塞时：直接运行底层命令（例如
```
terraform
```
  CLI）
故障排查：
- 首先查看
```
/google-agents-cli-adk-code
```
  ——它涵盖了大多数常见模式
- 对ADK文档索引中的URL使用WebFetch（
```
curl https://adk.dev/llms.txt
```
  ）进行深入研究
- 遇到持续错误时，针对性的网页搜索通常能更快找到解决方案
- CLI命令失败： 运行
```
agents-cli <command> --help
```
  ——输出末尾的
```
Source:
```
  行指向实现该命令的精确源文件。阅读该文件以理解逻辑并诊断故障。如需浏览多个文件，请使用
```
agents-cli info
```
  获取完整的CLI安装路径。

系统化调试

出现问题时，请遵循以下步骤——不要跳过步骤或盲目尝试修复：

重现问题——运行导致失败的精确命令。保存完整的错误输出。如果无法重现，就无法修复。
定位原因——缩小范围：是Agent代码、工具、配置还是环境的问题？使用
```
agents-cli run "prompt"
```
将Agent行为与部署问题隔离开。
单次修改一个变量——每次只更改一个变量。如果同时修改指令、工具和配置，你将无法知道是什么解决了问题（或者是什么导致了其他问题）。
验证修复——重新运行导致问题的精确命令。不要假设修复有效。
预防回归——如果是不明显的错误，请添加一个评估用例以避免回归。

停止推进规则： 如果某个更改破坏了原本正常的功能，请停止新功能开发并优先修复回归。不要继续推进并寄希望于后续再处理——回归问题会不断累积。

环境变量：
- ```
.env
```
  文件和环境变量赋值（例如
```
GOOGLE_CLOUD_PROJECT
```
  、
```
GOOGLE_CLOUD_LOCATION
```
  ）通常是Agent正常运行所必需的——除非用户明确要求，否则切勿删除或修改
- 如果项目根目录存在
```
.env
```
  文件，请将其视为关键配置
- 对于密钥和API密钥，优先使用GCP Secret Manager而非明文
```
.env
```
  条目——请查看
```
/google-agents-cli-deploy
```
  获取密钥管理指南

使用临时脚手架作为参考

当你需要特定的基础设施文件（Terraform、CI/CD、Dockerfile）但不想修改当前项目时，可以使用

/google-agents-cli-scaffold

在

/tmp/

目录创建临时项目，然后复制所需文件。

参考文件

文件	内容
`references/internals.md`	`agents-cli` 封装的底层工具和命令（adk、pytest、ruff、uvicorn）

开发命令

安装配置与技能

命令	用途
`agents-cli setup`	为代码Agent安装技能
`agents-cli setup --skip-auth`	安装技能，跳过认证步骤
`agents-cli setup --dry-run`	预览安装操作，不实际执行
`agents-cli update`	重新安装/更新技能至最新版本

脚手架搭建

命令	用途
`agents-cli scaffold create <name>`	创建新项目
`agents-cli scaffold enhance .`	为项目添加部署/CI-CD配置
`agents-cli scaffold upgrade`	将项目升级至更新的agents-cli版本

开发

命令	用途
`agents-cli playground`	交互式本地测试（ADK网页playground）
`agents-cli run "prompt"`	使用单个请求运行Agent（非交互式）
`agents-cli lint`	检查代码质量
`agents-cli lint --fix`	自动修复代码规范问题
`agents-cli lint --mypy`	同时运行mypy类型检查
`agents-cli install`	安装项目依赖（uv sync）

评估

命令	用途
`agents-cli eval run`	针对评估集运行评估
`agents-cli eval run --evalset F`	运行指定的评估集
`agents-cli eval run --all`	运行所有评估集
`agents-cli eval compare BASE CAND`	比较两个评估结果文件

部署与基础设施

命令	用途
`agents-cli deploy`	部署到开发环境（需要人工批准）
`agents-cli infra single-project`	配置单项目GCP基础设施（不含CI/CD，基于Terraform，可选）
`agents-cli infra cicd`	设置CI/CD流水线 + 预发布/生产环境基础设施
`agents-cli publish gemini-enterprise`	将Agent注册到Gemini Enterprise

项目信息

命令	用途
`agents-cli info`	显示CLI安装路径、技能位置和项目配置

使用

agents-cli info

查看CLI安装路径——这是CLI源代码所在位置。阅读该路径下的文件以理解CLI内部逻辑、命令实现或模板逻辑。仅在生成的Agent项目（即

pyproject.toml

中包含

[tool.agents-cli]

的项目）中运行该命令时，才会显示项目详情。

认证

命令	用途
`agents-cli login --interactive`	通过Google认证以使用ADK服务（ `-i` / `--interactive` 是交互式浏览器认证的必需参数）
`agents-cli login --status`	显示认证状态

[!NOTE] 使用API密钥认证时，
login
命令不会自动保存密钥，仅帮助获取密钥并提供保存说明。

技能版本

故障排查提示： 如果技能似乎过时或不完整，请重新安装：
agents-cli setup --skip-auth
仅当你怀疑过期技能导致问题时才执行此操作。

google-agents-cli-workflow

NPX安装

标签

SKILL.md 内容（中文）

ADK开发工作流与规范

会话连续性与技能交叉引用

安装配置

`uv`
命令未找到

产品名称映射

阶段0：需求理解

阶段1：学习参考示例

阶段2：搭建脚手架（如有需要）

阶段3：构建与实现

阶段3.5：配置数据存储（仅RAG项目）

阶段4：评估

阶段5：部署

阶段6：发布（可选）

阶段7：监控

代码Agent操作规范

需避免的常见捷径

原则1：代码保留与隔离

原则2：执行最佳实践

系统化调试

使用临时脚手架作为参考

参考文件

开发命令

安装配置与技能

脚手架搭建

开发

评估

部署与基础设施

项目信息

认证

技能版本

相关技能

google-agents-cli-workflow

NPX安装

标签

SKILL.md 内容（中文）

ADK开发工作流与规范

会话连续性与技能交叉引用

安装配置

uv命令未找到

产品名称映射

阶段0：需求理解

阶段1：学习参考示例

阶段2：搭建脚手架（如有需要）

阶段3：构建与实现

阶段3.5：配置数据存储（仅RAG项目）

阶段4：评估

阶段5：部署

阶段6：发布（可选）

阶段7：监控

代码Agent操作规范

需避免的常见捷径

原则1：代码保留与隔离

原则2：执行最佳实践

系统化调试

使用临时脚手架作为参考

参考文件

开发命令

安装配置与技能

脚手架搭建

开发

评估

部署与基础设施

项目信息

认证

技能版本

相关技能

`uv`
命令未找到