使用 Antigravity 和 Spec-kit 进行规范驱动的 ADK 智能体开发

1. 简介

向现有代理添加功能（一种新的数据库支持功能）通常意味着要编写样板代码、连接集成，并使所有内容与代码库中已有的模式保持一致。Antigravity 可加速此流程的每个阶段：它会分析您的代码库以构建所需的上下文，生成结构化规范和实现方案供您审核，并执行代码更改 - 所有这些都以领域知识为指导，而领域知识可帮助您捕获可重用的技能和强制执行不可协商原则的项目章程。本 Codelab 介绍了一种通过引入新周期来大幅提升规范文档（大量参考 spec-kit）的方式，从而增强 Antigravity 规范驱动的开发范式。

构建内容

一个本地运行的餐厅礼宾应用，通过完整的 SDD 周期添加了预订功能：

• 预订 - 宾客预订餐位和查看预订信息，由新的 MCP Toolbox 数据库工具和 Cloud SQL reservations 表提供支持
• （挑战）- 为代理开发自己的界面
• （挑战）- 在 Antigravity 代理的帮助下部署到 Google Cloud

起始代码提供了一个可正常运行的 ADK 代理，该代理具有菜单搜索（通过 MCP Toolbox 进行关键字搜索和语义搜索）和饮食偏好跟踪（通过 ToolContext 进行）功能。您无需手动编写应用代码即可扩展它，Antigravity 会根据您的规范处理实现。

学习内容

• 如何引导项目上下文，以便 Antigravity 了解现有代码库
• 如何创建封装领域知识（例如 ADK Codelab 模式）以供重复使用的 Antigravity 技能
• 如何在规划和分析期间设置 SDD 工作流验证的项目章程
• 如何在 Antigravity 中使用 Spec-Driven Development (SDD) 工作流来系统地添加功能
• 如何通过 MCP Toolbox 使用新的数据库支持的工具来扩展 ADK 智能体

前提条件

• 本地机器上安装了 Google Antigravity 和 git
• 已启用有效结算账号的 Google Cloud 账号
• 如果您之前已完成 4 个必备的 ADK Codelab（或具备同等知识），将有助于您了解应用场景背景：
• 使用 ADK 构建 AI 智能体：基础知识
• 使用 ADK 构建 AI 智能体：配备工具
• 使用 ADK 和 CloudSQL 构建持久性 AI 智能体
• 在 Cloud Run 上部署、管理和观察 ADK 智能体
• 数据库即工具：使用 ADK、MCP Toolbox 和 Cloud SQL 的智能体 RAG

2. 设置环境

重要注意事项：

本教程需要具有有效结算账号的 Google Cloud 项目。如果您还没有，请使用本 Codelab 顶部的横幅获取可用于本教程的试用结算账号。

此步骤会克隆初始代码库、通过 Google Cloud 进行身份验证、预配 Cloud SQL 数据库，并准备本地 Antigravity 环境。

注意：此 Codelab 完全在本地机器上的 Google Antigravity 中运行。设置包括使用 gcloud CLI 命令进行手动身份验证

安装必要工具

确保您的系统具有以下 CLI 可执行文件：

• git
• gcloud
• uv
• npm

安装说明因您机器的操作系统而异。

克隆初始代码库

在 Antigravity（或系统终端）中打开一个终端。克隆配套代码库并进入相应目录：

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

在 Antigravity 中打开克隆的代码库。文件->打开文件夹->选择克隆的目录 sdd-adk-agents-agy

移除上游远程。SDD 工作流会为功能规范创建 Git 分支 - 移除远程代码库可防止意外推送到初始代码库：

git remote remove origin

重要提示：此 Codelab 中的 SDD 工作流使用 git 分支来整理功能规范。移除 origin 远程可确保您的本地分支和提交保持本地状态。如果您想备份自己的工作，请添加自己的遥控器：git remote add origin <your-repo-url>

向 Google Cloud 进行身份验证

运行两个身份验证命令。两者都会打开浏览器以进行 OAuth：

gcloud auth login
gcloud auth application-default login

注意：在第二个 OAuth 命令中，当系统提示您选择权限时。检查所有选项

