Эта страница переведена с помощью Cloud Translation API.

Разработка агентов ADK на основе спецификаций с использованием Antigravity и Spec-kit

1. Введение

Добавление новых функций к существующему агенту — например, возможностей, основанных на базе данных — обычно означает написание шаблонного кода, настройку интеграций и поддержание согласованности всего с уже существующими шаблонами в кодовой базе. Antigravity ускоряет каждый этап этого процесса: он анализирует вашу кодовую базу для создания необходимого контекста, создает структурированные спецификации и планы реализации для вашего ознакомления и выполняет изменения кода — всё это под руководством знаний предметной области, которые он помогает вам зафиксировать в виде многократно используемых навыков, и структуры проекта, которая обеспечивает соблюдение незыблемых принципов. Этот практический семинар представляет способ значительно ускорить парадигму разработки, основанной на спецификациях (Spec-driven Development), с помощью нового цикла, который позволит улучшить документацию по спецификациям, активно используя spec-kit.

Что вы построите

Приложение для консьерж-обслуживания ресторанов, работающее локально и позволяющее бронировать столики в соответствии с полным циклом разработки программного обеспечения (SDD):

Бронирование столиков — гости бронируют столики и проверяют бронирование, используя новые инструменты базы данных MCP Toolbox и таблицу reservations Cloud SQL.
(Задание) – разработайте собственный пользовательский интерфейс для агента.
(Задание) – разверните приложение в Google Cloud с помощью агента Antigravity.

Стартовый код предоставляет работающий агент ADK с поиском по меню (по ключевому слову + семантика через MCP Toolbox) и отслеживанием пищевых предпочтений (через ToolContext). Вы можете расширять его без написания кода приложения вручную — Antigravity реализует его в соответствии с вашими требованиями.

Что вы узнаете

Как инициализировать контекст проекта, чтобы Antigravity понимал существующую кодовую базу?
Как создавать навыки Antigravity, которые позволяют упаковывать знания предметной области (например, шаблоны кодовой лаборатории ADK) для повторного использования.
Как определить структуру проекта, которой будут соответствовать рабочие процессы SDD на этапах планирования и анализа?
Как использовать рабочие процессы разработки, основанные на спецификации (Spec-Driven Development, SDD), в Antigravity для систематического добавления новых функций.
Как расширить функциональность агента ADK с помощью новых инструментов, работающих с базами данных, через MCP Toolbox.

Предварительные требования

На вашем локальном компьютере должны быть установлены Google Antigravity и git
Учетная запись Google Cloud с активной платёжной ведомостью.
Предварительное прохождение четырех обязательных практических заданий по ADK (или эквивалентные знания) поможет понять контекст использования:
Создание агентов искусственного интеллекта с помощью ADK: основы
Создание ИИ-агентов с помощью ADK: расширение возможностей с помощью инструментов.
Создание постоянно работающих агентов ИИ с помощью ADK и CloudSQL
Развертывание, управление и мониторинг агента ADK в Cloud Run
База данных как инструмент: Agentic RAG с ADK, MCP Toolbox и Cloud SQL.

2. Настройте свою среду.

На этом этапе выполняется клонирование стартового репозитория, аутентификация в Google Cloud, развертывание базы данных Cloud SQL и подготовка локальной среды Antigravity.

Установите необходимые компоненты.

Убедитесь, что в вашей системе установлен следующий исполняемый файл CLI:

Инструкция по установке различается в зависимости от операционной системы вашего компьютера.

Клонируйте стартовый репозиторий

Откройте терминал в 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

Аутентификация с помощью Google Cloud

Выполните две команды аутентификации. Обе откроют браузер для аутентификации OAuth:

gcloud auth login
gcloud auth application-default login

Поскольку вы работаете с Antigravity локально, аутентификация выполняется вручную. Команда auth login аутентифицирует CLI gcloud . application-default login аутентифицирует SDK Google Cloud, используемые вашим приложением — вызовы Vertex AI из ADK и коннектор Cloud SQL Python используют учетные данные по умолчанию для приложений.

