יצירת סומלייה דוריאן מולטי-מודאלי באמצעות ADK ו-Antigravity

1. סקירה כללית

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

ב-Codelab הזה, תבנו ותבדקו מערכת מרובת סוכנים מולטי-מודאלית בשם Durian Sommelier באמצעות הערכה לפיתוח סוכנים (ADK) ו-Agents CLI. אם תרצו, תוכלו לפרוס אותה ב-Cloud Run באמצעות Antigravity CLI (השלבים העיקריים נמשכים כ-45 דקות, ושני השלבים האופציונליים של Antigravity מוסיפים עוד כ-20 דקות). הבחירה בדוריאן ממחישה איפה נגמרת התפיסה של ה-AI ומתחילים החושים האנושיים:

  • מה ה-AI יכול לראות: Gemini יכול לבחון תמונה של הקליפה ולזהות סימנים של זנים, כמו הכוכב בעל חמשת הקודקודים בבסיס של מוסאנג קינג, הקצה הכהה והשקוע של בלאק ת'ורן (D200), הטבעת בגודל מטבע של D24 או גבעול יבש ומצומק.
  • מה שרק בני אדם יכולים לחוש: מודל לא יכול להריח את התפר כדי לזהות ריח של אלכוהול, להקיש על הקליפה כדי לשמוע צליל חלול או ללחוץ על שני קוצים כדי להרגיש אם הם קפיציים.
  • מה הסוכן צריך לזכור: שני פירות דוריאן בשלים לחלוטין עדיין מחלקים את הקונים. יש אנשים שאוהבים את הטעם המריר והאלכוהולי של XO D24 מעץ ותיק, ואחרים מעדיפים את הטעם המתוק והלא מריר של Red Prawn (D175).

הגבול החושי של הדוריאן: ראיית AI לעומת חושים אנושיים

מה תפתחו

  • שלב 1 – סוכן ראייה יחיד: סוכן ADK, שנוצר באמצעות Agents CLI, שמזהה את הזן והטריות של דוריאן מתמונה.
  • שלב 2 – החושים האנושיים והזיכרון של חוש הטעם: כלים שנותנים ציון למה שהקונה מריח, שומע ומרגיש, וגם כלי ששומר את פרופיל הטעם שלו בין הסשנים.
  • שלב 3 – רכז ומומחים: רכז של durian_advisor שקורא למפקח ראייה ולסומלייה חושי, ואז נותן פסיקה אחת ברורה.
  • שלב 4 – שירות סוכן Cloud Run: שלב אופציונלי שבו Antigravity CLI פורס את הסוכן עם המיומנויות של Agents CLI.
  • שלב 5 – צ'אט בוט לאינטרנט ב-Cloud Run: בשלב אופציונלי נוסף, Antigravity CLI יוצר ומפעיל אפליקציית צ'אט שמותאמת לנייד ומתקשרת עם הנציג.

ארכיטקטורה

ארכיטקטורת Durian Sommelier: צ'אט בוט באינטרנט ב-Cloud Run קורא למתאם durian_advisor ב-Cloud Run, שקורא למומחים לראייה ולחושים ושומר את הטעם של הקונה במצב הסשן של ADK

שני השירותים של Cloud Run מגיעים מהשלבים האופציונליים של Antigravity. בלעדיהם, אתם מריצים את אותם סוכנים ב-ADK Playground ב-Cloud Shell.

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

  • מיומנות בסיסית בתכנות ב-Python
  • היכרות עם כלי שורת הפקודה ועם מושגים שקשורים ל-AI גנרטיבי
  • לא נדרש ניסיון קודם עם ADK,‏ Agents CLI או Antigravity CLI

מה תלמדו

  • איך ליצור פרויקט ADK עם agents-cli create ולבנות סוכן מולטי-מודאלי שקורא תמונות
  • איפה נגמרת התפיסה של ה-AI (ריח, צליל, מגע וטעם אישי) ואיך לעצב כלים שמשלבים את האדם שבתהליך בשביל החושים האלה
  • איך לזכור את ההעדפות של כל משתמש בסשנים שונים באמצעות מצב ADK ברמת user:
  • איך לפצל סוכן אחד לסוכן מתאם ולסוכנים מומחים עם פנייה אחת, שהסוכן המתאם קורא להם כמו לכלים
  • אופציונלי: איך לתת ל-Antigravity CLI את המיומנויות של Agents CLI כדי שהוא יוכל לפרוס את הסוכן ואת הצ'אט בוט לאינטרנט ב-Cloud Run

הדרישות

  • חשבון Google (אם רוצים לממש קרדיטים לסדנה, צריך להשתמש בחשבון @gmail.com אישי)
  • קישור לקרדיט לסדנה שקיבלתם מהמדריך (וגם מצלמה של טלפון כדי לסרוק את קוד ה-QR) או חשבון פעיל לחיוב ב-Cloud
  • Google Chrome (מומלץ להשתמש בחלון פרטי כדי למנוע ערבוב בין החשבון האישי לחשבון לצורכי עבודה)

