פיתוח סוכנים באמצעות ADK שמבוסס על מפרט, עם Antigravity ו-Spec-kit

1. מבוא

הוספת תכונות לסוכן קיים – יכולת חדשה שמגובה במסד נתונים – בדרך כלל כרוכה בכתיבת קוד סטנדרטי, בהגדרת שילובים ובשמירה על עקביות עם התבניות שכבר נמצאות בבסיס הקוד. ‫Antigravity מאיץ את כל שלבי התהליך הזה: הוא מנתח את ה-codebase כדי לבנות את ההקשר שהוא צריך, יוצר מפרטים מובנים ותוכניות הטמעה לבדיקה שלכם, ומבצע את השינויים בקוד – והכול בהתאם לידע בתחום שעוזר לכם לתעד ככישורים לשימוש חוזר וכמסמך הגדרות פרויקט שמחיל עקרונות שאי אפשר להתפשר עליהם. ב-codelab הזה נציג דרך לשפר את פרדיגמת הפיתוח מבוסס-המפרט של Antigravity על ידי הצגת מחזור חדש לשיפור תיעוד המפרט, עם הפניות רבות ל-spec-kit

מה תפַתחו

אפליקציית קונסיירז' למסעדות שפועלת באופן מקומי עם הזמנת מקום שנוספה באמצעות מחזור SDD מלא:

• הזמנת מקומות – האורחים מזמינים שולחנות ובודקים הזמנות, באמצעות כלים חדשים למסדי נתונים של MCP Toolbox וטבלה של Cloud SQL reservations
• (אתגר) – פיתוח ממשק משתמש משלכם לסוכן
• (אתגר) – פריסה ב-Google Cloud בעזרת סוכן Antigravity

קוד ההתחלה מספק סוכן ADK פעיל עם חיפוש בתפריט (מילת מפתח + סמנטי באמצעות MCP Toolbox) ומעקב אחר העדפות תזונתיות (באמצעות ToolContext). אתם יכולים להרחיב את הפונקציונליות בלי לכתוב קוד אפליקציה באופן ידני – Antigravity מטפל בהטמעה על סמך המפרט שלכם.

מה תלמדו

• איך להגדיר הקשר לפרויקט כדי ש-Antigravity יבין codebase קיים
• איך יוצרים מיומנויות Antigravity שכוללות ידע בתחום (למשל, ADK codelab patterns) for reuse
• איך מגדירים חוקה לפרויקט שתהליכי העבודה של SDD יאמתו מולה במהלך התכנון והניתוח
• איך משתמשים בתהליכי עבודה של פיתוח מבוסס-מפרט (SDD) ב-Antigravity כדי להוסיף תכונות באופן שיטתי
• איך מרחיבים סוכן ADK באמצעות כלים חדשים שמגובים במסד נתונים דרך MCP Toolbox

דרישות מוקדמות

• ‫Google Antigravity ו-git מותקנים במחשב המקומי
• חשבון Google Cloud עם חשבון לחיוב לתקופת ניסיון מופעל
• כדי להבין את ההקשר של תרחיש השימוש, כדאי להשלים קודם את ארבעת ה-codelab של ADK (או ידע מקביל):
• יצירת סוכני AI באמצעות ADK: הבסיס
• יצירת סוכני AI באמצעות ADK: כלים שימושיים
• יצירת סוכני AI מתמידים באמצעות ADK ו-CloudSQL
• פריסה, ניהול ומעקב של סוכן ADK ב-Cloud Run
• מסד נתונים ככלי: RAG מבוסס-סוכן עם ADK, ערכת הכלים MCP ו-Cloud SQL

2. הגדרת הסביבה

הערות חשובות:

כדי לבצע את ההדרכה הזו, צריך פרויקט ב-Google Cloud עם חשבון חיוב פעיל. אם עדיין אין לכם חשבון, אתם יכולים לפעול לפי השלבים הבאים כדי לקבל חשבון לחיוב לתקופת ניסיון שתוכלו להשתמש בו במדריך הזה:

1. פתיחת חלון פרטי
2. אם אתם מצטרפים לסדנה, בדרך כלל כתובת ה-URL של פורטל מימוש השוברים תופיע בסדנה. אחרת, תוכלו לעבור אל פורטל מימוש השוברים של חשבון החיוב של תקופת הניסיון.
3. צריך להתחבר באמצעות חשבון Gmail אישי ( אי אפשר להשתמש בחשבונות Google Workspace או בכתובות אימייל אחרות!) )
4. פועלים לפי ההוראות למימוש

בשלב הזה מתבצע שיבוט של מאגר התחלה, אימות ב-Google Cloud, הקצאה של מסד נתונים ב-Cloud SQL והכנה של סביבת Antigravity המקומית.

הערות: ה-codelab הזה פועל כולו ב-Google Antigravity במחשב המקומי שלכם. ההגדרה כוללת אימות ידני באמצעות פקודת gcloud CLI

שכפול מאגר התחלתי

פותחים טרמינל ב-Antigravity (או בטרמינל של המערכת). משכפלים את מאגר הקוד של התוסף ונכנסים לספרייה:

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

פותחים את המאגר המשוכפל ב-Antigravity. ‫File (קובץ) -> Open Folder (פתיחת תיקייה) -> בוחרים את הספרייה המשוכפלת sdd-adk-agents-agy

מסירים את המאגר המרוחק במעלה הזרם. תהליכי העבודה של SDD יוצרים ענפי git למפרטי תכונות – הסרת המאגר המרוחק מונעת דחיפה בטעות למאגר המתחיל:

git remote remove origin

חשוב: תהליכי העבודה של SDD ב-codelab הזה משתמשים בענפים של git כדי לארגן מפרטים של תכונות. הסרת המאגר המרוחק origin מבטיחה שהענפים והקומטים המקומיים יישארו מקומיים. אם רוצים לגבות את העבודה, מוסיפים שלט משלכם: git remote add origin <your-repo-url>

התקנת דרישות מוקדמות

מריצים את סקריפט הדרישות המוקדמות. הסקריפט בודק אם קיימים (ומתקין אם חסרים) git,‏ curl,‏ gcloud,‏ uv,‏ Python 3.12 ו-MCP Toolbox:

bash scripts/setup_prerequisites.sh

הערות: הורדת כל הדרישות המוקדמות תיקח זמן. אפשר לפתוח כרטיסייה חדשה כדי להמשיך לקטע הבא בזמן שמחכים לסיום ההורדה.

אימות ב-Google Cloud

מריצים שתי פקודות אימות. שניהם פותחים דפדפן ל-OAuth:

gcloud auth login
gcloud auth application-default login

הערות: בפקודת OAuth השנייה, כשמוצגת בקשה לבחירת הרשאה. מה האפשרויות שלי?

הערות: חשוב לוודא שאתם מאמתים את עצמכם באמצעות כתובת האימייל שבה השתמשתם כדי להפעיל את חשבון הניסיון לחיוב.

מכיוון שאתם עובדים באופן מקומי עם 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 משמש לקריאות ל-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

הערות: הפעלת ממשקי API עשויה להימשך זמן מה. צריך לעשות את זה רק פעם אחת לכל פרויקט.

הקצאת משאבים ב-Cloud SQL

מגדירים את הסיסמה למסד הנתונים ומוסיפים אותה ל-.env:

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

חשוב: הסיסמה שמוצגת למעלה היא רק לצורך הדרכה. בסביבת ייצור, צריך לאחסן את פרטי הכניסה בצורה מאובטחת באמצעות שירות כמו Secret Manager ולהפנות אליהם בזמן הריצה – לעולם אל תבצעו קומיט של סודות בטקסט פשוט לבקרת מקור.

יוצרים את המכונה של 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 – כך פועלת התכונה של חיפוש סמנטי.

הערות: הפקודה הזו נמשכת כ-5 דקות והיא תפעל ברקע. משאירים אותו פועל בכרטיסיית הטרמינל הזו ופותחים כרטיסיית טרמינל חדשה לשלבים הבאים.

התקנת יחסי תלות

