👗 Flutter, ADK Go, और Gemini की मदद से वर्चुअल फ़िटिंग रूम और एआई स्टाइलिस्ट बनाना

1. परिचय

आपको क्या बनाना है

इस कोडलैब में, आपको डेवलपर की भूमिका निभानी होगी. डेवलपर को Fashion App बनाना है. यह एक काल्पनिक खुदरा ब्रैंड के लिए, Flutter का शॉपिंग ऐप्लिकेशन है. आपका मिशन: एआई की मदद से काम करने वाली दो ऐसी सुविधाएं जोड़ें जिनसे ऑनलाइन शॉपिंग का अनुभव बेहतर हो.

1. वर्चुअल फ़िटिंग रूम — इसमें कोई व्यक्ति अपनी फ़ोटो अपलोड करता है. इसके बाद, वह कपड़ों का कोई आइटम चुनता है. फिर, उसे एआई से जनरेट की गई ऐसी इमेज दिखती है जिसमें उसने वह आइटम पहना हुआ है.
2. एआई स्टाइलिस्ट — एआई एजेंट, उपयोगकर्ता की जगह, अवसर, और स्टाइल की प्राथमिकताओं के आधार पर, पूरे कपड़ों के सुझाव देता है. उपयोगकर्ता, बातचीत के ज़रिए इन सुझावों को बेहतर बना सकता है.

इसका आइडिया आसान है: जब लोग फ़िटिंग रूम में कपड़े पहनकर देखते हैं, तो उनके खरीदने की संभावना काफ़ी बढ़ जाती है. लेकिन ऑनलाइन? आपने सिर्फ़ अंदाज़ा लगाया है. यह प्रोजेक्ट, एआई की मदद से इस अंतर को कम करता है.

आर्किटेक्चर के बारे में खास जानकारी

Flutter App  ──── HTTP/REST ────▶  ADK Go Backend
                                       │
                            ┌──────────┼──────────┐
                       Fitting Room  Stylist    Catalog
                         Agent       Agent      Agent
                                       │
                            Gemini API + Cloud Storage

मुख्य टेक्नोलॉजी

कॉम्पोनेंट	टेक्नोलॉजी	मकसद
एजेंट फ़्रेमवर्क	Go के लिए ADK (Agent Development Kit)	मल्टी-एजेंट ऑर्केस्ट्रेशन, सेशन, आर्टफ़ैक्ट
एजेंट के जवाब में तर्क शामिल करना (Pro)	Gemini 3.1 Pro की झलक	यह कुकी, फ़िटिंग रूम और स्टाइलिस्ट एजेंट को मैनेज करती है
एजेंट की तर्क क्षमता (फ़्लैश)	Gemini 3 Flash की झलक	यह रूट और कैटलॉग एजेंट को चालू करता है (लाइटवेट राउटिंग/लुकअप)
इमेज जनरेट करने की सुविधा	Gemini 2.5 Flash की इमेज	इस सुविधा की मदद से, कपड़े आज़माने और कपड़ों के कॉम्बिनेशन वाली इमेज जनरेट की जाती हैं
फ़्रंटएंड	Flutter (Dart)	क्रॉस-प्लैटफ़ॉर्म ऐप्लिकेशन (वेब, iOS, Android)
डिवाइस का स्टोरेज	Google Cloud Storage	यह कुकी, प्रॉडक्ट की इमेज और जनरेट किए गए आर्टफ़ैक्ट सेव करती है
होस्टिंग	Cloud Run	सर्वरलेस कंटेनर डिप्लॉयमेंट

2. 📦 ज़रूरी शर्तें और Cloud Shell का सेटअप

1. Cloud Shell Editor खोलें

👉 अपने ब्राउज़र में Cloud Shell Editor खोलें.

अगर टर्मिनल, स्क्रीन पर सबसे नीचे नहीं दिखता है, तो:

• व्यू → टर्मिनल पर क्लिक करें

Cloud Shell में Go, Git, और gcloud CLI पहले से इंस्टॉल होते हैं. इसलिए, आपको इन्हें स्थानीय तौर पर सेट अप करने की ज़रूरत नहीं होती.

2. Flutter SDK टूल सेट अप करना

Cloud Shell में, Flutter पहले से इंस्टॉल होता है. यह /google/flutter पर मौजूद होता है. उस डायरेक्ट्री का मालिकाना हक किसी दूसरे सिस्टम उपयोगकर्ता के पास है. इसलिए, पहली बार flutter चलाने पर आपको fatal: detected dubious ownership गड़बड़ी दिखेगी. इसे git की safe-directory सूची में एक बार जोड़ें:

git config --global --add safe.directory /google/flutter

पुष्टि करें कि Flutter आपके PATH पर मौजूद है और काम कर रहा है:

flutter --version

पहली बार चलाने पर, Dart SDK डाउनलोड होता है और Flutter टूल बनता है. इसमें एक मिनट लगता है. आपको Flutter 3.x • channel stable जैसा कुछ दिखेगा.

बंडल किए गए Flutter को प्राथमिकता दें. अगर आपको अपने स्टेबल क्लोन (उदाहरण के लिए, किसी खास Flutter वर्शन के लिए) पर पिन करना है, तो यह कमांड चलाएं:

cd ~
git clone https://github.com/flutter/flutter.git -b stable --depth 1
echo 'export PATH="$HOME/flutter/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

ध्यान दें कि $HOME/flutter/bin, $PATH से /google/flutter से पहले आता है. इसलिए, आपका क्लोन /google/flutter से जीत जाता है.

3. रिपॉज़िटरी का क्लोन बनाना

cd ~
git clone https://github.com/gca-americas/fashion-app-demo
cd fashion_app_demo

4. प्रोजेक्ट स्ट्रक्चर एक्सप्लोर करना

fashion_app_demo/
├── adk_backend/                 # Go backend with ADK agents
│   ├── main.go                  # Entry point — wires all agents + REST server
│   ├── catalog/                 # Catalog Agent — product lookup
│   │   ├── agent.go
│   │   ├── catalog.yaml         # Product database (YAML)
│   │   └── instructions.md      # Agent persona prompt
│   ├── fittingroom/             # Fitting Room Agent — virtual try-on
│   │   ├── agent.go
│   │   ├── instructions.md      # Agent persona prompt
│   │   └── tool_instructions.md # Image generation prompt
│   ├── stylist/                 # Stylist Agent — outfit curation
│   │   ├── agent.go
│   │   └── instructions.md      # Agent persona + output format
│   ├── rootagent/               # Root Agent — routes to the right agent
│   │   └── agent.go
│   └── tools/                   # Shared tools
│       ├── imagetool.go         # getProductImage — loads product images
│       ├── outfit_gen_tool.go   # generate_outfit_image — creates outfit images
│       └── cors_helper.go      # CORS middleware + request logging
│
├── flutter_frontend/            # Flutter cross-platform app
│   ├── lib/
│   │   ├── main.dart            # App entry point + Provider setup
│   │   ├── app_config.dart      # Backend URL configuration
│   │   ├── core_app/            # Pre-built shopping app (browse, cart, etc.)
│   │   └── workshop_tasks/      # AI feature code
│   │       ├── step_1_try_it_on/  # Virtual Try-On flow
│   │       │   ├── providers/     # TryItOnProvider (state management)
│   │       │   ├── services/      # AdkFittingRoomService (HTTP calls)
│   │       │   └── ui/            # Screens (product detail → try on → fitting room)
│   │       └── step_2_style_me/   # Style Me flow
│   │           ├── models/        # Outfit, StyleRequest data classes
│   │           ├── providers/     # StylingProvider (state management)
│   │           ├── services/      # AdkStylingService (HTTP calls)
│   │           └── ui/            # Screens (form sheet → outfit carousel)
│   └── assets/images/           # Product catalog images

मुख्य डायरेक्ट्री:

• adk_backend/ — यहां एआई एजेंट मौजूद होते हैं. हर एजेंट का अपना पैकेज होता है. इसमें Go कोड और मार्कडाउन निर्देश होते हैं.
• flutter_frontend/lib/workshop_tasks/ — यहां Flutter यूज़र इंटरफ़ेस (यूआई), उन एजेंट से कनेक्ट होता है.
• flutter_frontend/lib/core_app/ — यह पहले से बना हुआ शॉपिंग ऐप्लिकेशन है. आपको इसमें बदलाव करने की ज़रूरत नहीं है.

3. ☁️ Google Cloud प्रोजेक्ट का सेटअप

1. नया प्रोजेक्ट बनाना

gcloud projects create fashion-app-demo --name="Fashion App Demo"
gcloud config set project fashion-app-demo

अगर प्रोजेक्ट आईडी पहले से मौजूद है, तो उसके आगे कोई भी नंबर जोड़ें. उदाहरण के लिए, fashion-app-demo-42.

2. बिलिंग खाता लिंक करना

इस कोडलैब में यह माना गया है कि आपके पास पहले से ही एक चालू बिलिंग खाता है. Vertex AI, Cloud Build, और Cloud Run, इन सभी के लिए बिलिंग की ज़रूरत होती है. इसके बिना, aiplatform.googleapis.com और cloudbuild.googleapis.com के लिए अगला चरण (gcloud services enable) पूरा नहीं होगा. साथ ही, जिन एपीआई को चालू किया गया है वे भी वर्कलोड नहीं चलाएंगे.

अपने बिलिंग खातों की सूची बनाएं:

gcloud billing accounts list

OPEN

कॉलम में मौजूद है. इसमें True लिखा होना चाहिए. अगर आपको False दिखता है (यह समस्या, बिना शुल्क आज़माने की अवधि खत्म होने पर आम तौर पर दिखती है), तो इसका मतलब है कि खाता बंद हो गया है और आपसे किसी भी चीज़ के लिए शुल्क नहीं लिया जाएगा. आगे बढ़ने से पहले, नीचे दिए गए समस्या हल करने से जुड़े ब्लॉक पर जाएं.

ACCOUNT_ID खाते का ACCOUNT_ID (0X0X0X-0X0X0X-0X0X0X जैसा दिखता है) कॉपी करें और उसे अपने प्रोजेक्ट से लिंक करें:OPEN: True

gcloud billing projects link fashion-app-demo \
 --billing-account=YOUR_BILLING_ACCOUNT_ID

लिंक की पुष्टि करें:

gcloud billing projects describe fashion-app-demo

आपको billingEnabled: true दिखेगा. अगर खाता लिंक करने के बाद भी आपको billingEnabled: false दिखता है, तो इसका मतलब है कि खाता बंद है (OPEN: False). इस समस्या को हल करने के लिए, यहां दिया गया तरीका देखें.