2. מימוש קרדיטים ב-Google Cloud (אופציונלי)

אם אתם משלימים את ה-Codelab הזה בעצמכם ואתם עומדים בדרישות, השתמשו בבאנר הקרדיטים של Google Developer Program בדף הזה כדי לקבל קרדיטים בלי כרטיס אשראי. אם אתם משתתפים בסדנה עם קישור לקרדיט לאירוע שקיבלתם מהמדריך, בצעו את השלבים לקבלת קרדיט לאירוע שמפורטים בקטע הזה.

מימוש שובר הפרסום לאירוע

אתם יכולים לממש קרדיטים לאירועי סדנאות דרך Google Builders Hub (חלק מ-Google Developer Program).

כדי לממש את הזיכוי לאירוע:

  1. פותחים את הקישור לקרדיט לסדנה בחלון פרטי ונכנסים באמצעות חשבון @gmail.com האישי.
  2. בכרטיס Claim Your Benefit, לוחצים על Claim Credit.

כרטיס "מימוש ההטבה" ב-Google Builders Hub, שבו מוצג הכפתור "מימוש הקרדיט".

  1. אופציונלי: אם מופיעה בקשה ליצור פרופיל ב-Google Developer Program, ממלאים את הטופס.
  2. כשמופיעה תיבת הדו-שיח צריך לסרוק כדי לאמת שאתה אנושי, סורקים את קוד ה-QR באמצעות הטלפון ומשלימים את האימות. אם קוד ה-QR לא מופיע, מרעננים את הדף ולוחצים שוב על מימוש הקרדיט.
  3. מוודאים שמופיעה ההודעה Successfully claimed your event credit!‎ ולוחצים על Open Billing Account.

כרטיס אישור של Google Builders Hub שבו מוצג הכיתוב "מימשת בהצלחה את הקרדיט לאירוע" והכפתור "פתיחת החשבון לחיוב".

🔍 בדיקת העבודה שלכם

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

  1. אם הדף Billing account management לא פתוח, פותחים את Google Cloud Billing (או מעתיקים את כתובת ה-URL לחלון פרטי):
https://console.cloud.google.com/billing
  1. לוחצים על הכרטיסייה Your billing accounts ומרעננים את הדף עד שבעמודה Status של חשבון לחיוב שכולל את GDP Credit מופיע הסטטוס Active.

דף ניהול החשבון לחיוב ב-Google Cloud, שבו מוצג חשבון לחיוב ב-Cloud פעיל בקרדיט GDP.

3. יצירת פרויקט ב-Google Cloud (אופציונלי)

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

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

  1. פותחים את הדף Create a project (או מעתיקים את כתובת ה-URL לחלון הפרטי):
https://console.cloud.google.com/projectcreate
  1. ממלאים את פרטי הפרויקט:
    • ‫Project name: מזינים שם תיאורי, למשל google-cloud-workshop.
    • חשבון לחיוב (אם מוצג): בוחרים את החשבון GDP Credit (או את החשבון הפעיל לחיוב).
    • משאב הורה: משאירים את האפשרות ללא ארגון מסומנת (או בוחרים את הארגון שלכם, אם צריך).
  2. רושמים או זוכרים את מזהה הפרויקט שנוצר ולוחצים על Create.

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

🔍 בדיקת העבודה שלכם

בסיום יצירת הפרויקט, פותחים את Notifications בסרגל הכלים של מסוף Google Cloud ולוחצים על Select Project.

תפריט ההתראות במסוף Google Cloud, שבו מוצגים הקישורים Create Project ו-Select Project.

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

בקטע הזה תגדירו את Google Cloud Shell, תפעילו את Agent Platform API ותתקינו את Agents CLI באמצעות uv.

הגדרת Cloud Shell

הפעלת Cloud Shell

פותחים את Google Cloud Shell כשגם עורך הקוד וגם תצוגת הטרמינל מופעלים (או מעתיקים את כתובת ה-URL לחלון הפרטי), ואם מופיעה בקשה, לוחצים על Authorize:

https://shell.cloud.google.com/?show=ide,terminal

תיבת הדו-שיח Authorize Cloud Shell

הגדרת מזהה הפרויקט ב-Google Cloud

מעתיקים את קטע הקוד הבא ומדביקים אותו במסוף Cloud Shell. יוצג תפריט ממוספר של פרויקטים בענן הזמינים ב-Google Cloud. מקלידים את המספר שמופיע ליד הפרויקט (לדוגמה, 1) ולוחצים על Enter:

unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

ההנחיה הצפויה:

1) durian-sommelier-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].
[environment: untagged] Read more to tag: g.co/cloud/project-env-tag.

מזהה הפרויקט שבחרתם אמור להופיע עכשיו מודגש בצהוב בהנחיה של מסוף Cloud Shell:

מסוף Cloud Shell עם מזהה הפרויקט שנבחר מודגש בצהוב

הפעלת Agent Platform API

מפעילים את Agent Platform API, שבו הסוכנים משתמשים כדי להפעיל את Gemini:

gcloud services enable aiplatform.googleapis.com

🔍 בדיקת העבודה שלכם

הפלט אמור להיראות כך:

Operation "operations/acat.p2-..." finished successfully.

התקנת Agents CLI

מוודאים ש-uv זמין ושתיקיית הכלים שלו נמצאת ב-PATH:

which uv || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

מתקינים את Agents CLI ככלי של uv:

uv tool install google-agents-cli==1.7.0

‫uv מתקין כל כלי בסביבה מבודדת משלו ומוסיף רק את הפקודה agents-cli ל-PATH, כך ש-Python של המערכת נשאר ללא שינוי. אתם גם לא צריכים להתקין את ADK בעצמכם. כל פרויקט שנוצר באמצעות Agents CLI מקבל סביבה וירטואלית משלו עם גרסת ADK שהתבנית נבדקה מולה.

🔍 בדיקת העבודה שלכם

מוודאים ש-Agents CLI מוכן:

agents-cli --version

הפלט אמור להיראות כך:

agents-cli, version 1.7.0

5. יצירת סוכן ראייה ממוחשבת מולטי-מודאלי

מתחילים בקטן: משתמשים ב-Agents CLI כדי ליצור פרויקט ADK, ואז הופכים את הסוכן לדוגמה שלו למסווג חזותי של דוריאן.

יצירת תבנית לפרויקט

יוצרים את הפרויקט durian-advisor. ‫--agent adk_python בוחרת את תבנית ה-ADK של Python, ‏--deployment-target cloud_run ו---region us-central1 מכינות אותה ל-Cloud Run, ‏--prototype מדלגת על הגדרת CI/CD ו---yes מאשרת את ברירות המחדל:

cd ~ && agents-cli create durian-advisor \
  --agent adk_python \
  --deployment-target cloud_run \
  --region us-central1 \
  --prototype \
  --yes

הפלט אמור להיראות כך:

> Verifying GCP credentials...
> ✓ Connected to project: your-project-id

✅ Success! Your agent project is ready.

פותחים את הפרויקט ב-Cloud Shell Editor. הפעולה הזו טוענת מחדש את החלון ומפעילה מחדש את הטרמינל:

cloudshell workspace ~/durian-advisor

מתקינים את יחסי התלות של הפרויקט בתיקייה .venv שלו:

cd ~/durian-advisor && agents-cli install

בדיקת קובץ הסביבה

‫Agents CLI גם כתב קובץ .env שאומר ל-ADK לקרוא ל-Gemini דרך הפרויקט שלכם ב-Google Cloud:

grep GOOGLE_ ~/durian-advisor/.env

הפלט אמור להיראות כך:

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

שמירה של GOOGLE_CLOUD_LOCATION=global. ‫Gemini 3.8 Flash מוגש מנקודת הקצה global, ולא מנקודות קצה אזוריות כמו us-central1, למרות ששירותי Cloud Run פועלים ב-us-central1.

אם הערך של GOOGLE_CLOUD_PROJECT הוא your-gcp-project-id, סימן ש-Agents CLI לא זיהה את הפרויקט. כדי להגדיר אותו:

sed -i "s/your-gcp-project-id/$(gcloud config get-value project)/" ~/durian-advisor/.env

כתיבת מסווג הראייה

לכל זן יש סימנים בקליפה ש-Gemini יכול לזהות בתמונה:

מדריך חזותי לזני דוריאן שמראה את הבסיס והקוצים של מוסאנג קינג, בלאק ת'ורן, רד פראון ו-D24

פותחים את app/agent.py:

cloudshell edit ~/durian-advisor/app/agent.py

מחליפים את התוכן שלו בקוד הבא:

"""A single multimodal agent that inspects durian photos."""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

MODEL = "gemini-3.8-flash"

INSTRUCTION = """You are a durian visual classifier. Inspect the durian photo or shell description.
1. Base seam: a 5-point star means Musang King (D197). A dark sunken tip means Black Thorn (D200). A coin-sized brown ring means D24. An oval body with widely spaced, hooked thorns means Red Prawn (D175).
2. Stem: plump, moist, and greenish means it fell within about 12 hours. Dry and shriveled means it is days old.
3. Husk: closed seams mean natural ripening. Wide splits or mold mean it is past its best.
Give the likely cultivar and a visual freshness score from 1 to 10. Then list what a photo cannot tell you: the aroma, the tap sound, the thorn springiness, and whether the buyer will enjoy the taste."""

root_agent = Agent(
    name="durian_advisor",
    model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
    description="Classifies durian cultivars and visual freshness from photos.",
    instruction=INSTRUCTION,
)

app = App(root_agent=root_agent, name="app")

יש כמה פרטים שחשוב לשים לב אליהם:

  • מזהה המודל מופיע רק ב-MODEL. כל נציג שתוסיפו בהמשך יירש את המודל הזה, כך שהחלפת מודלים היא שינוי של שורה אחת.
  • ‫retry_options מנסה שוב שגיאות זמניות, כמו הגבלת קצב של יצירת בקשות, עד שלוש פעמים.
  • ‫app = App(...) עוטף את הסוכן גם בשביל ה-Playground וגם בשביל שרת Cloud Run. משאירים את שם האפליקציה app ואת שם הסוכן durian_advisor, שתואמים לשרת שנוצר ול-agents-cli-manifest.yaml.