注意：请务必使用您用于申领试用结算账号的电子邮件地址进行身份验证

由于您是在本地使用 Antigravity，因此需要手动进行身份验证。auth login 对 gcloud CLI 进行身份验证。application-default login 对应用使用的 Google Cloud SDK 进行身份验证 - ADK 的 Vertex AI 调用和 Cloud SQL Python 连接器都依赖于应用默认凭证。

设置您的 Google Cloud 项目

在运行项目设置脚本之前，将位置变量写入 .env：

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global 用于 Vertex AI / Gemini API 调用。
• REGION=us-central1 用于 Cloud SQL 和其他 GCP 基础架构

重要提示！以下步骤旨在帮助您快速设置与试用结算账号（严格）相关联的 Google Cloud 项目。如果您想使用自己之前的项目，可以跳过以下步骤，改为执行以下步骤：

在 .env 文件中添加您自己的项目名称作为 GOOGLE_CLOUD_PROJECT 变量

在终端中使用 gcloud config set project your-project-id 激活您的项目

然后，您可以直接跳到“启用 API”部分

如果您不确定，请继续阅读下文

下载并运行项目设置脚本。它会创建或验证具有试用结算功能的 Google Cloud 项目，并将项目 ID 保存到 .env，然后获取该项目 ID：

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

正在启用 API

启用必需的 API：

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

注意：启用 API 可能需要一点时间。您只需为每个项目执行一次此操作。

安装依赖项

我们将使用 uv 作为 Python 项目管理器。uv 是一个用 Rust 编写的快速 Python 软件包和项目管理器（文档）。此 Codelab 使用它是因为它速度快且简单易用。安装 Python 依赖项：

uv sync

然后，使用项目配置更新 ADK 代理的 .env 文件：

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

准备数据库基础设施和数据

设置数据库密码并将其添加到 .env：

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

重要提示：上述硬编码的密码仅用于教程目的。在生产环境中，请使用 Secret Manager 等服务安全地存储凭据，并在运行时引用它们，切勿将明文密钥提交到源代码控制系统。

然后，运行 scripts/setup_database.sh 脚本来准备所需的所有基础架构。它将执行以下操作：

• 创建 Cloud SQL 实例
• 检查实例是否已准备就绪
• 授予 Vertex AI 权限
• 创建数据库
• 种子数据库
• 在后台运行 MCP Toolbox 服务

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

此命令将在后台运行设置，您可以定期检查 database_setup.log 文件中的输出

现在，我们应该拥有所有必需的入门级 ADK 代理代码库，可以开始工作了。现在，在等待一切就绪的同时，我们将在下一部分中详细介绍 Antigravity 和规范驱动的开发

3. 探索起始代码并了解规范驱动开发

此步骤将介绍起始代码结构、引入规范驱动开发方法、为数据库植入初始数据，并在您开始扩展基本代理之前验证其是否正常运行。

项目结构

在 Antigravity 编辑器中打开克隆的代码库项目，并查看目录布局：

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── mcp-toolbox-postgres/
│   │   │   └── SKILL.md     # MCP Toolbox config skill
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis skill
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

关键文件

代理应用文件

• restaurant_concierge/agent.py - 核心代理。一种将 MCP Toolbox 数据库工具与基于 ToolContext 的饮食偏好跟踪功能相结合的 LlmAgent。智能体从工具箱服务器加载所有工具，并添加两个使用 ToolContext 管理状态的 Python 函数（save_dietary_preference、get_dietary_preferences）。
• tools.yaml - MCP Toolbox 工具定义。定义了三个菜单搜索工具：关键字搜索 (search_menu)、通过 pgvector (semantic_search_menu) 进行的语义搜索和类别过滤条件 (get_menu_by_category)。目前还没有预订工具，您稍后会添加这些工具
• server.py - 一个最小的 FastAPI 服务器，展示了如何以 FastAPI 对象的形式访问 ADK。ADK 中的 get_fast_api_app() 提供内置端点，包括用于 SSE 流式传输和会话管理 API 的 /run_sse。

Antigravity 文件