क्या आपके पास बिलिंग खाता नहीं है? console.cloud.google.com/billing पर जाकर, एक बिलिंग खाता बनाएं. Google Cloud के नए उपयोगकर्ताओं को 300 डॉलर का क्रेडिट मुफ़्त में मिलता है. यह इस कोडलैब के लिए काफ़ी है. यहां Gemini API कॉल और Cloud Run के इस्तेमाल पर सिर्फ़ कुछ सेंट का शुल्क लगता है. पुष्टि के लिए, आपके पास क्रेडिट कार्ड होना ज़रूरी है. हालांकि, बिना शुल्क वाली सेवा के तहत तय सीमा से ज़्यादा इस्तेमाल करने और पैसे चुकाकर खाता इस्तेमाल करने का विकल्प चुनने पर ही आपसे शुल्क लिया जाएगा.

समस्या हल करना: OPEN: False / billingEnabled: false / UREQ_PROJECT_BILLING_NOT_OPEN.

अगर आपने gcloud services enable ... चलाया है और आपको इस तरह की गड़बड़ी का मैसेज मिला है:

ERROR: (gcloud.services.enable) FAILED_PRECONDITION: Billing account for
project '...' is not open. Billing must be enabled for activation of
service(s) '...' to proceed.
...
reason: UREQ_PROJECT_BILLING_NOT_OPEN

इसका मतलब है कि बिलिंग खाते में पेमेंट का कोई तरीका जोड़ना ज़रूरी है. मुफ़्त में आज़माने की सुविधा वाला आपका खाता बंद कर दिया गया है. ऐसा इसलिए हुआ है, क्योंकि आज़माने की अवधि खत्म हो गई है, क्रेडिट का इस्तेमाल हो गया है या फ़ाइल में कोई कार्ड नहीं है. इसलिए, भले ही प्रोजेक्ट इससे "लिंक" हो, लेकिन कोई भी सेवा चालू नहीं की जा सकती. इसे इस तरह ठीक करें:

1. अपने ब्राउज़र में console.cloud.google.com/billing खोलें.
2. ट्रायल खाते (OPEN: False वाले खाते) पर क्लिक करें.
3. अपग्रेड करें, फिर से चालू करें या पेमेंट का तरीका जोड़ें पर क्लिक करें. बटन का नाम, बिना किसी शुल्क आज़माने की सुविधा की स्थिति के हिसाब से अलग-अलग हो सकता है. क्रेडिट/डेबिट कार्ड जोड़ें.
4. इसके अलावा, नए कार्ड से नया पैसे चुकाकर लिया जाने वाला खाता सेट अप करने के लिए, बिलिंग पेज पर सबसे ऊपर मौजूद खाता बनाएं पर क्लिक करें.
5. Cloud Shell में जाकर, समस्या ठीक होने की पुष्टि करें:

   gcloud billing accounts list --filter="open:true"
   

   अब इससे कम से कम एक खाता दिखना चाहिए. link कमांड को उस ACCOUNT_ID के साथ फिर से चलाएं. इसके बाद, अगले चरण में enable कमांड को फिर से आज़माएं.

कोडलैब का इस्तेमाल करने पर, सिर्फ़ कुछ पैसे खर्च होते हैं. कार्ड जोड़ने पर, एपीआई अनलॉक हो जाते हैं. इसके लिए, आपको कोई शुल्क नहीं देना पड़ता.

3. ज़रूरी एपीआई चालू करना

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

एपीआई	मकसद
aiplatform.googleapis.com	Vertex AI — fitting_tool, Vertex AI के ज़रिए Gemini की इमेज जनरेशन सुविधा का इस्तेमाल करता है
storage.googleapis.com	Cloud Storage — इसमें प्रॉडक्ट कैटलॉग की इमेज और आज़माने के जनरेट किए गए नतीजे सेव किए जाते हैं
run.googleapis.com	Cloud Run — बैकएंड को सर्वरलेस कंटेनर के तौर पर होस्ट करता है
cloudbuild.googleapis.com	Cloud Build — यह सोर्स से Docker इमेज बनाता है
artifactregistry.googleapis.com	Artifact Registry — इसमें बनाई गई Docker इमेज सेव होती हैं

4. GCS बकेट बनाना

export PROJECT_ID=$(gcloud config get-value project)
gcloud storage buckets create gs://fashion-app-$PROJECT_ID \
 --location=us-central1 \
 --uniform-bucket-level-access

Google Cloud के सभी प्रॉडक्ट में बकेट के नाम यूनीक होते हैं. $PROJECT_ID पहले से ही यूनीक है. इसलिए, fashion-app-$PROJECT_ID भी यूनीक होगा. --uniform-bucket-level-access फ़्लैग, मॉडर्न डिफ़ॉल्ट है. यह IAM के लिए लेगसी ACL को बंद करता है.

5. प्रॉडक्ट कैटलॉग की इमेज अपलोड करना

बैकएंड का getProductImage टूल, gs://$GCS_BUCKET/catalog-assets/images/ से डेटा पढ़ता है. कैटलॉग की इमेज को इस पाथ पर अपलोड करें:

cd ~/fashion_app_demo
gcloud storage cp flutter_frontend/assets/images/*.png \
 gs://fashion-app-$PROJECT_ID/catalog-assets/images/

अपलोड की गई फ़ाइलों की पुष्टि करें. आपको .png फ़ाइलों की सूची दिखेगी:

gcloud storage ls gs://fashion-app-$PROJECT_ID/catalog-assets/images/

6. .env फ़ाइल को कॉन्फ़िगर करना

cd ~/fashion_app_demo/adk_backend
cat > .env << EOF
GOOGLE_CLOUD_PROJECT=$PROJECT_ID
GCS_BUCKET=fashion-app-$PROJECT_ID
EOF

इसके लिए, किसी एपीआई पासकोड की ज़रूरत नहीं होती. Vertex AI (Gemini के कॉल) और Cloud Storage (इमेज अपलोड/डाउनलोड) दोनों की पुष्टि ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल के ज़रिए होती है. इन्हें अगले चरण में सेट अप किया जाता है. .env फ़ाइल, बैकएंड को सिर्फ़ यह बताती है कि किस प्रोजेक्ट और बकेट का इस्तेमाल करना है.

7. ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल की मदद से पुष्टि करना

आपको बैकएंड को स्थानीय तौर पर शुरू करने से पहले, इसे चलाना होगा. Go बैकएंड, Vertex AI (Gemini) और Cloud Storage को किए गए हर कॉल की पुष्टि करने के लिए, एडीसी का इस्तेमाल करता है. एडीसी के बिना, बैकएंड शुरू हो जाएगा. हालांकि, आज़माने के हर अनुरोध पर 401 CREDENTIALS_MISSING गड़बड़ी दिखेगी.

एक क्रेडेंशियल से दोनों सेवाओं को ऐक्सेस किया जा सकता है. इन दोनों निर्देशों को इसी क्रम में चलाएं:

# 1. Log in (opens a browser; in Cloud Shell, paste the verification code back)
gcloud auth application-default login

# 2. Attach your project as the quota / billing project for ADC
gcloud auth application-default set-quota-project $(gcloud config get-value project)

पुष्टि करें कि एडीसी सही तरीके से काम कर रहा है:

gcloud auth application-default print-access-token | head -c 20 && echo "..."

आपको टोकन के ~20 वर्णों के बाद ... दिखेगा. अगर गड़बड़ी होती है, तो इसका मतलब है कि लॉगिन नहीं हुआ है. पहले चरण को फिर से चलाएं.

सभी के लिए एक ही पुष्टि करने का तरीका. Go कोड, Gemini के लिए आपके प्रोजेक्ट आईडी के साथ Backend: genai.BackendVertexAI का इस्तेमाल करता है. साथ ही, Cloud Storage क्लाइंट, gs:// को पढ़ने/लिखने के लिए उसी एडीसी का इस्तेमाल करता है. बाद में Cloud Run पर डिप्लॉय करने पर, एडीसी अपने-आप Cloud Run सेवा खाते से बदल जाता है. इसके लिए, पुष्टि करने वाले कोड में कोई बदलाव करने की ज़रूरत नहीं होती.

आपको हर नए खाते या नए Cloud Shell सेशन के लिए, यह प्रोसेस फिर से करनी होगी. एडीसी, हर Google खाते के लिए ~/.config/gcloud/application_default_credentials.json में सेव किया जाता है. खाते स्विच करने पर, हो सकता है कि फ़ाइल मौजूद न हो या पुरानी हो. ऐसा तब भी हो सकता है, जब Cloud Shell आपको कुछ समय के लिए होम डायरेक्ट्री देता है. ऊपर दी गई दोनों कमांड को फिर से चलाएं. एडीसी के पुराने होने के लक्षण: बैकएंड लॉग में 401 CREDENTIALS_MISSING दिखता है. ऐसा तब होता है, जब कोडलैब का सेटअप पहले ही पूरा हो चुका हो.

4. 🏗️ आर्किटेक्चर की खास जानकारी

अब एनवायरमेंट तैयार है. इसलिए, कोड देखने से पहले यह समझते हैं कि सिस्टम कैसे काम करता है.

चार एजेंट वाला सिस्टम

बैकएंड को Go के लिए ADK (Agent Development Kit) का इस्तेमाल करके, मल्टी-एजेंट सिस्टम के तौर पर बनाया गया है. इसमें चार एजेंट एक साथ काम करते हैं. हर एजेंट की एक खास ज़िम्मेदारी होती है:

                   ┌──────────────┐
                   │ Root Agent   │  ← Routes requests to the right agent
                   │ (gemini-3-   │
                   │  flash-      │
                   │  preview)    │
                   └──────┬───────┘
                          │
           ┌──────────────┼──────────────┐
           ▼              ▼              ▼
  ┌────────────────┐ ┌──────────┐ ┌────────────────┐
  │ Fitting Room   │ │ Catalog  │ │ Stylist        │
  │ Agent          │ │ Agent    │ │ Agent          │
  │ (gemini-3.1-   │ │ (gemini- │ │ (gemini-3.1-   │
  │  pro-preview)  │ │  3-flash-│ │  pro-preview)  │
  │                │ │  preview)│ │                │
  │ Tools:         │ │          │ │ Tools:         │
  │ • fitting_tool │ │ Tools:   │ │ • fitting_tool │
  │ • getProduct   │ │ • list   │ │ • getProduct   │
  │   Image        │ │ Products │ │   Image        │
  │ • catalog_agent│ │ • get    │ │ • catalog_agent│
  │   (delegation) │ │ Product  │ │   (delegation) │
  │                │ │  Image   │ │ • generate_    │
  └────────────────┘ └──────────┘ │   outfit_image │
                                  └────────────────┘

एजेंट	मॉडल	भूमिका
रूट एजेंट	gemini-3-flash-preview	ट्रैफ़िक पुलिस. यह कुकी, उपयोगकर्ता के मैसेज को पढ़ती है और उसे सही स्पेशलिस्ट एजेंट को सौंपती है. यह तेज़ और कम मेमोरी वाला मॉडल इस्तेमाल करता है, क्योंकि इसे सिर्फ़ राउटिंग के फ़ैसले लेने होते हैं.
कैटलॉग एजेंट	gemini-3-flash-preview	प्रॉडक्ट एक्सपर्ट. यह YAML फ़ाइल से प्रॉडक्ट कैटलॉग लोड करता है और प्रॉडक्ट के बारे में पूछे गए सवालों के जवाब देता है. यह कम संसाधनों का इस्तेमाल करता है, क्योंकि यह सिर्फ़ डेटा ढूंढता है.
फ़िटिंग रूम एजेंट	gemini-3.1-pro-preview	वर्चुअल तौर पर आज़माने की सुविधा के विशेषज्ञ. यह सुविधा, उपयोगकर्ता की फ़ोटो और प्रॉडक्ट की इमेज लेती है. इसके बाद, एक कंपोज़िट इमेज जनरेट करती है, जिसमें व्यक्ति को वह प्रॉडक्ट पहने हुए दिखाया जाता है. यह ज़्यादा बेहतर मॉडल का इस्तेमाल करता है, क्योंकि इसे इमेज के बारे में तर्क देना होता है.
स्टाइलिश एजेंट	gemini-3.1-pro-preview	फ़ैशन सलाहकार. यह जगह, अवसर, और प्राथमिकताओं के हिसाब से, कैटलॉग में मौजूद कपड़ों के तीन कॉम्बिनेशन तैयार करता है. हर पोशाक के लिए, आज़माने वाली इमेज जनरेट कर सकता है. यह क्रिएटिव रीज़निंग के लिए, बेहतर मॉडल का इस्तेमाल करता है.

एंट्री पॉइंट: main.go

सब कुछ main.go से शुरू होता है. यह एजेंट को एक साथ जोड़ता है और एचटीटीपी सर्वर शुरू करता है:

// main.go — simplified for clarity


func main() {
   godotenv.Load()  // Load .env file


   // 1. Create the artifact storage (GCS-backed)
   artifacts, _ := gcsartifact.NewService(ctx, bucket)


   // 2. Build agents bottom-up (dependencies first)
   catagent, _    := catalog.NewCatalogAgent(apikey, "catalog/catalog.yaml")
   fitagent, _    := fittingroom.NewFittingRoomAgent(apikey, catagent)
   stylistAgent, _ := stylist.NewStylistAgent(apikey, catagent)
   ragent, _      := rootagent.NewRootAgent(apikey, fitagent, catagent, stylistAgent)


   // 3. Register all agents with a multi-loader
   loader, _ := agent.NewMultiLoader(ragent, fitagent, catagent, stylistAgent)


   // 4. Create the ADK REST server
   restHandler, _ := adkrest.NewServer(adkrest.ServerConfig{
       SessionService:  session.InMemoryService(),
       MemoryService:   memory.InMemoryService(),
       AgentLoader:     loader,
       ArtifactService: artifacts,
   })


   // 5. Mount behind /api/ with CORS support
   r := mux.NewRouter()
   r.Use(tools.LocalhostCORS)
   r.PathPrefix("/api/").Handler(
       http.StripPrefix("/api", tools.LogHandler(restHandler)))


   http.Server{Addr: ":8080", Handler: r}.ListenAndServe()
}

ध्यान देने लायक कुछ ज़रूरी बातें:

• एजेंट बॉटम-अप तरीके से बनाए जाते हैं: कैटलॉग एजेंट को सबसे पहले बनाया जाता है, क्योंकि फ़िटिंग रूम और स्टाइलिस्ट एजेंट, दोनों इस पर निर्भर करते हैं. ये दोनों एजेंट, प्रॉडक्ट की जानकारी खोजने का काम कैटलॉग एजेंट को सौंपते हैं.
• agent.NewMultiLoader चारों एजेंट को रजिस्टर करता है, ताकि REST API नाम के हिसाब से किसी भी एजेंट को रूट कर सके.
• adkrest.NewServer, REST API अपने-आप उपलब्ध कराता है. आपको एंडपॉइंट हैंडलर खुद नहीं लिखने होते. ADK में, सेशन मैनेजमेंट, आर्टफ़ैक्ट स्टोरेज, और एजेंट एक्ज़ीक्यूशन की सुविधा पहले से मौजूद होती है.
• यह कुकी, सेशन की जानकारी को मेमोरी में सेव करती है. session.InMemoryService() इसका मतलब है कि सर्वर रीस्टार्ट होने पर सेशन बंद हो जाते हैं. डेमो के लिए यह ठीक है. प्रोडक्शन में, आपको परसिस्टेंट स्टोर का इस्तेमाल करना होगा.
• gcsartifact.NewService, Google Cloud Storage में आर्टफ़ैक्ट (जनरेट की गई इमेज) सेव करता है, ताकि वे सभी अनुरोधों में बने रहें. साथ ही, उन्हें GCS यूआरआई के ज़रिए शेयर किया जा सके.

5. 🤖 ADK (Agent Development Kit) के बारे में ज़्यादा जानकारी

एडीके क्या है?

Agent Development Kit (ADK), Google का एक ओपन-सोर्स फ़्रेमवर्क है. इसकी मदद से, Go (और Python/Java) में एआई एजेंट बनाए जा सकते हैं. यह आपके ऐप्लिकेशन और Gemini API के बीच की लेयर है.

Gemini API को सीधे तौर पर कॉल किया जा सकता है. हालांकि, जब आपके ऐप्लिकेशन को:

• कैटलॉग में मौजूद प्रॉडक्ट खोजना
• उपयोगकर्ता की फ़ोटो के आधार पर इमेज जनरेट करना
• यह याद रखना कि पहले कौनसे कपड़े सुझाए गए थे
• एक से ज़्यादा एआई एजेंट के साथ मिलकर काम करना

आपको स्ट्रक्चर की ज़रूरत है. ADK, यह स्ट्रक्चर उपलब्ध कराता है.

एजेंट लूप

हर एडीके एजेंट, इस लूप को फ़ॉलो करता है:

1. Receive a message (from user or another agent)
2. Think — the LLM reasons about what to do
3. Act — call a tool, delegate to a sub-agent, or respond
4. Return — send the result back

यह लूप, एक ही अनुरोध में कई बार दोहराया जा सकता है. उदाहरण के लिए, स्टाइलिस्ट एजेंट ये काम कर सकता है:

1. "समुद्र तट पर छुट्टियां बिताने के लिए मुझे स्टाइल करो"
2. प्रॉडक्ट की सूची पाने के लिए, catalog_agent टूल को कॉल करें
3. आउटफ़िट के तीन कॉम्बिनेशन चुनें
4. इमेज जनरेट करने के लिए, हर ड्रेस के लिए fitting_tool को कॉल करें
5. स्ट्रक्चर्ड JSON रिस्पॉन्स दिखाना

मुख्य सिद्धांत (इस रिपॉज़िटरी के कोड के साथ)

एलएलएम एजेंट

मुख्य बिल्डिंग ब्लॉक. llmagent.New() की मदद से बनाया गया:

// From catalog/agent.go
agent, err := llmagent.New(llmagent.Config{
   Name:        "catalog_agent",                    // Unique identifier
   Model:       m,                                  // Which LLM to use
   Description: "An agent that can search and list products from the catalog",
   Instruction: instructions,                       // Persona prompt (embedded from .md file)
   Tools:       []tool.Tool{listTool, imageTool},   // What the agent can do
})

Instruction फ़ील्ड, एजेंट की भूमिका के बारे में बताता है. इससे एलएलएम को पता चलता है कि एजेंट कौन है और उसे किस तरह का व्यवहार करना है. इस रिपॉज़िटरी में, निर्देशों को मार्कडाउन फ़ाइलों के तौर पर लिखा जाता है. साथ ही, Go के //go:embed डायरेक्टिव का इस्तेमाल करके, उन्हें कंपाइल करने के समय एम्बेड किया जाता है:

//go:embed instructions.md
var instructions string

इससे प्रॉम्प्ट, इनलाइन स्ट्रिंग के बजाय अलग-अलग वर्शन वाले दस्तावेज़ों के तौर पर सेव होते हैं.

टूल

टूल, Go फ़ंक्शन होते हैं जिन्हें एलएलएम कॉल कर सकता है. ADK, LLM के टूल-कॉलिंग फ़ॉर्मैट और आपके टाइप किए गए Go फ़ंक्शन के बीच अनुवाद करता है:

// From catalog/agent.go
type ListProductsArgs struct{}                    // Input (can be empty)
type ListProductsResult struct {
   Products []Product `json:"products"`          // Output
}


func ListProducts(ctx tool.Context, args ListProductsArgs) (ListProductsResult, error) {
   return ListProductsResult{Products: catalogProducts}, nil
}


// Register it:
listTool, _ := functiontool.New(functiontool.Config{
   Name:        "listProducts",
   Description: "list all products in the catalog",
}, ListProducts)

एडीके, आपके Go स्ट्रक्ट से JSON स्कीमा अपने-आप जनरेट करता है और इसे एलएलएम को भेजता है. जब एलएलएम, listProducts को कॉल करने का फ़ैसला करता है, तो ADK आर्ग्युमेंट को डिसिरियलाइज़ करता है, आपके फ़ंक्शन को कॉल करता है, और नतीजे वापस भेजता है.

tool.Context पैरामीटर, टूल को ADK की रनटाइम सेवाओं का ऐक्सेस देता है. इनमें सबसे अहम आर्टफ़ैक्ट हैं:

// Save an image as an artifact
ctx.Artifacts().Save(ctx, "my_image", imagePart)


// Load an artifact
resp, _ := ctx.Artifacts().Load(ctx, "my_image")

सब-एजेंट को सौंपना

कोई एजेंट, agenttool.New() के ज़रिए किसी दूसरे एजेंट को टूल के तौर पर इस्तेमाल कर सकता है:

// From fittingroom/agent.go
Tools: []tool.Tool{
   loadartifactstool.New(),              // List available artifacts
   imgtool,                              // Get product images
   agenttool.New(catalogAgent, nil),     // Delegate to catalog agent
   fittingTool,                          // Generate try-on image
},

जब फ़िटिंग रूम एजेंट को प्रॉडक्ट की जानकारी चाहिए होती है, तो वह कैटलॉग एजेंट को कॉल कर सकता है. यह कॉल, किसी सामान्य टूल की तरह किया जाता है. एलएलएम को यह टूल, टूल की सूची में दिखता है. इसके बाद, वह इसे चालू करने का फ़ैसला कर सकता है.

सेशन

सेशन, बातचीत के इतिहास को ट्रैक करते हैं. ADK का REST API, इन्हें अपने-आप मैनेज करता है:

POST /api/apps/{appName}/users/{userId}/sessions  →  Creates a new session
POST /api/run  (with sessionId)                   →  Runs agent within that session

इस ऐप्लिकेशन में डिज़ाइन से जुड़ा एक अहम फ़ैसला लिया गया है: फ़िटिंग रूम, हर अनुरोध के लिए एक नया सेशन बनाता है (हर बार आज़माने की सुविधा अलग होती है). वहीं, स्टाइलिश लुक पाने के लिए सुझाव देने वाली सुविधा, एक ही सेशन का फिर से इस्तेमाल करती है. इससे, यह सुविधा पिछले सुझावों को याद रखती है और मिले सुझावों के आधार पर उन्हें बेहतर बना सकती है.

राज्य

स्टेट, सेशन से जुड़ा एक की-वैल्यू स्टोर होता है. एजेंट, कोऑर्डिनेट करने के लिए इस कुकी की स्थिति को पढ़ते और लिखते हैं:

// Write to state
ctx.State().Set("previously_used_products", "[\"id_bomber\",\"id_hat\"]")


// Read from state
val, err := ctx.State().Get("previously_used_products")

स्टाइलिश एजेंट, यह याद रखने के लिए स्टेट का इस्तेमाल करता है कि उसने पहले कौनसे प्रॉडक्ट सुझाए थे, ताकि अगली बार वह अलग-अलग प्रॉडक्ट चुन सके.

कलाकृतियां

आर्टफ़ैक्ट, बाइनरी ऑब्जेक्ट (आम तौर पर इमेज) होते हैं. इन्हें हर सेशन के हिसाब से सेव किया जाता है. टेक्स्ट वाले जवाबों के उलट, इन्हें अलग से सेव किया जाता है और नाम के हिसाब से फ़ेच किया जाता है:

// Save a generated image as an artifact
artName := fmt.Sprintf("generated_fitting_%s_%s", ctx.InvocationID(), uuid.NewString()[:8])
ctx.Artifacts().Save(ctx, artName, imagePart)


// The frontend fetches it via:
// GET /api/apps/{app}/users/{user}/sessions/{session}/artifacts/{artName}

इससे जवाबों का साइज़ कम रहता है. एजेंट सिर्फ़ आर्टफ़ैक्ट का नाम दिखाता है और फ़्रंटएंड, बाइनरी इमेज डेटा को अलग से फ़ेच करता है.

कॉलबैक

कॉलबैक ऐसे हुक होते हैं जो एजेंट लूप में खास पॉइंट पर चलते हैं. वे एक्ज़ीक्यूशन की जांच कर सकते हैं, उसमें बदलाव कर सकते हैं या उसे छोटा कर सकते हैं:

llmagent.Config{
   // Runs before the agent starts — used to save uploaded images
   BeforeAgentCallbacks: []agent.BeforeAgentCallback{SaveIncomingBlobs},


   // Runs before each LLM call — used to inject context
   BeforeModelCallbacks: []llmagent.BeforeModelCallback{
       ExtractAndInjectUserImage,
       InjectPreviousProducts,
   },


   // Runs after each LLM response — used to extract data
   AfterModelCallbacks: []llmagent.AfterModelCallback{SaveSelectedProducts},
}

अगर कॉलबैक से शून्य नहीं है, तो डिफ़ॉल्ट व्यवहार को छोड़ दिया जाता है. उदाहरण के लिए, BeforeModelCallback जो कैश मेमोरी में सेव किया गया जवाब दिखाता है, वह एलएलएम को कॉल करने की प्रोसेस को पूरी तरह से छोड़ देगा.

JSON स्कीमा लागू करना

फ़िटिंग रूम और स्टाइलिस्ट, दोनों एजेंट एलएलएम को स्ट्रक्चर्ड JSON में जवाब देने के लिए मजबूर करते हैं:

GenerateContentConfig: &genai.GenerateContentConfig{
   ResponseMIMEType:   "application/json",
   ResponseJsonSchema: fittingSchemaMap(),  // Defines the expected structure
}

इससे यह पक्का होता है कि Flutter के फ़्रंटएंड को हमेशा पार्स किया जा सकने वाला डेटा मिले, न कि बिना स्ट्रक्चर वाला लेख.

कैटलॉग एजेंट: सबसे आसान उदाहरण

कैटलॉग एजेंट (catalog/agent.go), सिस्टम में सबसे आसान एजेंट है. ADK पैटर्न को समझने के लिए, यह एक अच्छा शुरुआती पॉइंट है.

इसमें दो टूल होते हैं:

1. listProducts — YAML फ़ाइल से, प्रॉडक्ट का पूरा कैटलॉग दिखाता है
2. getProductImage — यह GCS (या लोकल फ़ॉलबैक) से प्रॉडक्ट की इमेज लोड करता है और उसे आर्टफ़ैक्ट के तौर पर सेव करता है

getProductImage टूल में एक अहम पैटर्न दिखता है — आर्टफ़ैक्ट कैश मेमोरी के साथ कई सोर्स से लोड करना:

// From tools/imagetool.go — simplified
func GetProductImage(ctx tool.Context, args GetProductImageArgs) (GetProductImageResult, error) {
   // First: check if it's already an artifact
   _, err := ctx.Artifacts().Load(ctx, args.ImageName)
   if err == nil {
       return GetProductImageResult{Image: args.ImageName}, nil  // Cache hit!
   }


   // Second: try loading from GCS bucket
   rc, err := client.Bucket(bucket).Object("catalog-assets/images/" + args.ImageName).NewReader(ctx)
   if err != nil {
       // Third: fall back to local filesystem
       localData, _ := os.ReadFile("../flutter_frontend/assets/images/" + args.ImageName)
       ctx.Artifacts().Save(ctx, args.ImageName, &genai.Part{InlineData: ...})
       return GetProductImageResult{Image: args.ImageName}, nil
   }


   // Save to artifact cache and return
   ctx.Artifacts().Save(ctx, args.ImageName, &genai.Part{InlineData: ...})
   return GetProductImageResult{Image: args.ImageName}, nil
}

यह टूल सबसे पहले आर्टफ़ैक्ट, फिर GCS, और फिर स्थानीय फ़ाइलों को आज़माता है. लोड होने के बाद, इमेज को आर्टफ़ैक्ट के तौर पर कैश मेमोरी में सेव कर लिया जाता है, ताकि बाद के कॉल तुरंत किए जा सकें.

6. 🧪 एआई पाइपलाइन: एजेंट की कार्रवाइयां

अब हम दो सबसे बेहतरीन एजेंट के बारे में बात करते हैं. ये ऐसे एजेंट हैं जो इमेज जनरेट करते हैं और कपड़ों को व्यवस्थित करते हैं.

6.1 फ़िटिंग रूम एजेंट

फ़ाइल:

adk_backend/fittingroom/agent.go

फ़िटिंग रूम एजेंट, "वर्चुअल तौर पर आज़माएं" सुविधा के पीछे काम करने वाला इंजन है. जब कोई व्यक्ति अपनी फ़ोटो अपलोड करता है और कोई प्रॉडक्ट चुनता है, तो यह एजेंट उस व्यक्ति की ऐसी इमेज जनरेट करता है जिसमें उसे वह प्रॉडक्ट पहने हुए दिखाया गया हो.

fitting_tool — चरण-दर-चरण

मुख्य लॉजिक, doFitting फ़ंक्शन में होता है. जब एजेंट इस नंबर पर कॉल करता है, तो क्या होता है:

पहला चरण: उपयोगकर्ता की इमेज ठीक करना

func doFitting(ctx tool.Context, args FittingToolArgs) (FittingToolResult, error) {
   if len(args.Accessories) > 2 {
       args.Accessories = args.Accessories[:2]  // Safety limit: max 2 items
   }


   var userPart *genai.Part
   if strings.HasPrefix(args.UserImage, "gs://") {
       // If we have a GCS URI from a previous fitting, use it directly
       userPart = &genai.Part{FileData: &genai.FileData{
           FileURI:  args.UserImage,
           MIMEType: gcsURIMimeType(args.UserImage),
       }}
   } else {
       // Otherwise, load the image from artifact storage
       userImgResp, err := ctx.Artifacts().Load(ctx, args.UserImage)
       userPart = userImgResp.Part
   }

उपयोगकर्ता की इमेज दो सोर्स से मिल सकती है:

• आर्टफ़ैक्ट का नाम (जैसे कि upload_abc123_1) — यह शुरुआती अपलोड है, जिसे SaveIncomingBlobs कॉलबैक ने सेव किया है
• gs:// यूआरआई — यह पहले जनरेट किया गया फ़िटिंग का नतीजा है. इसे GCS में सेव किया जाता है, ताकि इसे अलग-अलग सेशन में फिर से इस्तेमाल किया जा सके

इस डुअल-पाथ डिज़ाइन का मकसद यह है: जब स्टाइलिस्ट एजेंट बाद में कपड़ों को आज़माने की सुविधा जनरेट करता है, तो वह फ़िटिंग रूम के शुरुआती नतीजे से GCS यूआरएल का फिर से इस्तेमाल करता है. इससे, उपयोगकर्ता की पहचान सभी कपड़ों के लिए एक जैसी बनी रहती है.

दूसरा चरण: मल्टीमॉडल प्रॉम्प्ट बनाना

   parts := []*genai.Part{
       genai.NewPartFromText(toolInstructions),           // Identity preservation prompt
       genai.NewPartFromText("Reference Person Photo:"),
       userPart,                                          // The user's photo
   }


   for _, acc := range args.Accessories {
       accResp, _ := ctx.Artifacts().Load(ctx, acc)       // Load product image artifact
       parts = append(parts, genai.NewPartFromText("Product Image to Apply:"))
       parts = append(parts, accResp.Part)                // The product photo
   }

toolInstructions (tool_instructions.md से एम्बेड किया गया) ज़रूरी है. इससे Gemini को यह पता चलता है कि सिर्फ़ कपड़े बदलते समय, उपयोगकर्ता की पहचान (चेहरा, शरीर का टाइप, त्वचा का रंग, बाल) को बनाए रखना है. इस तरह की प्रॉम्प्ट इंजीनियरिंग के बिना, मॉडल व्यक्ति की उपस्थिति में बदलाव कर सकता है.

तीसरा चरण: इमेज जनरेट करने के लिए Gemini को कॉल करना

   client, _ := genai.NewClient(ctx, &genai.ClientConfig{
       Backend:  genai.BackendVertexAI,                 // Vertex AI endpoint
       Project:  os.Getenv("GOOGLE_CLOUD_PROJECT"),     // From your .env
       Location: "global",                              // Multi-region endpoint
   })


   resp, _ := client.Models.GenerateContent(ctx, "gemini-2.5-flash-image",
       []*genai.Content{genai.NewContentFromParts(parts, "user")},
       &genai.GenerateContentConfig{
           ResponseModalities: []string{"TEXT", "IMAGE"},  // Request both text and image output
           Temperature:        genai.Ptr(float32(0.2)),    // Low temperature for consistency
       })

सभी चार एजेंट और इमेज जनरेट करने वाला टूल, पुष्टि करने का एक ही तरीका इस्तेमाल करते हैं: Backend: genai.BackendVertexAI. इसमें प्रोजेक्ट आईडी का इस्तेमाल किया जाता है और पुष्टि, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल के ज़रिए की जाती है. ऑर्केस्ट्रेशन मॉडल (gemini-3.1-pro-preview, gemini-3-flash-preview) और इमेज मॉडल (gemini-2.5-flash-image), सभी एक ही Vertex AI एंडपॉइंट के पीछे मौजूद होते हैं. साथ ही, एक ही एडीसी, Cloud Storage के ऐक्सेस को अनुमति देता है. हर कॉल के लिए एक क्रेडेंशियल.

चौथा चरण: नतीजे को सेव करना

   // Find the image in the response (may contain both text + image parts)
   var genPart *genai.Part
   for _, p := range resp.Candidates[0].Content.Parts {
       if p.InlineData != nil {
           genPart = p
           break
       }
   }


   // Save as an ADK artifact
   artName := fmt.Sprintf("generated_fitting_%s_%s", ctx.InvocationID(), uuid.NewString()[:8])
   ctx.Artifacts().Save(ctx, artName, genPart)


   // Also upload to GCS for cross-session reuse
   objectName := fmt.Sprintf("generated-fittings/%s.jpg", ctx.InvocationID())
   w := storageClient.Bucket(bucket).Object(objectName).NewWriter(ctx)
   w.Write(genPart.InlineData.Data)
   gcsURI := fmt.Sprintf("gs://%s/%s", bucket, objectName)


   return FittingToolResult{ArtifactName: artName, GCSUrl: gcsURI}, nil

डुअल-सेव (आर्टफ़ैक्ट + GCS) की सुविधा, फ़िटिंग रूम और स्टाइलिस्ट के बीच एजेंट हैंडऑफ़ की सुविधा के लिए ज़रूरी है. आर्टफ़ैक्ट से, मौजूदा सेशन में तुरंत ऐक्सेस मिलता है. वहीं, GCS यूआरआई की मदद से, स्टाइलिस्ट (जो किसी दूसरे सेशन में चलता है) बाद में उसी इमेज को रेफ़रंस कर सकता है.

SaveIncomingBlobs कॉलबैक

एजेंट के जवाब देने से पहले, यह BeforeAgentCallback चलता है. इससे उपयोगकर्ता की अपलोड की गई इमेज सेव हो जाती हैं:

func SaveIncomingBlobs(ctx agent.CallbackContext) (*genai.Content, error) {
   for pindex, p := range ctx.UserContent().Parts {
       if p.InlineData != nil {
           aname := fmt.Sprintf("upload_%s_%d", ctx.InvocationID(), pindex)
           ctx.Artifacts().Save(ctx, aname, p)
       }
   }
   return nil, nil  // Return nil to proceed with normal agent execution
}

(nil, nil) को वापस भेजकर, कॉलबैक यह सिग्नल देता है कि "प्रीप्रोसेसिंग हो गई है — अब एजेंट को सामान्य तरीके से चलाएं." अगर यह फ़ंक्शन, शून्य नहीं है, तो यह एजेंट को पूरी तरह से शॉर्ट-सर्किट कर देगा.

6.2 स्टाइलिस्ट एजेंट

फ़ाइल:

adk_backend/stylist/agent.go

स्टाइलिश एजेंट, सिस्टम में सबसे बेहतर है. यह आपकी पसंद के हिसाब से कपड़ों के सुझाव देता है. साथ ही, बातचीत के ज़रिए सुझावों को बेहतर बनाने में मदद करता है.

तीन कॉलबैक — स्टाइलिस्ट की याददाश्त

स्टाइलिश जवाब देने वाला मॉडल, बातचीत के कॉन्टेक्स्ट को बनाए रखने के लिए तीन कॉलबैक का इस्तेमाल करता है:

पहला कॉलबैक:

InjectPreviousProducts (BeforeModel)

समस्या: अगर उपयोगकर्ता कहता है कि "मुझे अलग-अलग विकल्प दिखाओ," तो एलएलएम एक ही प्रॉडक्ट को फिर से सुझा सकता है. ऐसा इसलिए, क्योंकि यह अपने-आप यह ट्रैक नहीं करता कि उसने पहले कौनसे प्रॉडक्ट सुझाए थे.

समाधान: हर जवाब के बाद, प्रॉडक्ट आईडी को सेशन की स्थिति में सेव किया जाता है. एलएलएम को कॉल करने से पहले, यह कॉलबैक उन्हें पढ़ता है और एक हिंट जोड़ता है:

func InjectPreviousProducts(ctx agent.CallbackContext, req *model.LLMRequest) (*model.LLMResponse, error) {
   prev, err := ctx.State().Get(stateKeyPreviousProducts)  // Read from session state
   if err != nil {
       return nil, nil  // No previous state — first run
   }


   // Append hint to the user's message
   for i := len(req.Contents) - 1; i >= 0; i-- {
       if req.Contents[i].Role == "user" {
           req.Contents[i].Parts = append(req.Contents[i].Parts,
               genai.NewPartFromText(fmt.Sprintf(
                   "IMPORTANT: You previously suggested these products: %s. "+
                   "You MUST pick DIFFERENT complementary products this time.", prev)))
           break
       }
   }
   return nil, nil  // Continue to LLM call
}

दूसरा कॉलबैक:

ExtractAndInjectUserImage (BeforeModel)

समस्या: जब उपयोगकर्ता सुझाव/राय देता है या शिकायत करता है ("इसे और अनौपचारिक बनाओ"), तो फ़ॉलो-अप मैसेज में उपयोगकर्ता की फ़ोटो फिर से शामिल नहीं की जाती. हालांकि, फ़िटिंग टूल को इसकी ज़रूरत होती है.

समाधान: पहले अनुरोध पर, यह कॉलबैक उपयोगकर्ता की इमेज का रेफ़रंस निकालता है और उसे स्टेट में सेव करता है. इसके बाद के अनुरोधों पर, यह इसे फिर से इंजेक्ट करता है:

func ExtractAndInjectUserImage(ctx agent.CallbackContext, req *model.LLMRequest) (*model.LLMResponse, error) {
   var foundImgStr string


   // Search for user image in the latest message
   for i := len(req.Contents) - 1; i >= 0; i-- {
       if req.Contents[i].Role == "user" {
           for _, part := range req.Contents[i].Parts {
               if strings.Contains(part.Text, "User try-on base image") {
                   foundImgStr = part.Text  // Found the GCS URI reference
               }
           }
           break
       }
   }


   if foundImgStr != "" {
       ctx.State().Set(stateKeyUserImageStr, foundImgStr)  // Save for later
   } else {
       // Not in current message — retrieve from state and inject
       val, _ := ctx.State().Get(stateKeyUserImageStr)
       if savedImgStr, ok := val.(string); ok {
           // Inject into the latest user message
           req.Contents[last].Parts = append(req.Contents[last].Parts,
               genai.NewPartFromText("REMINDER: Use this image: " + savedImgStr))
       }
   }
   return nil, nil
}

तीसरा कॉलबैक:

SaveSelectedProducts (AfterModel)

एलएलएम के कपड़ों के सुझाव देने के बाद, यह कॉलबैक JSON को पार्स करके प्रॉडक्ट आईडी निकालता है. साथ ही, उन्हें सेव करता है, ताकि InjectPreviousProducts कॉलबैक अगली बार उनका इस्तेमाल कर सके:

func SaveSelectedProducts(ctx agent.CallbackContext, resp *model.LLMResponse, respErr error) (*model.LLMResponse, error) {
   for _, part := range resp.Content.Parts {
       ids := extractProductIDs(part.Text)  // Parse JSON → extract product IDs
       if len(ids) > 0 {
           data, _ := json.Marshal(ids)
           ctx.State().Set(stateKeyPreviousProducts, string(data))  // Save to state
       }
   }
   return nil, nil  // Don't modify the response
}

ये तीनों कॉलबैक मिलकर, फ़ीडबैक लूप बनाते हैं:

Request 1:  User sends styling request + user image
           → ExtractAndInjectUserImage SAVES image to state
           → LLM generates 3 outfits
           → SaveSelectedProducts SAVES product IDs to state


Request 2:  User says "make it more casual"
           → ExtractAndInjectUserImage INJECTS saved image into prompt
           → InjectPreviousProducts INJECTS "don't reuse these IDs"
           → LLM generates 3 NEW outfits
           → SaveSelectedProducts UPDATES product IDs in state

6.3 रूट एजेंट

फ़ाइल:

adk_backend/rootagent/agent.go

सबसे आसान एजेंट — सिर्फ़ 31 लाइनें:

func NewRootAgent(project string, fittingAgent, catalogAgent, stylistAgent agent.Agent) (agent.Agent, error) {
   m, _ := gemini.NewModel(ctx, "gemini-3-flash-preview", &genai.ClientConfig{
       Backend:  genai.BackendVertexAI,
       Project:  project,
       Location: "global",
   })


   return llmagent.New(llmagent.Config{
       Name:        "root_agent",
       Model:       m,
       Description: "A root agent that delegates to other agents",
       Instruction: "You are a helpful shopping assistant. If the user asks about fitting " +
           "items or generating images, delegate to the fitting room agent. If the user " +
           "asks about products, delegate to the catalog agent. If the user asks for " +
           "styling advice, delegate to the stylist agent.",
       SubAgents: []agent.Agent{fittingAgent, catalogAgent, stylistAgent},
   })
}

यह gemini-3-flash-preview (सबसे तेज़ मॉडल) का इस्तेमाल करता है, क्योंकि राउटिंग के फ़ैसले आसान होते हैं. एलएलएम को सिर्फ़ उपयोगकर्ता के इरादे को पढ़ना होता है और सही सब-एजेंट को चुनना होता है. इसके लिए किसी टूल की ज़रूरत नहीं होती. SubAgents, डेलिगेशन को अपने-आप मैनेज करता है.

7. 📱 Flutter फ़्रंटएंड आर्किटेक्चर

Flutter फ़्रंटएंड, खुदरा खरीदारी करने वाला पूरी तरह से काम करने वाला ऐप्लिकेशन है. एआई की सुविधाएं flutter_frontend/lib/workshop_tasks/ में लाइव हैं. ये core_app/ में पहले से मौजूद शॉपिंग अनुभव से अलग हैं.

MVVM पैटर्न

यह ऐप्लिकेशन, Provider पैकेज के साथ Model-View-ViewModel आर्किटेक्चर का इस्तेमाल करता है:

┌──────────────────┐    ┌────────────────────┐    ┌──────────────────┐
│  View (Widget)   │◀───│ ViewModel (Provider)│◀───│  Service (HTTP)  │
│                  │    │                     │    │                  │
│ • Renders UI     │    │ • Holds state       │    │ • Makes API calls│
│ • User gestures  │───▶│ • Business logic    │───▶│ • Parses response│
│ • Listens for    │    │ • notifyListeners() │    │ • Returns data   │
│   state changes  │    │                     │    │                  │
└──────────────────┘    └────────────────────┘    └──────────────────┘

हर लेयर की एक तय भूमिका होती है:

• मॉडल: Product, Outfit, StyleRequest जैसी डेटा क्लास और TryOnState जैसे एनम
• ViewModel (ChangeNotifier): यह मौजूदा स्थिति को बनाए रखता है और notifyListeners() के ज़रिए यूज़र इंटरफ़ेस (यूआई) में हुए बदलावों को ब्रॉडकास्ट करता है
• व्यू (विजेट): context.watch() की मदद से ViewModel को सब्सक्राइब करता है और स्टेट बदलने पर फिर से बनाता है
• Service: यह ADK के बैकएंड को एचटीटीपी कॉल करता है और टाइप किया गया डेटा दिखाता है

सेवा लेयर

सेवाओं को ऐब्सट्रैक्ट इंटरफ़ेस के तौर पर तय किया जाता है. साथ ही, इन्हें ADK के हिसाब से लागू किया जाता है:

// Abstract interface — defines WHAT the service does
abstract class TryItOnService {
 Future<(Uint8List?, String?)> generateTryOnImage(
   Uint8List userImageBytes,
   Uint8List productImageBytes,
 );
}


// Concrete implementation — defines HOW (via ADK REST API)
class AdkFittingRoomService implements TryItOnService { ... }

इस तरह से अलग करने का मतलब है कि ऐप्लिकेशन के बाकी हिस्से में बदलाव किए बिना, ADK के बैकएंड को Firebase AI, मॉक सर्विस या किसी अन्य सुविधा से बदला जा सकता है.

एपीआई के लिए तीन चरणों वाला पैटर्न

AdkFittingRoomService और AdkStylingService, दोनों ही एडीके बैकएंड से कम्यूनिकेट करने के लिए एक ही पैटर्न का इस्तेमाल करते हैं:

पहला चरण: सेशन बनाना

Future<String> _createSession() async {
 final url = Uri.parse(
   '$_baseUrl/apps/${Uri.encodeComponent(_appName)}/users/$_userId/sessions');
 final response = await _client.post(url,
   headers: {'Content-Type': 'application/json'},
   body: jsonEncode({}));
 final body = jsonDecode(response.body) as Map<String, dynamic>;
 return body['id'] as String;  // Returns the session ID
}

दूसरा चरण: एजेंट को चलाना

Future<(String?, String?)> _runAgent({required String sessionId, ...}) async {
 final requestBody = jsonEncode({
   'appName': _appName,
   'userId': _userId,
   'sessionId': sessionId,
   'newMessage': {
     'role': 'user',
     'parts': [
       {'text': 'Generate a virtual try-on...'},
       {'inlineData': {'mimeType': 'image/jpeg', 'data': base64Encode(userImageBytes)}},
       {'inlineData': {'mimeType': 'image/png', 'data': base64Encode(productImageBytes)}},
     ],
   },
 });
 final response = await _client.post(Uri.parse('$_baseUrl/run'), body: requestBody);
 // Parse response events for artifact name and GCS URL...
}

तीसरा चरण: आर्टफ़ैक्ट फ़ेच करना

Future<Uint8List?> _loadArtifact({required String sessionId, required String artifactName}) async {
 final url = Uri.parse(
   '$_baseUrl/apps/$_appName/users/$_userId/sessions/$sessionId/artifacts/$artifactName');
 final response = await _client.get(url);
 final part = jsonDecode(response.body) as Map<String, dynamic>;
 final data = part['inlineData']['data'] as String;
 return base64Decode(data);  // Returns raw image bytes
}

डिजाइन में एक अहम अंतर यह है कि कपड़े आज़माने की सेवा, हर अनुरोध के लिए एक नया सेशन बनाती है (_createSession() को हर बार कॉल किया जाता है). वहीं, स्टाइलिंग सेवा, एक ही सेशन का फिर से इस्तेमाल करती है (_sessionId ??= await _createSession()), ताकि कई बार बातचीत की जा सके.

स्टेट मैनेजमेंट: TryItOnProvider

फ़ाइल:

workshop_tasks/step_1_try_it_on/providers/try_it_on_provider.dart

TryItOnProvider, आज़माने की पूरी प्रोसेस को मैनेज करता है. यह स्टेट मशीन के तौर पर TryOnState enum का इस्तेमाल करता है:

enum TryOnState { initial, imagePicked, generating, success, error }


class TryItOnProvider with ChangeNotifier {
 TryOnState _state = TryOnState.initial;
 Uint8List? _userImageBytes;
 Uint8List? _generatedImage;
 String? _errorMessage;

निजी स्थिति में बदलाव करने से, डेटा में एकरूपता बनी रहती है. इसका मतलब है कि आपको कभी भी पुराने डेटा को मिटाए बिना और यूज़र इंटरफ़ेस (यूआई) को सूचना दिए बिना, स्थिति को अपडेट नहीं करना चाहिए:

 void _setGenerating() {
   _state = TryOnState.generating;
   _errorMessage = null;            // Clear any previous error
   _wasLastGenerationCached = false;
   notifyListeners();               // Tell the UI to rebuild
 }


 void _setSuccess(Uint8List image, {bool isCached = false}) {
   _generatedImage = image;
   _errorMessage = null;
   _wasLastGenerationCached = isCached;
   _state = TryOnState.success;
   notifyListeners();
 }

जनरेट करने का मुख्य तरीका, इन सभी को एक साथ जोड़ता है:

 Future<String?> generateTryOnImage(String productImagePath) async {
   final userImageBytes = _userImageBytes;
   if (userImageBytes == null) {
     _setError('No image selected.');
     return _errorMessage;
   }


   // Check local cache first
   final cachedImage = ImageUtils.getCachedImage(_sessionCache, userImageBytes, productUint8List);
   if (cachedImage != null) {
     _setSuccess(cachedImage, isCached: true);
     return null;
   }


   _setGenerating();  // Triggers loading state in UI


   try {
     final (generatedBytes, gcsUrl) = await _aiService.generateTryOnImage(
       userImageBytes, productUint8List);
     if (generatedBytes != null) {
       _fittingGcsUrl = gcsUrl;     // Save for the stylist agent later
       _setSuccess(generatedBytes);
     }
   } catch (e) {
     _setError(e.toString());
   }
   return _state == TryOnState.success ? null : _errorMessage;
 }

यूज़र इंटरफ़ेस (यूआई): स्टेट राऊटर के तौर पर स्क्रीन

फ़ाइल:

workshop_tasks/step_1_try_it_on/ui/2_try_it_on_screen.dart

कपड़े आज़माने की सुविधा वाली स्क्रीन, Dart 3 की पैटर्न मैचिंग सुविधा का इस्तेमाल करती है. इससे AnimatedSwitcher के साथ मिलकर, सब-स्क्रीन के बीच रूट किया जा सकता है. ऐसा, सेवा देने वाली कंपनी की स्थिति के आधार पर किया जाता है:

class TryItOnScreen extends StatelessWidget {
 @override
 Widget build(BuildContext context) {
   final tryOnProvider = context.watch<TryItOnProvider>();


   return ScaffoldWithBackgroundNoise(
     appBar: const TryOnAppBar(),
     body: AnimatedSwitcher(
       duration: AppDurations.medium,
       child: switch (tryOnProvider.state) {
         TryOnState.initial || TryOnState.error => const ChooseImageScreen(),
         TryOnState.imagePicked || TryOnState.generating => LoadingScreen(
           userImage: tryOnProvider.userImageBytes),
         TryOnState.success => const FittingRoomScreen(),
       },
     ),
   );
 }
}

context.watch() ने सेवा देने वाली कंपनी की सदस्यता ली हो. जब भी notifyListeners() को कॉल किया जाता है, यह विजेट फिर से बनता है. साथ ही, AnimatedSwitcher एक स्क्रीन से दूसरी स्क्रीन पर आसानी से ट्रांज़िशन करता है. कोई Navigator.push नहीं है — स्क्रीन का कॉन्टेंट, स्टेट एनम के आधार पर बदलता है.

एजेंटिक हैंडऑफ़: फ़िटिंग रूम → स्टाइलिस्ट

सबसे दिलचस्प UX पैटर्न यह है कि ऐप्लिकेशन, फ़िटिंग रूम एजेंट से स्टाइलिस्ट एजेंट को कॉन्टेक्स्ट कैसे पास करता है.

5_fitting_room.dart में, वर्चुअल तौर पर आज़माने की इमेज जनरेट होने के बाद, "मुझे स्टाइल करो" बटन पर क्लिक करने से एक फ़ॉर्म खुलता है. जब उपयोगकर्ता यह सबमिट करता है:

// From 1_style_me_form_sheet.dart
Navigator.pop(context, StyleRequest(
 location: _locationController.text.trim(),
 occasion: _occasionController.text.trim(),
 notes: _notesController.text.trim(),
 gcsUserImageUrl: provider.fittingGcsUrl,          // GCS URI from fitting result
 userImageData: provider.fittingGcsUrl == null
     ? provider.userImageBytes : null,              // Fallback to raw bytes
 selectedProductId: provider.selectedProduct?.id,   // Product they already tried on
 selectedProductTitle: provider.selectedProduct?.title,
));

StyleRequest में स्टाइलिस्ट की ज़रूरत की हर चीज़ शामिल होती है:

• जगह और अवसर — स्टाइलिंग के लिए टेक्स्ट कॉन्टेक्स्ट
• GCS उपयोगकर्ता की इमेज का यूआरएल — ताकि स्टाइलिस्ट, उपयोगकर्ता की उसी इमेज का फिर से इस्तेमाल कर सके
• चुना गया प्रॉडक्ट — ताकि स्टाइलिस्ट इसे हर पोशाक में शामिल कर सके

इसे एजेंटिक हैंडऑफ़ कहा जाता है. इसमें मल्टीमॉडल कॉन्टेक्स्ट को एक एआई एजेंट से दूसरे एआई एजेंट को आसानी से ट्रांसफ़र किया जाता है. साथ ही, उपयोगकर्ता को सिर्फ़ एक सामान्य फ़ॉर्म दिखता है.

स्टाइलिंग फ़्लो: StylingProvider

फ़ाइल:

workshop_tasks/step_2_style_me/providers/styling_provider.dart

TryItOnProvider की तुलना में StylingProvider ज़्यादा आसान है, क्योंकि यह ज़्यादातर जटिलता को बैकएंड को सौंप देता है:

class StylingProvider with ChangeNotifier {
 StylingState _state = StylingState.initial;
 List<Outfit> _outfits = [];


 Future<bool> getStyleSuggestions(StyleRequest request) async {
   if (_state == StylingState.loading) return false;  // Prevent spam
   _currentRequest = request;
   _setLoading();
   try {
     final suggestions = await _stylingService.getStyleSuggestions(request);
     _setSuccess(suggestions);
     return true;
   } catch (e) {
     _setError('Something went wrong.');
   }
   return false;
 }


 // Multi-turn refinement — uses the same session
 Future<bool> refineWithFeedback(String feedback) async {
   if (_state == StylingState.loading) return false;
   _setLoading();
   try {
     final suggestions = await _stylingService.refineWithFeedback(feedback);
     _setSuccess(suggestions);
     return true;
   } catch (e) {
     _setError('Something went wrong.');
   }
   return false;
 }
}

refineWithFeedback तरीके से, उसी सेशन में सादा टेक्स्ट मैसेज भेजा जाता है. बैकएंड के InjectPreviousProducts और ExtractAndInjectUserImage कॉलबैक, कॉन्टेक्स्ट मैनेजमेंट को अपने-आप हैंडल करते हैं.

8. 🚀 ऐप्लिकेशन को स्थानीय तौर पर चलाना

Cloud Shell का बेहतर अनुभव पाने के लिए, Go बैकएंड, कंपाइल किए गए Flutter वेब ऐप्लिकेशन को उसी पोर्ट (8080) से दिखाता है. एक प्रोसेस, एक झलक यूआरएल, क्रॉस-ऑरिजिन से जुड़ी कोई समस्या नहीं, कॉन्फ़िगरेशन फ़ाइलों में बदलाव करने की ज़रूरत नहीं.

शुरू करने से पहले — एडीसी की जांच करना

Vertex AI को कॉल करने के लिए, बैकएंड को ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल की ज़रूरत होती है. अगर आपने इस Cloud Shell सेशन और इस Google खाते में प्रोजेक्ट सेटअप करने का सातवां चरण पूरा कर लिया है, तो आपको कुछ और करने की ज़रूरत नहीं है. अगर आपने कुछ समय बाद वापस आकर खाता इस्तेमाल करना शुरू किया है, खाता बदला है या आपको पक्का नहीं है कि आपने कौनसे खाते से साइन इन किया है, तो पांच सेकंड में इसकी पुष्टि करें:

gcloud auth application-default print-access-token | head -c 20 && echo "..."

अगर इससे टोकन के ~20 वर्ण प्रिंट होते हैं, तो इसका मतलब है कि सब कुछ ठीक है. अगर कोई गड़बड़ी होती है, तो प्रोजेक्ट सेटअप करने का सातवां चरण फिर से पूरा करें:

gcloud auth application-default login
gcloud auth application-default set-quota-project $(gcloud config get-value project)

आपको दो Cloud Shell टर्मिनल इस्तेमाल करने होंगे:

• टर्मिनल A — यह बैकएंड को लगातार चलाता है (./run.sh). इसे खुला रखें.
• टर्मिनल B — Flutter के वेब बिल्ड को एक बार चलाता है (flutter build web). काम पूरा होने पर बंद हो जाता है.

इनमें से कोई भी काम पहले किया जा सकता है. हालांकि, पहली बार में बेहतर अनुभव पाने के लिए, पहले Flutter बनाएं. इससे बैकएंड के पास, शुरू होने के साथ ही यूज़र इंटरफ़ेस (यूआई) उपलब्ध होगा.

1. टर्मिनल B — Build the Flutter Web Bundle (one-shot)

नया Cloud Shell टैब खोलें (टर्मिनल पैनल के सबसे ऊपर मौजूद +), फिर:

cd ~/fashion_app_demo/flutter_frontend
flutter pub get
flutter build web

इससे flutter_frontend/build/web/ तैयार होता है. यह स्टैटिक फ़ाइलों (एचटीएमएल, JS, ऐसेट) की एक डायरेक्ट्री होती है. यह प्रोसेस पूरी होने के बाद बंद हो जाती है. बैकएंड, डायरेक्ट्री के मौजूद होने का पता चलते ही इन्हें दिखा देगा.

जब भी Dart कोड में बदलाव करें, तब टर्मिनल B में flutter build web को फिर से चलाएं. टर्मिनल A का बैकएंड, अगले अनुरोध पर नया बिल्ड चुन लेता है. इसके लिए, रीस्टार्ट करने की ज़रूरत नहीं होती.

fatal: detected dubious ownership in repository at '/google/flutter' (×4)

अगर आपने नया Cloud Shell सेशन शुरू किया है या आपने उस Google खाते से साइन इन किया है जिससे आपने सेटअप नहीं किया था, तो आपको यह मैसेज दिखेगा. समस्या को ठीक करने के लिए, § ज़रूरी शर्तें 2.2 में दिया गया एक ही लाइन का कोड इस्तेमाल करें. इसे हर खाते के लिए सिर्फ़ एक बार चलाना होगा:

git config --global --add safe.directory /google/flutter

इसके बाद, flutter pub get && flutter build web को फिर से चलाएं. कॉन्फ़िगरेशन को ~/.gitconfig में सेव किया जाता है, ताकि इस खाते के लिए, आने वाले समय के सेशन में भी इसका इस्तेमाल किया जा सके.

2. टर्मिनल A — बैकएंड शुरू करें (लंबे समय तक चलने वाला)

अपने ओरिजनल Cloud Shell टर्मिनल में:

cd ~/fashion_app_demo/adk_backend
./run.sh

आपको इस तरह की विंडो दिखेगी:

Serving Flutter web build from ../flutter_frontend/build/web

इस टर्मिनल को चालू रखें — बैकएंड तब तक चालू रहेगा, जब तक run.sh चालू है. इसे रोकने के लिए, Ctrl+C पर टैप करें.

सर्वर, पोर्ट 8080 पर मौजूद सभी चीज़ों को दिखाता है:

• / — Flutter वेब ऐप्लिकेशन (खरीदारी का यूज़र इंटरफ़ेस)
• /api/ — ADK REST एंडपॉइंट (इन्हें Flutter ऐप्लिकेशन कॉल करता है)
• ADK Dev UI — यह / पर भी उपलब्ध होता है, जब कोई Flutter बिल्ड नहीं होता है. यह एजेंट को सीधे तौर पर डीबग करने के लिए फ़ायदेमंद होता है

आउटपुट से जुड़ी समस्या हल करना ./run.sh

Flutter build not found — run flutter build web ... बैकएंड शुरू हो गया है, लेकिन कोई यूज़र इंटरफ़ेस (यूआई) उपलब्ध नहीं है. आपने पहला चरण छोड़ दिया है या बिल्ड नहीं हो पाया. टर्मिनल B में:

cd ~/fashion_app_demo/flutter_frontend
flutter pub get
flutter build web

टर्मिनल A के बैकएंड को चालू रहने दें. यह अगले अनुरोध पर नया बिल्ड चुन लेगा. इसके लिए, रीस्टार्ट करने की ज़रूरत नहीं है.

Error 401 ... CREDENTIALS_MISSING जब उपयोगकर्ता कोई फ़ोटो अपलोड करता है बैकएंड चल रहा है, लेकिन Vertex AI से पुष्टि नहीं हो पा रही है. एडीसी मौजूद नहीं है या पुराना है. टर्मिनल A से, प्रोजेक्ट सेटअप करने का सातवां चरण फिर से करें:

gcloud auth application-default login
gcloud auth application-default set-quota-project $(gcloud config get-value project)

इसके बाद, टर्मिनल A में रीस्टार्ट करने से पहले, पुराने क्रेडेंशियल वाले सभी एनवायरमेंट वैरिएबल भी मिटा दें:

unset GOOGLE_APPLICATION_CREDENTIALS
./run.sh

यह पक्का करें कि एडीसी, खास तौर पर Vertex AI के लिए काम करता हो. अगर ज़रूरी हो, तो $PROJECT_ID को बदलें:

ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
curl -sS -X POST \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -H "x-goog-user-project: $(gcloud config get-value project)" \
 "https://aiplatform.googleapis.com/v1beta1/projects/$(gcloud config get-value project)/locations/global/publishers/google/models/gemini-3-flash-preview:generateContent" \
 -d '{"contents":[{"role":"user","parts":[{"text":"ping"}]}]}'

अगर यह JSON candidates ऐरे दिखाता है, तो इसका मतलब है कि एडीसी ठीक से काम कर रहा है. समस्या कहीं और है. अगर SERVICE_DISABLED के साथ 403 गड़बड़ी होती है, तो gcloud services enable aiplatform.googleapis.com को फिर से चलाएं. अगर PERMISSION_DENIED के साथ 403 गड़बड़ी होती है, तो इसका मतलब है कि आपके खाते के पास इस प्रोजेक्ट के लिए roles/aiplatform.user नहीं है.

Warning: The user provided project/location will take precedence over the API key from the environment variable. आपको यह सूचना हर एजेंट के लिए एक बार दिखेगी. हालांकि, कुल मिलाकर यह सूचना आपको चार बार दिखेगी. इससे कोई नुकसान नहीं होता. Go कोड, जान-बूझकर एडीसी + प्रोजेक्ट का इस्तेमाल कर रहा है. एसडीके सिर्फ़ यह सूचना दे रहा है कि आपके एनवायरमेंट में मौजूद किसी भी GOOGLE_API_KEY को अनदेखा किया जा रहा है. इसकी सबसे सामान्य वजह यह है कि कोडलैब के पुराने वर्शन में मौजूद .env फ़ाइल में GOOGLE_API_KEY=... लाइन शामिल थी. चेतावनी की आवाज़ बंद करने के लिए, .env को फिर से जनरेट करें:

export PROJECT_ID=$(gcloud config get-value project)
cd ~/fashion_app_demo/adk_backend
cat > .env << EOF
GOOGLE_CLOUD_PROJECT=$PROJECT_ID
GCS_BUCKET=fashion-app-$PROJECT_ID
EOF

इसके बाद, टर्मिनल A में ./run.sh को रीस्टार्ट करें. यह भी देखें कि $PROJECT_ID में कोई वैल्यू मौजूद है या नहीं. इसके बाद ही .env जनरेट करें — अगर मौजूदा gcloud कॉन्फ़िगरेशन में कोई प्रोजेक्ट नहीं है, तो gcloud config get-value project, (unset) दिखाता है. इससे एक खाली .env और एक bucket doesn't exist गड़बड़ी जनरेट होती है.

storage: bucket doesn't exist: Error 404 आपके .env में GCS_BUCKET की वैल्यू मौजूद नहीं है या गलत है. cat ~/fashion_app_demo/adk_backend/.env चलाएं — अगर GCS_BUCKET=fashion-app- (काटा गया, कोई प्रोजेक्ट नहीं), तो छठे चरण को चलाने पर gcloud config get-value project खाली दिखता है. समस्या ठीक करने के लिए:

gcloud config set project YOUR_PROJECT_ID
# then regenerate .env as in step 6

यह भी पुष्टि करें कि इस प्रोजेक्ट पर बकेट मौजूद है: gcloud storage ls gs://fashion-app-$(gcloud config get-value project). अगर ऐसा नहीं है, तो चौथा चरण (बकेट बनाएं) और पांचवां चरण (इमेज अपलोड करें) पूरा करें.

3. वेब की झलक देखने की सुविधा खोलना

1. Cloud Shell में, सबसे ऊपर दाईं ओर मौजूद वेब प्रीव्यू आइकॉन → पोर्ट 8080 पर प्रीव्यू करें पर क्लिक करें
2. Flutter शॉपिंग ऐप्लिकेशन, नए टैब में लोड होता है
3. प्रॉडक्ट कैटलॉग ब्राउज़ करें और कोई आइटम चुनें
4. कपड़े आज़माने की सुविधा शुरू करने के लिए, व्यक्ति के आइकॉन (👤) पर टैप करें
5. कोई फ़ोटो अपलोड करें और एआई को, आज़माने के लिए इमेज जनरेट करते हुए देखें
6. कपड़ों के सुझाव पाने के लिए, "स्टाइल मी" पर टैप करें
7. फ़ॉलो-अप फ़ीडबैक टाइप करें, जैसे कि "इसे और ज़्यादा सामान्य बनाओ" — एक ही सेशन में बेहतर बनाना

Cloud Shell में एक ही ऑरिजिन का होना क्यों ज़रूरी है. अगर बैकएंड 8080 पर और Flutter 8081 पर अलग-अलग चल रहा है, तो Flutter JS (आपके ब्राउज़र में चल रहा है) http://localhost:8080/api को कॉल करने की कोशिश करेगा. हालांकि, ब्राउज़र से localhost का मतलब Cloud Shell VM नहीं, बल्कि आपका लैपटॉप है. दोनों को एक ही पोर्ट से सर्व करने पर, यह समस्या पूरी तरह से ठीक हो जाती है: Flutter ऐप्लिकेशन के एपीआई कॉल, एक ही प्रीव्यू यूआरएल के हिसाब से /api पर जाते हैं.

9. ☁️ Cloud Run पर डिप्लॉय करना

Flutter Build को बैकएंड में बंडल करना

Cloud Run कंटेनर, एपीआई और यूज़र इंटरफ़ेस (यूआई), दोनों को एक इमेज से शिप करता है. Flutter वेब बिल्ड को adk_backend/flutter_web/ में कॉपी करें. जब Go सर्वर को यह तय करना होता है कि कौनसे यूज़र इंटरफ़ेस (यूआई) को दिखाना है, तब वह सबसे पहले इस पाथ की जांच करता है:

cd ~/fashion_app_demo/flutter_frontend
flutter build web
rm -rf ../adk_backend/flutter_web
cp -r build/web ../adk_backend/flutter_web

(अगर आपने स्थानीय तौर पर बदलाव किए हैं, तो हो सकता है कि आपके पास Run-Locally चरण से पहले ही build/web मौजूद हो. flutter build web को फिर से चलाने पर भी कोई समस्या नहीं होगी.)

बैकएंड को डिप्लॉय करना (एपीआई + यूज़र इंटरफ़ेस (यूआई) उपलब्ध कराता है)

cd ~/fashion_app_demo/adk_backend

gcloud run deploy fashion-app-backend \
 --source . \
 --region us-central1 \
 --allow-unauthenticated \
 --set-env-vars "GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GCS_BUCKET=fashion-app-$PROJECT_ID" \
 --memory 1Gi \
 --cpu 2 \
 --timeout 300s \
 --min-instances 0 \
 --max-instances 3

डिप्लॉय होने के बाद, आपको https://fashion-app-backend-xyz-uc.a.run.app जैसा सेवा का यूआरएल मिलेगा. इसे ब्राउज़र में खोलें — Flutter शॉपिंग ऐप्लिकेशन, / से लोड होता है. साथ ही, इसके एपीआई कॉल एक ही होस्ट पर /api/ पर जाते हैं. फ़्रंटएंड कॉन्फ़िगरेशन में बदलाव करने की ज़रूरत नहीं है. साथ ही, कोई एपीआई पासकोड नहीं भेजा गया है.

app_config.dart, एक ही ऑरिजिन वाले रिलेटिव यूआरएल /api का इस्तेमाल करता है. इसलिए, डिप्लॉय किया गया Flutter ऐप्लिकेशन, डिप्लॉय किए गए बैकएंड से अपने-आप कम्यूनिकेट करता है. एक ही बिल्ड, बिना किसी बदलाव के लोकल तौर पर और Cloud Run पर काम करता है.

Cloud Run सेवा खाते की अनुमतियां. Cloud Run जिस डिफ़ॉल्ट Compute Engine सेवा खाते के तौर पर काम करता है उसे roles/aiplatform.user (Vertex AI को कॉल करना) और roles/storage.objectUser (आपके बकेट को पढ़ना/लिखना) की अनुमति चाहिए. ज़्यादातर नए प्रोजेक्ट में, डिफ़ॉल्ट Editor भूमिका में ये दोनों अनुमतियां शामिल होती हैं. इसलिए, आम तौर पर डिप्लॉयमेंट बिना किसी बदलाव के काम करता है. अगर आपने अपने प्रोजेक्ट के IAM को ज़्यादा सुरक्षित बनाया है, तो इन दोनों भूमिकाओं के लिए साफ़ तौर पर अनुमति दें:

SA=$(gcloud iam service-accounts list \
 --filter="email:*[e-mail]" \
 --format="value(email)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member="serviceAccount:$SA" --role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member="serviceAccount:$SA" --role="roles/storage.objectUser"

डिप्लॉयमेंट की पुष्टि करना

अपने ब्राउज़र में Cloud Run का यूआरएल खोलें और पूरा फ़्लो आज़माएं:

1. ब्राउज़ करें → कोई प्रॉडक्ट चुनें
2. आज़माएं → अपनी फ़ोटो अपलोड करें → एआई से जनरेट की गई इमेज देखें
3. स्टाइल मी → जगह/मौके की जानकारी भरें → क्यूरेट किए गए कपड़े देखें
4. सुझाव/राय दें या शिकायत करें → "इसे ज़्यादा कैज़ुअल बनाओ" टाइप करें → अपडेट किए गए कपड़े देखें
5. बैग में जोड़ें → खरीदारी की प्रोसेस पूरी करें

10. 🎉 निष्कर्ष

आपने क्या बनाया

आपने एआई की मदद से काम करने वाली खुदरा शॉपिंग की सभी सुविधाओं का इस्तेमाल किया है. जैसे:

• ✅ मल्टी-एजेंट बैकएंड, जिसमें चार विशेषज्ञ एजेंट एक साथ काम करते हैं
• ✅ वर्चुअल फ़िटिंग रूम, जो हर व्यक्ति के हिसाब से, कपड़े आज़माने की इमेज जनरेट करता है
• ✅ एक एआई स्टाइलिस्ट, जो बातचीत के ज़रिए कपड़ों के कॉम्बिनेशन बनाता है और उन्हें बेहतर बनाता है
• ✅ क्रॉस-प्लैटफ़ॉर्म Flutter ऐप्लिकेशन, जो एजेंट के बैकएंड से कनेक्ट होता है
• ✅ ज़्यादा उपयोगकर्ताओं को हैंडल करने वाले, बिना किसी रुकावट के होस्ट किए जा सकने वाले, और बिना सर्वर के काम करने वाले ऐप्लिकेशन के लिए, Cloud Run डिप्लॉयमेंट

खास कॉन्सेप्ट

सिद्धांत	आपने इसे कहां देखा
ADK की मदद से मल्टी-एजेंट ऑर्केस्ट्रेशन	रूट एजेंट, फ़िटिंग रूम, कैटलॉग, और स्टाइलिस्ट एजेंट को रूट करता है
Gemini की मल्टीमॉडल इमेज जनरेट करने की सुविधा	fitting_tool उपयोगकर्ता की फ़ोटो को प्रॉडक्ट की इमेज के साथ जोड़ना
बातचीत करने वाले एआई के लिए सेशन की स्थिति	स्टाइलिश, बार-बार मिलने वाले फ़ीडबैक के लिए सेशन का फिर से इस्तेमाल कर रहा है
बाइनरी डेटा के लिए आर्टफ़ैक्ट स्टोरेज	इमेज स्टोरेज को टेक्स्ट वाले जवाबों से अलग करना
मिडलवेयर लॉजिक के लिए कॉलबैक	SaveIncomingBlobs, InjectPreviousProducts, SaveSelectedProducts
Flutter में MVVM + Provider	ChangeNotifier के साथ TryItOnProvider और StylingProvider
एजेंटिक हैंडऑफ़	StyleRequest एजेंटों के बीच मल्टीमॉडल कॉन्टेक्स्ट पास करना

अगले चरण

• 🎨 एजेंट के प्रॉम्प्ट को पसंद के मुताबिक बनाएं — स्टाइलिस्ट की पर्सनैलिटी बदलने के लिए, instructions.md में बदलाव करें
• 🛍️ ज़्यादा प्रॉडक्ट जोड़ें — catalog.yaml को नए आइटम के साथ अपडेट करें
• 📱 मोबाइल के लिए बनाएं — flutter build ios या flutter build apk चलाएं
• 🔄 परसिस्टेंट सेशन जोड़ना — InMemoryService को डेटाबेस से बैकअप लिए गए इंप्लिमेंटेशन से बदलें
• 🔒 पुष्टि करने की सुविधा जोड़ना — IAM की मदद से Cloud Run एंडपॉइंट को सुरक्षित करना

संसाधन

• ADK का दस्तावेज़ — एजेंट डेवलपमेंट किट के आधिकारिक दस्तावेज़
• ADK Go का सोर्स कोड — GitHub रिपॉज़िटरी
• ADK Go पैकेज के बारे में जानकारी — एपीआई के बारे में जानकारी
• Gemini API का दस्तावेज़ — मॉडल की सुविधाएं और गाइड
• Flutter Provider Package — स्टेट मैनेजमेंट के दस्तावेज़
• Cloud Run का दस्तावेज़ — डिप्लॉयमेंट और स्केलिंग से जुड़ी गाइड