إنشاء تطبيق متعدّد الوسائط لاختيار فاكهة الدوريان باستخدام ADK وAntigravity

1. نظرة عامة

إنّ اختيار ثمرة دوريان جيدة من كشك على جانب الطريق هو لغز حسي. على المشترين التمييز بين فاكهة موسانغ كينغ (D197) الأصلية والشبيهة بها، وتحديد ما إذا كانت الثمرة قد سقطت هذا الصباح أو قبل أيام، وتخمين ما إذا كانوا سيستمتعون بمذاقها.

في هذا الدرس التطبيقي حول الترميز، ستنشئ وتختبر نظامًا متعدد الوكلاء ومتعدد الوسائط باسم Durian Sommelier باستخدام حزمة تطوير الوكلاء (ADK) وAgents CLI، ويمكنك اختياريًا نشره على Cloud Run باستخدام Antigravity CLI (تستغرق الخطوات الأساسية حوالي 45 دقيقة، وتضيف خطوتَي Antigravity الاختياريتَين حوالي 20 دقيقة). يُظهر اختيار فاكهة دوريان أين ينتهي إدراك الذكاء الاصطناعي وتبدأ الحواس البشرية:

  • ما يمكن للذكاء الاصطناعي رؤيته: يمكن لـ Gemini فحص صورة القشرة ورصد علامات الأصناف، مثل النجمة الخماسية في قاعدة ثمرة "موسانغ كينغ"، أو الطرف الداكن الغائر لثمرة "بلاك ثورن" (D200)، أو الحلقة التي بحجم العملة المعدنية لثمرة "D24"، أو الساق الجافة والذابلة.
  • ما يمكن للإنسان فقط استشعاره: لا يمكن للنموذج شمّ رائحة الثمرة من الأسفل بحثًا عن رائحة كحولية، أو النقر على القشرة لسماع صوت أجوف، أو الضغط على شوكتَين لمعرفة ما إذا كانتا ترتدّان.
  • ما يجب أن يتذكّره الوكيل: لا يزال المشترون منقسمين حول ثمرتَي دوريان ناضجتَين تمامًا. فقد يفضّل شخص ما المذاق المرّ واللاذع لفاكهة XO D24 من شجرة قديمة، بينما يفضّل شخص آخر المذاق الحلو والخالي من المرارة لفاكهة Red Prawn (D175).

الحدود الحسية لفاكهة الدوريان: رؤية الذكاء الاصطناعي مقابل الحواس البشرية

ما ستنشئه

  • المرحلة 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 التجريبية في Cloud Shell.

المتطلبات الأساسية

  • إتقان أساسي للبرمجة بلغة Python
  • الإلمام بأدوات سطر الأوامر ومفاهيم الذكاء الاصطناعي التوليدي
  • لا يُشترط توفّر خبرة سابقة في ADK أو Agents CLI أو Antigravity CLI

أهداف الدورة التعليمية

  • كيفية إنشاء مشروع ADK باستخدام agents-cli create وإنشاء وكيل متعدّد الوسائط يقرأ الصور
  • حدود إدراك الذكاء الاصطناعي (الرائحة والصوت واللمس والذوق الشخصي) وكيفية تصميم أدوات تعتمد على المشاركة البشرية لهذه الحواس
  • كيفية تذكُّر الإعدادات المفضّلة لكل مستخدم في جميع الجلسات باستخدام حالة ADK على مستوى user:
  • كيفية تقسيم وكيل واحد إلى وكيل منسّق ووكلاء متخصصين في الردود الفردية يستدعيهم كأدوات
  • اختياريًا، كيفية منح Antigravity CLI مهارات Agents CLI ليتمكّن من نشر وكيلك وروبوت دردشة على الويب في Cloud Run

المتطلبات

  • حساب Google (يُرجى استخدام حساب @gmail.com شخصي في حال المطالبة برصيد ورشة العمل)
  • رابط رصيد ورشة العمل من المدرّب (بالإضافة إلى كاميرا الهاتف لمسح رمز الاستجابة السريعة ضوئيًا) أو حساب فوترة نشط على Cloud
  • Google Chrome (يُنصح باستخدام نافذة التصفّح المتخفي لتجنُّب الخلط بين الحسابات الشخصية وحسابات العمل)

2. طلب الحصول على أرصدة Google Cloud (اختياري)

