👗 Flutter, ADK Go ও Gemini ব্যবহার করে একটি ভার্চুয়াল ফিটিং রুম এবং এআই স্টাইলিস্ট তৈরি করুন

১. ভূমিকা

আপনি যা তৈরি করবেন

এই কোডল্যাবে, আপনি একজন ডেভেলপারের ভূমিকায় অবতীর্ণ হয়ে একটি কাল্পনিক রিটেইল ব্র্যান্ডের জন্য ‘ফ্যাশন অ্যাপ’ নামের একটি ফ্লাটার শপিং অ্যাপ তৈরি করবেন। আপনার কাজ হলো: দুটি এআই-চালিত ফিচার যোগ করা, যা অনলাইন শপিং-এর অভিজ্ঞতাকে আমূল বদলে দেবে।

1. ভার্চুয়াল ফিটিং রুম — একজন ব্যবহারকারী নিজের একটি ছবি আপলোড করেন, একটি পোশাক নির্বাচন করেন এবং সেই পোশাকটি পরা অবস্থায় এআই দ্বারা তৈরি নিজের একটি ছবি দেখতে পান।
2. এআই স্টাইলিস্ট — ব্যবহারকারীর অবস্থান, উপলক্ষ এবং স্টাইলের পছন্দের উপর ভিত্তি করে একটি এআই এজেন্ট সম্পূর্ণ পোশাকের সুপারিশ তৈরি করে দেয় — এবং ব্যবহারকারী কথোপকথনের মাধ্যমে সেগুলোকে আরও পরিমার্জন করতে পারেন।

মূল ধারণাটি খুবই সহজ: মানুষ যখন ট্রায়াল রুমে পোশাক পরে দেখে, তখন তাদের সেগুলো কেনার সম্ভাবনা অনেক বেশি থাকে। কিন্তু অনলাইনে? সেটা কেবলই আন্দাজ করা। এই প্রকল্পটি কৃত্রিম বুদ্ধিমত্তার মাধ্যমে সেই ব্যবধানটি পূরণ করে।

স্থাপত্যের এক ঝলক

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

মূল প্রযুক্তি

উপাদান	প্রযুক্তি	উদ্দেশ্য
এজেন্ট ফ্রেমওয়ার্ক	Go-এর জন্য ADK (এজেন্ট ডেভেলপমেন্ট কিট)	মাল্টি-এজেন্ট অর্কেস্ট্রেশন, সেশন, আর্টিফ্যাক্ট
এজেন্ট যুক্তি (প্রো)	জেমিনি ৩.১ প্রো প্রিভিউ	ফিটিং রুম এবং স্টাইলিস্ট এজেন্টদের ক্ষমতা দেয়
এজেন্ট যুক্তি (ফ্ল্যাশ)	জেমিনি ৩ ফ্ল্যাশ প্রিভিউ	রুট এবং ক্যাটালগ এজেন্টদের (লাইটওয়েট রাউটিং/লুকআপ) শক্তি যোগায়।
চিত্র তৈরি	জেমিনি ২.৫ ফ্ল্যাশ ইমেজ	ট্রাই-অন এবং পোশাকের ছবি তৈরি করে
ফ্রন্টএন্ড	ফ্লাটার (ডার্ট)	ক্রস-প্ল্যাটফর্ম অ্যাপ (ওয়েব, আইওএস, অ্যান্ড্রয়েড)
স্টোরেজ	গুগল ক্লাউড স্টোরেজ	পণ্যের ছবি এবং তৈরি করা নিদর্শনগুলি সংরক্ষণ করে
হোস্টিং	ক্লাউড রান	সার্ভারবিহীন কন্টেইনার স্থাপন

২. 📦 পূর্বশর্ত ও ক্লাউড শেল সেটআপ

১. ক্লাউড শেল এডিটর খুলুন

👉 আপনার ব্রাউজারে ক্লাউড শেল এডিটর খুলুন।

যদি টার্মিনালটি স্ক্রিনের নীচে প্রদর্শিত না হয়:

• ভিউ → টার্মিনাল-এ ক্লিক করুন

ক্লাউড শেলে Go, Git, এবং gcloud CLI আগে থেকেই ইনস্টল করা থাকে — কোনো লোকাল সেটআপের প্রয়োজন নেই।

২. ফ্লাটার এসডিকে সেট আপ করুন

ক্লাউড শেল-এর সাথে /google/flutter এ ফ্লাটার আগে থেকেই ইনস্টল করা থাকে। যেহেতু ওই ডিরেক্টরিটি অন্য একজন সিস্টেম ব্যবহারকারীর মালিকানাধীন, তাই আপনি প্রথমবার flutter চালানোর সময় একটি fatal: detected dubious ownership ত্রুটি পাবেন। এটিকে একবার গিট-এর নিরাপদ-ডিরেক্টরি তালিকায় যোগ করুন:

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

ফ্লাটার আপনার PATH এ আছে এবং কাজ করছে কিনা তা যাচাই করুন:

flutter --version

প্রথমবার চালালে ডার্ট এসডিকে ডাউনলোড হয় এবং ফ্লাটার টুলটি বিল্ড হয় — এক মিনিট অপেক্ষা করুন। আপনি Flutter 3.x • channel stable . এর মতো কিছু দেখতে পাবেন।

বান্ডেল করা ফ্লাটারটি ব্যবহার করুন। যদি আপনি আপনার নিজস্ব স্টেবল ক্লোন পিন করতে চান (যেমন, একটি নির্দিষ্ট ফ্লাটার সংস্করণের জন্য), তাহলে চালান:

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 উপর প্রাধান্য পাবে।

৩. রিপোজিটরি ক্লোন করুন

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

