با Gemini 3 و ADK، «مغازه‌دار چانه‌زن» خودتان را بسازید، با Gemini 3 و ADK، «مغازه‌دار چانه‌زن» خودتان را بسازید

۱. مرور کلی

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

با راجو ، مغازه‌دار جدید هوش مصنوعی خود آشنا شوید. او آثار دیجیتالی شگفت‌انگیزی می‌فروشد، اما برای خرید آنها باید با او چانه بزنید!

ما از Gemini 3 (مغز)، ADK (کیت توسعه عامل - بدنه) و Google Cloud Run (محل فروشگاه) برای زنده کردن Raju استفاده خواهیم کرد.

راجو مغازه دار

آنچه یاد خواهید گرفت

ما کل پشته را برای یک برنامه Agentic مدرن خواهیم ساخت:

معماری عامل راجو

  • فروشگاه (Cloud Run) : جایی که برنامه شما در اینترنت قرار دارد.
  • مغز (جوزا ۳) : هوشی که به راجو قدرت می‌دهد.
  • بدن (ADK) : چارچوبی که مغز را به ابزارها متصل می‌کند.
  • موجودی کالا (ابزارها) : کد پایتونی که راجو برای بررسی موجودی کالا استفاده می‌کند.
  • نمای فروشگاه (UI) : رابط کاربری که مشتریان شما می‌بینند.

شما یاد خواهید گرفت که چگونه:

  • «Dukaan دیجیتال» (محیط ابری گوگل) خود را راه‌اندازی کنید.
  • «استخدام» راجو (دریافت کلیدهای API جمینی ۳).
  • به راجو چانه زدن را یاد بده (دستورالعمل‌های سیستم و شخصیت‌ها).
  • به راجو موجودی بدهید (ابزارهای ADK).
  • یک ویترین فروشگاه (رابط کاربری فرانت‌اند) بسازید.
  • آماده برای کسب و کار (استقرار در Cloud Run).

آنچه شما نیاز دارید

  • یک پروژه ابری گوگل.
  • حس شوخ طبعی (برای چانه زنی).
  • دانش پایه پایتون.

۲. راه‌اندازی دوکان (پروژه ابری)

قبل از اینکه راجو را بسازیم، به یک مکان برای فروشگاه نیاز داریم. در فضای ابری، این به معنای یک پروژه با یک حساب صورتحساب است.

مرحله 1: فعال کردن صورتحساب

مرحله 1: فعال کردن صورتحساب

  1. لینک دریافت را در پنجره ناشناس (Incognito Window) باز کنید.
  2. با حساب کاربری جیمیل شخصی خود وارد شوید.
  3. برای دسترسی به اعتبار، روی دکمه کلیک کنید.
  4. ایمیل خود را تأیید کنید و شرایط را بپذیرید تا نسخه آزمایشی شما فعال شود.

مرحله ۲: ایجاد پروژه

مرحله ۲: ایجاد پروژه

  1. به صفحه ایجاد پروژه بروید.
  2. یک نام پروژه منحصر به فرد وارد کنید (مثلاً raju-shop-agent ).
  3. در منوی کشویی «حساب پرداخت»، حساب پرداخت آزمایشی خود را انتخاب کنید.
  4. روی CREATE کلیک کنید و منتظر بمانید تا پروژه آماده شود.

مرحله ۳: تأیید لینک پرداخت

  1. به صفحه حساب صورتحساب مرتبط بروید.
  2. اگر گزینه‌ای برای «پیوند یک حساب صورتحساب» می‌بینید، روی آن کلیک کنید.
  3. مطمئن شوید که حساب پرداخت آزمایشی (Trial Billing Account) انتخاب شده است.
  4. شما اکنون آماده ساخت هستید!

خلاصه

در این مرحله، شما پروژه گوگل کلود و حساب پرداخت خود را راه‌اندازی می‌کنید و پایه و اساس برنامه خود را ایجاد می‌کنید.

در مرحله بعد، فضای کاری را که قرار است کد را در آن بسازید، در بخش «آماده‌سازی محیط» (Preparation your Environment) تنظیم خواهیم کرد.

۳. ساخت غرفه (چیدمان محیط)

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

کلود شل در مقابل ترمینال محلی

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

۱. فعال کردن پوسته ابری

روی آیکون «فعال‌سازی پوسته ابری» (یک نماد ترمینال) در بالا سمت راست سربرگ کنسول ابری گوگل کلیک کنید.