בדיקת הנציג ב-Playground

מפעילים את סביבת הניסויים של ADK:

cd ~/durian-advisor && agents-cli playground

הפלט אמור להיראות כך:

INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

לוחצים על Web Preview בסרגל הכלים של Cloud Shell ובוחרים באפשרות Preview on port 8080. אם בממשק המשתמש של ADK Dev תתבקשו לבחור נציג, בחרו באפשרות app. אחר כך שולחים את ההנחיה הזו, או מצרפים תמונה של דוריאן באמצעות כפתור ההעלאה:

I'm at a stall looking at a round durian with pyramid-shaped thorns and a 5-point star at the base. The stem is green and moist. What cultivar is this, and will it taste sweet?

🔍 בדיקת העבודה שלכם

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

לפני שממשיכים, לוחצים על Ctrl + C בטרמינל כדי לעצור את ה-playground.

6. הוספת חושים אנושיים וזיכרון של טעמים

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

הוספת קטלוג הזנים

יצירת app/durian_data.py:

cloudshell edit ~/durian-advisor/app/durian_data.py

מדביקים את קטלוג קובצי העזר. שמירת הנתונים במודול משלהם שומרת על קוד הסוכן קצר:

"""Reference catalog of durian cultivars."""

CULTIVAR_CATALOG = {
    "musang_king": {
        "code": "D197",
        "name": "Musang King (Mao Shan Wang)",
        "visual_markers": "5-point star seam at the base, pyramid-shaped thorns",
        "flavor": "rich, bittersweet, buttery custard",
        "bitterness": "medium",
    },
    "black_thorn": {
        "code": "D200",
        "name": "Black Thorn (Ochee)",
        "visual_markers": "Dark sunken tip at the base, round pumpkin-like body",
        "flavor": "sweet, creamy, slightly winey",
        "bitterness": "low",
    },
    "red_prawn": {
        "code": "D175",
        "name": "Red Prawn (Udang Merah)",
        "visual_markers": "Oval body, widely spaced and slightly hooked thorns",
        "flavor": "sweet, floral, soft and sticky",
        "bitterness": "none",
    },
    "xo_d24": {
        "code": "D24",
        "name": "XO D24 (Sultan, old tree)",
        "visual_markers": "Coin-sized brown ring at the base, dense sharp thorns",
        "flavor": "intense, bitter, with a boozy finish",
        "bitterness": "high",
    },
}

הוספת הכלים החושיים

יצירת app/sensory_tools.py:

cloudshell edit ~/durian-advisor/app/sensory_tools.py

מדביקים את הקוד הבא:

"""Tools for cultivar lookup and human-in-the-loop sensory checks."""

from typing import Any, Literal

from .durian_data import CULTIVAR_CATALOG

AROMA_POINTS = {"sweet_fragrant": 4, "boozy_fermented": 3, "faint_grassy": 0, "sour_rotten": 0}
TAP_POINTS = {"hollow": 3, "solid": 0}
THORN_POINTS = {"springy": 3, "rigid": 0}


def get_cultivar_profile(cultivar_key: str) -> dict[str, Any]:
    """Looks up the visual markers, flavor, and bitterness of a durian cultivar.

    Args:
        cultivar_key: One of 'musang_king', 'black_thorn', 'red_prawn', or 'xo_d24'.
    """
    key = cultivar_key.strip().lower().replace(" ", "_").replace("-", "_")
    if key not in CULTIVAR_CATALOG:
        return {"status": "NOT_FOUND", "supported": list(CULTIVAR_CATALOG)}
    return {"status": "OK", "cultivar": CULTIVAR_CATALOG[key]}


def evaluate_human_sensory_clues(
    aroma: Literal["sweet_fragrant", "boozy_fermented", "faint_grassy", "sour_rotten"],
    tap_sound: Literal["hollow", "solid"],
    thorn_feel: Literal["springy", "rigid"],
) -> dict[str, Any]:
    """Scores the ripeness clues that only a human buyer can smell, hear, and feel.

    Args:
        aroma: What the buyer smells at the seam of the husk.
        tap_sound: What the buyer hears when tapping the husk.
        thorn_feel: How two thorns feel when the buyer presses them together.
    """
    score = AROMA_POINTS[aroma] + TAP_POINTS[tap_sound] + THORN_POINTS[thorn_feel]
    if aroma == "sour_rotten":
        verdict = "SPOILED"
    elif score >= 7:
        verdict = "RIPE"
    elif score >= 4:
        verdict = "NOT_QUITE_READY"
    else:
        verdict = "UNRIPE"
    return {"status": "OK", "ripeness_score": score, "max_score": 10, "verdict": verdict}