إذا كنت تكمل هذا الدرس التطبيقي حول الترميز بنفسك وكنت مؤهلاً، استخدِم بانر أرصدة Google Developer Program في هذه الصفحة للحصول على أرصدة بدون بطاقة ائتمان. إذا كنت تحضر ورشة عمل باستخدام رابط رصيد فعالية من المدرّب، اتّبِع خطوات رصيد الفعالية في هذا القسم.

الحصول على رصيد الفعالية

يمكنك الحصول على أرصدة ورش العمل من خلال Google Builders Hub (جزء من Google Developer Program).

للمطالبة برصيد الفعالية، يُرجى اتّباع الخطوات التالية:

  1. افتح رابط رصيد ورشة العمل في نافذة تصفّح متخفٍ وسجِّل الدخول باستخدام حسابك الشخصي على @gmail.com.
  2. في بطاقة طلب الحصول على المزايا، انقر على طلب الحصول على الرصيد.

بطاقة "المطالبة بالمزايا" في Google Builders Hub مع زر "المطالبة بالرصيد"

  1. اختياري: إذا ظهر لك طلب لإنشاء ملف شخصي في Google Developer Program، أكمِل النموذج.
  2. عند ظهور مربّع الحوار المسح الضوئي لإثبات أنّك مستخدم، امسح رمز الاستجابة السريعة ضوئيًا باستخدام هاتفك وأكمِل عملية التحقّق. إذا لم يظهر رمز الاستجابة السريعة، أعِد تحميل الصفحة وانقر على المطالبة بالرصيد مرة أخرى.
  3. تأكَّد من ظهور الرسالة تمت المطالبة برصيد الحدث بنجاح، ثم انقر على فتح حساب الفوترة.

بطاقة تأكيد في Google Builders Hub تعرض رسالة "تمت المطالبة برصيد الفعالية بنجاح" وزر "فتح حساب الفوترة".

🔍 التحقّق من عملك

قد تستغرق عملية توفير حساب الفوترة مدة تصل إلى خمس دقائق. للتأكّد من أنّ رصيدك نشط، أكمِل الخطوات التالية:

  1. إذا لم تكن صفحة إدارة حساب الفوترة مفتوحة، افتح Google Cloud Billing (أو انسخ عنوان URL في نافذة التصفّح المتخفي):
https://console.cloud.google.com/billing
  1. انقر على علامة التبويب حسابات الفوترة وأعِد تحميل الصفحة إلى أن يظهر حساب يحتوي على رصيد GDP على أنّه نشط في عمود الحالة.

صفحة إدارة حساب الفوترة في Google Cloud تعرض حساب فوترة نشطًا لرصيد GDP

3- إنشاء مشروع على Google Cloud (اختياري)

أنشئ مشروعًا مخصّصًا على Google Cloud للاحتفاظ بجميع الموارد من هذا الدرس التطبيقي حول الترميز بشكل منفصل لتتمكّن من إزالتها نهائيًا عند الانتهاء.

لإنشاء مشروع على Google Cloud، اتّبِع الخطوات التالية:

  1. افتح إنشاء مشروع (أو انسخ عنوان URL في نافذة التصفّح المتخفي):
https://console.cloud.google.com/projectcreate
  1. أدخِل تفاصيل مشروعك:
    • اسم المشروع: أدخِل اسمًا وصفيًا، مثل google-cloud-workshop.
    • حساب الفوترة (إذا ظهر): اختَر حساب رصيد GDP (أو حساب الفوترة النشط).
    • المورد الرئيسي: اترك الخيار بدون مؤسسة محدّدًا (أو اختَر مؤسستك إذا لزم الأمر).
  2. دوِّن رقم تعريف المشروع الذي تم إنشاؤه، ثم انقر على إنشاء.

نموذج "إنشاء مشروع على Google Cloud" يعرض اسم المشروع ورقم تعريف المشروع الذي تم إنشاؤه والمورد الرئيسي وزر "إنشاء".

🔍 التحقّق من عملك

بعد الانتهاء من إنشاء المشروع، افتح الإشعارات في شريط أدوات وحدة تحكّم Google Cloud، ثم انقر على اختيار مشروع.

قائمة "الإشعارات" في Google Cloud Console التي تعرض رابطَي "إنشاء مشروع" و"اختيار مشروع"

4. إعداد البيئة