فعال کردن پوسته ابری

اکنون Cloud Shell مقداردهی اولیه خواهد شد. این شامل موارد زیر است:

  • تأیید: در صورت درخواست، روی تأیید کلیک کنید تا به Cloud Shell اجازه دهید از طرف شما با APIهای Google Cloud تماس برقرار کند.
  • تأمین: Cloud Shell یک ماشین مجازی موقت برای جلسه شما فراهم می‌کند.
  • اتصال: سپس به این ماشین مجازی متصل می‌شود. کل این فرآیند ممکن است یک یا دو دقیقه طول بکشد.

صبر کنید تا خط فرمان ( user@cloudshell:~ $ ) را ببینید.

۲. تنظیمات پروژه را تأیید کنید

Cloud Shell معمولاً پروژه فعلی شما را به طور خودکار انتخاب می‌کند. فقط برای اطمینان، آن را تأیید کنید:

gcloud config get-value project

اگر شناسه پروژه شما ( raju-shop-agent ) را برنمی‌گرداند ، آن را به صورت دستی تنظیم کنید:

gcloud config set project raju-shop-agent

گزینه ۲: ترمینال محلی

اگر ترمینال لپ‌تاپ خودتان (iTerm، PowerShell و غیره) را ترجیح می‌دهید، باید تنظیمات بیشتری انجام دهید.

۱. پیش‌نیازها را نصب کنید

مطمئن شوید که موارد زیر را نصب کرده‌اید:

۲. وارد شوید و gcloud را پیکربندی کنید

رابط خط فرمان گوگل کلود (Google Cloud CLI) را راه‌اندازی کنید و وارد حساب کاربری خود شوید:

gcloud auth login

پروژه خود را تنظیم کنید (به جای raju-shop-agent ، شناسه پروژه واقعی خود را قرار دهید):

gcloud config set project raju-shop-agent

اعتبارنامه‌های پیش‌فرض برنامه را تنظیم کنید (این به ابزارهای محلی کمک می‌کند تا با Google Cloud ارتباط برقرار کنند):

gcloud auth application-default login

خلاصه

در این مرحله، محیط توسعه خود (Cloud Shell یا Local) را انتخاب و پیکربندی کردید.

در مرحله بعد، با ابزاری آشنا خواهیم شد که به ما کمک می‌کند تا در Meeting Gemini CLI سریع‌تر بسازیم.

۴. با دستیار خود آشنا شوید (Gemini CLI)

حالا، با بهترین دوست جدیدتان برای توسعه هوش مصنوعی آشنا شوید: Gemini CLI !

مقدمه رابط خط فرمان Gemini

Gemini CLI یک رابط خط فرمان قدرتمند است که به شما کمک می‌کند:

  • خودکارسازی گردش‌های کاری: پروژه‌های هوش مصنوعی خود را به طور کارآمد مدیریت کنید.
  • تولید کد: تولید کد، رابط کاربری و حتی کل فایل‌ها.
  • اکوسیستم افزونه‌ها: قابلیت‌های آن را با افزونه‌های مختلف (مانند افزونه Cloud Run که بعداً از آن استفاده خواهیم کرد) گسترش دهید.

۱. نصب رابط خط فرمان Gemini (فقط ترمینال محلی)

اگر از ترمینال لپ‌تاپ محلی خود استفاده می‌کنید:

npm install -g @google/gemini-cli

اگر از Google Cloud Shell استفاده می‌کنید:

رابط خط فرمان Gemini به صورت پیش‌فرض در Cloud Shell نصب شده است، بنابراین نیازی به نصب چیزی ندارید!

۲. راه‌اندازی و احراز هویت

یک پنجره ترمینال (یا تب) جدید در Cloud Shell (یا ترمینال محلی) خود باز کنید و Gemini CLI را اجرا کنید:

gemini

راه‌اندازی اولیه: اگر این اولین بار است که آن را اجرا می‌کنید، رابط خط فرمان (CLI) شما را در یک فرآیند راه‌اندازی سریع راهنمایی می‌کند.

  • احراز هویت: از شما خواسته می‌شود که وارد سیستم شوید. توصیه می‌کنیم از حساب کاربری شخصی Gmail خود استفاده کنید تا از سهمیه‌های رایگان سخاوتمندانه موجود برای مدل‌های Gemini بهره‌مند شوید.
  • متن پروژه: بهتر است gemini از داخل پوشه پروژه خود اجرا کنید تا متن کد شما را درک کند. (از آنجایی که هنوز پوشه را ایجاد نکرده‌ایم، اجرای آن از دایرکتوری خانگی شما فعلاً مشکلی ندارد).