איך הכלים האלה פועלים:

  • ‫ADK הופך כל פונקציה לכלי שהמודל יכול להפעיל. ה-docstring הופך לתיאור הכלי, והקטע Args מסביר כל פרמטר.
  • ההנחיות לגבי הסוג Literal[...] הופכות לבחירות קבועות בסכימה של הכלי, כך ש-Gemini חייב למפות את "מריח קצת כמו אלכוהול" לערך מותר אחד בדיוק, כמו boozy_fermented.
  • הפונקציה get_cultivar_profile מחזירה סטטוס NOT_FOUND מפורש עם המקשים הנתמכים במקום להמציא זן.

הוספת הכלי "זיכרון הטעם"

יצירת app/memory_tools.py:

cloudshell edit ~/durian-advisor/app/memory_tools.py

מדביקים את הקוד הבא:

"""Tool that remembers each buyer's durian palate across sessions."""

from typing import Any, Literal

from google.adk.tools import ToolContext


def save_palate_preference(
    favorite_flavors: str,
    bitterness_tolerance: Literal["none", "low", "medium", "high"],
    tool_context: ToolContext,
) -> dict[str, Any]:
    """Saves the buyer's durian taste preferences to their long-term profile.

    Args:
        favorite_flavors: Flavors and textures the buyer enjoys, such as
            'sweet, creamy custard'.
        bitterness_tolerance: How much bitterness the buyer enjoys.
    """
    profile = {
        "favorite_flavors": favorite_flavors,
        "bitterness_tolerance": bitterness_tolerance,
    }
    # The "user:" prefix scopes this key to the buyer, so it follows them
    # into every future session of this app.
    tool_context.state["user:palate_profile"] = profile
    return {"status": "SAVED", "palate_profile": profile}

איך פועל זיכרון הטעם:

  • ‫ADK מעביר את tool_context באופן אוטומטי ומסתיר אותו מהמודל, כך ש-Gemini רואה רק את שני הפרמטרים של הטעם.
  • הקידומת user: מגדירה את היקף מפתח המצב למשתמש במקום לסשן הנוכחי, כך שהפרופיל מלווה את הקונה בכל שיחה חדשה.
  • לא צריך כלי נפרד כדי להוריד את הקבצים. הנציגים קוראים את הפרופיל ישירות לתוך ההוראות שלהם באמצעות ה-placeholder‏ {user:palate_profile?}. הפונקציה ? גורמת לפלייסהולדר להיות ריק כשעדיין אין פרופיל, במקום להציג שגיאה.

🔍 בדיקת העבודה שלכם

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

cd ~/durian-advisor && uv run python -c "from app.sensory_tools import evaluate_human_sensory_clues as score; print(score('boozy_fermented', 'hollow', 'springy'))"

הפלט אמור להיראות כך:

{'status': 'OK', 'ripeness_score': 9, 'max_score': 10, 'verdict': 'RIPE'}

7. תיאום בין סוכנים מומחים

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

  • ‫vision_inspector_agent קורא את הזן והטריות מהתמונה ומחזיר דוח מובנה.
  • ‫sensory_sommelier_agent מדרג את מה שהקונה הריח, שמע והרגיש, ובודק את הזן לפי הטעם שלו.
  • ‫durian_advisor מדבר עם הקונה, שומר את העדפות הטעם שלו, מתקשר לכל מומחה וכותב את פסק הדין הסופי.

יצירת ה-Vision Inspector

יצירת app/vision_agent.py:

cloudshell edit ~/durian-advisor/app/vision_agent.py

מדביקים את הקוד הבא:

"""Vision inspector: reads the cultivar and freshness from a durian photo."""

from google.adk.agents import Agent
from pydantic import BaseModel, Field


class VisionReport(BaseModel):
    cultivar_key: str = Field(
        description="musang_king, black_thorn, red_prawn, xo_d24, or unknown"
    )
    visual_freshness: int = Field(description="1 (stale) to 10 (freshly fallen)")
    evidence: str = Field(description="The visual markers behind your answer")


vision_inspector_agent = Agent(
    name="vision_inspector_agent",
    description="Identifies a durian's cultivar and visual freshness from the buyer's photo or shell description.",
    mode="single_turn",
    # Specialists only see their tool-call input by default. Opt in to the
    # conversation history so this agent can see the uploaded photo.
    include_contents="default",
    # Report back to the coordinator instead of taking over the conversation.
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
    output_schema=VisionReport,
    instruction="""You are a durian vision inspector. Examine the durian photo or shell description in the conversation.
Cultivar markers:
- 5-point star seam at the base: musang_king
- Dark sunken tip at the base: black_thorn
- Oval body with widely spaced, slightly hooked thorns: red_prawn
- Coin-sized brown ring at the base and dense, sharp thorns: xo_d24
Freshness: a plump, moist, greenish stem and closed seams score high. A dry, shriveled stem or a split, moldy husk scores low.
If the markers are unclear, use 'unknown'.""",
)
  • ‫output_schema=VisionReport גורם למומחה להחזיר נתונים מובְנים שהרכז יכול להסתמך עליהם.
  • ‫include_contents="default" מאפשר למומחה לראות את השיחה, כולל התמונה שהועלתה. בלעדיו, מומחה לפעולה אחת רואה רק את הבקשה שהרכז מעביר.
  • disallow_transfer_to_parent ו-disallow_transfer_to_peers מסירים את הכלי transfer_to_agent ש-ADK היה נותן לסוכן המשנה הזה. מומחה שרואה את כל השיחה עלול להתפתות להחזיר את הצ'אט לרכז במקום להחזיר את הדוח שלו.

