google-agents-cli-workflow

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 上构建、评估和部署智能体。它适用于任何编码智能体——Gemini CLI、Claude Code、Codex 或其他。使用 uvx google-agents-cli setup 安装。

要求：google-agents-cli ~= 0.5.1
如果版本落后，运行：uv tool install "google-agents-cli~=0.5.1"

检查版本：agents-cli info
如果需要，请先安装 uv。

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

在每个阶段之前重新阅读相关技能——而不是在已经开始并遇到问题之后。上下文压缩可能已丢弃早期技能内容。如果技能不可用，运行 uvx google-agents-cli setup 安装它们。

阶段	技能	何时加载
0 — 理解	—	无需技能——如果存在，读取 .agents-cli-spec.md，否则与用户明确目标
1 — 研究示例	—	查看下方 Notable Samples 表格——在搭建脚手架之前克隆并研究匹配的示例
2 — 脚手架	/google-agents-cli-scaffold	在创建或增强项目之前
3 — 构建	/google-agents-cli-adk-code	在编写智能体代码之前——API 模式、工具、回调、状态
4 — 评估	/google-agents-cli-eval	在运行任何评估之前——数据集模式、指标、评估-修复循环
5 — 部署	/google-agents-cli-deploy	在部署之前——目标选择、403/超时故障排除
6 — 发布	/google-agents-cli-publish	部署后，如果注册到 Gemini Enterprise（可选）
7 — 观察	/google-agents-cli-observability	部署后——追踪、日志记录、监控设置

---

设置

如果 agents-cli 未安装：

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

vertexai Python SDK 包名称不变。

---

阶段 0：理解

在编写或搭建任何东西之前，了解你要构建什么。

如果当前目录中存在 .agents-cli-spec.md，请阅读它——它是你的主要事实来源。否则：

不要继续规划、搭建或编码。向用户提出以下问题并等待他们的回答。在获得用户回答之前，你必须不要继续。不要假设、研究或自己填空。用户的意图驱动一切——跳过此步骤会导致浪费工作。

始终询问：

1. 智能体将解决什么问题？——核心目的和能力
2. 需要哪些外部 API 或数据源？——工具、集成、认证要求
3. 安全约束？——智能体绝对不能做什么，护栏
4. 部署偏好？——先原型（推荐）还是完整部署？如果部署：Agent Runtime、Cloud Run 还是 GKE？

根据上下文询问：

• 如果提到数据检索或搜索（RAG、语义搜索、向量搜索、嵌入、相似性搜索、数据摄取）→ 数据存储？ 选项：agent_platform_vector_search（嵌入、相似性搜索）或 agent_platform_search（文档搜索、搜索引擎）。
• 如果智能体应对其他智能体可用 → A2A 协议？ 将智能体启用为 A2A 兼容服务。
• 如果选择完整部署 → CI/CD 运行器？ GitHub Actions（默认）还是 Google Cloud Build？
• 如果智能体应跨会话记住用户偏好或事实 → Memory Bank？ 跨对话的长期记忆。参见 /google-agents-cli-adk-code。
• 如果选择 Cloud Run 或 GKE → 会话存储？ 内存中（默认）、Cloud SQL（持久化）或 Agent Platform Sessions（托管）。
• 如果选择带 CI/CD 的部署 → Git 仓库？ 是否已存在，还是需要创建？如果创建，公开还是私有？

一旦获得用户的回答，将规范写入当前目录的 .agents-cli-spec.md 并获得用户批准。参见 /google-agents-cli-scaffold 了解这些选择如何映射到 CLI 标志。至少包含以下部分——如果用户想要详细的规范，可以扩展更多细节：

# 智能体规范

## 概述
描述智能体的目的及其工作原理。

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

## 所需工具
每个工具及其目的、API 详细信息和认证需求。

## 约束与安全规则
具体规则——不仅仅是通用声明。

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

## 参考示例
查看阶段 1 中的 Notable Samples——列出与此用例匹配的任何示例。