في هذا القسم، يمكنك إعداد Google Cloud Shell وتفعيل Agent Platform API وتثبيت Agents CLI باستخدام uv.

ضبط إعدادات Cloud Shell

تشغيل Cloud Shell

افتح Google Cloud Shell مع تفعيل كلّ من أداة تعديل الرموز وعرض Terminal (أو انسخ عنوان URL إلى نافذة التصفّح المتخفي)، وانقر على تفويض إذا طُلب منك ذلك:

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

مربّع حوار تفويض 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 Terminal:

وحدة 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 نموذج Python ADK، ويُعدّه --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". يؤدي هذا الإجراء إلى إعادة تحميل النافذة وإعادة تشغيل الوحدة الطرفية:

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.

إذا ظهرت رسالة your-gcp-project-id في GOOGLE_CLOUD_PROJECT، يعني ذلك أنّ Agents CLI لم يتمكّن من رصد مشروعك. يمكنك ضبطه باستخدام:

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

كتابة مصنِّف الرؤية

يحتوي كل صنف على علامات في القشرة يمكن لـ Gemini رصدها في الصورة:

دليل مرئي لأصناف الدوريان يعرض علامات القاعدة والأشواك لأصناف "موسانغ كينغ" و"بلاك ثورن" و"ريد برون" و"دي 24"

افتح 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(...) الوكيل لكل من بيئة الاختبار وخادم Cloud Run. احتفِظ باسم التطبيق app واسم الوكيل durian_advisor، اللذين يتطابقان مع الخادم الذي تم إنشاؤه وagents-cli-manifest.yaml.

اختبار الوكيل في Playground

بدء استخدام ADK Playground:

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

من المفترض أن تظهر لك نتيجة مشابهة لما يلي:

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

انقر على معاينة الويب في شريط أدوات Cloud Shell واختَر معاينة على المنفذ 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: نطاق مفتاح الحالة للمستخدم بدلاً من الجلسة الحالية، وبالتالي يرافق الملف الشخصي المشتري في كل محادثة جديدة.
  • ولست بحاجة إلى أداة "get" منفصلة. يقرأ الوكلاء الملف الشخصي مباشرةً في تعليماتهم باستخدام العنصر النائب {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 مع المشتري، ويحفظ ذوقه، ويتصل بكل خبير، ويكتب الحكم النهائي.

إنشاء أداة فحص الرؤية

إنشاء 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

استبدِل محتواه بالمنسّق:

"""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. وتشير التعليمات إليهما بهذين الاسمين.

اختبار المنسّق في Playground

ابدأ تشغيل البيئة التجريبية مرة أخرى:

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

افتح معاينة الويب على المنفذ 8080 وأجرِ هذه المحادثة القصيرة مع الوكيل.

علِّم Gemini ذوقك:

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)، وهو وكيل الترميز المستند إلى الذكاء الاصطناعي من Google للواجهة الطرفية، بنشره. تعلّم مهارات Agents CLI أداة Antigravity كيفية نشر وكيل ADK بشكل صحيح.

تفعيل واجهات برمجة التطبيقات الخاصة بالنشر

فعِّل واجهات برمجة التطبيقات 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، ويرسل رسالة اختبار إلى الخدمة المباشرة. تستغرق عملية التشغيل بأكملها من خمس إلى ثماني دقائق تقريبًا.

عند انتهاء Antigravity، يمكنك الخروج منه بالضغط على 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. إنشاء روبوت دردشة على الويب بأسلوب "البرمجة الوصفية" (اختياري)

وكيلك متاح الآن ولكنّه خاص. الآن، ستستأنف محادثة 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 Invoker في durian-advisor وتنشر التطبيق باستخدام Cloud Build. ويختبر عادةً نقطة نهاية المحادثة قبل انتهائها. يستغرق التشغيل بأكمله حوالي عشر دقائق. عند طباعة عنوان URL، اخرج بالضغط على 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، والذي يمكن لعمليات النشر الأخرى في مشروعك مشاركته. احذف صورتَي هذا الدرس التطبيقي حول الترميز فقط واحتفِظ بالمستودع.

حذف صورة الوكيل:

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

يمكنك إلغاء تثبيت واجهة سطر الأوامر (CLI) للوكلاء:

uv tool uninstall google-agents-cli

حذف مشروع Google Cloud بالكامل (اختياري)

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

الخطوات التالية