۳. سلام کنید!

به محض اینکه اعلان gemini> را مشاهده کردید، یک آزمایش انجام دهید تا مطمئن شوید مغز شما متصل است:

Hi

شما باید یک پاسخ دوستانه از مدل دریافت کنید.

۴. دستورات ضروری

  • /quit : برای خروج از رابط خط فرمان Gemini و بازگشت به ترمینال استاندارد خود، این دستور را تایپ کنید.
  • /help : فهرستی از تمام دستورات موجود را مشاهده کنید.

خلاصه

در این مرحله، شما Gemini CLI را نصب، احراز هویت و تأیید کردید.

در مرحله بعد، ما از کیت توسعه عامل (ADK) برای ساخت اسکلت فروشگاه خود در Opening Shop (The Code) استفاده خواهیم کرد.

۵. پر کردن قفسه‌ها (تنظیمات پروژه)

ما از صفر نمی‌سازیم (فروشگاه‌داران باهوش در زمان صرفه‌جویی می‌کنند). ما از کیت توسعه عامل (ADK) استفاده خواهیم کرد.

ADK چیست؟

پر کردن قفسه‌ها

ADK "سیستم مدیریت فروشگاه" شماست. این یک چارچوب انعطاف‌پذیر است که موارد زیر را مدیریت می‌کند:

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

ما از بسته‌ی آغازین Agent برای راه‌اندازی فوری یک "Dukaan" آماده‌ی تولید استفاده خواهیم کرد. این بسته، پایه و اساسی امن و مقیاس‌پذیر در اختیار ما قرار می‌دهد تا بتوانیم روی فروش تمرکز کنیم.

در ترمینال Cloud Shell (یا ترمینال محلی) خود، این دستور را اجرا کنید تا عامل خود را تولید کنید:

uvx agent-starter-pack create raju-shop

رابط خط فرمان (CLI) برای پیکربندی فروشگاه شما چند سوال از شما می‌پرسد. گزینه‌های زیر را انتخاب کنید (عدد را تایپ کنید و Enter را بزنید):

  1. نوع عامل: 1 را انتخاب کنید ( adk_base - یک عامل پایه ReAct).
  2. هدف استقرار: 2 ( Cloud Run - اجرای کانتینر بدون سرور) را انتخاب کنید.
  3. نوع جلسه: 1 را انتخاب کنید ( In-memory session - ساده و سریع).
  4. CI/CD Runner: 3 را انتخاب کنید ( Skip - فعلاً به صورت دستی مستقر خواهیم کرد).

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

cd raju-shop
make install
source .venv/bin/activate

کاوش و پیکربندی عامل

حالا که بسته‌ی اولیه آماده شده، ساختار آن را بررسی کنید.

۱. ساختار پوشه را بررسی کنید

برای مشاهده‌ی نحوه‌ی سازماندهی فروشگاه خود، دستور زیر را اجرا کنید: 

tree .

شما باید ساختاری شبیه به این را ببینید: 

.
├── app
│   ├── __init__.py
│   ├── agent.py
│   ├── app_utils
│   │   ├── telemetry.py
│   │   └── typing.py
│   └── fast_api_app.py
├── Dockerfile
├── GEMINI.md
├── Makefile
├── pyproject.toml
├── README.md
├── tests
│   ├── integration
│   │   ├── test_agent.py
│   │   └── test_server_e2e.py
│   └── unit
│       └── test_dummy.py
└── uv.lock

مهم‌ترین فایل app/agent.py است. مغز راجو اینجاست!

۲. کد را بررسی کنید

app/agent.py در ویرایشگر Cloud Shell (یا IDE محلی) خود باز کنید و نگاهی سریع به آن بیندازید:

  • root_agent = Agent(...) : این هوش مصنوعی شما را تعریف می‌کند. این هوش مصنوعی دارای یک model (مغز) و tools (دست‌ها) است.
  • ابزارها : توابع پایتون مانند get_weather را خواهید دید. اینها ابزارهایی هستند که عامل می‌تواند از آنها استفاده کند.
  • app = App(...) : این عامل شما را در یک وب سرور قرار می‌دهد تا بتوانیم با آن ارتباط برقرار کنیم.