• .agents/skills/mcp-toolbox-postgres/SKILL.md - 一项技能，可指导 Antigravity 如何为 MCP 工具箱创建合适的 tools.yaml 配置。此技能将介绍与 sources、tools 和 embeddingModels 相关的配置，这些配置是构建合适的 RAG 流水线所必需的。在您添加适当的 YAML 前言以供 Antigravity 识别之前，此技能不会被激活
• .agents/skills/repo-research/SKILL.md - 一项技能，可教导 Antigravity 如何以增量方式分析代码库并生成结构化项目上下文文档。它采用 4 阶段方法：表面扫描（仅限目录树）、配置文件和元数据文件、入口点和数据模型，然后进行有针对性的深入分析 - 每个阶段都会在继续下一个阶段之前停止并写入发现的结果。在您稍后添加 YAML 前言之前，它也处于非活动状态。激活后，调用该功能以生成 .agents/rules/project-context.md，这是一份全面的初始配置文档，涵盖架构、运行时依赖项、API 接口和网域词汇表。

Spec-Driven Development：从 Antigravity 的内置规划到结构化 SDD

借助 AI 编码助理，您可以轻松根据提示生成代码。风险：您用一句话描述了一项功能，助理写了数百行代码，您接受了它，因为看起来没问题。这种方式有时称为“氛围编程”，即凭感觉进行引导，根据输出结果是否有效来接受或拒绝。对于原型和临时脚本，它的速度很快。当代码库变大、功能相互交互或您在几周后重新查看代码时，如果无法重构做出决策的原因，就会出现问题。

规范驱动开发 (SDD) 为此循环添加了结构。在生成任何代码之前，您需要编写规范：功能的作用、服务对象、成功标准。AI 助理会根据该规范运行，您在查看其输出时也是如此。规范成为意图的唯一可信来源。如果代码与规范不一致，您可以在审核时发现。如果要求发生变化，您需要先更新规范，然后再重新生成。决策有据可查，而非临时起意。

这种权衡是实际存在的：与氛围编程 (vibe coding) 相比，SDD 在每个特征上的速度较慢。您先编写文档，然后再编写代码。但回报会不断增加 - 代码库的每次未来更改都有上下文，每次 AI 生成的实现都有可审核的合约，您可以通过指向规范来让协作者（人类或 AI）加入项目，而无需凭记忆解释决策。

Antigravity 已经遵循了规范驱动的开发原则。当您将代理设置为规划模式时，它会在编写任何代码之前生成两个制品：

• 实施计划 - 拟议的技术方法、文件更改和架构决策的概览
• 任务列表 - 工作项的结构化细分

Antigravity 会要求您在执行之前查看并批准这些制品。这种先规划再实现的循环是规范驱动型开发的核心：规范指导代码，而不是反过来。

此 Codelab 在此基础上进一步介绍了基于 spec-kit（GitHub 提供的一个规范驱动型开发框架）的意见主导型版本控制工作流。每个功能都经过精心设计的流水线，其中每个制品都是一个独立的文档，您可以在 git 中查看、修改和跟踪这些制品。该流水线包含两个可选的质量关口阶段（明确和分析），可在问题成为实现问题之前发现它们：

阶段	工件	用途
/speckit.specify	spec.md	定义要构建的内容（面向用户，与技术无关）
/speckit.clarify （可选）	更新时间：spec.md	找出未明确指定的区域，提出有针对性的澄清问题，将答案重新编码到规范中
/speckit.plan	plan.md、data-model.md、research.md	设计如何构建（技术方法、数据模型、研究）
/speckit.tasks	tasks.md	将计划分解为有序的、可操作的步骤
/speckit.analyze （可选）	分析报告	在实施之前，检查任务是否存在风险、缺口或缺失的极端情况
/speckit.implement	代码变更	执行任务，并逐一勾选

每个制品都以文件形式持久保存在 specs/<feature-branch>/ 中，在 Git 中受版本控制，并且可重复使用。如果对话中断，或者您想稍后重新查看决策，规范文档始终存在，不会埋没在对话记录中。

注意：Antigravity 内置制品在界面方面具有优势，可让用户对生成的制品（甚至是图片！）。因此，在本教程中，我们将修改原始 spec-kit 提示，以在 implement 阶段与内置制品集成