פותחים כרטיסייה חדשה ב-Terminal. מוודאים שאתם עדיין בספריית הפרויקט של מאגר ה-repo המשוכפל וטוענים מחדש את משתני הסביבה:

source .env

נשתמש ב-uv כמנהל פרויקטים של Python. ‫uv הוא מנהל חבילות ופרויקטים מהיר של Python שנכתב ב-Rust ( מסמכים ). אנחנו משתמשים בו ב-Codelab הזה כדי להשיג מהירות ופשטות. מתקינים את יחסי התלות של 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

עכשיו אמור להיות לנו מאגר (repo) של סוכן ADK שנדרש כדי להתחיל לעבוד. עכשיו נדבר יותר על Antigravity ועל Spec-driven development בקטע הבא בזמן שמחכים שכל מה שצריך יהיה מוכן

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)
│   │   ├── 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. הסוכן טוען את כל הכלים משרת ארגז הכלים ומוסיף שתי פונקציות Python‏ (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 לסטרימינג של SSE וממשקי API לניהול סשנים.

Antigravity Files

• ‫.agents/skills/adk-agent-development/SKILL.md – מיומנות מוגדרת מראש ( שנוצרה על ידי Antigravity) שמכילה דפוסי הפניה מרוכזים מכל ארבעת סדנאות ה-ADK. הוא לא פעיל כרגע (חסר לו YAML frontmatter) – תצטרכו לעדכן אותו בהמשך. ‫Antigravity טוען את המיומנות הזו באופן אוטומטי כשהוא מזהה עבודה שקשורה לתכונות של סוכן ADK ולדוגמאות שלהן – זה הידע שמנחה את Antigravity כשהוא מתכנן את תכונת ההזמנה בהמשך
• ‫.agents/skills/repo-research/SKILL.md – מיומנות שמלמדת את Antigravity איך לנתח מאגר באופן מצטבר וליצור מסמך הקשר מובנה של הפרויקט. הגישה מבוססת על 4 שלבים: סריקה שטחית (רק עץ הספריות), קובצי תצורה ומטא-נתונים, נקודות כניסה ומודלים של נתונים, ואז בדיקות מעמיקות ממוקדות – כל שלב מסתיים בכתיבת הממצאים לפני שמתקדמים לשלב הבא. בדומה למיומנות ADK, היא לא פעילה עד שמוסיפים לה YAML frontmatter בשלב מאוחר יותר. אחרי ההפעלה, מפעילים אותו כדי ליצור .agents/rules/project-context.md – מסמך מקיף להצטרפות שכולל ארכיטקטורה, תלות בזמן ריצה, ממשק API ומילון מונחים של הדומיין.

פיתוח מבוסס-מפרט: מתכנון מובנה ב-Antigravity ועד פיתוח מובנה מבוסס-מפרט

עוזרי תכנות מבוססי-AI מאפשרים ליצור קוד בקלות מהנחיה. הסיכון: אתם מתארים תכונה במשפט, העוזר הדיגיטלי כותב מאות שורות ואתם מאשרים אותן כי הן נראות לכם נכונות. לפעמים קוראים לזה 'קידוד לפי תחושה' – אתם מנווטים לפי תחושה, ומקבלים או דוחים את הפלט לפי מה שנראה לכם שעובד. הוא מהיר ליצירת אבות טיפוס ולסקריפטים חד-פעמיים. הבעיה מתרחשת כשהבסיס של הקוד גדל, כשיש אינטראקציה בין התכונות או כשחוזרים לקוד שבועות אחרי שכתבו אותו ולא מצליחים לשחזר את הסיבה להחלטה שהתקבלה.

פיתוח מבוסס-מפרט (SDD) מוסיף מבנה ללולאה הזו. לפני שמתחילים ליצור קוד, כותבים מפרט: מה התכונה עושה, למי היא מיועדת ומהם קריטריוני ההצלחה. העוזר הדיגיטלי מבוסס ה-AI פועל לפי המפרט הזה – וכך גם אתם כשאתם בודקים את התוצאות שלו. המפרט הופך למקור המידע האמין היחיד לגבי הכוונה. אם הקוד חורג מהמפרט, אפשר לזהות את זה בבדיקה. אם הדרישות משתנות, צריך לעדכן קודם את המפרט ואז ליצור מחדש את הקובץ. ההחלטות מתועדות, ולא מאולתרות.

הפשרה היא אמיתית: כל תכונה ב-SDD איטית יותר מאשר ב-vibe coding. אתם כותבים מסמכים לפני שאתם כותבים קוד. אבל התועלת מצטברת – לכל שינוי עתידי בבסיס הקוד יש הקשר, לכל הטמעה שנוצרה על ידי AI יש חוזה שניתן לבדיקה, ואפשר לצרף משתפי פעולה (אנושיים או AI) על ידי הפניה שלהם למפרטים במקום להסביר החלטות מתוך הזיכרון.

חברת Antigravity כבר פועלת לפי עקרונות של פיתוח מבוסס-מפרט. כשמגדירים את הסוכן למצב תכנון, הוא יוצר שני פריטי מידע שנוצרו בתהליך פיתוח (Artifact) לפני שהוא כותב קוד כלשהו:

• תוכנית הטמעה – סקירה כללית של הגישה הטכנית המוצעת, השינויים בקובץ והחלטות לגבי הארכיטקטורה
• רשימת משימות – פירוט מובנה של פריטי עבודה

‫Antigravity מבקש מכם לבדוק ולאשר את הארטיפקטים האלה לפני ההפעלה. הלולאה הזו של תכנון ואז הטמעה היא הליבה של פיתוח מבוסס-מפרטים: המפרטים מכוונים את הקוד, ולא להפך.

ב-Codelab הזה אנחנו לוקחים את הבסיס הזה צעד אחד קדימה עם תהליך עבודה מבוסס דעה ומבוסס בקרת גרסאות שמבוסס על spec-kit – מסגרת פיתוח מבוססת מפרטים מ-GitHub. כל תכונה עוברת תהליך מובנה שבו כל ארטיפקט הוא מסמך עצמאי שאפשר לבדוק, לערוך ולעקוב אחריו ב-git. תהליך העבודה כולל שני שלבים אופציונליים של בדיקת איכות (הבהרה וניתוח) שמאפשרים לזהות בעיות לפני שהן הופכות לבעיות בהטמעה:

שלב	Artifact	מטרה
/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

מאגר המתחילים כולל את תהליכי העבודה של SDD ב-.agents/workflows/ ותבניות ב-.specify/templates/. תשתמשו בהם בהמשך כדי להוסיף תכונות לסוכן.

4. השלמת ההגדרה של 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>

נקודת ביקורת: קובץ .env מכיל GOOGLE_CLOUD_PROJECT,‏ GOOGLE_CLOUD_LOCATION,‏ REGION ו-DB_PASSWORD. המכונה של Cloud SQL,‏ restaurant-db, פועלת. ‫toolbox זמין ב-PATH (מותקן על ידי setup_prerequisites.sh). יחסי התלות של Python מותקנים.

הוספת נתונים למסד הנתונים

טוענים את משתני הסביבה ומריצים את סקריפט האתחול של מסד הנתונים כדי ליצור את הסכימה ולהוסיף 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. הווקטורים התלת-ממדיים מאוחסנים בעמודה embedding של menu_items – אין צורך בקוד הטמעה בצד האפליקציה.

בדיקת הסוכן הבסיסי

מפעילים את MCP Toolbox כתהליך ברקע:

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 למפתחים:

uv run adk web .

פותחים את ממשק המשתמש של כלי הפיתוח בדפדפן. אחרי כן, בודקים את הסוכן באמצעות ההנחיות הבאות:

What appetizers do you have?

בדיקה: הסוכן שולח שאילתה למסד הנתונים ומחזיר פריטים בתפריט

I'm vegetarian

בדיקה: הסוכן שומר את העדפת התזונה במצב הסוכן

Can I make a reservation for tomorrow?

בדיקה: הנציג לא יכול לטפל בזה (עדיין אין כלים להזמנה)

מפסיקים את ממשק המשתמש של ADK למפתחים באמצעות הקשה על Ctrl+C פעמיים. משאירים את ארגז הכלים פועל ברקע – תשתמשו בו שוב בהמשך

נקודת ביקורת: הסוכן הבסיסי פועל – חיפוש בתפריט (מילת מפתח + סמנטי) והעדפות תזונתיות פועלים בצורה תקינה. בקשות להזמנת משאבים נכשלות כי לא קיימים כלי הזמנה. אתם מבינים את מבנה הפרויקט ואת הפער שאתם עומדים למלא.

5. הוספת הקשר לפרויקט באמצעות Antigravity

עכשיו נדמה מצב עם תנאי ש"קצת יותר קרוב" לעבודה היומיומית שלנו:

• מאגר שלא מנוהל היטב
• קובץ README מיושן
• התיעוד לא מתעדכן לעיתים קרובות

הערה: אם המצב הזה לא משקף את המצב שלכם, סימן שהמזל שלכם משחק לטובתכם.

במקרים כאלה, הדבר הראשון שאנחנו רוצים לעשות הוא בדרך כלל ליצור מפה או הקשר לגבי הפרויקט שאנחנו רוצים ש-Antigravity יעבוד עליו. בשלב הזה מוצגת דוגמה אחת לגישה שבה אפשר להעניק ל-Antigravity הבנה עמוקה של בסיס קוד קיים, על ידי יצירת מיומנות שמנתחת את המאגר ומפיקה מסמך הקשר של הפרויקט.

הוא גם מגדיר את חוקת הפרויקט – העקרונות שאי אפשר להתפשר עליהם, שעל פיהם מתבצעת אימות של תהליכי העבודה של SDD. ביחד, הם מספקים ל-Antigravity את ההקשר והמגבלות שהוא צריך בשביל מחזורי ה-SDD בהמשך

היררכיית ההקשר של Antigravity

‫Antigravity משתמש בשלוש רמות של הקשר, שלכל אחת מהן היקף שונה:

• כללים (.agents/rules/): הוראות שתמיד פעילות. כל שיחה במרחב העבודה הזה רואה אותם ( אם הפעלתם אותם). כדאי להשתמש בכללים כדי לספק הקשר רחב יותר לפרויקט, כמו החלטות לגבי ארכיטקטורה, תקני קידוד או מידע על מערך הטכנולוגיות.
• כישורים (.agents/skills/): ידע על פי דרישה. ‫Antigravity טוען מיומנות רק כשהמשימה הנוכחית תואמת לשדה description של המיומנות. שימוש במיומנויות כדי לקבל חומר עזר ספציפי לדומיין.
• תהליכי עבודה (.agents/workflows/): הנחיות שמורות שמופעלות באמצעות פקודות /. אפשר להשתמש בתהליכי עבודה לתהליכים חוזרים שכוללים כמה שלבים, כמו צינור ה-SDD.

הערה: בפרויקט יש כרגע תהליכי עבודה (צינור SDD) ומיומנות (פיתוח סוכן ADK), אבל אין כללים. כלל project-context.md מאפשר ל-Antigravity להבין באופן עקבי את בסיס הקוד – אילו טכנולוגיות נמצאות בשימוש, איך הקבצים מאורגנים ומה נבנה עד עכשיו.

הפעלת המיומנויות

מאגר התחלה כולל שתי מיומנויות שנכתבו מראש ב-.agents/skills/. הם מכילים הוראות מפורטות, אבל מתחילים בהערות TODO(codelab) במקום ב-YAML frontmatter הנדרש. ללא frontmatter, ‏ Antigravity לא יכול לגלות אותם.

כדי להשתמש במיומנויות אנטי-גרביטציה, צריך להוסיף לחלק העליון של הקובץ בלוק frontmatter בפורמט YAML עם שני שדות:

• ‫name – מזהה ייחודי של המיומנות
• ‫description – סיכום בשפה טבעית ש-Antigravity משווה אליו כדי להחליט איזו מיומנות לטעון עבור בקשה מסוימת

פתוח

.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.
---

הערות: המיומנות 'פיתוח סוכן ADK' מכילה דפוסים ותמציתיים ודוגמאות מתוך חמישה סדנאות קוד של ADK – מבנה הסוכן, סוגי הכלים, ניהול המצב, פריסה

פתוח

.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.
---

הערות: כדאי לקרוא את הקובץ repo-research SKILL.md בפירוט. זוהי דוגמה להנחיה לניתוח המאגר. שימו לב שכללי העדכון המצטבר הם שמרניים בכוונה. אם ההקשר של Antigravity נגמר באמצע המחקר או שהשיחה מופרעת, כל מה שהתגלה עד עכשיו כבר נשמר בקובץ. אם מפעילים מחדש את המיומנות, היא ממשיכה מהמקום שבו היא נעצרה בלי לאבד את ההתקדמות.

אזהרה! ניתוח של מאגר גדול עלול לגרום לניצול מהיר של המכסה.

מוודאים שלשני הכישורים יש 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

בתיבת הצ'אט או ב-Agent Manager של Antigravity (במצב עריכה, מקישים על ctrl + L), מתחילים שיחה חדשה. סוג:

Research this repository and create a project context document

‫Antigravity מתאים את הבקשה שלכם למיומנות 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 מסמן הפרות כהפרות קריטיות. אם החוקה נשארת כתבנית ריקה עם אסימוני placeholder, אין לביקורות האלה שום דבר לאמת מולו – התוכניות והניתוחים מופעלים ללא אמצעי הגנה.

החוקה מגדירה עקרונות פרויקט שאי אפשר להתפשר עליהם. זהו מאגר קטן שמתוחזק על ידי מפתח יחיד, ולכן החוקה צריכה לשקף את ההיקף הזה – כדאי לשמור על פשטות ועקביות, ולהימנע מתכנון יתר.

במנהל הסוכנים של 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 frontmatter, הוראות ופתרון קונפליקטים. ‫.specify/memory/constitution.md מכיל שלושה עקרונות של פרויקט שתהליכי העבודה של התוכנית והניתוח מאמתים. אתם מבינים את היררכיית ההקשר בשלוש רמות: כללים (תמיד פעילים), מיומנויות (על פי דרישה), תהליכי עבודה (פקודות סלאש).

6. מחזור 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)