Настройте свой проект в Google Cloud.

Перед запуском скрипта настройки проекта запишите переменные местоположения в файл .env :

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

GOOGLE_CLOUD_LOCATION=global используется для вызовов API Vertex AI / Gemini.
REGION=us-central1 используется для Cloud SQL и другой инфраструктуры GCP.

ВАЖНО! Приведенные ниже шаги помогут быстро настроить проект Google Cloud, связанный с пробной учетной записью (строгая настройка). Если вы предпочитаете использовать свой предыдущий проект, вы можете пропустить следующий шаг и выполнить следующий:

Добавьте название своего проекта в качестве переменной GOOGLE_CLOUD_PROJECT в файл .env.

Активируйте свой проект в терминале с помощью команды `gcloud config set project your-project-id`.

Затем вы можете сразу перейти к разделу «Включение API».

Если вы не уверены в этом, продолжите чтение раздела ниже.

Загрузите и запустите скрипт настройки проекта. Он создаст или проверит проект Google Cloud с пробной оплатой, сохранит идентификатор проекта в файле .env , а затем выполнит его команду:

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

Установите зависимости

В качестве менеджера проектов на Python мы будем использовать uv . uv — это быстрый пакет Python и менеджер проектов, написанный на Rust ( документация ). В этом практическом занятии он используется для повышения скорости и простоты. Установите зависимости Python:

uv sync

Затем обновите файл .env агента ADK, указав конфигурацию вашего проекта:

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

Затем запустите скрипт 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. Изучите стартовый код и разберитесь в разработке, основанной на спецификациях (Spec-Driven Development).

На этом этапе рассматривается структура начального кода, знакомится с методологией разработки, основанной на спецификациях (Spec-Driven Development), выполняется инициализация базы данных и проверяется работоспособность базового агента перед его расширением.

Структура проекта

Откройте клонированный проект репозитория в редакторе 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 — Основной агент. LlmAgent , который объединяет инструменты базы данных MCP Toolbox с отслеживанием диетических предпочтений на основе ToolContext . Агент загружает все инструменты с сервера Toolbox и добавляет две функции Python ( save_dietary_preference , get_dietary_preferences ), которые используют ToolContext для управления состоянием.
tools.yaml — определения инструментов MCP Toolbox. Определены три инструмента поиска по меню: поиск по ключевым словам ( search_menu ), семантический поиск с помощью pgvector ( semantic_search_menu ) и фильтр по категориям ( get_menu_by_category ). Инструментов бронирования пока нет — вы добавите их позже.
server.py — Минимальный FastAPI-сервер, демонстрирующий, как можно получить доступ к ADK как к объекту FastAPI. get_fast_api_app() из ADK предоставляет встроенные конечные точки, включая /run_sse для потоковой передачи SSE и API управления сессиями.

Файлы об антигравитации

.agents/skills/mcp-toolbox-postgres/SKILL.md — Навык, который помогает Antigravity создавать правильную конфигурацию tools.yaml для MCP toolbox. Этот навык научит вас настраивать параметры, связанные с sources , tools и embeddingModels , необходимые для построения корректного конвейера RAG. Этот навык не будет активирован, пока вы не добавите соответствующий YAML-текст, который будет распознан Antigravity.
.agents/skills/repo-research/SKILL.md — навык, обучающий Antigravity поэтапному анализу репозитория и созданию структурированного документа контекста проекта. Он использует 4-этапный подход: поверхностное сканирование (только дерево каталогов), файлы конфигурации и метаданных, точки входа и модели данных, а затем целенаправленный углубленный анализ — на каждом этапе происходит остановка и запись результатов перед переходом к следующему. Он также неактивен, пока вы не добавите YAML-заголовок позже. После активации вызовите его для генерации .agents/rules/project-context.md — всеобъемлющего документа для адаптации, охватывающего архитектуру, зависимости времени выполнения, поверхность API и глоссарий предметной области.

