adk-dev-guide

ADK 开发工作流与指南

会话连续性

如果这是一个较长的会话，请在每个阶段开始前重新阅读相关技能 — 编写代码前阅读 /adk-cheatsheet，运行评估前阅读 /adk-eval-guide， 部署前阅读 /adk-deploy-guide，搭建脚手架前阅读 /adk-scaffold。 上下文压缩可能会丢失之前的技能内容。

---

DESIGN_SPEC.md — 主要参考资料

重要提示：如果项目中存在 DESIGN_SPEC.md，它就是首要的事实来源。

请先阅读它，以了解：

• 功能需求与能力
• 成功标准与质量阈值
• Agent 行为约束
• 预期的工具与集成

规范就是你的契约。 所有实现决策都应与之保持一致。如有疑问，请查阅 DESIGN_SPEC.md。

---

阶段 1：理解规范

编写任何代码之前：

1. 认真阅读 DESIGN_SPEC.md
2. 确定所需的核心能力
3. 留意任何约束或 Agent 不应执行的事项
4. 了解评估的成功标准

阶段 2：构建与实现

实现 Agent 逻辑：

1. 在 Agent 目录中编写或修改代码（查看 Agent 指引文件，例如 GEMINI.md 或 CLAUDE.md，确定目录名称）
2. 开发期间使用 make playground（或 adk web .）进行交互式测试
3. 根据用户反馈迭代实现

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

阶段 3：评估

这是最重要的阶段。 评估会使用评估集和评分指标端到端验证 Agent 的行为。

必须执行： 运行评估前启用 /adk-eval-guide。其中包含评估集架构、配置格式和关键注意事项。切勿跳过。

测试（pytest）不等于评估。 测试用于检查代码正确性，但无法说明 Agent 的行为是否正确。务必运行 adk eval。

1. 从小规模开始：先使用 1-2 个示例评估用例，而不是完整套件
2. 运行评估：adk eval（如果项目有 Makefile，也可以使用 make eval）
3. 与用户讨论结果
4. 先修复问题，并迭代核心用例
5. 只有核心用例通过后，才添加边缘用例和新场景
6. 重复以上过程，直到达到质量阈值

预计需要在此阶段迭代 5-10 次以上。

阶段 4：部署

达到评估阈值后：

1. 准备就绪后进行部署 — 部署选项请参阅 /adk-deploy-guide

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

---

编码 Agent 操作指南

原则 1：代码保留与隔离

执行代码修改时，首要目标是精准地进行手术式修改。你必须只修改用户请求直接指定的代码部分，同时严格保留所有周边及无关代码。

执行前必须核验：

完成任何代码替换前，请确认：

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

示例：

• 用户请求：“将 Agent 的指令改为提供食谱建议。”
• 错误（违规）：

  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-3-flash-preview",  # 保留
      instruction="You are a recipe suggester."  # 可以修改，属于直接目标
  )
  

原则 2：执行最佳实践

• 模型选择 — 严重：

  • 除非得到明确要求，否则绝不要更改模型。 如果代码使用 gemini-3-flash-preview，就保持使用 gemini-3-flash-preview。不要“升级”或“修正”模型名称。
  • 创建新 Agent（而非修改现有 Agent）时，请使用 Gemini 3 系列：gemini-3-flash-preview、gemini-3-pro-preview。
  • 除非用户明确要求，否则不要使用较旧的模型（gemini-2.0-flash、gemini-1.5-flash 等）。

• 位置比模型更重要：

  • 如果模型返回 404，几乎总是 GOOGLE_CLOUD_LOCATION 的问题（例如，需要使用 global 而不是 us-central1）。
  • 通过更改模型名称来“修复” 404 属于违规行为——应修正位置。
  • 某些模型（如 gemini-3-flash-preview）要求使用特定位置。请查看错误消息中的提示。

• ADK 内置工具导入（必须精准）：

  # 正确 - 导入工具实例
  from google.adk.tools.load_web_page import load_web_page
  
  # 错误 - 导入模块，而非工具
  from google.adk.tools import load_web_page
  

  将导入的工具直接传入 tools=[load_web_page]，而不是 tools=[load_web_page.load_web_page]。

• 运行 Python 命令：

  • 始终使用 uv 执行 Python 命令（例如，uv run python script.py）
  • 执行脚本前运行 make install（或 uv sync）
  • 查阅 Makefile 和 README.md，了解可用命令（如果存在）

• 打破无限循环：

  • 如果连续 3 次或更多次遇到相同错误，立即停止
  • 不要重试失败的操作——先修复根本原因
  • 危险信号：锁定 ID 不断递增、名称不断追加 v5->v6->v7、反复说“我再试一次”
  • 状态冲突（错误 409：资源已存在）：使用 terraform import 导入现有资源，而不是重试创建
  • 工具 bug：继续操作前先修复源代码中的 bug——不要绕过它们
  • 陷入困境时：直接运行底层命令（例如，terraform CLI），而不是调用有问题的工具

• 故障排查：

  • 首先查看 /adk-cheatsheet——其中涵盖了大多数常见模式
  • 使用 Glob/Grep/Read 搜索已安装的 ADK 软件包（通过 python -c "import google.adk; print(google.adk.__path__[0])" 查找；如果使用 uv，请运行 uv run python）
  • 如需 ADK 文档索引，请使用 curl https://adk.dev/llms.txt
  • 遇到框架问题或 GCP 产品问题时，请查阅官方文档
  • 遇到持续存在的错误时，针对性地使用 Google Search 往往能更快找到解决方案

---

将脚手架用作参考

如果需要特定基础设施文件，但不想直接为当前项目创建脚手架，请使用 /adk-scaffold 技能在 /tmp/ 中创建临时参考项目，然后复制所需内容。

完整的 CLI 命令和选项请参阅 /adk-scaffold。

---

开发命令

通过 Agent Starter Pack CLI 创建的项目包含一个 Makefile，其中提供以下命令。 如需创建或增强项目，请参阅 /adk-scaffold 技能中的完整说明。 对于未通过脚手架创建的项目，请使用对应的 ADK CLI 命令。

Make（通过脚手架创建）	对应的 ADK CLI 命令	用途
make playground	adk web .	交互式本地测试
make test	pytest	运行单元测试和集成测试
make eval	adk eval <agent_dir> <evalset>	对 evalset 运行评估
make lint	ruff check .	检查代码质量
make setup-dev-env	—（仅限通过脚手架创建）	设置开发基础设施（Terraform）
make deploy	—（仅限通过脚手架创建）	部署到开发环境（需要人工批准）

---

技能版本

**故障排除提示：**如果你反复遇到错误、工具意外失败，或者这些技能中的说明似乎不完整，或引用了你找不到的功能，则这些技能可能已过时。运行：

npx skills check -g

如果报告技能已过时，请告知用户进行更新：

npx skills update -g

不要在每次会话中都运行此检查——仅在你怀疑问题是由技能过时导致时运行。