google-agents-cli-workflow

Agent 开发工作流与指南

agents-cli 是一个 CLI 和技能工具包，用于在 Google Cloud 上构建、评估和部署 Agent。它适用于任何编码 Agent——Antigravity CLI、Claude Code、Codex 等——也适用于你选择的 Agent 框架（默认使用 Agent Development Kit (ADK)）。使用 uvx google-agents-cli setup 安装。

编写 Agent 代码前，请确保项目已完成脚手架搭建（参见阶段 2）。 跳过脚手架搭建会丢失评估样板代码、CI/CD 配置和项目约定。

要求：google-agents-cli = 1.11.0 如果版本较旧，请运行：uv tool install "google-agents-cli=1.11.0"

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

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

每个阶段开始前都要重新阅读相关技能——不要等到已经开始并遇到问题后才阅读。上下文压缩可能会丢弃之前的技能内容。如果技能不可用，请运行 uvx google-agents-cli setup 进行安装。

阶段	技能	加载时机
0 — 了解需求	—	无需技能——如果存在 .agents-cli-spec.md，请阅读；否则与用户确认目标
1 — 学习示例	/google-agents-cli-adk-code	在设计期间加载，先于脚手架搭建。Python：references/samples.md 主题索引会将需求映射到相应的实现示例。Go：上游 examples/ 起到同样的作用。是的，请尽早加载。
2 — 搭建脚手架	/google-agents-cli-scaffold	创建或增强项目之前
3 — 构建	/google-agents-cli-adk-code	编写 Agent 代码之前——API 模式、工具、回调、状态
4 — 评估	/google-agents-cli-eval	运行任何评估之前——数据集架构、指标、评估修复循环
5 — 部署	/google-agents-cli-deploy	部署之前——目标选择、403/超时故障排查
6 — 发布	/google-agents-cli-publish	部署后，如需在 Gemini 中注册（可选）
7 — 观测	/google-agents-cli-observability	部署后——跟踪、日志记录、监控设置

---

设置

如果尚未安装 agents-cli：

uv tool install google-agents-cli

找不到 uv 命令

请按照官方安装指南安装 uv。

产品名称映射

用户对产品的称呼并不一致（Vertex AI 或 Agent Platform → Gemini 平台，Agent Engine 或 Agent Runtime → Gemini 平台中的 Agent Runtime，等等）。请使用 references/terminology.md 将用户术语映射为 CLI 值。

---

阶段 0：了解需求

在编写或搭建任何内容之前，先弄清楚要构建什么——通过设计对话，而不是核对清单。加载 references/brainstorming.md 并遵循其中的要求：每次只问一个问题；对于非简单的 Agent，提出 2–3 种架构方案；并在搭建任何内容之前确认设计。

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

在用户批准规格说明之前，不要继续规划、搭建或编写代码。不要自行假设、调研或补全缺失信息——一切以用户意图为准。

根据复杂度调整流程： 简单的 Agent（单个工具、固定角色设定）只需问几个问题、写一份 2–3 句的规格说明，并获得一次批准；复杂的 Agent（多 Agent、RAG、外部 API／身份验证、安全关键型）则按 references/brainstorming.md 完整执行。

需要讨论的主题（每次只问一个问题，并根据用户情况调整——参见操作指南）：

1. Agent 要解决什么问题？ — 核心用途和能力
2. 需要哪些外部 API 或数据源？ — 工具、集成、身份验证要求
3. 有哪些安全约束？ — Agent 绝不能做什么、需要哪些防护措施
4. 部署偏好是什么？ — 先做原型（推荐）还是完整部署？如果要部署，选择 Agent Runtime、Cloud Run 还是 GKE？

根据上下文提问：