启动代码库在 .agents/workflows/ 中包含这些 SDD 工作流，在 .specify/templates/ 中包含模板。您稍后将使用这些工具为代理添加功能。

4. 使用 Antigravity 引导项目上下文

现在，我们来模拟一种“更接近”日常工作的条件：

• 管理不善的代码库
• README 已过时
• 文档不会频繁更新

注意：如果此情况与您的实际情况不符，请认为自己非常幸运

在这种情况下，我们通常首先要做的就是创建有关我们希望 Antigravity 处理的项目的地图或上下文。此步骤展示了一种方法示例，该方法通过创建分析代码库并生成项目上下文文档的技能，使 Antigravity 能够深入了解现有代码库。

它还会设置项目章程，即 SDD 工作流验证所依据的不可协商的原则。这些信息共同为 Antigravity 提供了后续 SDD 周期所需的背景信息和限制条件

Antigravity 上下文层次结构

Antigravity 使用了三个级别的上下文，每个级别的范围都不同：

• 规则 (.agents/rules/)：始终处于有效状态的指令。此工作区中的每项对话都会显示它们（如果您已启用）。使用规则可提供项目范围内的背景信息，例如架构决策、编码标准或技术栈信息。
• 技能 (.agents/skills/)：按需获取知识。Antigravity 仅在当前任务与技能的 description 字段匹配时加载技能。使用技能获取特定领域的参考资料。
• 工作流 (.agents/workflows/)：通过 / 命令触发的已保存提示。使用工作流来处理可重复的多步流程，例如 SDD 流水线。

注意：该项目目前有工作流（SDD 流水线）和 2 项技能（repo-research 和 mcp-toolbox-postgres），但没有规则。稍后，我们将创建一条 project-context.md 规则，让 Antigravity 持久了解代码库 - 使用的技术、文件组织方式、目前已构建的内容。

激活技能

起始代码库在 .agents/skills/ 中包含两个预先编写的技能。它们包含详细说明，但以 TODO(codelab) 注释开头，而不是必需的 YAML 前言。如果没有前言，Antigravity 就无法发现它们。

反重力技能需要在文件顶部的 YAML 前言块中包含两个字段：

• name - 技能的唯一标识符
• description - Antigravity 在决定为给定请求加载哪个技能时会匹配的自然语言摘要

在编辑器中打开 .agents/skills/mcp-toolbox-postgres/SKILL.md。将顶部的 TODO(codelab) 注释行替换为以下前言：

---
name: mcp-toolbox-postgres
description: Configure MCP Toolbox for PostgreSQL — sources, tools, and embedding models
---

注意：MCP Toolbox Postgres 技能包含 sources、tools 和 embedding models 的正确配置

在编辑器中打开 .agents/skills/repo-research/SKILL.md。将顶部的 TODO(codelab) 注释行替换为以下前言：

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

注意：请详细阅读 repo-research SKILL.md。以下是一个用于分析代码库的示例提示，请注意，增量更新规则有意保持保守。如果在研究过程中 Antigravity 的上下文用完或对话中断，目前为止发现的所有内容都已保存到文件中。重新调用技能后，系统会从上次中断的位置继续，而不会丢失进度。

警告！分析大型代码库可能会快速耗尽您的配额！

验证这两个技能是否都具有有效的前言：

head -4 .agents/skills/mcp-toolbox-postgres/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

每个都应显示用 --- 分隔符封装的 name: 和 description: 字段。如果分隔符或字段缺失，Antigravity 将无法识别该技能。

这两项技能都是按需加载的 - Antigravity 会根据 description 字段将您的请求与完整说明进行匹配，只有在相关时才会提取完整说明。

安装公开可用的技能

ADK 技能速查表

之前，我们检查了自行创建的技能（repo-research 和 mcp-toolbox-postgres 技能）。不过，还有许多其他技能可用于支持我们的软件开发，并且可以轻松安装到编码智能体中。例如，在本教程中，我们需要与 ADK 进行互动，因此需要具备有关如何使用 ADK 进行构建的适当知识。我们来使用以下命令安装 ADK 文档技能