יצירת סומלייה חושי

יצירת app/sensory_agent.py:

cloudshell edit ~/durian-advisor/app/sensory_agent.py

מדביקים את הקוד הבא:

"""Sensory sommelier: scores the buyer's senses and checks palate fit."""

from google.adk.agents import Agent
from pydantic import BaseModel, Field

from .sensory_tools import evaluate_human_sensory_clues, get_cultivar_profile


class SensoryClues(BaseModel):
    cultivar_key: str = Field(description="Cultivar from the vision inspector")
    aroma: str = Field(description="What the buyer smelled at the seam")
    tap_sound: str = Field(description="What the buyer heard when tapping the husk")
    thorn_feel: str = Field(description="How the thorns felt when pressed together")


sensory_sommelier_agent = Agent(
    name="sensory_sommelier_agent",
    description="Scores the smell, sound, and touch clues the buyer reports, and checks the cultivar against their palate.",
    mode="single_turn",
    # Report back to the coordinator instead of taking over the conversation.
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
    input_schema=SensoryClues,
    instruction="""You are a durian sensory sommelier.
Buyer palate profile: {user:palate_profile?}

1. Call evaluate_human_sensory_clues with the buyer's aroma, tap sound, and thorn feel.
2. Call get_cultivar_profile for the cultivar.
3. Compare the cultivar's bitterness with the buyer's bitterness tolerance.
Report the ripeness verdict, the palate fit, and one sentence of advice.""",
    tools=[evaluate_human_sensory_clues, get_cultivar_profile],
)
  • input_schema=SensoryClues מגדיר מה הרכז צריך להעביר: הזן ושלושת הדוחות החושיים של הקונה, במילים שלו. המומחה ממפה את המילים האלה לערכים המותרים של הכלי.
  • ‫{user:palate_profile?} מוסיף להוראה את פלטת הצבעים שהקונה שמר, כדי שהמומחה יוכל להעריך את ההתאמה בלי לחפש בזיכרון.
  • אף אחת מהן לא מגדירה את model. שניהם מקבלים בירושה את MODEL של הרכז.
  • שני המומחים משתמשים באותם שני דגלי העברה, כך שכל אחד מהם תמיד מדווח בחזרה לרכז.

חיבור החוטים של הרכזת

פותחים את app/agent.py:

cloudshell edit ~/durian-advisor/app/agent.py

מחליפים את התוכן שלו ב-coordinator:

"""Durian advisor: a concierge that coordinates vision and sensory specialists."""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from .memory_tools import save_palate_preference
from .sensory_agent import sensory_sommelier_agent
from .vision_agent import vision_inspector_agent

MODEL = "gemini-3.8-flash"

root_agent = Agent(
    name="durian_advisor",
    model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
    description="Durian concierge that combines what the camera sees with what the buyer senses.",
    instruction="""You are a friendly durian concierge helping a buyer at a fruit stall.
Buyer palate profile: {user:palate_profile?}

1. When the buyer shares taste preferences, call save_palate_preference.
2. When the buyer shows or describes a durian, call vision_inspector_agent.
3. A camera cannot smell, hear, or feel. Unless the buyer already reported the seam aroma, tap sound, and thorn feel, ask them to check. Then call sensory_sommelier_agent.
4. Call one specialist at a time. Finish with ONE verdict covering the cultivar, ripeness, and palate fit. If the durian does not suit their palate, suggest a cultivar that does.""",
    tools=[save_palate_preference],
    sub_agents=[vision_inspector_agent, sensory_sommelier_agent],
)

app = App(root_agent=root_agent, name="app")

שני המומחים משתמשים ב-mode="single_turn", ולכן ADK נותן למתאם שני כלים נוספים שנקראים vision_inspector_agent ו-sensory_sommelier_agent. ההוראה מתייחסת אליהם בשמות האלה.

בדיקת הרכז בסביבת הניסויים

מפעילים מחדש את מגרש המשחקים:

cd ~/durian-advisor && agents-cli playground

פותחים את Web Preview ביציאה 8080 ומנהלים את השיחה הקצרה הזו עם הנציג.

למדו אותו מה אתם אוהבים:

Hi! Please remember my taste: I love sweet, creamy custard durians and I can't stand bitterness.

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

{
  "user:palate_profile": {
    "favorite_flavors": "sweet, creamy custard",
    "bitterness_tolerance": "none"
  }
}

תראו לו דוריאן (תארו אותו או צרפו תמונה):