更详细规范的可选部分：要处理的边缘情况、架构与子智能体、数据源与认证、非功能性需求。

一旦你有了清晰的理解，继续阶段 1。

阶段 1：研究参考示例

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

# 克隆一个示例进行研究——阅读关键文件，理解模式，然后将其应用到
# 你自己的脚手架项目中。不要使用 `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 — 按计划或响应事件运行的智能体，无需交互式用户。
  关键词：计划任务、cron、每日、pubsub、事件驱动、警报、电子邮件、环境
  关键文件：expense_agent/fast_api_app.py、expense_agent/agent.py、expense_agent/config.py、terraform/
• adk-ae-oauth — 具有 OAuth 2.0 用户同意的智能体，部署到 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 工具、媒体/图像处理和 Gemini Enterprise 注册。
  关键词：MCP、媒体、视频生成、Veo、虚拟试穿、零售、全栈、React、Gemini Enterprise
  关键文件：genmedia4commerce/agent.py、genmedia4commerce/agent_utils.py、genmedia4commerce/fast_api_app.py
• deep-search — 研究智能体，迭代直到质量达标，并带有来源引用。
  关键词：研究、引用、迭代、接地、多智能体、人在回路中、网络搜索、报告
  关键文件：app/agent.py、app/config.py
• safety-plugins — 可重用的安全护栏，可插入任何智能体运行器。
  关键词：安全、护栏、Model Armor、过滤器
  关键文件：safety_plugins/plugins/model_armor.py、safety_plugins/plugins/agent_as_a_judge.py、safety_plugins/main.py
• data-science — 在托管沙箱中执行代码以进行数据分析的智能体。
  关键词：SQL、BigQuery、代码执行、沙箱
  关键文件：data_science/sub_agents/analytics/agent.py
• memory-bank — 通过 Memory Bank（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、基础设施）。它涵盖架构选择（部署目标、智能体类型、会话存储）以及项目创建或增强。

如果项目已由 agents-cli 创建或增强，则跳过此阶段——从项目根目录运行 agents-cli info 进行检查。

阶段 3：构建与实现

实现智能体逻辑：

1. 在智能体目录中编写/修改代码（检查 GEMINI.md / CLAUDE.md 了解目录名称）
2. 快速冒烟测试：使用 agents-cli run "your prompt" 验证更改后智能体是否正常工作——这是在不离开终端的情况下检查行为的最快方法
3. 根据用户反馈迭代实现

如果用户要求交互式测试，建议使用 agents-cli playground——它会打开一个基于 Web 的游乐场，用于与智能体进行手动对话。

有关 ADK API 模式和代码示例，请使用 /google-agents-cli-adk-code。

永远不要编写断言 LLM 输出内容的 pytest 测试（例如，检查响应中的关键词、验证角色、评估语气）。LLM 输出是非确定性的——这些测试本质上是脆弱的，应属于评估，而不是 pytest。使用 agents-cli run 进行快速检查，使用 agents-cli eval generate 后跟 agents-cli eval grade 进行系统验证。

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

对于 agentic_rag 项目，在测试之前配置数据存储：agents-cli infra datastore，然后 agents-cli data-ingestion。使用 infra datastore——不是 infra single-project（相同的数据存储配置但更快，跳过不相关的 Terraform）。

阶段 4：评估

这是最重要的阶段。 评估端到端验证智能体行为。

强制要求： 在运行评估之前激活 /google-agents-cli-eval。
它包含数据集模式、配置格式和关键陷阱。不要跳过。

不要跳过此阶段。 构建智能体后，你必须继续评估。不要编写 pytest 测试来验证智能体行为——那是评估的用途。

uv run pytest 与 agents-cli eval——了解区别：