npx skills add google/adk-docs

然后，系统会提示您确认安装，如下所示

按 y 继续，系统会显示下一个提示，让您选择要安装的技能，如下所示。目前，我们只选择 adk-cheatsheet（按空格键选择，然后按 Enter 键确认）

然后，只需点击 Enter 即可选择其他选项，以启用默认安装并在当前项目中安装技能

您会看到，新的 ADK 技能已添加到 .agents/skills 目录中，即 adk-cheatsheet

Caveman Skills

洞穴人技能是减少令牌使用量的一项实用技能。此技能可以减少代理的输出 token，因此当您像本教程一样利用完整的规范驱动开发时，此技能会是一个不错的组合

npx skills add JuliusBrussee/caveman

与之前类似，我们暂时先选择 caveman 技能

然后，只需点击 Enter 即可选择其他选项，以启用默认安装并在当前项目中安装技能

现在，我们应该已经配置了 4 项技能，可以开始 SDD 之旅了

.agents/skills/
├── adk-cheatsheet
├── caveman
├── mcp-toolbox-postgres
└── repo-research

生成项目上下文

确保规则目录存在：

mkdir -p .agents/rules

在 Antigravity 的代理管理器/聊天框中（在编辑器模式下按 ctrl + L），开始新的对话。Type:

Research this repository and create a project context document, and communicate efficiently

Antigravity 会将您的请求与 repo-research 和 caveman 技能（高效沟通的指令）相匹配，并开始系统地分析代码库。它会读取配置文件、源代码和文档，然后根据自己的发现填充项目上下文模板。

完成后，在编辑器中打开 .agents/rules/project-context.md。其中包含有关项目的具体信息：技术栈（Python 3.12、ADK、MCP 工具箱、Cloud SQL）、项目结构、数据模型（包含 pgvector 的 menu_items 表）和外部集成。

提示：项目背景文档会随着项目的发展而不断完善。您可以重新运行技能，以使用新添加的内容更新上下文。增量更新规则可确保保留现有内容，并附加而非覆盖新技术、实体和集成。

对于有针对性的更新，请使用具体提示：“研究数据库架构并更新项目上下文”或“使用新工具定义更新项目上下文”。每次调用都会添加到现有文档中。

设置项目章程

在规划和分析期间，SDD 工作流会引用 .specify/memory/constitution.md 中的项目章程。/speckit.plan 工作流会针对该问题运行“宪法检查”，并将违规行为标记为“严重”。/speckit.analyze如果章程留空，仅包含占位符令牌，则这些检查将没有任何可供验证的内容，计划和分析将在没有安全措施的情况下运行。

章程定义了不可协商的项目原则。这是一个由单个开发者维护的小型代码库，因此章程应反映这一范围 - 保持简单、一致，避免过度设计。

在 Antigravity 的代理管理器中，发起新对话。运行宪法工作流：

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

Antigravity 会使用具体原则填充宪法模板，分配版本 (1.0.0)，并跨 SDD 模板运行一致性检查。

在 .specify/memory/constitution.md 中查看生成的章程。验证这三项原则是否已列出并明确说明。

注意：该章程特意只保留了 3 项原则，以供独立开发者参考。/speckit.constitution 工作流支持增量修订 - 再次运行该工作流并添加其他原则，它会自动处理版本控制。对于团队项目，您需要添加有关代码审核、测试规范、可观测性和 API 版本控制的原则。

检查点： .agents/rules/project-context.md 存在，包含有关代码库的具体信息。.agents/skills/repo-research/SKILL.md 演示了如何使用 YAML 前言、指令和冲突解决来创建技能。.specify/memory/constitution.md 包含计划和分析工作流要验证的三个项目原则。您了解三级上下文层次结构：规则（始终处于有效状态）、技能（按需）和工作流（斜杠命令）。

5. SDD 周期 - 添加预留功能

此步骤将介绍完整的 SDD 周期，以向餐厅礼宾服务代理添加预订功能。您将通过每个阶段（指定、阐明、规划、任务、分析、实施）来推动 Antigravity 的发展，并观察每个制品如何在前一个制品的基础上构建。这是 Codelab 的核心学习体验。