The vendor is showing me a round durian with a coin-sized brown ring at the base and dense, sharp thorns. The stem is green and moist. Should I buy it?

המוקדן מתקשר למספר vision_inspector_agent, שמזוהה בתור XO D24. אחר כך הוא מבקש מכם להריח את התפר, לטפוח על הקליפה וללחוץ שני קוצים זה לזה.

דיווח על מה שחשתם:

It smells a bit boozy, the knock sounds hollow, and the thorns spring back when I press them.

מתחילים מחדש: לוחצים על סשן חדש ושואלים:

Which durian should I pick today?

🔍 בדיקת העבודה שלכם

  • אחרי שאתם מדווחים על החושים שלכם, הרכז מתקשר אל sensory_sommelier_agent ונותן פסק דין אחד: ה-XO D24 בשל (9 מתוך 10), אבל המרירות הגבוהה שלו מתנגשת עם החיך שלכם, אז בקשו במקום זאת שרימפס אדום (D175) או קוץ שחור (D200).
  • בכרטיסייה אירועים, אתם יכולים לראות ש-durian_advisor מתקשר לכל מומחה, ו-sensory_sommelier_agent מתקשר ל-evaluate_human_sensory_clues ול-get_cultivar_profile.
  • בשיחה החדשה, הסוכן כבר מכיר את הטעם שלכם וממליץ על זן מתוק ולא מריר בלי לשאול שוב.

מקישים על Ctrl + C בטרמינל כדי לעצור את ה-Playground.

8. פריסה באמצעות Antigravity (אופציונלי)

יצרתם ובדקתם את הסוכן באופן ידני. עכשיו תפרסו את האפליקציה באמצעות Antigravity CLI (agy), סוכן ה-AI של Google לתכנות בטרמינל. הסקילים של Agents CLI מלמדים את Antigravity איך לפרוס סוכן ADK בצורה נכונה.

הפעלת ממשקי ה-API לפריסה

מפעילים את ממשקי ה-API של Cloud Run,‏ Cloud Build ו-Artifact Registry, שבהם Agents CLI משתמש כדי ליצור ולארח את הסוכן:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

הפלט אמור להיראות כך:

Operation "operations/acat.p2-..." finished successfully.

התקנת המיומנויות של Agents CLI

מתקינים את שבעת הסקילים של Agents CLI בתיקיית הפרויקט, שבה Antigravity מגלה אותם באופן אוטומטי:

cd ~/durian-advisor && agents-cli setup --workspace

🔍 בדיקת העבודה שלכם

ls -1 ~/durian-advisor/.agents/skills

הפלט אמור להיראות כך:

google-agents-cli-adk-code
google-agents-cli-deploy
google-agents-cli-eval
google-agents-cli-observability
google-agents-cli-publish
google-agents-cli-scaffold
google-agents-cli-workflow

הפעלת Antigravity CLI

‫Antigravity CLI מותקן מראש ב-Cloud Shell. מפעילים אותו מתיקיית הפרויקט:

cd ~/durian-advisor && agy --dangerously-skip-permissions

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

מבקשים מ-Antigravity לפרוס את האפליקציה

מדביקים את ההנחיה הזו ב-Antigravity:

Use the google-agents-cli-deploy skill to deploy this ADK agent to Cloud Run in us-central1 as a private service. Keep GOOGLE_CLOUD_LOCATION=global so Gemini keeps working, save the exact service URL to .env as AGENT_BASE_URL, and smoke-test the deployed agent with agents-cli run.

‫Antigravity קורא את המיומנות ויכול להיות שהוא יריץ קודם את הבדיקות של הפרויקט. לאחר מכן הוא מריץ את agents-cli deploy, שיוצר את הקונטיינר באמצעות Cloud Build ופורס את השירות durian-advisor, ושולח הודעת בדיקה לשירות הפעיל. התהליך כולו נמשך כחמש עד שמונה דקות.

כשהמשחק מסתיים, לוחצים פעמיים על Ctrl + D כדי לצאת ממנו.

🔍 בדיקת העבודה שלכם

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

cd ~/durian-advisor && source .env && agents-cli run --url "$AGENT_BASE_URL" --mode adk "Which durian suits a beginner?"

הפלט אמור להיראות כך:

Querying remote agent: https://durian-advisor-123456789012.us-central1.run.app (mode: adk)
[user]: Which durian suits a beginner?
[durian_advisor]: For beginners, you want a durian that is sweet, creamy, and gentle on the palate, with little to no bitterness...

עכשיו מוודאים שהשירות דוחה קריאות בלי אסימון:

curl -s -o /dev/null -w "%{http_code}\n" "$AGENT_BASE_URL"

הפלט אמור להיראות כך:

403

9. תכנות הצ'אט בוט לאתר בשיטת Vibe coding (אופציונלי)

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

המשך השימוש ב-Antigravity

cd ~/durian-advisor && agy --dangerously-skip-permissions

בתוך Antigravity, מריצים את הפקודה דרך שורת הפקודות הבאה ובוחרים את שיחת הפריסה מהרשימה:

/resume

מבקשים מ-Antigravity ליצור את הצ'אט בוט

מדביקים את ההנחיה הבאה:

Build a mobile-friendly "Durian Sommelier" web chatbot in a new web/ folder that talks to our deployed agent at AGENT_BASE_URL (ADK app name "app").

- Add palate quick-set buttons, a photo upload, and one-tap sensory chips: Smells sweet, Smells boozy, Hollow knock, Solid knock, Thorns spring back, Thorns feel stiff.
- Use a small FastAPI server that proxies chat requests to the agent with a Google ID token, because the agent service is private.
- Show only durian_advisor's replies in the chat, not the specialists' intermediate output.
- Keep a stable user ID per browser and reuse one ADK session, creating a new one if it is missing.

Deploy it to Cloud Run as durian-sommelier-web in us-central1 with public access. Run it as a new service account named durian-sommelier-web that can invoke durian-advisor, and print the URL.

חברת Antigravity כותבת את האפליקציה, יוצרת את חשבון השירות, מקצה לו את התפקיד מפעיל Cloud Run ב-durian-advisor ופורסת את האפליקציה באמצעות Cloud Build. בדרך כלל, לפני שהיא מסיימת, היא בודקת את נקודת הקצה של הצ'אט. התהליך כולו נמשך כעשר דקות. כשהכתובת מודפסת, לוחצים פעמיים על Ctrl + D כדי לצאת.

🔍 בדיקת העבודה שלכם

פותחים את כתובת ה-URL של https://durian-sommelier-web-....run.app ש-Antigravity הדפיסה, ואז:

  1. לוחצים על כפתור של טעם, למשל מתוק וקרמי. הנציג מאשר שההעדפות שלכם נשמרו.
  2. מעלים תמונה של דוריאן או מקלידים תיאור קצר של הקליפה. הסוכן מזהה את הזן ומבקש מכם לבצע בדיקות חושיות.
  3. לוחצים על הצ'יפים של החושים שמתאימים לדוריאן שלכם. הסוכן עונה עם פסיקה אחת שכוללת את מידת הבשלות וההתאמה לטעם.

10. הסרת המשאבים

מוחקים את המשאבים שיצרתם כדי להפסיק לצבור חיובים.

מחיקת שירותי Cloud Run

כדי למחוק את הצ'אט בוט באתר:

gcloud run services delete durian-sommelier-web --region us-central1 --quiet

מוחקים את שירות הסוכן:

gcloud run services delete durian-advisor --region us-central1 --quiet

מחיקת חשבון השירות

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

gcloud iam service-accounts delete "durian-sommelier-web@$(gcloud config get-value project).iam.gserviceaccount.com" --quiet

מחיקת קובצי האימג' של הקונטיינרים

פריסות מקור ב-Cloud Run דוחפות את קובץ האימג' של הקונטיינר של כל שירות למאגר Artifact Registry בשם cloud-run-source-deploy, שפריסות אחרות בפרויקט יכולות לשתף. למחוק רק את שתי התמונות של ה-Codelab הזה ולשמור את המאגר.

כדי למחוק את התמונה של הסוכן:

gcloud artifacts packages delete durian-advisor --repository cloud-run-source-deploy --location us-central1 --quiet

כדי למחוק את התמונה של הצ'אט בוט באתר:

gcloud artifacts packages delete durian-sommelier-web --repository cloud-run-source-deploy --location us-central1 --quiet

🔍 בדיקת העבודה שלכם

gcloud run services list --region us-central1

הפלט אמור להיראות כך:

Listed 0 items.

מחיקת הקבצים המקומיים

מסירים את תיקיית הפרויקט, כולל המיומנויות והסביבה הווירטואלית שלה:

rm -rf ~/durian-advisor

אם רוצים, מסירים את Agents CLI:

uv tool uninstall google-agents-cli

מחיקת פרויקט הענן כולו (אופציונלי)

PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete "$PROJECT_ID" --quiet

11. מזל טוב

מעולה! יצרתם ובדקתם מערכת מרובת סוכנים מולטי-מודאלית של Durian Sommelier באמצעות ADK ו-Agents CLI. אם ביצעתם את השלבים האופציונליים, פרסתם אותו גם ב-Cloud Run באמצעות Antigravity CLI.

מה השגתם

  • יצרתם פרויקט ADK עם agents-cli create ובניתם סוכן ראייה ממוחשבת מולטי-מודאלי עם הגדרה אחת של MODEL
  • כלים מובְנים עם האדם שבתהליך לריח, לצליל ולמגע, וגם זיכרון של חוש הטעם שמאוחסן במצב ADK ברמת user:
  • פיצול הנציג לנציג מתאם אחד של durian_advisor ולשני נציגים מומחים של single_turn, שהנציג המתאם מפעיל כמו כלים
  • (אופציונלי) השתמשתם ב-Antigravity CLI עם המיומנויות של Agents CLI כדי לפרוס את הסוכן וצ'אט בוט באינטרנט ב-Cloud Run

השלבים הבאים