המפרט מתמקד במה ובסיבה – ולא באיך. התיאור מתייחס לחוויית המשתמש ("אורחים יכולים להזמין מקום במסעדה על ידי הזנת השם, מספר הסועדים, התאריך והשעה") בלי להזכיר טבלאות SQL,‏ tools.yaml או ממשקי ADK API. פרטי ההטמעה מגיעים בשלב התכנון.

בודקים את המפרט שנוצר בכתובת specs/<branch-name>/spec.md. מוודאים שהיא כוללת את הדרישות הפונקציונליות ואת קריטריוני ההצלחה.

הסבר על המפרט (אופציונלי)

מריצים את תהליך העבודה להבהרה כדי לזהות ולפתור בעיות של אזורים לא מוגדרים במפרט:

/speckit.clarify

‫Antigravity סורק את המפרט כדי לזהות אי בהירויות, קריטריונים חסרים לקבלה ודרישות לא מפורטות מספיק. הוא שואל שאלות הבהרה ממוקדות – לכל שאלה יש תשובה קצרה או ביטוי קצר. התשובות שלכם מוצפנות ישירות בחזרה למפרט, וכך הוא הופך למדויק יותר לפני תחילת התכנון.

טיפ: השלב של הבהרה הוא אופציונלי, אבל מומלץ לתכונות מורכבות. אם המפרטים פשוטים, אפשר לדלג ישירות לתכנון.