৪. প্রকল্পের কাঠামো অন্বেষণ করুন

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/ — যেখানে এআই এজেন্টগুলো থাকে। প্রতিটি এজেন্টের নিজস্ব প্যাকেজ রয়েছে, যাতে গো কোড ও মার্কডাউন নির্দেশাবলী থাকে।
• flutter_frontend/lib/workshop_tasks/ — যেখানে ফ্লাটার UI সেই এজেন্টগুলোর সাথে সংযোগ স্থাপন করে।
• flutter_frontend/lib/core_app/ — এটি আগে থেকে তৈরি করা শপিং অ্যাপ। আপনাকে এটি পরিবর্তন করতে হবে না।

৩. ☁️ গুগল ক্লাউড প্রজেক্ট সেটআপ

১. একটি নতুন প্রকল্প তৈরি করুন

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

প্রজেক্ট আইডিটি আগে থেকে নেওয়া থাকলে, এর সাথে একটি র‍্যান্ডম সংখ্যা জুড়ে দিন (যেমন, fashion-app-demo-42 )।

২. একটি বিলিং অ্যাকাউন্ট লিঙ্ক করুন

এই কোডল্যাবটি ধরে নেয় যে আপনার ইতিমধ্যেই একটি সক্রিয় বিলিং অ্যাকাউন্ট আছে। Vertex AI, Cloud Build, এবং Cloud Run সবগুলোর জন্যই বিলিং প্রয়োজন — এটি ছাড়া, পরবর্তী ধাপটি ( gcloud services enable ) aiplatform.googleapis.com এবং cloudbuild.googleapis.com এর জন্য ব্যর্থ হবে, এবং এমনকি যে API-গুলো সক্রিয় হবে, সেগুলোও আসলে ওয়ার্কলোড চালাবে না।

আপনার বিলিং অ্যাকাউন্টগুলির তালিকা দিন:

gcloud billing accounts list

দেখুন

OPEN

কলাম। এখানে অবশ্যই True লেখা থাকতে হবে। যদি False লেখা থাকে (যা মেয়াদোত্তীর্ণ ফ্রি ট্রায়ালের ক্ষেত্রে সাধারণ), তাহলে অ্যাকাউন্টটি বন্ধ হয়ে গেছে এবং আপনি আসলে কোনো কিছুর জন্য অর্থ প্রদান করবেন না — এগিয়ে যাওয়ার আগে নিচের ট্রাবলশুটিং ব্লকে চলে যান।

একটি OPEN: True অ্যাকাউন্টের ACCOUNT_ID (যা 0X0X0X-0X0X0X-0X0X0X এর মতো দেখতে) কপি করুন এবং আপনার প্রোজেক্টের সাথে লিঙ্ক করুন:

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- এ গিয়ে একটি তৈরি করুন। নতুন গুগল ক্লাউড ব্যবহারকারীরা ৩০০ ডলারের ফ্রি ক্রেডিট পান, যা এই কোডল্যাবের জন্য যথেষ্ট — এখানকার জেমিনি এপিআই কল এবং ক্লাউড রান ব্যবহারে মাত্র কয়েক সেন্ট খরচ হয়। ভেরিফিকেশনের জন্য আপনার একটি ক্রেডিট কার্ড লাগবে, কিন্তু আপনি ফ্রি টিয়ার অতিক্রম করে পেইড অ্যাকাউন্ট বেছে না নেওয়া পর্যন্ত আপনার থেকে কোনো চার্জ কাটা হবে না।

সমস্যা সমাধান: 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. ক্লাউড শেলে ফিরে গিয়ে সমাধানটি নিশ্চিত করুন:

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

   এখন এটি অন্তত একটি অ্যাকাউন্ট ফেরত দেবে। সেই ACCOUNT_ID দিয়ে উপরের link কমান্ডটি আবার চালান, তারপর পরবর্তী ধাপে enable কমান্ডটি পুনরায় চেষ্টা করুন।

কোডল্যাবটি ব্যবহার করতে প্রকৃত খরচ হয় মাত্র কয়েক সেন্ট — একটি কার্ড যোগ করলে কোনো চলমান চার্জ ছাড়াই এপিআইগুলো আনলক করা যায়।

৩. প্রয়োজনীয় এপিআইগুলো সক্রিয় করুন

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

এপিআই	উদ্দেশ্য
aiplatform.googleapis.com	ভার্টেক্স এআই — fitting_tool ভার্টেক্স এআই-এর মাধ্যমে জেমিনির ইমেজ জেনারেশনকে কল করে।
storage.googleapis.com	ক্লাউড স্টোরেজ — পণ্যের ক্যাটালগের ছবি এবং তৈরি করা ট্রাই-অন ফলাফল সংরক্ষণ করে
run.googleapis.com	ক্লাউড রান — ব্যাকএন্ডকে একটি সার্ভারলেস কন্টেইনার হিসেবে হোস্ট করে
cloudbuild.googleapis.com	ক্লাউড বিল্ড — সোর্স থেকে ডকার ইমেজ তৈরি করে
artifactregistry.googleapis.com	আর্টিফ্যাক্ট রেজিস্ট্রি — নির্মিত ডকার ইমেজ সংরক্ষণ করে

৪. একটি 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

গুগল ক্লাউডের সর্বত্র বাকেটের নামগুলো বিশ্বব্যাপী অনন্য। যেহেতু $PROJECT_ID ইতিমধ্যেই অনন্য, fashion-app-$PROJECT_ID ও অনন্য হবে। --uniform-bucket-level-access ফ্ল্যাগটি হলো আধুনিক ডিফল্ট — এটি IAM-এর সুবিধার জন্য পুরোনো ACL-গুলোকে নিষ্ক্রিয় করে দেয়।

৫. পণ্যের ক্যাটালগের ছবি আপলোড করুন

ব্যাকএন্ডের getProductImage টুলটি gs://$GCS_BUCKET/catalog-assets/images/ থেকে ডেটা পড়ে। 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/

৬. .env ফাইলটি কনফিগার করুন।

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