• uv run pytest — 测试代码正确性：导入工作、函数返回预期类型、API 契约成立。不测试智能体是否表现良好。
• agents-cli eval — 测试智能体行为：响应质量、工具使用、角色一致性、安全合规性。这才是验证智能体实际工作的方法。
• agents-cli run "prompt" — 开发期间的快速一次性冒烟测试。如果要测试多个提示，请使用 --start-server 选项持久化本地服务器，这减少了重复调用的开销，并允许通过 --session-id 恢复本地会话。使用此方法进行快速迭代，而不是 pytest。

永远不要编写检查 LLM 响应内容的 pytest 测试（例如，断言出现海盗关键词、检查智能体是否提到过敏）。LLM 输出是非确定性的。请改用带有 LLM 作为评判标准的评估。

1. 从小开始：从 1-2 个示例评估用例开始，而不是完整套件
2. 运行评估：agents-cli eval run（链接 generate + grade）。对于调试或自定义跟踪位置，使用两步形式：agents-cli eval generate 然后 agents-cli eval grade。
3. 与用户讨论结果
4. 修复问题并首先迭代核心用例
5. 仅在核心用例通过后，添加边缘用例和新场景
6. 重复直到达到质量标准

预计此处需要 5-10 次以上迭代。

阶段 5：部署

一旦达到评估阈值：

1. 检查项目是否配置了部署目标——运行 agents-cli info 查看当前配置
2. 如果项目是原型（无部署目标），首先添加部署支持：

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

   参见 /google-agents-cli-deploy 了解部署目标决策矩阵（Agent Runtime vs Cloud Run vs GKE）。
3. 准备就绪时部署：agents-cli deploy

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

阶段 6：发布（可选）

并非所有智能体都需要此步骤——目前支持 Gemini Enterprise。参见 /google-agents-cli-publish 了解注册模式、标志和故障排除。

阶段 7：观察

部署后，使用可观察性工具监控生产环境中的智能体行为。参见 /google-agents-cli-observability 了解 Cloud Trace、提示-响应日志记录、BigQuery Analytics 和第三方集成。

---

编码智能体的操作指南

常见的应避免的捷径

智能体通常会以看似合理的借口跳过步骤。识别这些并加以抵制：

捷径	为什么会失败
“用户的请求足够清晰，无需澄清”	你在猜测需求。阶段 0 的存在是为了在搭建脚手架之前确认意图——即使一个问题也可以防止全面返工。
“智能体在 agents-cli run 中正确响应，因此不需要评估”	一个提示不是测试套件。评估能捕获回归、边缘情况和工具轨迹问题，单次运行永远无法做到。
“我将使用更新/更好的模型”	脚手架模型是经过深思熟虑选择的。未经要求更改它违反了代码保留（原则 1），并且通常会破坏东西——错误的位置、已弃用的版本或 404。你的训练数据可能已过时——依赖技能和模型列表命令，而不是你对模型名称的了解。
“我可以跳过脚手架并手动设置”	手动设置会遗漏评估样板、CI/CD 配置和项目配置清单约定。即使对于快速实验，也要使用 agents-cli create。

原则 1：代码保留与隔离

代码修改需要精确——仅更改用户请求直接针对的代码段，并严格保留所有周围和不相关的代码。

强制性的执行前验证：

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

1. 目标识别： 根据用户的明确指示，明确定义要更改的确切行或表达式。
2. 保留检查： 确认所有代码、配置值（例如 model、version、api_key）、注释和格式在识别目标之外保持不变。

示例：

• 用户请求： “将智能体的指令更改为食谱推荐器。”
• 不正确（违规）：

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

• 正确（合规）：

  root_agent = Agent(
      name="recipe_suggester",  # 可以，与新目的相关
      model="gemini-flash-latest",  # 保留
      instruction="You are a recipe suggester."  # 可以，直接目标
  )
  

原则 2：执行最佳实践

• 模型选择——关键：

  • 除非明确要求，否则永远不要更改模型。
  • 创建新智能体（而非修改现有）时，使用最新的 Gemini 模型。列出可用模型以选择最新的：

    # 使用 '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 安装路径。

系统化调试

当出现问题时，按以下顺序进行——不要跳过步骤或乱试修复：