תכנון ההטמעה

מריצים את תהליך העבודה של התכנון:

/speckit.plan

‫Antigravity יוצרת תוכנית טכנית בשני שלבים:

1. שלב המחקר – פותר בעיות לא ידועות בבסיס הקוד הקיים, יוצר research.md
2. שלב התכנון – יוצר את 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 בודק את רשימת המשימות מול המפרט והתוכנית, ומחפש מקרים חריגים חסרים, משימות שעלולות להתנגש או פערים בין הדרישות של המפרט לבין העבודה המתוכננת. לפתור בעיות קריטיות לפני ההטמעה.

טיפ: שלב הניתוח הכי שימושי כשמדובר ברשימת משימות ארוכה או בתכונה שמשפיעה על כמה מערכות משנה. לתכונה ממוקדת כמו הזמנת מקומות, מספיק סריקה מהירה.

7. הטמעה

מריצים את תהליך העבודה להטמעה:

/speckit.implement

‫Antigravity מציג תוכנית הטמעה סופית וארטיפקט של משימה. כדי להמשיך, צריך לבדוק ולאשר את ההסכם

טיפ: אפשר להוסיף תגובה ישירות! אפשר לעשות את זה רק באמצעות Artifact מובנה של 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 כדי לראות את כל השינויים ולוודא שהלוגיקה שקשורה להזמנות נוספה.