কোনো এপিআই কী-এর প্রয়োজন নেই। ভার্টেক্স এআই (জেমিনি কল) এবং ক্লাউড স্টোরেজ (ইমেজ আপলোড/ডাউনলোড) উভয়ই অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়াল -এর মাধ্যমে অথেন্টিকেট করে — যা পরবর্তী ধাপে সেট আপ করা হবে। .env ফাইলটি শুধু ব্যাকএন্ডকে বলে দেয় কোন প্রজেক্ট এবং বাকেট ব্যবহার করতে হবে।

৭. অ্যাপ্লিকেশনের ডিফল্ট ক্রেডেনশিয়াল দিয়ে প্রমাণীকরণ করুন

স্থানীয়ভাবে ব্যাকএন্ড চালু করার আগে আপনাকে অবশ্যই এটি চালাতে হবে। গো ব্যাকএন্ডটি ভার্টেক্স এআই (জেমিনি) এবং ক্লাউড স্টোরেজে প্রতিটি কল প্রমাণীকরণের জন্য এডিসি (ADC) ব্যবহার করে। এডিসি ছাড়া, ব্যাকএন্ডটি চালু হবে ঠিকই, কিন্তু প্রতিটি ট্রাই-অন রিকোয়েস্ট ৪০১ 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)

ADC সুস্থ আছে কিনা যাচাই করুন:

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

আপনি একটি টোকেনের প্রায় ২০টি অক্ষর দেখতে পাবেন, যার পরে ... থাকবে। যদি কোনো ত্রুটি হয়, তার মানে লগইনটি সফল হয়নি — ধাপ ১ আবার চালান।

সবকিছুর জন্য একটিই অথোরাইজেশন পাথ। Go কোডটি Gemini-এর জন্য আপনার প্রজেক্ট আইডি সহ Backend: genai.BackendVertexAI ব্যবহার করে, এবং ক্লাউড স্টোরেজ ক্লায়েন্ট gs:// তে রিড/রাইট করার জন্য একই ADC ব্যবহার করে। পরবর্তীতে যখন আপনি Cloud Run-এ ডিপ্লয় করবেন, তখন ADC স্বয়ংক্রিয়ভাবে Cloud Run সার্ভিস অ্যাকাউন্ট দ্বারা প্রতিস্থাপিত হয়ে যাবে — কোনো অথোরাইজেশন কোড পরিবর্তনের প্রয়োজন নেই।

প্রতিটি নতুন অ্যাকাউন্ট বা নতুন ক্লাউড শেল সেশনের জন্য আপনাকে এটি পুনরায় করতে হবে। প্রতিটি গুগল অ্যাকাউন্টের জন্য ADC ~/.config/gcloud/application_default_credentials.json ফাইলে সংরক্ষিত থাকে। আপনি যদি অ্যাকাউন্ট পরিবর্তন করেন (অথবা ক্লাউড শেল আপনাকে একটি ক্ষণস্থায়ী হোম অ্যাকাউন্ট দেয়), তাহলে ফাইলটি অনুপস্থিত বা পুরোনো হয়ে যেতে পারে। উপরের উভয় কমান্ড আবার চালান। পুরোনো ADC-এর লক্ষণ: কোডল্যাবের সেটআপ আগে সম্পন্ন হওয়ার পরেও ব্যাকএন্ড লগগুলিতে 401 CREDENTIALS_MISSING দেখা যায়।

৪. 🏗️ স্থাপত্যের সংক্ষিপ্ত বিবরণ

এখন যেহেতু পরিবেশ প্রস্তুত, কোড দেখার আগে চলুন সিস্টেমটি কীভাবে কাজ করে তা বুঝে নেওয়া যাক।

চার-এজেন্ট সিস্টেম

ব্যাকএন্ডটি Go-এর জন্য ADK (এজেন্ট ডেভেলপমেন্ট কিট) ব্যবহার করে একটি মাল্টি-এজেন্ট সিস্টেম হিসেবে তৈরি করা হয়েছে। চারটি এজেন্ট একসাথে কাজ করে, যাদের প্রত্যেকের একটি নির্দিষ্ট দায়িত্ব রয়েছে:

                   ┌──────────────┐
                   │ 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 থেকে শুরু হয়, যা এজেন্টগুলোকে একত্রিত করে এবং HTTP সার্ভার চালু করে:

// 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 আর্টিফ্যাক্ট (তৈরি করা ছবি) গুগল ক্লাউড স্টোরেজে সংরক্ষণ করে, ফলে সেগুলো একাধিক অনুরোধের পরেও অক্ষত থাকে এবং GCS URI-এর মাধ্যমে শেয়ার করা যায়।

৫. 🤖 এডিকে (এজেন্ট ডেভেলপমেন্ট কিট) নিয়ে বিস্তারিত আলোচনা

ADK কী?

এজেন্ট ডেভেলপমেন্ট কিট (ADK) হলো গুগলের একটি ওপেন-সোর্স ফ্রেমওয়ার্ক, যা দিয়ে Go (এবং Python/Java) ব্যবহার করে এআই এজেন্ট তৈরি করা যায়। এটি আপনার অ্যাপ্লিকেশন এবং জেমিনি এপিআই-এর মধ্যবর্তী স্তর হিসেবে কাজ করে।

আপনি সরাসরি জেমিনি এপিআই কল করতে পারেন । কিন্তু যখন আপনার অ্যাপের প্রয়োজন হবে:

• ক্যাটালগ থেকে পণ্য অনুসন্ধান করুন
• ব্যবহারকারীর তোলা ছবির উপর ভিত্তি করে ইমেজ তৈরি করুন।
• মনে করুন আগে কোন পোশাকগুলোর পরামর্শ দেওয়া হয়েছিল।
• একাধিক এআই এজেন্টের মধ্যে সমন্বয় সাধন করুন