تست محلی

در ترمینال Cloud Shell (یا ترمینال محلی)، عامل را اجرا کنید: 

adk web

این دستور یک وب سرور محلی را روی پورت ۸۰۰۰ اجرا می‌کند.

اگر از Cloud Shell استفاده می‌کنید:

  1. روی دکمه پیش‌نمایش وب (بالا سمت راست، شبیه چشم) کلیک کنید.
  2. تغییر پورت را انتخاب کنید.
  3. 8000 را وارد کنید و روی تغییر و پیش‌نمایش کلیک کنید.

اگر از ترمینال محلی استفاده می‌کنید:

  1. مرورگر خود را باز کنید و به http://localhost:8000 مراجعه کنید.

پس از باز شدن رابط کاربری:

  1. "app" را انتخاب کنید : در منوی کشویی بالا سمت چپ، مطمئن شوید که عاملی به نام app را انتخاب می‌کنید (در صورت وجود root_agent یا test_agent آنها را نادیده بگیرید).
  2. سلام کنید : عبارت «سلام!» را تایپ کنید و ببینید آیا پاسخ می‌دهد یا خیر.

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

خلاصه

در این مرحله، شما پروژه خود را scaffold کردید، آن را برای Gemini API پیکربندی کردید و با موفقیت اولین agent خود را به صورت محلی اجرا کردید!

در مرحله بعد، در آموزش راجو (پرسونا) به مامور خود شخصیت و نام می‌دهیم.

۶. آموزش راجو (پرسونا)

الان، مامور کسل کننده است. ما به او شخصیت خواهیم داد!

بوت کردن شخصیت راجو

به جای نوشتن کد، ما فقط به Gemini خواهیم گفت که چه می‌خواهیم.

۱. پرسونا را تعریف کنید

این دستور را در ترمینال خود اجرا کنید تا به راجو «بفهمانید» که کیست: 

gemini "In agent.py, update the root_agent instruction. You are Raju, a bargaining shopkeeper in a digital bazaar. You sell: Brass Lamp (50 coins), Silk Scarf (500 coins). Your goal is to sell high and be funny. Speak with an Indian-English flair."

۲. کد را تأیید کنید

app/agent.py را باز کنید. باید ببینید که Gemini دستورالعمل سیستم را برای شما نوشته است!

۳. تست محلی

حالا، با راجو چت کنید! در ترمینال Cloud Shell (یا ترمینال محلی): 

adk web

رابط کاربری وب (پورت پیش‌نمایش وب ۸۰۰۰ یا localhost:۸۰۰۰) را باز کنید، عامل برنامه را انتخاب کنید و این دستورالعمل‌ها را امتحان کنید:

  • «من چراغ برنجی را می‌خواهم اما ۵۰ سکه خیلی زیاد است!»
  • «چی می‌فروشی، دوست من؟»

ببین چه واکنشی نشان می‌دهد! او باید بامزه و دراماتیک باشد، اما از ارزان فروختن خودداری کند.

خلاصه

در این مرحله، شما دستورالعمل‌های سیستم عامل را برای ایجاد «راجو»، یک مغازه‌دار چانه‌زن با شخصیتی منحصر به فرد، سفارشی‌سازی کردید.

در مرحله بعد، به راجو این امکان را می‌دهیم که موجودی واقعی خود را در فهرست موجودی (افزودن ابزارها) بررسی کند.

۷. فهرست موجودی (افزودن ابزارها)

راجو باید بداند که واقعاً چه چیزهایی در انبار دارد. ما به او یک «پایگاه داده» و ابزاری برای بررسی آن خواهیم داد.

راجو به سطح بالاتری ارتقا یافت

۱. ابزار را ایجاد کنید

این دستور واحد را اجرا کنید تا فهرست موجودی، ابزار و اتصال آن به راجو ایجاد شود: 

gemini "In agent.py, create a dictionary INVENTORY with items: Brass Lamp (price 50, stock 5), Silk Scarf (price 500, stock 2), Taj Mahal (price 2000, stock 0). Then create a tool function check_inventory(item_name) that checks this dict. Finally, update the root_agent to use this tool and remove the default weather tools."

۲. جادو را تأیید کنید

