ساختن «متخصص چندحالتی دوریان» با ADK و Antigravity

۱. نمای کلی

انتخاب یک دوریان خوب در دکه کنار جاده یک معمای حسی است. خریداران باید بتوانند موسانگ کینگ (D197) واقعی را از نمونه‌های مشابه تشخیص دهند، قضاوت کنند که آیا میوه امروز صبح افتاده یا چند روز پیش، و حدس بزنند که آیا حتی از طعم آن لذت خواهند برد یا نه.

در این codelab، سیستم چندعاملی چندحالته Durian Sommelier را با Agent Development Kit (ADK) و Agents CLI می‌سازید و آزمایش می‌کنید، و به‌طور اختیاری آن را با Antigravity CLI در Cloud Run مستقر می‌کنید (مراحل اصلی حدود ۴۵ دقیقه طول می‌کشد؛ دو مرحله اختیاری Antigravity حدود ۲۰ دقیقه اضافه می‌کند). انتخاب خارگیل نشان می‌دهد که درک هوش مصنوعی کجا تمام می‌شود و حواس انسان کجا شروع می‌شود:

  • آنچه هوش مصنوعی می‌تواند ببیند: Gemini می‌تواند عکسی از پوسته را بررسی کند و نشانگرهای رقم را شناسایی کند، مانند ستاره پنج‌پر در پایه Musang King، نوک تیره و فرورفته Black Thorn (D200)، حلقه به‌اندازه سکه D24، یا ساقه خشک و چروکیده.
  • آنچه فقط انسان می‌تواند حس کند: مدل نمی‌تواند درز را بو کند تا بوی الکل را تشخیص دهد، به پوسته ضربه بزند تا صدای توخالی را بشنود، یا دو خار را فشار دهد تا ببیند آیا به حالت اول برمی‌گردند یا نه.
  • آنچه نماینده باید به‌خاطر داشته باشد: دو خارگیل کاملاً رسیده همچنان خریداران را به دو دسته تقسیم می‌کند. یک نفر طعم تلخ و الکلی XO D24 درخت کهنسال را دوست دارد، درحالی‌که دیگری کاستارد شیرین و بدون تلخی Red Prawn (D175) را می‌خواهد.

مرز حسی دوریان: بینایی هوش مصنوعی دربرابر حواس انسان

آنچه خواهید ساخت

  • مرحله ۱ - عامل بینایی واحد: یک عامل ADK، که با Agents CLI داربست‌بندی شده است، که نوع و تازگی خارمیوه را از روی عکس تشخیص می‌دهد.
  • مرحله ۲ - حواس انسانی و حافظه ذائقه: ابزارهایی که آنچه را خریدار بو می‌کند، می‌شنود، و احساس می‌کند امتیازدهی می‌کنند، به‌علاوه ابزاری که نمایه ذائقه آن‌ها را در جلسات مختلف ذخیره می‌کند.
  • مرحله ۳ - هماهنگ‌کننده و متخصصان: یک هماهنگ‌کننده durian_advisor که یک بازرس بینایی و یک سوملیه حسی را فرا می‌خواند، سپس یک حکم واضح ارائه می‌دهد.
  • مرحله ۴ - سرویس عامل Cloud Run: در یک مرحله اختیاری، Antigravity CLI عامل شما را با مهارت‌های Agents CLI مستقر می‌کند.
  • مرحله ۵ - روبات گپ وب 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:
  • نحوه تقسیم کردن یک عامل به یک هماهنگ‌کننده و عامل‌های متخصص تک‌نوبتی که آن را مثل ابزارها فراخوانی می‌کند
  • به‌طور اختیاری، نحوه ارائه مهارت‌های Agents CLI به Antigravity CLI تا بتواند عامل شما و روبات گپ وب را در Cloud Run مستقر کند

آنچه نیاز خواهید داشت

  • حساب Google (اگر اعتبار کارگاه را مطالبه می‌کنید، از حساب شخصی @gmail.com استفاده کنید)
  • پیوند اعتبار کارگاه از مربی (به‌علاوه دوربین تلفن برای اسکن کردن رمزینه پاسخ‌سریع) یا حساب Cloud Billing فعال
  • Google Chrome (توصیه می‌شود از پنجره «ناشناس» استفاده کنید تا حساب‌های شخصی و کاری باهم مخلوط نشوند)

۲. مطالبه کردن اعتبارهای Google Cloud (اختیاری)

اگر این codelab را به‌تنهایی تکمیل می‌کنید و واجدشرایط هستید، از برنمای اعتبارات 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 را باز کنید (یا نشانی وب را در پنجره «ناشناس» کپی کنید):
https://console.cloud.google.com/billing
  1. روی برگه حساب‌های صورت‌حساب شما کلیک کنید و صفحه را بازآوری کنید تا حسابی که حاوی اعتبار GDP است در ستون وضعیت، فعال نشان دهد.