আপনার একটি কাঠামো প্রয়োজন। ADK সেই কাঠামোটি প্রদান করে।

এজেন্ট লুপ

প্রতিটি 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

এর ফলে প্রম্পটগুলো ইনলাইন স্ট্রিং হিসেবে না থেকে আলাদা, সংস্করণযোগ্য নথি হিসেবে সংরক্ষিত থাকে।

সরঞ্জাম

টুল হলো গো ফাংশন যা এলএলএম কল করতে পারে। এডিকে এলএলএম-এর টুল-কলিং ফরম্যাট এবং আপনার টাইপ করা গো ফাংশনের মধ্যে অনুবাদের কাজটি পরিচালনা করে:

// 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)

ADK স্বয়ংক্রিয়ভাবে আপনার Go struct-গুলো থেকে একটি JSON স্কিমা তৈরি করে এবং সেটি LLM-এ পাঠায়। যখন LLM 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 যা একটি ক্যাশড রেসপন্স রিটার্ন করে, সেটি প্রকৃত LLM কলটি সম্পূর্ণরূপে এড়িয়ে যাবে।

JSON স্কিমা প্রয়োগ

ফিটিং রুম এবং স্টাইলিস্ট এজেন্ট উভয়ই এলএলএম-কে স্ট্রাকচার্ড JSON-এ উত্তর দিতে বাধ্য করে:

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

এটি নিশ্চিত করে যে ফ্লাটার ফ্রন্টএন্ড সর্বদা পার্সযোগ্য ডেটা গ্রহণ করে, কোনো অপরিকল্পিত টেক্সট নয়।

ক্যাটালগ এজেন্ট: সরলতম উদাহরণ

ক্যাটালগ এজেন্ট ( 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, এবং সবশেষে লোকাল ফাইলগুলো চেষ্টা করে। একবার লোড হয়ে গেলে, ছবিটি একটি আর্টিফ্যাক্ট হিসেবে ক্যাশ করা হয়, ফলে পরবর্তী কলগুলো তাৎক্ষণিকভাবে সম্পন্ন হয়।

৬. 🧪 এআই পাইপলাইন: এজেন্টদের কার্যকলাপ

এবার চলুন সবচেয়ে অত্যাধুনিক দুটি এজেন্ট নিয়ে আলোচনা করা যাক — যেগুলো প্রকৃতপক্ষে ছবি তৈরি করে এবং পোশাক নির্বাচন করে।

৬.১ ফিটিং রুম এজেন্ট

ফাইল:

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:// URI — এটি পূর্বে তৈরি করা একটি ফিটিং ফলাফল, যা বিভিন্ন সেশনে পুনরায় ব্যবহারের জন্য GCS-এ সংরক্ষিত থাকে।

এই দ্বৈত-পথের নকশাটি ইচ্ছাকৃত: স্টাইলিস্ট এজেন্ট যখন পরবর্তীতে পোশাক ট্রাই-অন তৈরি করে, তখন এটি প্রাথমিক ফিটিং রুমের ফলাফল থেকে GCS URL-টি পুনরায় ব্যবহার করে, যাতে সমস্ত পোশাকের ক্ষেত্রে ব্যবহারকারীর পরিচয় একই থাকে।

ধাপ ২: মাল্টিমোডাল প্রম্পটটি তৈরি করুন

   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 থেকে এমবেড করা) অত্যন্ত গুরুত্বপূর্ণ — এটি জেমিনিকে নির্দেশ দেয় যেন ব্যবহারকারীর পরিচয় (মুখ, শারীরিক গঠন, ত্বকের রঙ, চুল) অক্ষুণ্ণ রেখে শুধুমাত্র পোশাকটি প্রয়োগ করা হয়। এই নির্দিষ্ট নির্দেশনাটি ছাড়া, মডেলটি হয়তো ব্যক্তিটির চেহারা পরিবর্তন করে ফেলতে পারে।

ধাপ ৩: ছবি তৈরির জন্য জেমিনিকে ডাকুন

   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 এন্ডপয়েন্টের পেছনে থাকে এবং একই ADC ক্লাউড স্টোরেজ অ্যাক্সেসের অনুমোদনও দেয়—প্রতিটি কলের জন্য একটিমাত্র ক্রেডেনশিয়াল।

ধাপ ৪: ফলাফলটি সংরক্ষণ করুন।

   // 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

ফিটিং রুম এবং স্টাইলিস্টের মধ্যে এজেন্ট হস্তান্তরের মূল চাবিকাঠি হলো ডুয়াল-সেভ (আর্টিফ্যাক্ট + জিসিএস)। আর্টিফ্যাক্টটি বর্তমান সেশনের মধ্যে তাৎক্ষণিক অ্যাক্সেস প্রদান করে, অন্যদিকে জিসিএস ইউআরআই স্টাইলিস্টকে (যিনি একটি ভিন্ন সেশনে কাজ করেন) পরবর্তীতে একই ছবিটি রেফারেন্স করার সুযোগ দেয়।

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) রিটার্ন করার মাধ্যমে, কলব্যাকটি সংকেত দেয় যে, "আমার প্রিপ্রসেসিং শেষ — এখন এজেন্টটিকে স্বাভাবিকভাবে চালান।" যদি এটি nil ছাড়া অন্য কোনো কন্টেন্ট রিটার্ন করত, তবে এটি এজেন্টটিকে সম্পূর্ণরূপে শর্ট-সার্কিট করে দিত।

৬.২ স্টাইলিস্ট এজেন্ট

ফাইল:

adk_backend/stylist/agent.go

স্টাইলিস্ট এজেন্টটি এই সিস্টেমের সবচেয়ে অত্যাধুনিক ব্যবস্থা। এটি ব্যক্তিগত প্রয়োজন অনুযায়ী পোশাকের সুপারিশ তৈরি করে এবং কথোপকথনের মাধ্যমে বারবার পরিমার্জনে সহায়তা করে।