• 如果 Agent 需要脚手架未内置的能力——例如从你的数据中检索信息、沙盒代码执行、跨会话记忆、OAuth 授权、安全防护或事件驱动触发——该能力应通过克隆并研究配方实现，而不是设置脚手架标志。请在 /google-agents-cli-adk-code → references/samples.md 的主题索引中查找所需能力，并在阶段 1 研究对应配方。
• 如果 Agent 是实时或语音 Agent（Live API、语音对话、插话、电话通信），请在编写规格说明之前加载 /google-agents-cli-adk-code（references/adk-python-live.md）。实时 Agent 不适用于 A2A、Gemini 应用和默认模型。
• 如果希望 Agent 可供其他 Agent 使用，每个由 agents-cli 搭建的 Python Agent 脚手架都内置了 A2A 协议；无需单独选择，照常搭建即可。
• 如果选择完整部署，需确定 CI/CD 运行器：GitHub Actions（默认）还是 Google Cloud Build？
• 如果希望 Agent 跨会话记住用户偏好或事实，这属于跨对话的长期记忆。请加载 /google-agents-cli-adk-code——其中包含相关配方（位于 references/samples.md）和 ADK 记忆 API 详情。
• 如果选择 Cloud Run 或 GKE，需确定会话存储：内存（默认）、Cloud SQL（持久化）还是 Gemini 平台中的 Sessions（托管）。
• 如果选择通过 CI/CD 部署，需确定 Git 仓库：是否已有仓库，还是需要新建？如果新建，选择公开还是私有？

设计达成一致后，使用 references/spec-template.md 中的模板将规格说明写入 .agents-cli-spec.md，自行审阅后再征求用户批准。有关这些选择如何对应 CLI 标志，请参阅 /google-agents-cli-scaffold。

充分了解需求后，继续阶段 1。

阶段 1：研究参考方案

触发条件。 如果请求涉及以下任一事项：搜索你自己的文档 · 代表用户运行 shell 或 Python 代码 · 沙箱或按用户隔离的环境 · 在运行时加载 Agent 获取的技能 · 持续数天、可恢复或无人值守运行的工作 · 跨对话记忆 · 在执行前批准高风险操作 · 阻止有害内容或审核 Agent 的发言 · 使用用户自己的 API 密钥或凭据执行操作 · 通过 OAuth 同意访问用户自己的数据 · 向上下文隔离的子 Agent 分派任务 · 通过 A2A 与其他 Agent 通信 · 对事件或日程作出响应 · 在线研究某个主题并附上引用进行报告 · 生成图像或视频 · 根据生产跟踪记录监控已部署 Agent 的质量——那么已有方案实现了该功能。在着手实现之前，先查找相关方案。

此列表涵盖与 /google-agents-cli-adk-code → references/samples.md 中主题索引相同的功能。如果你扩展其中一项，也要扩展另一项。

现在加载 /google-agents-cli-adk-code。即使尚未搭建任何内容、也还没有编写代码，也要加载它；“现在还不是使用代码技能的阶段”正是让 Agent 跳过这一步的借口，而该技能中的编写代码的前提条件并不适用于你。

查找设计所需的每项功能。ADK Python： references/samples.md 中的主题索引将需求（检索、沙箱执行、记忆、审批关卡、护栏、按用户提供凭据、日程安排）映射到相应方案，并说明如何克隆。ADK Go： 没有参考目录——阅读 references/adk-go.md 了解 API，并查看上游的 examples/。

可能有多个方案符合需求——克隆并研究所有相关方案，从各自的 AGENTS.md 开始。

如果没有符合的方案，再进入阶段 2。但首先——你确定吗？重新阅读用户的请求，并再次检查对应语言的主题索引。跳过符合需求的方案，就意味着要重新构建已有模式，而且通常做得更差。

IMPORTANT — 退出标准： 研究完方案后，问问自己：能否应用其中的任何内容来帮助交付设计？继续之前，记下要复用的内容。在回答这个问题之前，不要继续。

此目录在任何阶段都很有用——遇到部署、发布或基础设施问题时，可以重新查阅。方案中的 Terraform 或注册模式之后可能正好派上用场。

阶段 2：搭建项目框架（如有需要）

首先检查项目是否已存在：在项目根目录运行 agents-cli info。如果项目已由 agents-cli 创建或增强，则跳过此阶段。

否则，在编写任何代码之前搭建项目框架：

• 尚无项目 → agents-cli scaffold create <name> --agent <template> --deployment-target <target>
• 导入现有代码 → agents-cli scaffold enhance .（添加 agents-cli 结构）

