۱. مقدمه
افزودن ویژگیها به یک عامل موجود - یک قابلیت جدید مبتنی بر پایگاه داده - معمولاً به معنای نوشتن کدهای تکراری، سیمکشی یکپارچهسازیها و حفظ سازگاری همه چیز با الگوهای موجود در پایگاه کد است. Antigravity هر مرحله از این فرآیند را تسریع میکند: پایگاه کد شما را تجزیه و تحلیل میکند تا زمینه مورد نیاز خود را بسازد، مشخصات و برنامههای پیادهسازی ساختاریافتهای را برای بررسی شما تولید میکند و تغییرات کد را اجرا میکند - همه اینها با دانش دامنه هدایت میشود که به شما کمک میکند تا مهارتهای قابل استفاده مجدد و یک قانون اساسی پروژه را که اصول غیرقابل مذاکره را اجرا میکند، به دست آورید. این آزمایشگاه کد با معرفی یک چرخه جدید برای تقویت مستندات مشخصات که به شدت به کیت مشخصات ارجاع میدهد، راهی برای تقویت الگوی توسعه مبتنی بر مشخصات Antigravity معرفی میکند.
آنچه خواهید ساخت
یک اپلیکیشن دربان رستوران محلی با قابلیت رزرو که از طریق یک چرخه کامل SDD اضافه شده است:
- رزرواسیون - مهمانان میزها را رزرو میکنند و رزروها را بررسی میکنند، که توسط ابزارهای جدید پایگاه داده MCP Toolbox و یک جدول
reservationsCloud SQL پشتیبانی میشود. - (چالش) - رابط کاربری خودتان را برای عامل توسعه دهید
- (چالش) - با کمک عامل ضد جاذبه، به فضای ابری گوگل (Google Cloud) اعزام شوید
کد اولیه، یک عامل ADK کارآمد با قابلیت جستجوی منو (کلمه کلیدی + معنایی از طریق MCP Toolbox) و ردیابی ترجیحات غذایی (از طریق ToolContext) ارائه میدهد. شما میتوانید آن را بدون نوشتن کد برنامه به صورت دستی گسترش دهید - Antigravity پیادهسازی را بر اساس مشخصات شما انجام میدهد.
آنچه یاد خواهید گرفت
- چگونه زمینه پروژه را بوتاسترپ کنیم تا Antigravity یک کدبیس موجود را درک کند
- چگونه مهارتهای ضد جاذبه ایجاد کنیم که دانش دامنه (مثلاً الگوهای آزمایشگاه کد ADK) را برای استفاده مجدد بستهبندی کنند
- چگونه یک اساسنامه پروژه تنظیم کنیم که گردشهای کاری SDD در طول برنامهریزی و تحلیل با آن اعتبارسنجی شوند
- نحوه استفاده از گردشهای کاری توسعه مبتنی بر Spec-Driven (SDD) در Antigravity برای افزودن سیستماتیک ویژگیها
- نحوه گسترش یک عامل ADK با ابزارهای جدید پشتیبانی شده توسط پایگاه داده از طریق جعبه ابزار MCP
پیشنیازها
- گوگل آنتیگراویتی و
gitروی دستگاه محلی شما نصب شده باشند - یک حساب Google Cloud با حساب پرداخت آزمایشی فعال
- تکمیل قبلی چهار آزمایشگاه کد پیشنیاز ADK (یا دانش معادل آن) برای درک زمینه مورد استفاده مفید خواهد بود:
- ساخت عاملهای هوش مصنوعی با ADK: بنیاد
- ساخت عاملهای هوش مصنوعی با ADK: توانمندسازی با ابزارها
- ساخت عاملهای هوش مصنوعی پایدار با ADK و CloudSQL
- استقرار، مدیریت و مشاهده ADK Agent در Cloud Run
- پایگاه داده به عنوان یک ابزار: Agentic RAG با ADK، جعبه ابزار MCP و Cloud SQL
۲. محیط خود را آماده کنید
این مرحله مخزن اولیه را کلون میکند، با Google Cloud احراز هویت میکند، یک پایگاه داده Cloud SQL را فراهم میکند و محیط Antigravity محلی شما را آماده میکند.
مخزن اولیه را کلون کنید
یک ترمینال در 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 remote remove origin
پیشنیازها را نصب کنید
اسکریپت پیشنیازها را اجرا کنید. این اسکریپت وجود (و در صورت عدم وجود) git ، curl ، gcloud ، uv ، Python 3.12 و MCP Toolbox را بررسی و نصب میکند:
bash scripts/setup_prerequisites.sh
احراز هویت با گوگل کلود
دو دستور احراز هویت را اجرا کنید. هر دو مرورگر را برای OAuth باز میکنند:
gcloud auth login
gcloud auth application-default login
از آنجایی که شما به صورت محلی با Antigravity کار میکنید، باید به صورت دستی احراز هویت کنید. auth login رابط خط فرمان gcloud را احراز هویت میکند. application-default login کیتهای توسعه نرمافزاری ابری گوگل (Google Cloud SDK) که برنامه شما از آنها استفاده میکند را احراز هویت میکند - فراخوانیهای هوش مصنوعی Vertex در ADK و رابط پایتون Cloud SQL هر دو به اعتبارنامههای پیشفرض برنامه (Application Default Credentials) متکی هستند.
پروژه گوگل کلود خود را راهاندازی کنید
قبل از اجرای اسکریپت راهاندازی پروژه، متغیرهای مکان را در .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 ذخیره میکند و سپس آن را سورس میکند:
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 های مورد نیاز:
gcloud services enable \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com
ارائه SQL ابری
رمز عبور پایگاه داده را تنظیم کرده و آن را به .env اضافه کنید:
export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env
نمونه Cloud SQL را ایجاد کنید:
gcloud sql instances create restaurant-db \
--database-version=POSTGRES_17 \
--edition=ENTERPRISE \
--region=${REGION} \
--availability-type=ZONAL \
--tier=db-custom-1-3840 \
--root-password=${DB_PASSWORD} \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on &
سطح db-custom-1-3840 حداقل مورد نیاز برای ادغام Vertex AI ML است. پرچم --enable-google-ml-integration به Cloud SQL اجازه میدهد مدلهای جاسازی Gemini را مستقیماً از SQL فراخوانی کند - این ویژگی جستجوی معنایی را تقویت میکند.
نصب وابستگیها
یک تب ترمینال جدید باز کنید. مطمئن شوید که هنوز در دایرکتوری پروژه repo کلون شده هستید و متغیرهای محیطی را مجدداً بارگذاری کنید:
source .env
ما از uv به عنوان مدیر پروژه پایتون استفاده خواهیم کرد. uv یک بسته سریع پایتون و مدیر پروژه است که با Rust نوشته شده است ( docs ). این codelab از آن برای سرعت و سادگی استفاده میکند. وابستگیهای پایتون را نصب کنید:
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
حالا، ما باید تمام مخزن عامل ADK اولیه مورد نیاز خود را برای کار کردن داشته باشیم. حالا بیایید در بخش بعدی، در حالی که منتظر آماده شدن همه چیز هستیم، بیشتر در مورد Antigravity و توسعه مبتنی بر Spec صحبت کنیم.
۳. کد اولیه را بررسی کنید و توسعه مبتنی بر مشخصات (Spec-Driven Development) را درک کنید
این مرحله ساختار کد اولیه را بررسی میکند، روش توسعه مبتنی بر Spec را معرفی میکند، پایگاه داده را راهاندازی میکند و قبل از شروع توسعه، عملکرد عامل پایه را تأیید میکند.
ساختار پروژه
پروژه مخزن کلون شده را در ویرایشگر 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) │ │ ├── adk-agent-development/ │ │ │ ├── SKILL.md # ADK patterns │ │ │ └── examples/ │ │ │ ├── basic_agent.py │ │ │ ├── Dockerfile │ │ │ ├── server.py │ │ │ ├── stateful_agent.py │ │ │ ├── toolbox_agent.py │ │ │ ├── tools_agent.py │ │ │ └── tools.yaml │ │ └── repo-research/ │ │ └── SKILL.md # Repo analysis │ └── 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 بارگذاری میکند و دو تابع پایتون (save_dietary_preferenceوget_dietary_preferences) را اضافه میکند که ازToolContextبرای مدیریت وضعیت استفاده میکنند. -
tools.yaml— تعاریف ابزار جعبه ابزار MCP. سه ابزار جستجوی منو تعریف شدهاند: جستجوی کلمات کلیدی (search_menu)، جستجوی معنایی از طریقpgvector(semantic_search_menu) و فیلتر دستهبندی (get_menu_by_category). هنوز هیچ ابزار رزروی وجود ندارد - میتوانید آنها را بعداً اضافه کنید. -
server.py— یک سرور FastAPI مینیمال، که نحوه دسترسی به ADK به عنوان شیء FastAPI را نشان میدهد.get_fast_api_app()از ADK، نقاط پایانی داخلی از جمله/run_sseبرای APIهای مدیریت جریان SSE و session فراهم میکند.
فایلهای ضد جاذبه
-
.agents/skills/adk-agent-development/SKILL.md— یک مهارت از پیش پیکربندی شده (تولید شده توسط Antigravity) حاوی الگوهای مرجع فشرده از هر چهار آزمایشگاه کد ADK. در حال حاضر غیرفعال است (فاقد YAML frontmatter) – باید بعداً آن را بهروزرسانی کنید. Antigravity این مهارت را به طور خودکار هنگام شناسایی کار مربوط به ویژگیهای عامل ADK و مثالهای آنها بارگذاری میکند – این دانشی است که Antigravity را هنگام برنامهریزی ویژگی رزرو در آینده راهنمایی میکند. -
.agents/skills/repo-research/SKILL.md— مهارتی که به Antigravity نحوه تجزیه و تحلیل تدریجی یک مخزن و تولید یک سند زمینه پروژه ساختاریافته را آموزش میدهد. این مهارت از یک رویکرد ۴ مرحلهای استفاده میکند: اسکن سطحی (فقط درخت دایرکتوری)، فایلهای پیکربندی و فراداده، نقاط ورودی و مدلهای داده، سپس بررسیهای عمیق هدفمند — هر مرحله قبل از رفتن به مرحله بعدی، متوقف شده و یافتهها را مینویسد. مانند مهارت ADK، این مهارت تا زمانی که YAML frontmatter را بعداً اضافه نکنید، غیرفعال است. پس از فعال شدن، آن را برای تولید.agents/rules/project-context.mdفراخوانی کنید — یک سند جامع برای آشنایی با معماری، وابستگیهای زمان اجرا، سطح API و واژهنامه دامنه.
توسعه مبتنی بر مشخصات: از برنامهریزی داخلی Antigravity تا SDD ساختاریافته
دستیاران کدنویسی هوش مصنوعی، تولید کد از یک درخواست را آسان میکنند. ریسک: شما یک ویژگی را در یک جمله توصیف میکنید، دستیار صدها خط مینویسد و شما آن را میپذیرید زیرا درست به نظر میرسد. این گاهی اوقات "کدنویسی ارتعاشی" نامیده میشود - شما با احساس هدایت میشوید، خروجی را بر اساس اینکه آیا به نظر میرسد کار میکند یا خیر، میپذیرید یا رد میکنید. این روش برای نمونههای اولیه و اسکریپتهای یکبار مصرف سریع است. وقتی پایگاه کد رشد میکند، وقتی ویژگیها با هم تعامل دارند، یا وقتی هفتهها بعد کد را دوباره بررسی میکنید و نمیتوانید دلیل تصمیمگیری را بازسازی کنید، از کار میافتد.
توسعه مبتنی بر مشخصات (SDD) به این حلقه ساختار میدهد. قبل از تولید هرگونه کد، شما یک مشخصات مینویسید: اینکه ویژگی چه کاری انجام میدهد، به چه کسی خدمت میکند، معیارهای موفقیت چیست. دستیار هوش مصنوعی بر اساس آن مشخصات کار میکند - و شما نیز هنگام بررسی خروجی آن، همین کار را میکنید. مشخصات به تنها منبع حقیقت برای هدف تبدیل میشود. اگر کد از مشخصات منحرف شود، آن را در بررسی متوجه میشوید. اگر الزامات تغییر کند، ابتدا مشخصات را بهروزرسانی میکنید، سپس دوباره تولید میکنید. تصمیمات مستند میشوند، نه بداهه.
این بده بستان واقعی است: SDD به ازای هر ویژگی کندتر از کدنویسی vibe است. شما قبل از نوشتن کد، اسناد را مینویسید. اما نتیجه نهایی ترکیبی است - هر تغییر آینده در پایگاه کد دارای زمینه است، هر پیادهسازی تولید شده توسط هوش مصنوعی دارای یک قرارداد قابل بررسی است و شما میتوانید با اشاره به مشخصات به همکاران (انسان یا هوش مصنوعی) به جای توضیح تصمیمات از حافظه، آنها را با این کار همراه کنید.
Antigravity از اصول توسعه مبتنی بر مشخصات پیروی میکند. وقتی عامل را روی حالت برنامهریزی تنظیم میکنید، قبل از نوشتن هر کدی، دو مصنوع تولید میکند:
- طرح پیادهسازی - مروری بر رویکرد فنی پیشنهادی، تغییرات فایل و تصمیمات معماری
- فهرست وظایف - تفکیک ساختاریافتهای از موارد کاری
آنتیگراویتی از شما میخواهد که این مصنوعات را قبل از اجرا بررسی و تأیید کنید. این حلقهی برنامهریزی و سپس پیادهسازی، هستهی اصلی توسعهی مبتنی بر مشخصات است: مشخصات، کد را هدایت میکنند، نه برعکس.
این آزمایشگاه کد، این پایه و اساس را با یک گردش کارِ خودمحور و کنترلشده بر اساس نسخه، مبتنی بر spec-kit - یک چارچوب توسعه مبتنی بر مشخصات از GitHub - فراتر میبرد. هر ویژگی از یک خط لولهی (pipeline) سنجیده عبور میکند که در آن هر مصنوع، یک سند مستقل است که میتوانید آن را در git بررسی، ویرایش و پیگیری کنید. این خط لوله شامل دو مرحلهی اختیاریِ کنترل کیفیت (شفافسازی و تحلیل) است که مشکلات را قبل از تبدیل شدن به مشکلات پیادهسازی، شناسایی میکنند:
فاز | مصنوع | هدف |
| | تعریف کنید چه چیزی بسازید (مرتبط با کاربر، بدون در نظر گرفتن فناوری) |
| | حوزههای نامشخص را شناسایی کنید، سوالات روشنکنندهی هدفمند بپرسید، پاسخها را در مشخصات کدگذاری کنید |
| | طراحی، نحوه ساخت آن (رویکرد فنی، مدلهای داده، تحقیق) |
| | طرح را به مراحل منظم و قابل اجرا تقسیم کنید |
| گزارش تحلیل | قبل از اجرا، وظایف را از نظر ریسکها، شکافها یا موارد حاشیهای از قلم افتاده بررسی کنید |
| تغییرات کد | وظایف را اجرا کنید و هر کدام را تیک بزنید |
هر مصنوع به عنوان یک فایل در specs/<feature-branch>/ ذخیره میشود، نسخه آن در git کنترل میشود و قابل استفاده مجدد است. اگر مکالمه قطع شود یا بخواهید بعداً تصمیمات را دوباره بررسی کنید، اسناد مشخصات همیشه آنجا هستند - نه در تاریخچه چت.
مخزن اولیه شامل این گردشهای کاری SDD در .agents/workflows/ و قالبها در .specify/templates/ است. بعداً از آنها برای افزودن ویژگیها به عامل استفاده خواهید کرد.
۴. راهاندازی کامل Cloud SQL و اطمینان از عملکرد صحیح عامل پایه
به تب ترمینال که دستور ایجاد Cloud SQL در آن اجرا میشود، برگردید. پس از اتمام، تأیید کنید که نمونه آماده است:
gcloud sql instances describe restaurant-db --format="value(state)"
اگر خروجی RUNNABLE را نشان داد، ادامه دهید. اگر PENDING_CREATE را نشان داد، لحظهای صبر کنید و دستور را دوباره اجرا کنید.
به حساب کاربری سرویس Cloud SQL دسترسی به Vertex AI را اعطا کنید (برای عملکرد جاسازی در پایگاه داده لازم است):
SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
--member="serviceAccount:$SERVICE_ACCOUNT" \
--role="roles/aiplatform.user" \
--quiet
ایجاد پایگاه داده:
gcloud sql databases create restaurant_db --instance=restaurant-db
باید خروجی را به این شکل ببینید
Creating Cloud SQL database...done. Created database [restaurant_db]. instance: restaurant-db name: restaurant_db project: <your-project-id>
پایگاه داده را Seed کنید
متغیرهای محیطی خود را بارگذاری کنید و اسکریپت seed پایگاه داده را اجرا کنید تا طرحواره ایجاد شود و 16 مورد از منوها را وارد کنید:
source .env
uv run python scripts/seed_db.py
خروجی مورد انتظار:
Creating extensions... Creating menu_items table... Inserting 16 menu items... Seeded 16 menu items. Done.
ایجاد جاسازیهای برداری برای جستجوی معنایی:
uv run python scripts/generate_embeddings.py
خروجی مورد انتظار:
Generating embeddings for 16 menu items... Generated embeddings for 16 menu items.
این از تابع embedding() داخلی Cloud SQL (از طریق افزونه google_ml_integration ) برای فراخوانی مستقیم gemini-embedding-001 از SQL استفاده میکند. بردارهای 3072 بعدی در ستون embedding از menu_items ذخیره میشوند - هیچ کد embedding سمت برنامهای لازم نیست.
عامل پایه را آزمایش کنید
جعبه ابزار MCP را به عنوان یک فرآیند پسزمینه شروع کنید:
set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &
جعبه ابزار، ابزارهای پایگاه داده را از طریق HTTP ارائه میدهد. عامل از طریق http://127.0.0.1:5000 به آن متصل میشود.
رابط کاربری ADK dev را شروع کنید:
uv run adk web .
رابط کاربری Dev را در مرورگر خود باز کنید. سپس، با استفاده از این دستورات، عامل را آزمایش کنید:
What appetizers do you have?
I'm vegetarian
Can I make a reservation for tomorrow?
رابط کاربری توسعه ADK را با دو بار Ctrl+C متوقف کنید. Toolbox را در پسزمینه فعال بگذارید - بعداً دوباره از آن استفاده خواهید کرد.
۵. متن پروژه بوتاسترپ با Antigravity
حالا، بیایید چیزهایی را با شرایطی که "کمی نزدیکتر" به کار روزمره ما است، شبیهسازی کنیم:
- مخزن به خوبی مدیریت نشده
- فایل README منسوخ شده است
- مستندات مرتباً بهروزرسانی نمیشوند
اولین کاری که در این نوع شرایط میخواهیم انجام دهیم، معمولاً ایجاد یک نقشه یا زمینه در مورد پروژهای است که میخواهیم Antigravity روی آن کار کند. این مرحله نمونهای از رویکردی را نشان میدهد که چگونه با ایجاد مهارتی که مخزن را تجزیه و تحلیل میکند و یک سند زمینه پروژه ایجاد میکند، درک عمیقی از یک پایگاه کد موجود به Antigravity ارائه میدهد.
همچنین اساسنامه پروژه را تعیین میکند - اصول غیرقابل مذاکرهای که گردشهای کاری SDD بر اساس آنها اعتبارسنجی میشوند. این موارد در کنار هم، زمینه و محدودیتهایی را که Antigravity برای چرخههای SDD در آینده نیاز دارد، فراهم میکنند.
سلسله مراتب زمینه ضد جاذبه
ضد جاذبه از سه سطح زمینه استفاده میکند که هر کدام دامنهی متفاوتی دارند:
- قوانین (
.agents/rules/): دستورالعملهای همیشه فعال. هر مکالمهای در این فضای کاری آنها را میبیند (اگر آن را فعال کرده باشید). از قوانین برای زمینههای کل پروژه مانند تصمیمات معماری، استانداردهای کدنویسی یا اطلاعات پشته فناوری استفاده کنید. - مهارتها (
.agents/skills/): دانش مورد نیاز. Antigravity فقط زمانی یک مهارت را بارگذاری میکند که وظیفه فعلی با فیلدdescriptionمهارت مطابقت داشته باشد. از مهارتها برای مطالب مرجع خاص دامنه استفاده کنید. - گردشهای کاری (
.agents/workflows/): دستورات ذخیره شده که با/اجرا میشوند. از گردشهای کاری برای فرآیندهای چند مرحلهای قابل تکرار مانند خط لوله SDD استفاده کنید.
فعال کردن مهارتها
مخزن اولیه شامل دو مهارت از پیش نوشته شده در .agents/skills/ است. آنها حاوی دستورالعملهای دقیقی هستند اما به جای frontmatter مورد نیاز YAML، با کامنتهای TODO(codelab) شروع میشوند. بدون frontmatter، Antigravity نمیتواند آنها را کشف کند.
مهارتهای ضد جاذبه به یک بلوک frontmatter از زبان YAML در بالای فایل با دو فیلد نیاز دارند:
-
name- یک شناسه منحصر به فرد برای مهارت -
description- خلاصهای به زبان طبیعی که آنتیگراویتی هنگام تصمیمگیری در مورد بارگذاری مهارت برای یک درخواست مشخص، آن را با آن مطابقت میدهد.
باز
.agents/skills/adk-agent-development/SKILL.md
در ویرایشگر . دو خط کامنت TODO(codelab) در بالا را با این frontmatter جایگزین کنید:
---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---
باز
.agents/skills/repo-research/SKILL.md
در ویرایشگر . دو خط کامنت TODO(codelab) در بالا را با این frontmatter جایگزین کنید:
---
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.
---
تأیید کنید که هر دو مهارت، frontmatter معتبری دارند:
head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md
هر کدام باید جداکنندههای --- را در کنار فیلدهای name: و description: نشان دهند. اگر جداکنندهها یا فیلدها وجود نداشته باشند، Antigravity مهارت را تشخیص نخواهد داد.
هر دو مهارت بنا به تقاضا بارگذاری میشوند - Antigravity درخواست شما را با فیلد description مطابقت میدهد و فقط در صورت لزوم دستورالعملهای کامل را دریافت میکند.
زمینه پروژه را ایجاد کنید
اطمینان حاصل کنید که دایرکتوری قوانین وجود دارد:
mkdir -p .agents/rules
در کادر گفتگوی Antigravity در قسمت مدیریت عامل/چت (در حالت ویرایشگر، ctrl + L را فشار دهید)، یک مکالمه جدید شروع کنید. تایپ کنید:
Research this repository and create a project context document
آنتیگراویتی درخواست شما را با مهارت repo-research مطابقت میدهد و شروع به تجزیه و تحلیل سیستماتیک کدبیس میکند. فایلهای پیکربندی، کد منبع و مستندات را میخواند، سپس یافتههای خود را در قالب زمینه پروژه قرار میدهد.
پس از تکمیل، .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 موارد نقض را به عنوان بحرانی علامتگذاری میکند. اگر اساسنامه به عنوان یک الگوی خالی با توکنهای جایگزین باقی بماند، این بررسیها هیچ چیزی برای اعتبارسنجی ندارند - برنامهها و تحلیلها بدون محافظ اجرا میشوند.
این قانون، اصول غیرقابل مذاکره پروژه را تعریف میکند. این یک مخزن کوچک است که توسط یک توسعهدهنده واحد نگهداری میشود، بنابراین قانون باید آن محدوده را منعکس کند - همه چیز را ساده و منسجم نگه دارید و از مهندسی بیش از حد خودداری کنید.
در بخش مدیریت عامل آنتیگراویتی، یک مکالمه جدید شروع کنید. گردش کار مربوط به اساسنامه را اجرا کنید:
/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.
آنتیگراویتی الگوی قانون اساسی را با اصول مشخص پر میکند، یک نسخه (1.0.0) اختصاص میدهد و بررسی سازگاری را در سراسر الگوهای SDD انجام میدهد.
قانون اساسی تولید شده را در .specify/memory/constitution.md بررسی کنید. تأیید کنید که سه اصل وجود دارند و به وضوح بیان شدهاند.
۶. چرخه SDD - افزودن ویژگی رزرو
این مرحله، یک چرخه کامل SDD را طی میکند تا امکان رزرو را به متصدی پذیرش رستوران اضافه کند. شما Antigravity را در هر مرحله هدایت میکنید - مشخص کردن، شفافسازی، برنامهریزی، وظایف، تجزیه و تحلیل، پیادهسازی - و مشاهده میکنید که چگونه هر مصنوع بر اساس مرحله قبلی ساخته میشود. این تجربه یادگیری اصلی codelab است.
ویژگی را مشخص کنید
در بخش مدیریت عامل آنتیگراویتی، یک مکالمه جدید شروع کنید. دستور گردش کار /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").
آنتیگراویتی یک شاخه ویژگی ایجاد میکند، یک سند مشخصات تولید میکند و اعتبارسنجی کیفیت را اجرا میکند. اگر آنتیگراویتی سوالات توضیحی ارائه میدهد، بر اساس توضیحات ویژگی بالا به آنها پاسخ دهید.
این مشخصات بر چیستی و چرایی تمرکز دارد - نه چگونگی. این مشخصات تجربه کاربری ("مهمانان میتوانند با ارائه نام، تعداد نفرات، تاریخ و زمان خود رزرو کنند") را بدون اشاره به جداول SQL، tools.yaml یا APIهای ADK توصیف میکند. جزئیات پیادهسازی در مرحله برنامهریزی آمده است.
مشخصات تولید شده در specs/<branch-name>/spec.md را بررسی کنید. تأیید کنید که الزامات عملکردی و معیارهای موفقیت را در بر میگیرد.
مشخصات را روشن کنید (اختیاری)
برای شناسایی و رفع موارد نامشخص در مشخصات، گردش کار clear را اجرا کنید:
/speckit.clarify
آنتیگراویتی (Antigravity) مشخصات را برای یافتن ابهامات، معیارهای پذیرش از دست رفته و الزامات نامشخص بررسی میکند. این نرمافزار سوالات شفافسازی هدفمند میپرسد - که هر کدام با یک انتخاب یا عبارت کوتاه قابل پاسخ هستند. پاسخهای شما مستقیماً در مشخصات کدگذاری میشوند و قبل از شروع برنامهریزی، آن را دقیقتر میکنند.
برنامهریزی برای اجرا
گردش کار برنامهریزی را اجرا کنید:
/speckit.plan
آنتیگراویتی از طریق دو مرحله یک طرح فنی ایجاد میکند:
- مرحله تحقیق - ناشناختههای مربوط به کدبیس موجود را حل میکند و
research.mdرا تولید میکند. - مرحله طراحی - ایجاد
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 تقسیم میکند. وظایف از یک قالب چکلیست دقیق با شناسهها، نشانگرهای اولویت و مسیرهای فایل پیروی میکنند، به عنوان مثال:
- [ ] [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
آنتیگراویتی فهرست وظایف را با مشخصات و برنامه مقایسه میکند و به دنبال موارد حاشیهایِ از قلم افتاده، وظایفی که ممکن است با هم در تضاد باشند یا شکافهایی بین الزامات مشخصات و کار برنامهریزیشده باشد، میگردد. قبل از پیادهسازی، به مسائل حیاتی رسیدگی کنید.
۷. پیادهسازی
گردش کار پیادهسازی را اجرا کنید:
/speckit.implement
آنتیگراویتی یک طرح اجرایی نهایی و مصنوعات وظیفه ارائه میدهد. آن را برای ادامه بررسی و تأیید کنید.
آنتیگراویتی وظایف را اجرا میکند و پس از تکمیل هر یک، آن را تیک میزند. پس از اتمام، راهنمای کامل مراحل را ارائه میدهد.
تغییرات کد را آزمایش کنید
پس از اتمام پیادهسازی، تأیید کنید که تغییرات کلیدی ایجاد شدهاند. نام دقیق فایلها و محتوای آنها ممکن است متفاوت باشد، اما این الگوها باید مانند 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,
...
این تغییرات باید روی اسکریپت پایگاه دادهی اولیه تأثیر بگذارند، بیایید سعی کنیم آن را اجرا کنیم
source .env
uv run python scripts/seed_db.py
اسکریپت بهروزرسانیشده باید جدول reservations را در صورتی که از قبل وجود نداشته باشد، ایجاد کند. باید خروجی را مشاهده کنید که ایجاد جدول جدید را تأیید میکند (دادههای menu_items موجود حفظ میشوند).
اگر همه چیز تا این مرحله خوب پیش برود، میتوانیم این ویژگی را روی رابط کاربری توسعهدهنده ADK agent آزمایش کنیم. Toolbox را مجدداً راهاندازی کنید تا تعاریف ابزار جدید در tools.yaml دریافت شود. هر فرآیند Toolbox موجود را متوقف کنید، سپس یک فرآیند جدید را شروع کنید:
pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &
رابط کاربری ADK dev را شروع کنید:
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 dev را با دو بار فشردن Ctrl+C متوقف کنید.
۸. چالشها (اختیاری)
اکنون شما با گردش کار کامل SDD آشنا هستید. آن را آزمایش کنید:
- یک چرخه SDD دوم را برای ساخت یک رابط چت وب برای متصدی رستوران اجرا کنید - این بار بدون راهنمایی گام به گام.
- عامل خود را برای سناریوی تولید در Cloud Run مستقر کنید
نکات
- این پروژه هیچ فریمورک frontend ندارد. آنتیگراویتی باید 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) راهاندازی کنید تا mount فایل استاتیک کار کند. - در
http://localhost:8080/static/index.htmlتست کنید. - آزمایشگاههای کد مرجع، نحوهی استقرار و حفظ عامل ADK را نشان میدهند، به Antigravity ارجاعاتی در این مورد بدهید!
۹. تبریک میگویم!
شما یک نماینده ADK دربان رستوران را با قابلیت رزرو گسترش دادهاید - کاملاً از طریق گردشهای کاری SDD آنتیگراویتی، بدون نوشتن کد برنامه با دست.
چیزی که ساختی
- یک کارمند پذیرش رستوران ADK با قابلیت جستجوی منو، جستجوی معنایی، ردیابی ترجیحات غذایی و رزرواسیون
- یک مهارت ضد جاذبه برای تحقیقات مخزن که یک سند زمینه پروژه را تولید و نگهداری میکند
- اساسنامه پروژه که اصول غیرقابل مذاکره را در طول برنامهریزی و تحلیل اجرا میکند
- یک چرخه کامل SDD که گردش کار مشخص کردن → شفافسازی → برنامهریزی → وظایف → تحلیل → پیادهسازی را نشان میدهد
آنچه آموختید
- نحوه استفاده از گردشهای کاری توسعه مبتنی بر Spec در Antigravity برای افزودن سیستماتیک ویژگیها به یک کدبیس موجود
- چگونه مهارتهای ضد جاذبه ایجاد کنیم که دانش دامنه را برای استفاده مجدد در مکالمات بستهبندی کند
- چگونه زمینه پروژه را بوتاسترپ کنیم تا Antigravity تصمیمات آگاهانهای در مورد معماری، الگوها و انتخابهای فناوری بگیرد
- چگونه یک اساسنامه پروژه تنظیم کنیم که گردشهای کاری SDD با آن اعتبارسنجی شوند
- نحوه گسترش یک عامل ADK با ابزارهای جدید پشتیبانی شده توسط پایگاه داده از طریق جعبه ابزار MCP
تمیز کردن
متوقف کردن هرگونه فرآیند محلی در حال اجرا (جعبه ابزار):
pkill -f toolbox 2>/dev/null
برای جلوگیری از هزینههای جاری، نمونه Cloud SQL را حذف کنید:
gcloud sql instances delete restaurant-db --quiet
در صورت تمایل، کل پروژه را حذف کنید:
gcloud projects delete $GOOGLE_CLOUD_PROJECT