তিনটি পুনরাবৃত্তি — স্টাইলিস্টের স্মৃতি

স্টাইলিস্ট একাধিক পালাবিশিষ্ট কথোপকথনে প্রাসঙ্গিকতা বজায় রাখতে তিনটি রেফারেন্স ব্যবহার করেন:

কলব্যাক ১:

InjectPreviousProducts (বিফোরমডেল)

সমস্যাটি হলো: যদি ব্যবহারকারী বলেন "আমাকে বিভিন্ন বিকল্প দেখাও," তাহলে এলএলএম (LLM) হয়তো আবারও একই পণ্যগুলোই সুপারিশ করতে পারে, কারণ এটি আগে কী সুপারিশ করেছে তা সহজাতভাবে ট্র্যাক করে না।

সমাধান: প্রতিটি প্রতিক্রিয়ার পরে, প্রোডাক্ট আইডিগুলি সেশন স্টেটে সংরক্ষণ করা হয়। পরবর্তী LLM কল করার আগে, এই কলব্যাকটি সেগুলি পড়ে এবং একটি ইঙ্গিত যোগ করে:

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 (মডেলের আগে)

সমস্যাটি হলো: যখন ব্যবহারকারী মতামত দেন ("আরও ক্যাজুয়াল করুন"), তখন পরবর্তী মেসেজে তাঁর ছবি আর যুক্ত করা হয় না। কিন্তু ফিটিং টুলটির জন্য ছবিটি প্রয়োজন।

সমাধান: প্রথম অনুরোধে, এই কলব্যাকটি ব্যবহারকারীর ছবির রেফারেন্স বের করে স্টেটে সংরক্ষণ করে। পরবর্তী অনুরোধগুলোতে, এটি পুনরায় তা যুক্ত করে:

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 (মডেলের পরে)

LLM পোশাকের পরামর্শ দিয়ে সাড়া দেওয়ার পর, এই কলব্যাকটি 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

৬.৩ মূল এজেন্ট

ফাইল:

adk_backend/rootagent/agent.go

সবচেয়ে সরল এজেন্ট — মাত্র ৩১ লাইন:

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 (দ্রুততম মডেল) ব্যবহার করে, কারণ রাউটিং সংক্রান্ত সিদ্ধান্তগুলো সহজ — LLM-কে শুধু ব্যবহারকারীর অভিপ্রায় পড়তে হয় এবং সঠিক সাব-এজেন্ট বেছে নিতে হয়। কোনো টুলের প্রয়োজন নেই; SubAgents স্বয়ংক্রিয়ভাবে দায়িত্ব অর্পণের কাজটি করে।

৭. 📱 ফ্লাটার ফ্রন্টএন্ড আর্কিটেকচার

ফ্লাটার ফ্রন্টএন্ডটি একটি সম্পূর্ণ কার্যকরী রিটেইল শপিং অ্যাপ। এআই ফিচারগুলো 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() এর মাধ্যমে UI-তে পরিবর্তনসমূহ প্রচার করে।
• ভিউ (উইজেট): context.watch () ব্যবহার করে ViewModel-এ সাবস্ক্রাইব করে। context.watch () এবং অবস্থার পরিবর্তন হলে পুনর্নির্মাণ করে
• পরিষেবা : ADK ব্যাকএন্ডে HTTP কল করে এবং টাইপ করা ডেটা ফেরত দেয়।

সার্ভিস লেয়ার

সার্ভিসগুলোকে অ্যাবস্ট্রাক্ট ইন্টারফেস হিসেবে সংজ্ঞায়িত করা হয়, যেগুলোর 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 উভয়ই ADK ব্যাকএন্ডের সাথে যোগাযোগের জন্য একই পদ্ধতি অনুসরণ করে:

ধাপ ১: একটি সেশন তৈরি করুন

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() ) যাতে একাধিকবার কথোপকথন সম্ভব হয়।

স্টেট ম্যানেজমেন্ট: দ্য ট্রাইইটঅনপ্রোভাইডার

ফাইল:

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;

প্রাইভেট স্টেট ট্রানজিশন সামঞ্জস্য নিশ্চিত করে — আপনি কখনোই পুরনো ডেটা মুছে না ফেলে এবং UI-কে অবহিত না করে স্টেট আপডেট করেন না:

 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;
 }

UI: স্টেট রাউটার হিসেবে স্ক্রিন

ফাইল:

workshop_tasks/step_1_try_it_on/ui/2_try_it_on_screen.dart

ট্রাই-অন স্ক্রিনটি প্রোভাইডারের অবস্থার উপর ভিত্তি করে সাব-স্ক্রিনগুলির মধ্যে রাউটিং করার জন্য ডার্ট ৩-এর প্যাটার্ন ম্যাচিং ও 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 নেই — স্টেট এনামের উপর ভিত্তি করে স্ক্রিনের কন্টেন্ট ইন-প্লেস পরিবর্তিত হয়।

এজেন্টিক হস্তান্তর: ফিটিং রুম → স্টাইলিস্ট

সবচেয়ে আকর্ষণীয় ইউএক্স প্যাটার্নটি হলো, অ্যাপটি কীভাবে ফিটিং রুম এজেন্ট থেকে স্টাইলিস্ট এজেন্টের কাছে কনটেক্সট প্রেরণ করে।

5_fitting_room.dart ফাইলে, ট্রাই-অন ইমেজটি তৈরি হওয়ার পর, "Style Me" বাটনটি একটি ফর্ম খোলে। যখন ব্যবহারকারী সাবমিট করেন:

// 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 ব্যবহারকারীর ছবির URL — যাতে স্টাইলিস্ট হুবহু একই ব্যবহারকারীর উপস্থাপনা পুনরায় ব্যবহার করতে পারেন।
• নির্বাচিত পণ্য — তাই স্টাইলিস্ট এটি প্রতিটি পোশাকে অন্তর্ভুক্ত করেন।