Разработка, основанная на спецификациях: от встроенного в Antigravity планирования до структурированной разработки, основанной на спецификациях.

Искусственный интеллект, используемый в качестве помощника в программировании, упрощает генерацию кода по запросу. Риск: вы описываете функцию одним предложением, помощник пишет сотни строк, и вы принимаете это, потому что это выглядит правильно. Иногда это называют «программированием по ощущениям» — вы управляете процессом интуитивно, принимая или отклоняя результат в зависимости от того, кажется ли он работающим. Это быстро для прототипов и одноразовых скриптов. Но это дает сбой, когда кодовая база разрастается, когда функции взаимодействуют, или когда вы возвращаетесь к коду через несколько недель и не можете вспомнить, почему было принято то или иное решение.

Разработка, основанная на спецификации (Spec-Driven Development, SDD), добавляет структуру в этот цикл. Прежде чем будет сгенерирован какой-либо код, вы пишете спецификацию: что делает функция, кому она предназначена, каковы критерии успеха. Искусственный интеллект работает на основе этой спецификации — и вы тоже, проверяя его результат. Спецификация становится единственным источником достоверной информации о намерениях. Если код отклоняется от спецификации, вы обнаруживаете это на этапе проверки. Если требования меняются, вы сначала обновляете спецификацию, а затем генерируете код заново. Решения документируются, а не импровизируются.

Компромисс реален: разработка через SDD медленнее на единицу функциональности, чем программирование через Vibe. Вы пишете документацию перед написанием кода. Но выгода накапливается — каждое будущее изменение в кодовой базе имеет контекст, каждая реализация, сгенерированная ИИ, имеет проверяемый контракт, и вы можете привлекать к сотрудничеству (людей или ИИ), указывая им на спецификации, вместо того чтобы объяснять решения по памяти.

Antigravity уже следует принципам разработки, основанной на спецификациях. Когда вы переводите агента в режим планирования , он создает два артефакта еще до написания какого-либо кода:

План реализации — обзор предлагаемого технического подхода, изменений в файлах и архитектурных решений.
Список задач — структурированное описание рабочих задач.

Antigravity требует от вас проверки и утверждения этих артефактов перед выполнением. Этот цикл «планирование-затем-реализация» является ядром разработки, основанной на спецификациях: спецификации направляют код, а не наоборот.

Этот практический семинар развивает эту основу, используя продуманный , контролируемый версиями рабочий процесс на основе 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 и может быть использован повторно. Если обсуждение прерывается или вы хотите вернуться к принятым решениям позже, документы со спецификациями всегда будут доступны — они не будут скрыты в истории чата.

В стартовом репозитории эти рабочие процессы SDD находятся в .agents/workflows/ , а шаблоны — в папке .specify/templates/ . Вы будете использовать их позже для добавления функций в агент.

4. Контекст проекта Bootstrap с использованием технологии Antigravity

Теперь давайте смоделируем ситуацию в условиях, которые «более или менее близки» к нашей повседневной работе:

Неэффективно управляемый репозиторий
README устарел
Документация обновляется нечасто.

В подобных ситуациях первым делом обычно создаётся карта или контекст проекта, с которым мы хотим, чтобы Antigravity работала. На этом этапе показан один из примеров подхода, позволяющего Antigravity глубоко понимать существующую кодовую базу путём создания навыка, который анализирует репозиторий и генерирует документ с контекстом проекта.

Это также закладывает основу для проекта — не подлежащие обсуждению принципы, которым соответствуют рабочие процессы SDD. В совокупности это дает Antigravity контекст и ограничения, необходимые для последующих циклов SDD.

Иерархия контекста антигравитации

В теории антигравитации используются три уровня контекста, каждый из которых имеет свой масштаб:

Правила ( .agents/rules/ ): Постоянно активные инструкции. Они видны в каждом диалоге в этом рабочем пространстве (если вы их активировали). Используйте правила для контекста всего проекта, например, для принятия архитектурных решений, соблюдения стандартов кодирования или получения информации о технологическом стеке.
Навыки ( .agents/skills/ ): Знания по запросу. Antigravity загружает навык только тогда, когда текущая задача соответствует полю description навыка. Используйте навыки для получения справочных материалов по конкретной предметной области.
Рабочие процессы ( .agents/workflows/ ): Сохраненные подсказки, запускаемые командами / . Используйте рабочие процессы для повторяющихся многоэтапных процессов, таких как конвейер SDD.

Активируйте навыки

В стартовом репозитории находятся два предварительно написанных навыка в папке .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
---

Откройте файл .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.
---

Примечания: Внимательно изучите файл SKILL.md repo-research . Это лишь один из примеров запроса на анализ вашего репозитория; обратите внимание, что правила инкрементального обновления намеренно консервативны. Если контекст 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 , чтобы выбрать другой вариант и включить установку по умолчанию, а также установить навык в вашем текущем проекте.

Вы увидите, что в каталог .agents/skills добавлен новый навык ADK, который называется adk-cheatsheet

Навыки пещерного человека

Одним из полезных навыков для сокращения использования токенов является навык «Пещерный человек» . Этот навык позволяет сократить количество выходных токенов у агента, что делает его хорошим дополнением при использовании разработки, полностью основанной на спецификациях, как в этом руководстве.

npx skills add JuliusBrussee/caveman

Как и прежде, давайте пока выберем навык " caveman .

Теперь у нас уже должно быть настроено 4 навыка, и мы готовы начать наш путь к разработке на основе SDD.

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

Сгенерируйте контекст проекта.

Убедитесь, что каталог с правилами существует:

mkdir -p .agents/rules

В окне «Менеджер агентов/Чат» игры Antigravity (в режиме редактора нажмите ctrl + L ) начните новый разговор. Введите:

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 Toolbox, Cloud SQL), структура проекта, модель данных (таблица menu_items с pgvector ) и внешние интеграции.

Совет: Документ с контекстом проекта расширяется по мере развития проекта. Вы можете повторно запустить навык, чтобы обновить контекст с учетом новых дополнений. Правила инкрементального обновления гарантируют сохранение существующего контента — новые технологии, сущности и интеграции добавляются, а не перезаписываются.

Для целевых обновлений используйте специальные подсказки: «Изучить схему базы данных и обновить контекст проекта» или «Обновить контекст проекта с новыми определениями инструментов». Каждый вызов добавляет данные в существующий документ.

Установить устав проекта

В процессе планирования и анализа рабочие процессы 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 . Убедитесь, что три принципа присутствуют и четко сформулированы.

Контрольная точка: файл .agents/rules/project-context.md содержит конкретную информацию о репозитории. .agents/skills/repo-research/SKILL.md демонстрирует создание навыков с помощью YAML-заголовков, инструкций и разрешения конфликтов. .specify/memory/constitution.md содержит три принципа проекта, которым соответствуют рабочие процессы планирования и анализа. Вы понимаете трехуровневую иерархию контекста: правила (всегда активны), навыки (по запросу), рабочие процессы (команды с косой чертой).

5. Цикл SDD — Добавление функции резервирования

На этом этапе описывается полный цикл разработки программного обеспечения (SDD) для добавления функции бронирования столиков в ресторан. Вы управляете Antigravity на каждом этапе — уточнение, планирование, задачи, анализ, реализация — наблюдая, как каждый результат основывается на предыдущем. Это основной учебный процесс в рамках практического занятия.