השינויים אמורים להשפיע על הסקריפט של מסד הנתונים הראשוני. ננסה להריץ אותו.

source .env
uv run python scripts/seed_db.py

הסקריפט המעודכן צריך ליצור את הטבלה reservations אם היא עדיין לא קיימת. אמור להופיע פלט שמאשר שהטבלה החדשה נוצרה (הנתונים הקיימים ב-menu_items נשמרים).

הערה: יכול להיות ש-Antigravity יצרו סקריפט נפרד להעברה (למשל, scripts/create_reservations.py) במקום לעדכן את seed_db.py. בודקים אם יש סקריפטים חדשים ב-git diff --name-only ומריצים אותם במקום זאת.scripts/

אם הכול יתנהל כשורה עד לשלב הזה, נוכל לבדוק את התכונה בממשק המשתמש של ADK agent Dev. מפעילים מחדש את ארגז הכלים כדי להשתמש בהגדרות החדשות של הכלי ב-tools.yaml. עוצרים את כל התהליכים הקיימים של Toolbox ומתחילים תהליך חדש:

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

מפעילים את ממשק המשתמש של 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 dev על ידי הקשה על Ctrl+C פעמיים.

נקודת ביקורת: הסוכן מטפל בהזמנת מקומות ובחיפוש הזמנות. השלמתם מחזור מלא של SDD: הגדרה ← הבהרה ← תכנון ← משימות ← ניתוח ← הטמעה ← בדיקה. בכל שלב נוצר ארטיפקט עם מספר גרסה ב-specs/<branch-name>/.