重要提示！Antigravity 是一款 AI 助理，其生成的制品（规范、计划、任务、代码）可能与本教程中的描述有所不同。文件名、确切的 SQL 架构和代码结构可能会有所不同。这是正常现象，也是 AI 辅助开发的一部分。SDD 工作流程可确保您在每个制品成为代码之前对其进行审核，因此请自行判断是否接受、修改或重新生成任何不符合您预期的输出。

指定功能

在 Antigravity 的代理管理器中，发起新对话。输入 /speckit.specify 工作流命令，并附上功能说明：

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

Antigravity 会创建功能分支、生成规范文档并运行质量验证。如果 Antigravity 提出澄清问题，请根据上述功能说明回答这些问题。

注意：完成规范后，Antigravity 可能会提供移交，例如“制定技术方案”或“明确规范要求”。这些是下一个工作流阶段（/speckit.plan 或 /speckit.clarify）的提示

规范侧重于“是什么”和“为什么”，而不是“如何做”。它描述了用户体验（“Guest can book a reservation by providing their name, party size, date, and time”），但未提及 SQL 表、tools.yaml 或 ADK API。实现细节在规划阶段确定。

查看 specs/<branch-name>/spec.md 中生成的规范。验证它是否捕获了功能要求和成功标准。

明确规范（可选）

运行澄清工作流程，以识别和解决规范中未明确指定的区域：

/speckit.clarify

Antigravity 会扫描规范，查找模糊之处、缺失的验收标准和未充分指定的要求。它会提出有针对性的澄清问题，每个问题都可以用简短的选择或短语回答。您的回答会直接编码回规范中，从而在开始规划之前提高规范的精确度。

提示：澄清步骤是可选的，但建议您针对复杂功能执行此步骤。对于简单的规范，请直接跳到规划阶段。

规划实施

运行规划工作流：

/speckit.plan Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Use your ADK and MCP toolbox skill to implement it properly

Antigravity 通过两个阶段生成技术方案：

1. 研究阶段 - 解决有关现有代码库的未知问题，生成 research.md
2. 设计阶段 - 创建 data-model.md（预留实体定义）并更新 project-context.md

在规划时，反重力应使用 adk-agent-development 技能。查看关键制品：

• specs/<branch-name>/plan.md - 技术方法：要修改哪些文件，要遵循哪些模式
• specs/<branch-name>/data-model.md - 预订实体定义（列、类型、关系）
• specs/<branch-name>/research.md - 做出的决定和理由

生成任务

运行任务工作流

/speckit.tasks

Antigravity 会将计划分解为 specs/<branch-name>/tasks.md 中的有序任务列表。任务遵循严格的清单格式，包含 ID、优先级标记和文件路径，例如：

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

任务分为以下阶段：设置 → 基础 → 用户故事 → 润色。扫描任务列表，了解将创建和修改哪些内容。

分析任务（可选）

运行分析工作流，以查看任务是否存在风险和缺口：

/speckit.analyze

Antigravity 会根据规范和计划检查任务列表，查找缺失的极端情况、可能冲突的任务，或规范的要求与计划的工作之间的差距。在实施之前解决严重问题。

提示：当任务列表较长或功能涉及多个子系统时，分析步骤最为有用。对于预订等重点功能，快速扫描就足够了。

6. 实现

运行实现工作流：

/speckit.implement

Antigravity 提交最终的实施计划和任务制品。查看并批准该请求，然后继续

提示：您可以直接发表评论！此操作只能通过 Antigravity 内置制品完成

Antigravity 会执行这些任务，并在完成每项任务后将其勾选。完成后，系统会显示完整的演练

测试代码更改

实现完成后，请验证是否已进行关键更改。确切的文件名和内容可能会有所不同，但这些模式应该会像在 tools.yaml 和 agent.py 中一样存在：

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

您将看到类似于以下内容的输出

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

对于 agent.py

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

您可能会看到如下变化

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

注意：如果 grep 未返回任何匹配项，则实现可能使用了不同的命名。检查 git diff 以查看完整的更改集，并验证是否已添加与预留相关的逻辑。