Важно! Antigravity — это помощник на основе искусственного интеллекта, и сгенерированные им артефакты (спецификации, планы, задачи, код) могут отличаться от описанных в этом руководстве. Названия файлов, точные схемы SQL и структура кода могут различаться. Это ожидаемо и является частью работы с разработкой с использованием ИИ. Рабочий процесс 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 задает уточняющие вопросы, отвечайте на них, основываясь на описании функции, приведенном выше.

Спецификация фокусируется на ЧТО и ПОЧЕМУ, а не НА КАК. Она описывает пользовательский опыт («Гости могут забронировать номер, указав свое имя, количество человек в группе, дату и время») без упоминания таблиц SQL, tools.yaml или API ADK. Детали реализации будут рассмотрены на этапе планирования.

Просмотрите сгенерированную спецификацию по адресу 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

Разработка технического плана для проекта «Антигравитация» осуществляется в два этапа:

Этап исследования — устраняет неясности, касающиеся существующего кода, генерирует research.md
Этап проектирования — создание data-model.md (определение сущности бронирования) и обновление project-context.md

В процессе планирования Antigravity следует использовать навык 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 . Задачи следуют строгому формату контрольного списка с идентификаторами, маркерами приоритета и путями к файлам, например:

- [ ] [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 выполняет задания, отмечая каждое выполненное. После завершения отобразится полное пошаговое руководство.

Проверьте изменения в коде.

После завершения внедрения убедитесь, что внесены все ключевые изменения. Точные имена файлов и их содержимое могут отличаться, но должны присутствовать следующие шаблоны, как в 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,
...

Изменения должны затронуть скрипт базы данных. Обновленный скрипт должен создать таблицу reservations , если она еще не существует. Вы должны увидеть сообщение, подтверждающее создание новой таблицы (существующие данные menu_items сохраняются).

Если до этого момента все пройдет успешно, мы можем протестировать функцию в пользовательском интерфейсе разработчика агента 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?

Теперь остановите пользовательский интерфейс разработчика ADK, дважды нажав Ctrl+C .

7. Задания (необязательно)

Теперь вы знаете весь рабочий процесс SSD. Проверьте его на практике:

Запустите второй цикл 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 .
В приведенных примерах уже показано, как развернуть и сохранить агент ADK, укажите ссылки на Antigravity!

8. Поздравляем!

Вы расширили функциональность агента ADK для консьерж-сервиса ресторана, добавив функцию бронирования — полностью с помощью рабочих процессов SDD от Antigravity, без написания кода приложения вручную.

То, что ты построил

Сервис консьерж-услуг для ресторанов ADK, включающий поиск по меню, семантический поиск, отслеживание диетических предпочтений и бронирование столиков.
Навык Antigravity для поиска информации в репозиториях, который генерирует и поддерживает документ с контекстом проекта.
Устав проекта, обеспечивающий соблюдение не подлежащих обсуждению принципов на этапах планирования и анализа.
Полный цикл SDD, демонстрирующий рабочий процесс: определение → уточнение → планирование → задачи → анализ → внедрение

Что вы узнали

Как использовать рабочие процессы разработки, основанные на спецификациях (Spec-Driven Development), в Antigravity для систематического добавления новых функций в существующую кодовую базу.
Как создать навыки «Антигравитации», которые позволяют упаковывать знания предметной области для повторного использования в различных диалогах.
Как создать контекст проекта, чтобы компания Antigravity могла принимать обоснованные решения относительно архитектуры, шаблонов и выбора технологий.
Как задать структуру проекта, которой будут соответствовать рабочие процессы SDD?
Как расширить функциональность агента ADK с помощью новых инструментов, работающих с базами данных, через MCP Toolbox.

Уборка

Остановите все запущенные локальные процессы (панель инструментов):

pkill -f toolbox 2>/dev/null

Чтобы избежать дальнейших платежей, удалите экземпляр Cloud SQL:

gcloud sql instances delete restaurant-db --quiet

При желании можно удалить весь проект:

gcloud projects delete $GOOGLE_CLOUD_PROJECT