完整工作流程请使用 /google-agents-cli-scaffold——其中涵盖架构选择（部署目标、Agent 类型、会话存储）以及项目创建或增强。

阶段 3：构建和实现

实现 Agent 逻辑：

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

如果用户要求交互式测试，建议使用 agents-cli playground——它会打开一个基于 Web 的交互环境，供用户与 Agent 手动对话。

如需了解 ADK API 模式和代码示例，请使用 /google-agents-cli-adk-code。

这里只进行冒烟测试——不要编写行为单元测试。 大模型的输出具有非确定性；行为检查应在评估（阶段 4）中进行，而不是在 pytest 或 go test 中进行。使用 agents-cli run "prompt" 进行快速检查。

配置配方基础设施（如果你改编了配方）

需要底层基础设施（数据存储、索引、沙盒、队列）的配方会附带自己的配置流程：按照其 Makefile（例如 make setup-infra、make data-ingestion）以及 AGENTS.md / README.md 操作，并将配方中的 infra/terraform/ 和 .env 适配到你的项目中。 agents-cli 没有用于此操作的命令。

阶段 4：评估

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

必须执行： 运行评估前，先启用 /google-agents-cli-eval。 其中包含数据集架构、配置格式和关键注意事项。不要跳过此步骤。

不要跳过此阶段。 构建 Agent 后，必须继续进行评估。

单元测试与 agents-cli eval——了解二者的区别：

• 单元测试（Python 使用 uv run pytest，Go 使用 go test ./...）——测试代码正确性：导入是否正常、函数是否返回预期类型、API 合约是否成立。不会测试 Agent 的行为是否良好。
• agents-cli eval——测试Agent 行为：回复质量、工具使用、角色一致性、安全合规性。这才是验证 Agent 是否真正可用的方式。
• agents-cli run "prompt"——开发期间进行快速的一次性冒烟测试。如果要测试多个提示词，请使用 --start-server 选项，让本地服务持续运行，从而减少重复调用的开销，并支持通过 --session-id 恢复本地会话。该命令用于快速迭代，而非单元测试。

绝不要编写用于检查大模型回复内容的单元测试（例如断言回复中出现海盗相关关键词，或检查 Agent 是否提到过敏问题）。大模型的输出具有非确定性。请使用带有大模型裁判标准的评估。

1. 从小处开始：先从 1-2 个示例评估用例开始，不要一开始就运行完整套件
2. 运行评估：agents-cli eval run（会依次执行 generate 和 grade）。如需调试或自定义跟踪位置，请分两步执行：先运行 agents-cli eval generate，再运行 agents-cli eval grade。
3. 与用户讨论结果
4. 修复问题，并优先迭代核心用例
5. 只有核心用例通过后，才添加边缘用例和新场景
6. 重复上述步骤，直到每个用例都达到你与用户商定的标准（eval run 无论得分如何都会以 0 退出，因此请查看得分）

预计需要在此阶段迭代 5-10 次或更多。

阶段 5：部署

用户同意评估得分足够好后：

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

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

   请参阅 /google-agents-cli-deploy，了解部署目标决策矩阵（Agent Runtime、Cloud Run 或 GKE）。
3. 准备就绪后进行部署：agents-cli deploy

重要： 未经人工明确批准，绝不要部署。

阶段 6：发布（可选）

并非所有 Agent 都需要发布——目前支持注册到 Gemini。有关注册模式、标志和故障排查，请参阅 /google-agents-cli-publish。

阶段 7：观察

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

---

编码 Agent 操作指南

应当抵制的常见捷径

Agent 经常会用听起来似乎合理的借口跳过步骤。请识别这些借口并予以纠正：