دوباره app/agent.py را باز کنید. خواهید دید که Gemini موارد زیر را دارد:

  1. فرهنگ لغت INVENTORY را ایجاد کرد.
  2. تابع پایتون check_inventory را نوشتم.
  3. لیست tools=[...] در تعریف عامل به‌روزرسانی شد.

۳. موجودی را آزمایش کنید

  1. سرور را مجدداً راه اندازی کنید (Ctrl+C، سپس adk web ).
  2. از راجو بپرس:
    • «تاج محل دارید؟» (او باید بگوید نه، موجودی صفر است).
    • «قیمت روسری ابریشمی چنده؟» (او باید قیمت واقعی را بررسی کند.)

خلاصه

در این مرحله، شما یک ابزار check_inventory پیاده‌سازی کردید، بی‌نظمی پیش‌فرض را حذف کردید و ابزار را به عامل خود متصل کردید.

در مرحله بعد، ما راجو را به صورت زنده در فضای ابری در بخش «فروشگاه راجو راه‌اندازی می‌شود (استقرار بک‌اند)» قرار خواهیم داد.

۸. فروشگاه راجو راه‌اندازی می‌شود (استقرار بخش پشتیبانی)

وقتشه که به روی دنیا باز بشیم! قبل از اینکه ویترین مغازه رو بسازیم، مغز و موجودی راجو (نماینده شما) رو به فضای ابری منتقل می‌کنیم.

راجو به اجرای زنده می‌رود

مهم: مدیریت ترمینال

ممکن است adk web از مرحله قبل در ترمینال فعلی شما در حال اجرا باشد.

  • اگر می‌خواهید آزمایش را به صورت محلی ادامه دهید ، آن را در حال اجرا نگه دارید .
  • برای مراحل استقرار بعدی ، یک پنجره/زبانه ترمینال جدید باز کنید .
  • توجه: هر زمان که agent.py تغییر می‌دهید، باید adk web متوقف (Ctrl+C) و مجدداً راه‌اندازی کنید تا تغییرات اعمال شوند!

۱. آماده‌سازی رابط خط فرمان Gemini

در پنجره ترمینال جدید خود:

  1. بررسی کنید که آیا از قبل داخل رابط خط فرمان Gemini هستید یا خیر (به دنبال اعلان gemini> بگردید).
  2. اگر چنین است، برای خروج از پوسته استاندارد /quit ‎ را تایپ کنید.
  3. مطمئن شوید که در پوشه پروژه هستید: 
    cd raju-shop

۲. افزونه Cloud Run را نصب کنید

افزونه Cloud Run را برای Gemini CLI در ترمینال Cloud Shell (یا ترمینال محلی) خود نصب کنید: 

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

۳. رابط خط فرمان Gemini را دوباره راه‌اندازی کنید

برای استفاده از افزونه جدید، دوباره Gemini CLI را اجرا کنید: 

gemini

شما باید خط فرمان Gemini CLI را ببینید.

۴. عامل را مستقر کنید

دو روش برای استفاده از افزونه‌های Gemini CLI وجود دارد:

گزینه ۱: دستور Slash (دستی) می‌توانید دستور و پرچم‌ها را به طور صریح تایپ کنید: 

/deploy --source . --name raju-agent --region us-central1 --allow-unauthenticated

گزینه ۲: زبان طبیعی (توصیه می‌شود) این روش آسان‌تر و قدرتمندتر است! می‌توانید از Gemini بخواهید این کار را برای شما انجام دهد و از سرور MCP برای فراخوانی ابزارهای مناسب استفاده می‌کند.

این خط فرمان را در رابط خط فرمان Gemini وارد کنید:

Deploy this agent app to cloud run on google cloud using the cloud-run MCP server.
Use project raju-shop-agent in us-central1 region.
Name the service raju-agent.
IMPORTANT: Make sure to allow unauthenticated invocations so my frontend can talk to it.

ممکن است رابط خط فرمان (CLI) برای استفاده از ابزار cloud-run از شما تأییدیه بخواهد. برای تأیید، Enter (یا y ) را فشار دهید.

منتظر جادو باشید: ۲-۳ دقیقه طول می‌کشد. پس از اتمام، پیام موفقیت‌آمیزی مانند این را خواهید دید: 