এটাই হলো এজেন্টিক হ্যান্ডঅফ — যার মাধ্যমে একটি এআই এজেন্ট থেকে অন্যটিতে মাল্টিমোডাল কনটেক্সট নির্বিঘ্নে স্থানান্তর করা হয়, এবং ব্যবহারকারী শুধুমাত্র একটি সাধারণ ফর্ম দেখতে পান।

স্টাইলিং প্রবাহ: স্টাইলিংপ্রোভাইডার

ফাইল:

workshop_tasks/step_2_style_me/providers/styling_provider.dart

StylingProvider TryItOnProvider চেয়ে সরল, কারণ এটি অধিকাংশ জটিলতা ব্যাকএন্ডের ওপর অর্পণ করে:

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 কলব্যাকগুলো স্বয়ংক্রিয়ভাবে সমস্ত কনটেক্সট ম্যানেজমেন্ট সামলে নেয়।

৮. 🚀 অ্যাপটি স্থানীয়ভাবে চালান

ক্লাউড শেল-এর মসৃণ অভিজ্ঞতার জন্য, গো ব্যাকএন্ড কম্পাইল করা ফ্লাটার ওয়েব অ্যাপটি একই পোর্ট (৮০৮০) থেকে পরিবেশন করে। একটি প্রসেস, একটি প্রিভিউ ইউআরএল, ক্রস-অরিজিন সংক্রান্ত কোনো ঝামেলা নেই, কনফিগারেশন ফাইল সম্পাদনারও প্রয়োজন নেই।

শুরু করার আগে — ADC-টি যৌক্তিকভাবে যাচাই করে নিন।

Vertex AI-কে কল করার জন্য ব্যাকএন্ডের অ্যাপ্লিকেশন ডিফল্ট ক্রেডেনশিয়াল প্রয়োজন। আপনি যদি এই ক্লাউড শেল সেশন এবং এই গুগল অ্যাকাউন্টে প্রজেক্ট সেটআপের ধাপ ৭ সম্পন্ন করে থাকেন, তাহলে আর কিছু করার প্রয়োজন নেই। আপনি যদি বিরতির পর ফিরে আসেন, অ্যাকাউন্ট পরিবর্তন করে থাকেন, বা নিশ্চিত না হন, তাহলে যাচাই করার জন্য ৫ সেকেন্ড সময় নিন:

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

যদি এটি একটি টোকেনের প্রায় ২০টি অক্ষর প্রিন্ট করে, তাহলে আপনার কাজ হয়ে গেছে। যদি কোনো ত্রুটি হয়, তাহলে প্রজেক্ট সেটআপের ধাপ ৭ আবার চালান :

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

আপনি দুটি ক্লাউড শেল টার্মিনাল ব্যবহার করবেন:

• টার্মিনাল A — ব্যাকএন্ড অবিরাম চালু রাখে ( ./run.sh )। এটি খোলা রাখুন।
• টার্মিনাল বি — ফ্লাটার ওয়েব বিল্ড একবার চালায় ( flutter build web )। কাজ শেষ হলে এটি বন্ধ হয়ে যায়।

ক্রমটি গুরুত্বপূর্ণ নয় — আপনি যেকোনো একটি প্রথমে শুরু করতে পারেন। কিন্তু প্রথমবার চালানোর সবচেয়ে মসৃণ অভিজ্ঞতার জন্য, প্রথমে ফ্লাটার বিল্ড করুন, যাতে ব্যাকএন্ড চালু হওয়ার মুহূর্ত থেকেই পরিবেশন করার জন্য একটি UI প্রস্তুত থাকে।

১. টার্মিনাল বি — ফ্লাটার ওয়েব বান্ডেল তৈরি করুন (এককালীন)

একটি নতুন ক্লাউড শেল ট্যাব খুলুন (টার্মিনাল প্যানেলের উপরের + চিহ্নে ক্লিক করুন), তারপর:

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

এটি flutter_frontend/build/web/ নামে একটি ডিরেক্টরি তৈরি করে, যেখানে স্ট্যাটিক ফাইল (HTML, JS, assets) থাকে এবং কাজ শেষ হলে এটি বন্ধ হয়ে যায়। ব্যাকএন্ড ডিরেক্টরিটি দেখামাত্রই ফাইলগুলো পরিবেশন করবে।

যখনই ডার্ট কোড পরিবর্তন করবেন, টার্মিনাল B-তে flutter build web পুনরায় চালান। পরবর্তী অনুরোধে টার্মিনাল A-এর ব্যাকএন্ড নতুন বিল্ডটি গ্রহণ করবে — কোনো রিস্টার্টের প্রয়োজন নেই ।

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

আপনি যদি একটি নতুন ক্লাউড শেল সেশনে থাকেন অথবা সেটআপ চালানোর সময়ের চেয়ে ভিন্ন কোনো গুগল অ্যাকাউন্ট দিয়ে সাইন ইন করে থাকেন, তাহলে এটি দেখতে পাবেন। এর সমাধানটি হলো § পূর্বশর্ত ধাপ ২.২ -এর সেই একই এক লাইনের কমান্ড — এটি প্রতিটি অ্যাকাউন্টের জন্য শুধু একবার চালাতে হবে:

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

এরপর flutter pub get && flutter build web আবার চালান। কনফিগারেশনটি ~/.gitconfig এ সংরক্ষিত থাকে, তাই এই অ্যাকাউন্টের পরবর্তী সেশনগুলোতেও এটি অপরিবর্তিত থাকবে।

২. টার্মিনাল এ — ব্যাকএন্ড চালু করুন (দীর্ঘস্থায়ী প্রক্রিয়া)

আপনার মূল ক্লাউড শেল টার্মিনালে:

cd ~/fashion_app_demo/adk_backend
./run.sh

আপনি এইরকম কিছু দেখতে পাবেন:

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

এই টার্মিনালটি চালু রাখুন — যতক্ষণ run.sh থাকবে, ব্যাকএন্ডও ততক্ষণ সচল থাকবে। এটি বন্ধ করতে Ctrl+C চাপুন।

সার্ভারটি ৮০৮০ পোর্টে সবকিছু উন্মুক্ত করে দেয়:

• / ওয়েব অ্যাপ (শপিং UI)
• /api/ — ADK REST এন্ডপয়েন্ট (ফ্লাটার অ্যাপ দ্বারা কল করা হয়)
• ADK Dev UI — ফ্লাটার বিল্ড না থাকলে এটি / এও পাওয়া যায়; সরাসরি এজেন্ট ডিবাগিংয়ের জন্য উপযোগী।

./run.sh আউটপুটের সমস্যা সমাধান

Flutter build not found — run flutter build web ... ব্যাকএন্ড চালু হয়েছে, কিন্তু পরিবেশন করার মতো কোনো UI নেই। আপনি ধাপ ১ বাদ দিয়েছেন, অথবা বিল্ডটি ব্যর্থ হয়েছে। টার্মিনাল B-তে:

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

টার্মিনাল A-এর ব্যাকএন্ড চালু রাখুন — এটি পরবর্তী অনুরোধে নতুন বিল্ডটি গ্রহণ করবে, রিস্টার্ট করার প্রয়োজন নেই।