صفحه مدیریت حساب «صورت‌حساب Google Cloud» که حساب صورت‌حساب «اعتبار GDP» فعال را نشان می‌دهد.

۳. ایجاد پروژه Google Cloud (اختیاری)

یک پروژه Google Cloud اختصاصی ایجاد کنید تا همه منابع این codelab را جدا نگه دارید تا بتوانید پس‌از اتمام کار، آن‌ها را به‌طور کامل حذف کنید.

برای ایجاد پروژه Google Cloud، این مراحل را دنبال کنید:

  1. ایجاد پروژه را باز کنید (یا نشانی وب را در پنجره «ناشناس» کپی کنید):
https://console.cloud.google.com/projectcreate
  1. جزئیات پروژه را وارد کنید:
    • نام پروژه: نامی توصیفی وارد کنید، مثلاً google-cloud-workshop.
    • حساب صورت‌حساب (اگر نشان داده شود): حساب اعتبار GDP (یا حساب صورت‌حساب فعال) خود را انتخاب کنید.
    • منبع اصلی: بدون سازمان را انتخاب‌شده باقی بگذارید (یا درصورت نیاز، سازمانتان را انتخاب کنید).
  2. شناسه پروژه تولیدشده را یادداشت کنید، سپس روی ایجاد کلیک کنید.

فرم «ایجاد پروژه Google Cloud» که نام پروژه، شناسه پروژه تولیدشده، منبع اصلی، و دکمه «ایجاد» را نشان می‌دهد.

🔍 بررسی کردن کارتان

پس‌از تکمیل ایجاد پروژه، اعلان‌ها را در نوارابزار کنسول Google Cloud باز کنید، و سپس روی انتخاب پروژه کلیک کنید.

منو اعلان‌های کنسول Google Cloud که «ایجاد پروژه» و پیوند «انتخاب پروژه» را نشان می‌دهد.

۴. راه‌اندازی محیط

در این بخش، Google Cloud Shell را راه‌اندازی می‌کنید، Agent Platform API را فعال می‌کنید، و Agents CLI را با uv نصب می‌کنید.

پیکربندی Cloud Shell

راه‌اندازی Cloud Shell

Google Cloud Shell را با فعال کردن نمای ویرایشگر کد و ترمینال باز کنید (یا نشانی وب را در پنجره «ناشناس» کپی کنید)، و درصورت درخواست، روی مجاز کردن کلیک کنید:

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

کادر گفتگوی «مجاز کردن Cloud Shell»

تنظیم شناسه پروژه Google Cloud

قطعه کد زیر را کپی کنید و در پایانه Cloud Shell جای‌گذاری کنید. منو شماره‌گذاری‌شده‌ای از پروژه‌های Google Cloud دردسترس شما نمایش داده می‌شود. شماره کنار پروژه‌تان را تایپ کنید (برای مثال، 1) و کلید ورود را فشار دهید:

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

۵. داربست‌بندی عامل بینایی چندحالته

از کوچک شروع کنید: از 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 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 می‌تواند در عکس تشخیص دهد:

راهنمای تصویری ارقام دورین که نشانگرهای پایه و خار «موسانگ کینگ»، «بلک تورن»، «رد پرون»، و «دی۲۴» را نشان می‌دهد

باز کردن 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 مطابقت دارد نگه دارید.

آزمایش کردن عامل در زمین بازی

شروع زمین بازی ADK:

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

باید خروجی مشابه زیر را ببینید:

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

در نوارابزار Cloud Shell، روی پیش‌نمایش وب کلیک کنید و پیش‌نمایش در درگاه ۸۰۸۰ را انتخاب کنید. اگر ADK Dev UI از شما خواست عاملی را انتخاب کنید، 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 را در پایانه فشار دهید تا زمین بازی متوقف شود.

‫۶. افزودن حواس انسانی و حافظه چشایی

دوربین نمی‌تواند بو کند، بشنود، یا احساس کند، بنابراین ابزارهایی خواهید ساخت که از خریدار می‌خواهد این کار را انجام دهد. همچنین به عامل حافظه بلندمدتی از سلیقه هر خریدار می‌دهید. در این مرحله ابزارها را می‌نویسید؛ در مرحله بعد آن‌ها را به عامل‌ها متصل می‌کنید.

افزودن کاتالوگ رقم