✦ I've successfully deployed your agent app to Cloud Run.

  Service Details:
   * Service Name: raju-agent
   * Project: raju-shop-agent
   * Region: us-central1
   * URL: https://raju-agent-xyz123-uc.a.run.app
   * Console: View in Google Cloud Console (...)

۵. تأیید استقرار

پس از اتمام استقرار، Gemini CLI یک Service URL ارائه می‌دهد. این URL را کپی کنید.

بررسی مرورگر (آیا زنده است؟) آدرس اینترنتی را در مرورگر خود وارد کنید.

  • موفقیت: شما باید مستندات FastAPI (Swagger UI) یا یک صفحه فرود عمومی ADK را ببینید. این تأیید می‌کند که سرویس Cloud Run شما در حال اجرا و قابل دسترسی است.
  • شکست: اگر با خطای ۴۰۳ Forbidden مواجه شدید، ممکن است فراموش کرده باشید که در اعلان استقرار، اجازه «فراخوانی‌های احراز هویت نشده» را بدهید.

ما منطق واقعی چانه‌زنی را در مرحله بعدی با ساخت یک رابط کاربری مناسب آزمایش خواهیم کرد!

خلاصه

در این مرحله، شما با استفاده از افزونه Gemini CLI، backend عامل خود را در Google Cloud Run مستقر کردید و آن را با استفاده از یک URL عمومی در دسترس قرار دادید.

در مرحله بعد، در بخش «ساخت نمای فروشگاه (رابط کاربری ظاهری)»، یک ویترین فروشگاه زیبا برای مشتریان خواهیم ساخت تا با راجو صحبت کنند.

۹. تزئین فروشگاه (رابط کاربری ظاهری)

ترمینال پیامکی کسل‌کننده است. ما یک ویترین پرجنب‌وجوش می‌خواهیم!

موکاپ رابط کاربری فروشگاه

نحوه عملکرد API ADK

برای ساخت یک رابط کاربری سفارشی، باید نحوه ارتباط با پشتیبان عامل خود را درک کنید. این کار از یک جریان دو مرحله‌ای پیروی می‌کند:

  1. مقداردهی اولیه جلسه: قبل از چت، باید یک شناسه جلسه (مانند سبد خرید) ایجاد کنید.
    • POST /apps/app/users/{user_id}/sessions/{session_id}
  2. ارسال پیام: برای صحبت کردن، متن خود را به نقطه پایانی اجرا ارسال می‌کنید.
    • POST /run (حجم داده شامل appName ، userId ، sessionId و text شما می‌شود).
  3. اطلاعات بیشتر: مستندات ADK Runtime API و Python API Reference را بررسی کنید.

ما از این منطق برای ساخت frontend خود استفاده خواهیم کرد.

شما دو راه برای ساخت این رابط کاربری دارید:

گزینه ۱: گوگل آنتی‌گراویتی (توصیه می‌شود - فقط محلی)

اگر روی دستگاه محلی خود کار می‌کنید، Google Antigravity بهترین تجربه است. این یک IDE بومی هوش مصنوعی است که به شما امکان می‌دهد کل رابط کاربری را "کدگذاری ارتعاشی" کنید.

۱. دانلود و نصب

فایل نصبی مربوط به سیستم عامل خود را از صفحه دانلود Google Antigravity دانلود و نصب کنید.

۲. فضای کاری خود را باز کنید

Antigravity را اجرا کنید. پوشه raju-shop خود را به عنوان یک فضای کاری باز کنید. این به هوش مصنوعی زمینه‌ای در مورد کل پروژه شما می‌دهد.

۳. رابط کاربری را با Agent Manager ایجاد کنید

به جای نوشتن خط به خط کد، از یک عامل هوش مصنوعی می‌خواهیم که این کار را با استفاده از Agent Manager برای ما انجام دهد.

  1. رابط چت Agent Manager (معمولاً در سمت راست) را پیدا کنید.
  2. عبارت زیر را در چت وارد کنید: 
Create a single file HTML chat interface named `index.html`. It should have a colorful header that says 'Raju's Royal Artifacts'. It should look like an Indian market stall with orange and pink colors.

**Backend Integration:**
The chat should send messages to my deployed agent at: <YOUR_DEPLOYED_AGENT_URL>