ব্যবহারকারী যখন একটি ছবি আপলোড করেন তখন Error 401 ... CREDENTIALS_MISSING ব্যাকএন্ড চালু আছে কিন্তু ভার্টেক্স এআই (Vertex AI)-তে অথেন্টিকেট করতে পারছে না। এডিসি (ADC) অনুপস্থিত অথবা পুরনো। টার্মিনাল এ (Terminal 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

বিশেষভাবে ভার্টেক্স এআই-এর জন্য এডিসি কাজ করে কিনা তা যাচাই করুন (প্রয়োজনে $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 অ্যারে রিটার্ন করে, তাহলে ADC ঠিক আছে; সমস্যাটি অন্য কোথাও। যদি 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 কোডটি ইচ্ছাকৃতভাবে ADC + প্রজেক্ট ব্যবহার করছে, এবং SDK শুধু উল্লেখ করছে যে আপনার এনভায়রনমেন্টে থাকা যেকোনো 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 পুনরায় চালু করুন। .env ফাইল তৈরি করার আগে $PROJECT_ID কোনো ভ্যালু আছে কিনা, তাও যাচাই করে নিন — যদি বর্তমান 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) । যদি না থাকে, তাহলে ধাপ ৪ (বাকেট তৈরি করা) এবং ধাপ ৫ (ছবি আপলোড করা) অনুসরণ করুন।

৩. ওয়েব প্রিভিউ খুলুন

1. ক্লাউড শেলে, ওয়েব প্রিভিউ আইকনে (উপরের-ডানদিকে) ক্লিক করুন → পোর্ট ৮০৮০-তে প্রিভিউ দেখুন।
2. ফ্লাটার শপিং অ্যাপটি একটি নতুন ট্যাবে লোড হয়।
3. পণ্যের ক্যাটালগ ব্রাউজ করুন এবং একটি আইটেম নির্বাচন করুন।
4. ট্রাই-অন প্রক্রিয়া শুরু করতে ব্যক্তির আইকনে (👤) ট্যাপ করুন।
5. একটি ছবি আপলোড করুন এবং দেখুন কীভাবে এআই একটি ট্রাই-অন ইমেজ তৈরি করে।
6. পোশাকের পরামর্শ পেতে 'স্টাইল মি'-তে ট্যাপ করুন।
7. ‘এটিকে আরও অনানুষ্ঠানিক করুন’-এর মতো ফলো-আপ ফিডব্যাক টাইপ করুন — একই সেশনে পরিমার্জন

ক্লাউড শেলে সেম-অরিজিন কেন গুরুত্বপূর্ণ। যদি ব্যাকএন্ড ৮০৮০ পোর্টে এবং ফ্লাটার ৮০৮১ পোর্টে আলাদাভাবে চলত, তাহলে আপনার ব্রাউজারে চলমান ফ্লাটার জেএস http://localhost:8080/api কল করার চেষ্টা করত — কিন্তু ব্রাউজারের localhost বলতে আপনার ল্যাপটপকে বোঝায়, ক্লাউড শেল ভিএম-কে নয়। উভয়কে একই পোর্ট থেকে সার্ভ করলে এই সমস্যার সম্পূর্ণ সমাধান হয়ে যায়: ফ্লাটার অ্যাপের এপিআই কলগুলো একই প্রিভিউ ইউআরএল-এর সাপেক্ষে /api তে যায়।

৯. ☁️ ক্লাউড রানে ডেপ্লয় করুন

ফ্লাটার বিল্ডটিকে ব্যাকএন্ডে বান্ডল করুন

ক্লাউড রান কন্টেইনারটি এপিআই এবং ইউআই উভয়ই একটি ইমেজ থেকে সরবরাহ করে। ফ্লাটার ওয়েব বিল্ডটি adk_backend/flutter_web/ -এ কপি করুন — কোন ইউআই পরিবেশন করা হবে তা বেছে নেওয়ার সময় গো সার্ভার প্রথমে এই পাথটিই পরীক্ষা করে:

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 এর মতো একটি সার্ভিস ইউআরএল পাবেন। এটি একটি ব্রাউজারে খুলুন — ফ্লাটার শপিং অ্যাপটি / থেকে লোড হয়, এবং এর এপিআই কলগুলো একই হোস্টের /api/ তে যায়। কোনো ফ্রন্টএন্ড কনফিগারেশন সম্পাদনার প্রয়োজন নেই, কোনো এপিআই কী-ও পাস করতে হবে না।

যেহেতু app_config.dart একই-অরিজিন রিলেটিভ ইউআরএল /api ব্যবহার করে, তাই ডেপ্লয় করা ফ্লাটার অ্যাপটি স্বয়ংক্রিয়ভাবে ডেপ্লয় করা ব্যাকএন্ডের সাথে যোগাযোগ স্থাপন করে। একই বিল্ড কোনো পরিবর্তন ছাড়াই স্থানীয়ভাবে এবং ক্লাউড রানে কাজ করে।

ক্লাউড রান সার্ভিস অ্যাকাউন্টের অনুমতি। ক্লাউড রান যে ডিফল্ট 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"

ডিপ্লয়মেন্ট যাচাই করুন

আপনার ব্রাউজারে ক্লাউড রান ইউআরএলটি খুলুন এবং সম্পূর্ণ প্রক্রিয়াটি অনুসরণ করুন:

1. ব্রাউজ করুন → একটি পণ্য নির্বাচন করুন
2. ট্রাই অন → আপনার ছবি আপলোড করুন → এআই-তৈরি ছবিটি দেখুন
3. স্টাইল মি → স্থান/অনুষ্ঠান পূরণ করুন → নির্বাচিত পোশাকগুলো দেখুন
4. মতামত দিন → 'আরও ক্যাজুয়াল করুন' টাইপ করুন → আপডেট করা পোশাকগুলো দেখুন
5. ব্যাগে যোগ করুন → কেনাকাটা সম্পন্ন করুন

১০. 🎉 উপসংহার

আপনি যা তৈরি করেছেন

আপনি একটি সম্পূর্ণ এআই-চালিত খুচরা কেনাকাটার অভিজ্ঞতা অন্বেষণ করেছেন:

• ✅ একটি মাল্টি-এজেন্ট ব্যাকএন্ড যেখানে ৪ জন বিশেষায়িত এজেন্ট একসাথে কাজ করে
• ✅ একটি ভার্চুয়াল ফিটিং রুম যা আপনার পছন্দ অনুযায়ী ট্রাই-অন ছবি তৈরি করে দেয়
• ✅ একজন এআই স্টাইলিস্ট , যে কথোপকথনের মাধ্যমে পোশাকের সম্ভার বাছাই করে এবং সেগুলোকে আরও পরিমার্জিত করে।
• ✅ একটি ক্রস-প্ল্যাটফর্ম ফ্লাটার অ্যাপ যা এজেন্ট ব্যাকএন্ডের সাথে সংযুক্ত হয়
• ✅ পরিবর্ধনযোগ্য ও সার্ভারবিহীন হোস্টিংয়ের জন্য ক্লাউড রান ডেপ্লয়মেন্ট

মূল ধারণা

ধারণা	যেখানে আপনি এটি দেখেছেন
ADK মাল্টি-এজেন্ট অর্কেস্ট্রেশন	ফিটিং রুম, ক্যাটালগ এবং স্টাইলিস্ট এজেন্টদের কাছে রুট এজেন্ট রাউটিং
জেমিনি মাল্টিমোডাল চিত্র তৈরি	ব্যবহারকারীর ছবির সাথে পণ্যের ছবি একত্রিত করার fitting_tool
কথোপকথনমূলক এআই-এর জন্য সেশন অবস্থা	স্টাইলিস্ট পুনরাবৃত্তিমূলক প্রতিক্রিয়ার জন্য সেশনগুলো পুনরায় ব্যবহার করছেন
বাইনারি ডেটার জন্য আর্টিফ্যাক্ট স্টোরেজ	টেক্সট প্রতিক্রিয়া থেকে ছবির স্টোরেজ আলাদা করা
মিডলওয়্যার লজিকের জন্য কলব্যাক	SaveIncomingBlobs , InjectPreviousProducts , SaveSelectedProducts
ফ্লাটারে MVVM + প্রোভাইডার	ChangeNotifier সাথে TryItOnProvider এবং StylingProvider
এজেন্টিক হস্তান্তর	StyleRequest এজেন্টদের মধ্যে মাল্টিমোডাল কনটেক্সট প্রেরণ করছে

পরবর্তী পদক্ষেপ

• 🎨 এজেন্টের নির্দেশাবলী নিজের মতো করে সাজান — স্টাইলিস্টের ব্যক্তিত্ব পরিবর্তন করতে instructions.md সম্পাদনা করুন।
• 🛍️ আরও পণ্য যোগ করুন — নতুন আইটেমগুলো দিয়ে catalog.yaml আপডেট করুন।
• 📱 মোবাইলের জন্য বিল্ড করুন — flutter build ios অথবা flutter build apk রান করুন
• 🔄 স্থায়ী সেশন যোগ করুন — InMemoryService একটি ডাটাবেস-সমর্থিত ইমপ্লিমেন্টেশন দিয়ে প্রতিস্থাপন করুন
• 🔒 প্রমাণীকরণ যোগ করুন — IAM দিয়ে ক্লাউড রান এন্ডপয়েন্ট সুরক্ষিত করুন

সম্পদ

• ADK ডকুমেন্টেশন — অফিসিয়াল এজেন্ট ডেভেলপমেন্ট কিট ডক্স
• ADK Go সোর্স কোড — গিটহাব রিপোজিটরি
• ADK Go প্যাকেজ রেফারেন্স — এপিআই রেফারেন্স
• জেমিনি এপিআই ডকুমেন্টেশন — মডেলের সক্ষমতা এবং নির্দেশিকা
• ফ্লাটার প্রোভাইডার প্যাকেজ — স্টেট ম্যানেজমেন্ট ডক্স
• ক্লাউড রান ডকুমেন্টেশন — ডেপ্লয়মেন্ট এবং স্কেলিং গাইড