捷径	失败原因
“用户的请求已经足够明确，不需要澄清”	你是在猜测需求。阶段 0 的目的是在搭建框架前确认意图——哪怕只问一个问题，也能避免彻底返工。
“Agent 在 agents-cli run 中响应正确，所以不需要评估”	一个提示词不等于一套测试。评估能发现单次运行无法发现的回归、边缘情况和工具调用轨迹问题。
“我会使用更新／更好的模型”	框架生成的模型是经过慎重选择的。未经用户要求就更改模型，违反代码保留原则（原则 1），而且常常会导致问题——例如位置不正确、版本已弃用或出现 404。你的训练数据很可能已经过时——请依赖技能和模型列表命令，而不是你对模型名称的了解。
“我已经知道如何构建这些功能——沙箱、记忆、审批关卡”	你即将重新发明轮子，而且做得更差。这些能力已经在 /google-agents-cli-adk-code → references/samples.md 中实现并经过实战验证；请先查看主题索引，并在设计自定义方案前打开对应配方的 AGENTS.md。
“我可以跳过框架生成，手动设置”	手动设置会遗漏评估样板代码、CI/CD 配置和项目配置清单惯例。即使是快速实验，也要使用 agents-cli create。

原则 1：代码保留与隔离

修改代码需要精确到位——只修改用户请求直接涉及的代码片段，并严格保留所有周边及无关代码。

执行前必须验证：

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

1. 确定目标： 仅根据用户的明确指示，清楚界定要更改的具体行或表达式。
2. 检查保留内容： 确认已确定目标之外的所有代码、配置值（例如 model、version、api_key）、注释和格式均保持不变。

示例：

• 用户请求：“将 Agent 的指令改为配方推荐者。”
• 错误（违规）：

  root_agent = Agent(
      name="recipe_suggester",
      model="gemini-1.5-flash",  # UNINTENDED - model was not requested to change
      instruction="You are a recipe suggester."
  )
  

• 正确（合规）：

  root_agent = Agent(
      name="recipe_suggester",  # OK, related to new purpose
      model="gemini-3.8-flash",  # PRESERVED
      instruction="You are a recipe suggester."  # OK, the direct target
  )
  

原则 2：执行最佳实践

• 模型选择 — 至关重要：

  • 除非收到明确要求，否则绝不要更改模型。
  • 创建新 Agent（而非修改现有 Agent）时，请使用最新的 Gemini 模型。列出 Agent 实际使用位置（默认是 GOOGLE_CLOUD_LOCATION 中的 global）可用的模型，而不是所有模型，因为并非每个位置都提供所有模型：

    uv run --with google-genai python -c "
    from google import genai
    # 使用你的 GOOGLE_CLOUD_LOCATION（'global'，或 'us-east1' 等区域）
    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 次或以上看到相同错误，请立即停止
  • 危险信号：Lock 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. 定位 — 缩小原因范围：问题出在 Agent 代码、工具、配置还是环境？使用 agents-cli run "prompt" 将 Agent 行为与部署问题区分开来。添加 -v（--verbose）以打印完整的 JSON 事件负载，便于检查工具调用、中间步骤和静默失败。
3. 一次修复一项 — 每次只更改一个变量。如果同时更改指令、工具和配置，你就无法判断是什么修复了问题（或又导致了什么问题）。
4. 验证 — 重新运行确切的复现命令。不要想当然地认为修复已生效。
5. 防范 — 如果是难以察觉的 Bug，请添加一个 eval 用例以捕获回归问题。

**停止推进规则：**如果某项更改导致原本正常运行的功能出问题，请暂停功能开发，优先修复回归问题。不要指望以后再回头处理后继续推进 — 回归问题会不断累积。

• 环境变量：
  • .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 封装的底层工具和命令，按语言分类（Python：adk、uv、ruff；Go：adk-go、go、golangci-lint）
references/spec-template.md	.agents-cli-spec.md 模板和可选章节
references/brainstorming.md	第 0 阶段设计对话手册（一问一答、方案、关卡）
references/terminology.md	产品名称 → CLI 值映射
references/commands.md	按阶段划分的 agents-cli 命令索引
references/extension.md	编写临时扩展或采用现有扩展（覆盖或添加命令）

开发命令

运行 agents-cli --help 或 agents-cli <command> --help，查看权威的标志列表。各阶段的命令索引位于 references/commands.md；各阶段的用法见上文对应章节。

要覆盖内置命令（例如，为 deploy 添加合规性检查），或添加新命令，agents-cli 提供了扩展系统。要为此仓库编写临时扩展或采用现有扩展，请加载 references/extension.md。

---

Skills 版本

**故障排查提示：**如果 Skills 似乎已过时或不完整，请重新安装：

agents-cli setup --skip-auth

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