**API Logic:**
1. **On Load:** Generate a random userId and sessionId. Call `POST /apps/app/users/{userId}/sessions/{sessionId}` to initialize.
2. **On Send:** Call `POST /run` with a JSON payload containing `appName: "app"`, `userId`, `sessionId`, and `newMessage: { role: "user", parts: [{ text: userInput }] }`.
3. **Display:** Show the user's message and the agent's response (from `content.parts[0].text`).

(مطمئن شوید که آدرس URL جایگزین را با آدرس URL سرویس واقعی خود که از مرحله Deployment دریافت کرده‌اید، جایگزین کنید!)

  1. ببینید که چطور عامل کد را برای شما می‌نویسد! می‌توانید به نمای ویرایشگر بروید تا ببینید که فایل به صورت بلادرنگ ایجاد می‌شود.

۴. نمای فروشگاه خود را آزمایش کنید

گوگل آنتی‌گراویتی (Google Antigravity) قابلیت پیش‌نمایش داخلی دارد. برای دیدن ویترین فروشگاه خود، روی دکمه‌ی «پیش‌نمایش» (که اغلب به شکل یک آیکون چشم است) کلیک کنید! روش دیگر این است که آن را به صورت محلی با استفاده از python3 -m http.server 8000 ارائه دهید.

گزینه ۲: رابط خط فرمان Gemini (سازگار با پوسته ابری)

اگر در Cloud Shell هستید، می‌توانید از رابط خط فرمان (CLI) مورد اعتماد Gemini خود برای ساخت رابط کاربری (frontend) در عرض چند ثانیه استفاده کنید.

این دستور را در ترمینال خود اجرا کنید: 

gemini "Create a single file HTML chat interface named index.html. Header: 'Raju\'s Royal Artifacts', Indian market theme (orange/pink). Backend: <YOUR_DEPLOYED_AGENT_URL>. Logic: On load, generate random user/session IDs and POST to /apps/app/users/{uid}/sessions/{sid}. On chat, POST to /run with appName='app', userId, sessionId, and newMessage structure. Parse the JSON response to show the agent text." > index.html

(به یاد داشته باشید که جایگزین کنید

با آدرس اینترنتی واقعی Cloud Run شما!)

خلاصه

در این مرحله، شما از Google Antigravity برای "کدگذاری پویا" یک رابط کاربری HTML سفارشی که به رابط کاربری زنده شما متصل می‌شود، استفاده کردید.

در مرحله بعد، با میزبانی این ویترین فروشگاه در وب در Taking the Shopfront Live ، تصویر را کامل خواهیم کرد.

۱۰. افتتاحیه بزرگ (استقرار فرانت‌اند)

راجو آنلاین است (بک‌اند)، اما مغازه‌اش به یک آدرس عمومی (فرانت‌اند) نیاز دارد! از گوگل آنتی‌گراویتی بخواهید رابط کاربری ما را روی فضای ابری مستقر کند.

استقرار فرانت‌اند

۱. از مدیر عامل بخواهید که مستقر شود

لازم نیست IDE را ترک کنیم. فقط از مدیر عامل بخواهید که استقرار را برای شما انجام دهد.

این پیام را در چت پیست کنید:

« index.html من را به عنوان یک وب‌سایت استاتیک در Google Cloud Run مستقر کنید. نام سرویس را raju-shop-frontend بگذارید. مطمئن شوید که به صورت عمومی قابل دسترسی است.»

۲. جادو را تماشا کنید

احتمالاً نماینده:

  1. یک Dockerfile یا پیکربندی برای ارائه فایل‌های استاتیک (مانند استفاده از nginx یا python) ایجاد کنید.
  2. تصویر کانتینر را بسازید.
  3. دستور gcloud run deploy را برای خودتان اجرا کنید.

۳. از فروشگاه خود دیدن کنید!