这些更改应会影响种子数据库脚本。更新后的脚本应在 reservations 表尚不存在时创建该表。您应该会看到确认已创建新表的输出（现有 menu_items 数据会保留）。

注意：Antigravity 可能创建了一个单独的迁移脚本（例如 scripts/create_reservations.py），而不是更新 seed_db.py。检查 git diff --name-only 中是否有任何新的 scripts/ 脚本，并运行这些脚本。

如果到目前为止一切顺利，我们可以在 ADK 代理程序开发界面上测试该功能。让我们执行数据库迁移以纳入新表，并重启 Toolbox 以获取 tools.yaml 中的新工具定义。停止所有现有的 Toolbox 进程，然后启动一个全新的进程：

lsof -ti:5000 | xargs kill -9 2>/dev/null; echo "Done"
./scripts/setup_database.sh > database_setup.log 2>&1 &

您可以在 database_setup.log 中查看输出日志，了解 Antigravity 是否生成了正确的代码和配置。如果您遇到错误，请尝试与代理互动以解决问题

如果一切顺利，我们就可以启动 ADK 开发者界面了：

uv run adk web .

在浏览器中打开 http://localhost:8000，然后使用以下提示进行测试：

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

检查：代理应确认预订详细信息并创建预订

Do I have any upcoming reservations?

检查：代理应列出您刚刚创建的预留

现在，按 Ctrl+C 两次，停止 ADK 开发者界面。

检查点：代理处理预订和查找。您已完成完整的 SDD 周期：指定 → 明确 → 规划 → 任务 → 分析 → 实现 → 测试。每个阶段都在 specs/<branch-name>/ 中生成了一个版本化工件。

7. 挑战（可选）

现在，您已了解完整的 SDD 工作流程。测试一下：

• 运行第二个 SDD 周期，为餐厅礼宾服务构建一个网络聊天界面，这次没有分步指南。
• 将代理部署到 Cloud Run 以用于生产场景

提示

• 项目没有前端框架。Antigravity 应该建议使用纯 HTML/CSS/JS - 如果它建议使用 React 或类似技术，请引导它走向简单（您的宪法中的“保持简单”原则应该能发现这一点）。
• ADK 服务器公开了 /run_sse 以用于流式传输，并公开了 /apps/{app_name}/users/{user_id}/sessions 以用于会话管理。Antigravity 会从项目上下文中发现这些信息。
• 实现后，使用 uv run uvicorn server:app --host 0.0.0.0 --port 8080（而非 adk web）启动服务器，以便静态文件装载正常运行。
• 在 http://localhost:8080/static/index.html 进行测试。
• 参考 Codelab 已展示如何部署和持久化 ADK 代理，请向 Antigravity 提供相关参考！

8. 恭喜！

您已通过 Antigravity 的 SDD 工作流扩展了餐厅礼宾 ADK 智能体，使其具备预订功能，而无需手动编写应用代码。

您构建的内容

• 具有菜单搜索、语义搜索、饮食偏好跟踪和预订功能的餐厅礼宾 ADK 代理
• 一种用于代码库研究的 Antigravity 技能，可生成和维护项目上下文文档
• 在规划和分析期间强制执行不可协商的原则的项目章程
• 完整的 SDD 周期，展示了指定 → 明确 → 规划 → 任务 → 分析 → 实现工作流

要点回顾

• 如何在 Antigravity 中使用 Spec-Driven Development 工作流，以系统地向现有代码库添加功能
• 如何创建 Antigravity 技能，将领域知识打包以便在对话中重复使用
• 如何引导项目上下文，以便 Antigravity 就架构、模式和技术选择做出明智的决策
• 如何设置 SDD 工作流验证的项目章程
• 如何通过 MCP Toolbox 使用新的数据库支持的工具来扩展 ADK 智能体

清理

停止所有正在运行的本地进程 (Toolbox)：

pkill -f toolbox 2>/dev/null

删除 Cloud SQL 实例，以免持续产生费用：

gcloud sql instances delete restaurant-db --quiet

（可选）删除整个项目：

gcloud projects delete $GOOGLE_CLOUD_PROJECT

重要提示：您可以使用以下命令在有限的时间内撤消此删除操作：gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}