1. 重现 — 运行失败的确切命令。保存完整的错误输出。如果无法重现，就无法修复。
2. 定位 — 缩小原因：是智能体代码、工具、配置还是环境？使用 agents-cli run "prompt" 将智能体行为与部署问题隔离。添加 -v（--verbose）以打印完整的 JSON 事件负载——有助于检查工具调用、中间步骤和静默失败。
3. 一次修复一件事 — 一次只更改一个变量。如果同时更改指令、工具和配置，你将不知道是什么修复了问题（或什么破坏了其他东西）。
4. 验证 — 重新运行确切的重现命令。不要假设修复有效。
5. 防护 — 如果是一个不明显的错误，添加一个评估用例以捕获回归。

停止线规则： 如果更改破坏了原本正常工作的东西，停止功能工作并首先修复回归。不要推进希望以后能绕回来——回归会累积。

• 环境变量：
  • .env 文件和环境变量赋值（例如 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION）通常是智能体运行所必需的——除非用户明确要求，否则永远不要删除或修改它们
  • 如果项目根目录中存在 .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	将技能安装到编码智能体
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 Web 游乐场）
agents-cli run "prompt"	使用单个提示运行智能体（非交互式）。添加 -v 以获取完整的 JSON 事件负载。
agents-cli lint	检查代码质量
agents-cli lint --fix	自动修复 lint 问题
agents-cli lint --mypy	同时运行 mypy 类型检查
agents-cli install	安装项目依赖（uv sync）

评估

命令	用途
agents-cli eval dataset synthesize	为你的智能体合成多轮评估场景（冷启动数据集）
agents-cli eval generate	在默认数据集上运行智能体推理，生成跟踪
agents-cli eval generate --dataset PATH	为特定数据集运行推理
agents-cli eval grade	使用 eval_config.yaml 中的指标对跟踪进行评分
agents-cli eval grade --metrics METRIC	使用特定指标评分（覆盖 eval_config.yaml）
agents-cli eval metric list	列出 SDK 中可用的内置指标
agents-cli eval compare BASE CAND	比较两个评分结果文件（回归检查）
agents-cli eval analyze --eval-result RESULTS	从评分结果文件中聚类失败模式
agents-cli eval optimize	使用评估数据自动调整智能体提示
agents-cli eval submit --dataset D --dest gs://BUCKET	在 Vertex AI Eval Service 上提交托管的云端评估运行
agents-cli eval results --run-id ID	获取已提交的云端评估运行的状态/结果

部署与基础设施

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

项目信息

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

使用 agents-cli info 发现 CLI 安装路径——这是 CLI 源代码所在的位置。读取该路径下的文件以了解 CLI 内部结构、命令实现或模板逻辑。该命令仅在生成的智能体项目内运行时显示项目详细信息（即项目根目录中有 agents-cli-manifest.yaml 的项目）。

认证

命令	用途
agents-cli login --interactive	使用 Google 进行 ADK 服务认证（-i / --interactive 是交互式基于浏览器认证所必需的）
agents-cli login --status	显示认证状态

[!NOTE]
使用 API 密钥进行认证时，login 命令不会自动持久化它们，它只是帮助检索它们并提供如何持久化的说明。

---

技能版本

故障排除提示： 如果技能看起来过时或不完整，请重新安装：

agents-cli setup --skip-auth

仅当你怀疑过时的技能导致问题时才这样做。

---

相关技能

• /google-agents-cli-scaffold — 项目创建、需求收集和增强
• /google-agents-cli-adk-code — ADK Python API 快速参考和生产示例智能体
• /google-agents-cli-eval — 评估方法、数据集模式和评估-修复循环
• /google-agents-cli-deploy — 部署目标、CI/CD 流水线和生产工作流程
• /google-agents-cli-publish — Gemini Enterprise 注册
• /google-agents-cli-observability — Cloud Trace、日志记录、BigQuery Analytics 和第三方集成