پس از اتمام کار، یک URL به شما می‌دهد (مثلاً https://raju-shop-frontend-xyz.run.app ). روی آن کلیک کنید.

تبریک! شما اکنون یک اپلیکیشن چانه‌زنی مغازه‌داری کاملاً مستقر و مبتنی بر هوش مصنوعی دارید. لینک را برای دوستانتان ارسال کنید و ببینید آیا می‌توانند تخفیف بگیرند!

خلاصه

در این مرحله، شما از Antigravity Agent Manager برای کانتینرایز کردن و استقرار برنامه frontend خود در Cloud Run استفاده کردید.

حالا شما کل مجموعه را ساخته‌اید! در بخش نتیجه‌گیری، بحث را جمع‌بندی خواهیم کرد.

۱۱. زمان اختتامیه (نتیجه‌گیری)

ماموریت انجام شد

تبریک! شما با موفقیت چالش «مغازه‌دار چانه‌زنی» را به پایان رساندید! شما راجو را از یک ایده صرف به یک مغازه‌دار هوش مصنوعی کاملاً مستقر و تعاملی در بازار دیجیتال تبدیل کردید. شما قدرت توسعه عاملی را از نزدیک تجربه کرده‌اید.

خلاصه سفر شما:

  • گوگل کلود: پروژه و حساب صورتحساب خود را تنظیم کنید و نماینده خود را در کلود ران مستقر کنید.
  • جمینی ۳: مغز هوشمندی که شخصیت و مهارت‌های چانه‌زنی راجو را تقویت می‌کند.
  • کیت توسعه عامل (ADK): چارچوبی که پایه و اساس آماده برای تولید را با قابلیت مشاهده داخلی (Telemetry) فراهم می‌کند و عامل شما را از روز اول قوی می‌سازد.
  • Gemini CLI: دستیار خط فرمان شما برای انجام وظایف سریع، آزمایش و افزونه‌ها.
  • گوگل آنتی‌گراویتی: IDE نسل بعدی که در آن شما رابط کاربری خود را «ویب کد» می‌کردید و استقرار را هماهنگ می‌کردید.

مراحل بعدی برای دوکان دیجیتال شما:

  • رفع مشکل تست‌های خراب: شما کد را تغییر دادید، اما تست‌ها چطور؟ تست‌های پیش‌فرض ( tests/unit/test_agent.py ) هنوز به دنبال آب و هوا می‌گردند! از رابط خط فرمان Gemini برای به‌روزرسانی خودکار آنها استفاده کنید. این را امتحان کنید: gemini "Update the tests in tests/unit/test_agent.py to test the new check_inventory tool instead of weather."
  • موجودی پویا: کاری کنید که وقتی یک کالا "فروخته می‌شود" مقادیر موجودی راجو به‌روزرسانی شود. آیا می‌توانید منطقی اضافه کنید که stock در دیکشنری INVENTORY خود پس از یک "خرید" موفق کاهش دهد؟
  • ابزار درگاه پرداخت: یک ابزار شبیه‌سازی‌شده‌ی process_payment پیاده‌سازی کنید. راجو می‌تواند پس از انجام معامله، این ابزار را فراخوانی کند!
  • کاوش در Antigravity: عمیق‌تر به بخش مدیریت عامل و فضاهای کاری Antigravity بپردازید. آیا می‌توانید از عامل بخواهید که index.html شما را اصلاح کند تا یک رسید زنده نمایش داده شود؟
  • فروشگاه خود را به اشتراک بگذارید: فروشگاه راجو در اینترنت فعال است! آدرس اینترنتی (URL) فروشگاه را با دوستانتان به اشتراک بگذارید و ببینید آیا آنها می‌توانند خریدی بهتر از شما پیدا کنند!

منابع

۱۲. پاکسازی

برای جلوگیری از تحمیل هزینه‌های غیرضروری به حساب Google Cloud خود برای منابع مورد استفاده در این آزمایشگاه کد، این مراحل را دنبال کنید.

۱. غیرفعال کردن سرویس‌های ابری (صرفه‌جویی در هزینه اختیاری)

اگر می‌خواهید هرگونه هزینه احتمالی مربوط به سرویس‌های مستقر خود را متوقف کنید و در عین حال پروژه و سایر پیکربندی‌های خود را دست نخورده نگه دارید، می‌توانید سرویس‌های Cloud Run خود را غیرفعال کنید.

ترمینال Cloud Shell (یا ترمینال محلی) خود را باز کنید و دستورات gcloud زیر را اجرا کنید: 

# Undeploy the backend agent

gcloud run services delete raju-agent --region us-central1

# Undeploy the frontend shop (if you deployed it)

gcloud run services delete raju-shop-frontend --region us-central1

۲. حذف پروژه گوگل کلود (توقف کامل هزینه‌ها)

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

  1. به صفحه پروژه‌ها در کنسول گوگل کلود بروید.
  2. پروژه خود ( raju-shop-agent ) را انتخاب کرده و روی حذف کلیک کنید.
  3. برای تأیید حذف پروژه، دستورالعمل‌ها را دنبال کنید.