ایجاد کردن 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 هر تابع را به ابزاری تبدیل می‌کند که مدل می‌تواند آن را فراخوانی کند. رشته مستندسازی به شرح ابزار تبدیل می‌شود و بخش 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: کلید وضعیت را به‌جای جلسه فعلی به کاربر محدود می‌کند، بنابراین نمایه خریدار را در هر مکالمه جدید دنبال می‌کند.
  • به ابزار «دریافت» جداگانه‌ای نیاز ندارید. عوامل نمایه را مستقیماً با جای‌بان {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'}

‫۷. هماهنگ کردن عامل‌های متخصص

یک عامل واحد که قوانین بینایی، امتیازدهی حسی، و تطبیق ذائقه را در یک پیام‌واره مدیریت می‌کند، اغلب دچار سردرگمی می‌شود. درعوض، هر کار را به یک متخصص متمرکز می‌دهید و اجازه می‌دهید هماهنگ‌کننده پاسخ‌های آن‌ها را ترکیب کند:

  • 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 به هماهنگ‌کننده می‌دهد. دستورالعمل با آن نام‌ها به آن‌ها ارجاع می‌دهد.

آزمایش هماهنگ‌کننده در زمین بازی

زمین بازی را دوباره شروع کنید:

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

پیش‌نمایش وب را در درگاه 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 رسیده است (۹ از ۱۰)، اما تلخی زیاد آن با ذائقه شما سازگار نیست، بنابراین به‌جای آن میگوی قرمز (D175) یا خار سیاه (D200) بخواهید.
  • در برگه رویدادها، می‌توانید durian_advisor تماس با هر کارشناس، و sensory_sommelier_agent تماس با evaluate_human_sensory_clues و get_cultivar_profile را ببینید.
  • در جلسه جدید، عامل ازقبل ذائقه شما را می‌داند و بدون اینکه دوباره بپرسد، یک رقم شیرین و بدون تلخی را توصیه می‌کند.

برای متوقف کردن زمین بازی، Ctrl + C را در پایانه فشار دهید.

‫۸. مستقر کردن با 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 از آن خارج شوید.

🔍 بررسی کردن کارتان

بااستفاده از نشانی وبی که 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

‫۹. کدنویسی حسی روبات گپ وب (اختیاری)

عامل شما فعال اما خصوصی است. اکنون مکالمه Antigravity را ازسر می‌گیرید که ازقبل نماینده شما، کلیدهای وضعیت آن، و نشانی وب آن را می‌داند و از آن می‌خواهید یک روبات گپ وب برای خریداران دوریان بسازد و مستقر کند.

ازسرگیری 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 خارج شوید.

🔍 بررسی کردن کارتان

نشانی وب https://durian-sommelier-web-....run.app را که Antigravity چاپ کرده است باز کنید، سپس:

  1. روی دکمه‌ای از پالت، مثلاً دکمه شیرین و خامه‌ای، تک‌ضرب بزنید. عامل تأیید می‌کند که پالت شما را ذخیره کرده است.
  2. عکس خارمیوه بارگذاری کنید یا شرح کوتاهی از پوسته آن تایپ کنید. عامل رقم را شناسایی می‌کند و از شما می‌خواهد بررسی‌های حسی را انجام دهید.
  3. روی تراشه‌های حسی که با خارمیوه شما مطابقت دارد ضربه بزنید. عامل با یک حکم که شامل رسیدگی و تناسب با ذائقه است پاسخ می‌دهد.

‫۱۰. مرتب‌سازی

منابعی را که ایجاد کرده‌اید حذف کنید تا دیگر هزینه‌ای برایتان نداشته باشند.

حذف کردن سرویس‌های 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

حذف کل پروژه Google Cloud (اختیاری)

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

‫۱۱. تبریک می‌گوییم

تبریک! شما یک سیستم چندعاملی چندحالتی Durian Sommelier را با ADK و Agents CLI ساختید و آزمایش کردید. اگر مراحل اختیاری را انجام داده باشید، آن را با Antigravity CLI در Cloud Run نیز مستقر کرده‌اید.

آنچه انجام داده‌اید

  • یک پروژه ADK با agents-cli create ایجاد کرد و یک عامل دیداری چندحالته با یک تنظیم MODEL ساخت
  • ابزارهای مشارکت انسانی در حلقه برای بو، صدا، و لمس، به‌علاوه حافظه ذائقه ذخیره‌شده در وضعیت ADK با دامنه user: ساخته شد
  • عامل را به یک هماهنگ‌کننده durian_advisor و دو متخصص single_turn تقسیم کنید که آن را مانند ابزارها فراخوانی می‌کند
  • (اختیاری) از Antigravity CLI با مهارت‌های Agents CLI برای مستقر کردن عامل و روبات گپ وب در Cloud Run استفاده کردید

مراحل بعدی

  • اگر آن‌ها را رد کردید، به مراحل اختیاری Antigravity برگردید تا عامل و روبات گپ وب را در Cloud Run مستقر کنید
  • ماندگار کردن حافظه Palate با سرویس جلسه با پشتیبانی پایگاه داده
  • سنجش کیفیت پاسخ با agents-cli eval
  • کاوش اسناد Agent Development Kit (ADK)
  • درباره Agents CLI بیشتر بدانید
  • اسناد Cloud Run را کاوش کنید
  • برای شرکت در کارگاه‌ها و مسیرهای یادگیری، به برنامه GEAR (Gemini Enterprise Agent Ready) بپیوندید