8. אתגרים (אופציונלי)

עכשיו אתם יודעים את כל תהליך העבודה של SDD. רוצים לנסות?

• מריצים מחזור שני של SDD כדי ליצור ממשק צ'אט באתר בשביל שירות הקונסיירז' של המסעדה – הפעם בלי הנחיות מפורטות.
• פריסת הסוכן ב-Cloud Run לתרחיש ייצור

רמזים

• לפרויקט אין מסגרת frontend. ‫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 לשיעורים האלה.

9. מעולה!

הרחבתם סוכן ADK של מסעדת קונסיירז' עם הזמנת מקומות – הכול באמצעות תהליכי העבודה של SDD של Antigravity, בלי לכתוב קוד אפליקציה באופן ידני.

מה יצרתם

• סוכן ADK של קונסיירז' במסעדה עם חיפוש בתפריט, חיפוש סמנטי, מעקב אחר העדפות תזונתיות והזמנת מקום
• מיומנות Antigravity למחקר במאגר, שיוצרת ושומרת מסמך הקשר של הפרויקט
• מסמך עקרונות לפרויקט שמכתיב עקרונות שאי אפשר להתפשר עליהם במהלך התכנון והניתוח
• מחזור SDD מלא שמדגים את תהליך העבודה: הגדרה ← הבהרה ← תכנון ← משימות ← ניתוח ← הטמעה

מה למדתם

• איך משתמשים בתהליכי עבודה של פיתוח מבוסס-מפרט ב-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

חשוב: אפשר לבטל את פעולת המחיקה הזו למשך תקופה מוגבלת באמצעות הפקודה gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}