ক্লাউড রানে ADK এজেন্ট স্থাপন, পরিচালনা এবং পর্যবেক্ষণ করুন

১. ভূমিকা

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

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

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

কোডল্যাবের মাধ্যমে, আপনি নিম্নলিখিত ধাপে ধাপে পদ্ধতিটি অনুসরণ করবেন:

  1. ADK এজেন্ট ডেটাবেস সেশন পরিষেবা হিসেবে ব্যবহারের জন্য CloudSQL-এ একটি PostgreSQL ডেটাবেস তৈরি করুন।
  2. একটি বেসিক ADK এজেন্ট সেট আপ করুন
  3. ADK রানার দ্বারা ব্যবহৃত হওয়ার জন্য ডাটাবেস সেশন সার্ভিস সেটআপ করুন।
  4. প্রাথমিকভাবে এজেন্টকে ক্লাউডে স্থাপন করুন
  5. লোড টেস্টিং এবং ইন্সপেক্ট ক্লাউড রান অটো স্কেলিং
  6. এজেন্টের নতুন সংস্করণটি স্থাপন করুন এবং ধীরে ধীরে নতুন সংস্করণগুলিতে ট্র্যাফিক বাড়ান।
  7. ক্লাউড ট্রেসিং সেটআপ করুন এবং এজেন্ট রান ট্রেসিং পরিদর্শন করুন

স্থাপত্যের সংক্ষিপ্ত বিবরণ

20d503f01eaadfd.jpeg

পূর্বশর্ত

  • পাইথন নিয়ে কাজ করতে স্বাচ্ছন্দ্যবোধ করি।
  • HTTP পরিষেবা ব্যবহার করে মৌলিক ফুল-স্ট্যাক আর্কিটেকচার সম্পর্কে ধারণা

আপনি যা শিখবেন

  • ADK কাঠামো এবং স্থানীয় ইউটিলিটি
  • ডাটাবেস সেশন পরিষেবা সহ ADK এজেন্ট সেটআপ করুন
  • ডাটাবেস সেশন সার্ভিস দ্বারা ব্যবহারের জন্য ক্লাউডএসকিউএল-এ পোস্টগ্রেসকিউএল সেটআপ করুন।
  • Dockerfile ব্যবহার করে অ্যাপ্লিকেশনটি Cloud Run-এ ডেপ্লয় করুন এবং প্রাথমিক এনভায়রনমেন্ট ভেরিয়েবল সেটআপ করুন।
  • লোড টেস্টিং-এর মাধ্যমে ক্লাউড রান অটো স্কেলিং কনফিগার ও টেস্ট করুন।
  • ক্লাউড রানের মাধ্যমে পর্যায়ক্রমিক রিলিজের কৌশল
  • ক্লাউড ট্রেসে ADK এজেন্ট ট্রেসিং সেটআপ করুন

আপনার যা যা লাগবে

  • ক্রোম ওয়েব ব্রাউজার
  • একটি জিমেইল অ্যাকাউন্ট
  • বিলিং সক্ষম একটি ক্লাউড প্রজেক্ট

সকল স্তরের (শিক্ষানবিশ সহ) ডেভেলপারদের জন্য ডিজাইন করা এই কোডল্যাবটির নমুনা অ্যাপ্লিকেশনে পাইথন ব্যবহার করা হয়েছে। তবে, এখানে উপস্থাপিত ধারণাগুলো বোঝার জন্য পাইথন জ্ঞানের প্রয়োজন নেই।

২. 🚀 ওয়ার্কশপ সেটআপের প্রস্তুতি

এখন, আমরা এই টিউটোরিয়ালের জন্য ক্লাউড শেল আইডিই (Cloud Shell IDE) ব্যবহার করব, সেখানে যেতে নিচের বোতামটিতে ক্লিক করুন।

ক্লাউড শেলে প্রবেশ করার পর, গিটহাব থেকে এই কোডল্যাবের টেমপ্লেট ওয়ার্কিং ডিরেক্টরিটি ক্লোন করুন এবং নিম্নলিখিত কমান্ডটি চালান। এটি deploy_and_manage_adk ডিরেক্টরিতে ওয়ার্কিং ডিরেক্টরিটি তৈরি করবে।

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

এরপর, ক্লোন করা রিপোজিটরিটি আপনার ওয়ার্কিং ডিরেক্টরি হিসেবে খোলার জন্য টার্মিনালে নিম্নলিখিত কমান্ডটি চালান।

cloudshell workspace ~/deploy_and_manage_adk && cd ~/deploy_and_manage_adk

এরপরে, আপনার ইন্টারফেসটি দেখতে এইরকম হবে।

82b938c0e24f13d5.png

এটি হবে আমাদের প্রধান ইন্টারফেস, উপরে IDE এবং নিচে টার্মিনাল। এখন আমাদের গুগল ক্লাউড প্রজেক্ট তৈরি ও সক্রিয় করার জন্য টার্মিনাল প্রস্তুত করতে হবে, যা পূর্বে দাবি করা ট্রায়াল বিলিং অ্যাকাউন্টের সাথে লিঙ্ক করা হবে। আপনার টার্মিনাল সেশন সর্বদা প্রস্তুত আছে কিনা তা নিশ্চিত করার জন্য আমরা আপনার জন্য একটি স্ক্রিপ্ট তৈরি করেছি। নিম্নলিখিত কমান্ডটি চালান (নিশ্চিত করুন যে আপনি ইতিমধ্যেই deploy_and_manage_adk ওয়ার্কস্পেসের ভিতরে আছেন)।

bash setup_trial_project.sh && source .env

এটি চালানোর সময়, আপনাকে একটি প্রস্তাবিত প্রজেক্ট আইডি নাম দেখানো হবে, চালিয়ে যাওয়ার জন্য আপনি Enter চাপতে পারেন।

77f289b73a047a98.png

কিছুক্ষণ অপেক্ষা করার পর যদি আপনি আপনার কনসোলে এই আউটপুটটি দেখতে পান, তাহলে আপনি পরবর্তী ধাপে যাওয়ার জন্য প্রস্তুত। e6db54f7313a98a.png

এটি দেখায় যে আপনার টার্মিনালটি ইতিমধ্যেই প্রমাণীকৃত এবং সঠিক প্রজেক্ট আইডিতে সেট করা আছে (বর্তমান ডিরেক্টরি পাথের পাশে হলুদ রঙ)। এই কমান্ডটি আপনাকে একটি নতুন প্রজেক্ট তৈরি করতে, প্রজেক্টটিকে একটি ট্রায়াল বিলিং অ্যাকাউন্টের সাথে খুঁজে বের করে লিঙ্ক করতে, এনভায়রনমেন্ট ভেরিয়েবল কনফিগারেশনের জন্য .env ফাইল প্রস্তুত করতে এবং আপনার জন্য টার্মিনালে সঠিক প্রজেক্ট আইডি সক্রিয় করতে সাহায্য করে।

এখন, আমরা পরবর্তী পদক্ষেপের জন্য প্রস্তুত।

৩. 🚀 এপিআই সক্রিয় করা

এই টিউটোরিয়ালে আমরা CloudSQL ডাটাবেস, Gemini মডেল এবং Cloud Run নিয়ে কাজ করব। এই প্রোডাক্টগুলো সক্রিয় করার জন্য নিম্নলিখিত API-গুলোর প্রয়োজন হবে; এগুলো চালু করতে এই কমান্ডগুলো চালান।

এতে কিছুটা সময় লাগতে পারে।

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com \
                       compute.googleapis.com

কমান্ডটি সফলভাবে কার্যকর হলে, আপনি নিচে দেখানো বার্তার মতো একটি বার্তা দেখতে পাবেন:

Operation "operations/..." finished successfully.

৪. 🚀 পাইথন এনভায়রনমেন্ট সেটআপ এবং এনভায়রনমেন্ট ভেরিয়েবল

এই কোডল্যাবে আমরা পাইথন ৩.১২ ব্যবহার করব এবং পাইথন ভার্সন ও ভার্চুয়াল এনভায়রনমেন্ট তৈরি ও পরিচালনার কাজ সহজ করার জন্য ইউভি (uv) পাইথন প্রজেক্ট ম্যানেজার ব্যবহার করব। এই ইউভি প্যাকেজটি ক্লাউড শেলে আগে থেকেই ইনস্টল করা থাকে।

.venv ডিরেক্টরিতে ভার্চুয়াল এনভায়রনমেন্টের জন্য প্রয়োজনীয় ডিপেন্ডেন্সিগুলো ইনস্টল করতে এই কমান্ডটি চালান।

uv sync --frozen

এরপরে, আমরা এই প্রোজেক্টের জন্য প্রয়োজনীয় এনভায়রনমেন্ট ভেরিয়েবল ফাইলগুলো পরীক্ষা করব। পূর্বে এই ফাইলটি setup_trial_project.sh স্ক্রিপ্ট দ্বারা সেট আপ করা হতো। এডিটরে .env ফাইলটি খোলার জন্য নিম্নলিখিত কমান্ডটি চালান।

cloudshell open .env

আপনি .env ফাইলে নিম্নলিখিত কনফিগারেশনগুলি ইতিমধ্যেই প্রয়োগ করা দেখতে পাবেন।

# .env

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# DB_CONNECTION_NAME=your-db-connection-name

এই কোডল্যাবের জন্য, আমরা GOOGLE_CLOUD_LOCATION এবং GOOGLE_GENAI_USE_VERTEXAI.

এখন আমরা পরবর্তী ধাপে যেতে পারি, যা হলো আমাদের এজেন্টের স্টেট এবং সেশন সংরক্ষণের জন্য ব্যবহৃত ডেটাবেসটি তৈরি করা।

৫. 🚀 ক্লাউডএসকিউএল ডেটাবেস প্রস্তুত করা

পরবর্তীতে ADK এজেন্ট দ্বারা ব্যবহারের জন্য আমাদের একটি ডাটাবেসের প্রয়োজন হবে। চলুন Cloud SQL-এ একটি PostgreSQL ডাটাবেস তৈরি করি। প্রথমে ডাটাবেস ইনস্ট্যান্স তৈরি করতে নিম্নলিখিত কমান্ডটি চালান। আমরা ডিফল্ট 'postgres' ডাটাবেস নামটি ব্যবহার করব, তাই এখানে ডাটাবেস তৈরির ধাপটি বাদ দিচ্ছি। আমাদের ডিফল্ট ডাটাবেস ইউজারনেমও (এটিও ' postgres') কনফিগার করতে হবে। এই টিউটোরিয়ালের সুবিধার্থে, পাসওয়ার্ড হিসেবে ADK-deployment123 ব্যবহার করা যাক।

gcloud sql instances create adk-deployment \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --tier=db-g1-small \
  --region=us-central1 \
  --availability-type=ZONAL \
  --project=${GOOGLE_CLOUD_PROJECT} && \
gcloud sql users set-password postgres \
  --instance=adk-deployment \
  --password=ADK-deployment123

উপরের কমান্ডে, প্রথম সাধারণ কমান্ড gcloud sql instances create adk-deployment ’ আমরা ডাটাবেস ইনস্ট্যান্স তৈরি করতে ব্যবহার করি। এই টিউটোরিয়ালের জন্য আমরা একটি স্যান্ডবক্স মিনিমাল স্পেসিফিকেশন ব্যবহার করছি। দ্বিতীয় কমান্ড gcloud sql users set-password postgres ডিফল্ট পোস্টগ্রেস ইউজারনেম এবং পাসওয়ার্ড পরিবর্তন করতে ব্যবহৃত হয়।

লক্ষ্য করুন যে আমরা আমাদের ডাটাবেস ইনস্ট্যান্সের নাম হিসেবে adk-deployment ব্যবহার করি। কাজ শেষ হলে, আপনি টার্মিনালে নীচের ছবির মতো আউটপুট দেখতে পাবেন, যা থেকে বোঝা যায় যে ইনস্ট্যান্সটি প্রস্তুত এবং ডিফল্ট ব্যবহারকারীর পাসওয়ার্ড আপডেট করা হয়েছে।

Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/your-project-id/instances/adk-deployment].
NAME: adk-deployment
DATABASE_VERSION: POSTGRES_17
LOCATION: us-central1-a
TIER: db-g1-small
PRIMARY_ADDRESS: xx.xx.xx.xx
PRIVATE_ADDRESS: -
STATUS: RUNNABLE
Updating Cloud SQL user...done. 

যেহেতু এই ডাটাবেসটি স্থাপন করতে কিছুটা সময় লাগবে, তাই CloudSQL ডাটাবেস স্থাপন প্রস্তুত হওয়া পর্যন্ত অপেক্ষা করার সময় চলুন পরবর্তী বিভাগে চলে যাই।

৬. 🚀 ADK এবং Gemini 2.5 দিয়ে ওয়েদার এজেন্ট তৈরি করুন।

ADK ডিরেক্টরি কাঠামোর পরিচিতি

চলুন, ADK কী কী সুবিধা দেয় এবং কীভাবে এজেন্ট তৈরি করতে হয়, তা দিয়ে শুরু করা যাক। ADK-এর সম্পূর্ণ ডকুমেন্টেশন এই URL- এ পাওয়া যাবে। ADK তার CLI কমান্ড এক্সিকিউশনের মাধ্যমে আমাদের অনেক ইউটিলিটি প্রদান করে। সেগুলোর মধ্যে কয়েকটি নিচে দেওয়া হলো:

  • এজেন্ট ডিরেক্টরি কাঠামো সেটআপ করুন
  • CLI ইনপুট আউটপুটের মাধ্যমে দ্রুত ইন্টারঅ্যাকশন চেষ্টা করুন
  • দ্রুত স্থানীয় ডেভেলপমেন্ট UI ওয়েব ইন্টারফেস সেটআপ করুন

এখন, weather_agent ডিরেক্টরিতে এজেন্টের কাঠামোটি পরীক্ষা করা যাক।

weather_agent/
├── __init__.py
├── agent.py
└── tool.py

এবং আপনি যদি init.py এবং agent.py ফাইলগুলো পরিদর্শন করেন, তাহলে এই কোডটি দেখতে পাবেন।

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]
# agent.py


import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
""",
    tools=[get_weather],
)

ADK কোডের ব্যাখ্যা

এই স্ক্রিপ্টটিতে আমাদের এজেন্ট ইনিসিয়েশন রয়েছে, যেখানে আমরা নিম্নলিখিত বিষয়গুলো ইনিশিয়ালাইজ করি:

  • ব্যবহৃত মডেলটি gemini-2.5-flash এ সেট করুন।
  • ওয়েদার এজেন্ট হিসেবে এজেন্ট কার্যকারিতা সমর্থন করার জন্য get_weather টুলটি প্রদান করুন।

ওয়েব UI স্থানীয়ভাবে চালান

এখন, আমরা এজেন্টের সাথে ইন্টারঅ্যাক্ট করতে এবং স্থানীয়ভাবে এর আচরণ পর্যবেক্ষণ করতে পারি। ADK আমাদের একটি ডেভেলপমেন্ট ওয়েব UI ব্যবহারের সুযোগ দেয়, যার মাধ্যমে আমরা ইন্টারঅ্যাকশন চলাকালীন কী ঘটছে তা পর্যবেক্ষণ করতে পারি। স্থানীয় ডেভেলপমেন্ট UI সার্ভারটি চালু করতে নিম্নলিখিত কমান্ডটি চালান।

uv run adk web --port 8080

এটি নিচের উদাহরণের মতো আউটপুট তৈরি করবে, যার মানে হলো আমরা ইতিমধ্যেই ওয়েব ইন্টারফেসটি অ্যাক্সেস করতে পারব।

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

এখন, এটি পরীক্ষা করার জন্য, আপনার ক্লাউড শেল এডিটরের উপরের অংশে থাকা ওয়েব প্রিভিউ বোতামে ক্লিক করুন এবং পোর্ট ৮০৮০-তে প্রিভিউ নির্বাচন করুন।

edc73e971b9fc60c.png

আপনি নিম্নলিখিত ওয়েব পেজটি দেখতে পাবেন, যেখানে আপনি উপরের বাম দিকের ড্রপ-ডাউন বোতাম থেকে উপলব্ধ এজেন্ট নির্বাচন করতে পারবেন (আমাদের ক্ষেত্রে এটি weather_agent হওয়া উচিত) এবং বটটির সাথে ইন্টারঅ্যাক্ট করতে পারবেন। এজেন্ট চালু থাকার সময়কার লগ সম্পর্কিত অনেক তথ্য আপনি বাম দিকের উইন্ডোতে দেখতে পাবেন।

25999e0b71c3989.png

এখন, এটির সাথে ইন্টারঅ্যাক্ট করার চেষ্টা করুন। বাম দিকের বারে, আমরা প্রতিটি ইনপুটের ট্রেস পরীক্ষা করতে পারি, যাতে আমরা বুঝতে পারি যে চূড়ান্ত উত্তর তৈরি করার আগে এজেন্টের নেওয়া প্রতিটি পদক্ষেপের জন্য কত সময় লাগে।

b4ba38adf419017e.png

এটি ADK-তে অন্তর্নির্মিত পর্যবেক্ষণযোগ্যতার বৈশিষ্ট্যগুলোর মধ্যে একটি, বর্তমানে আমরা এটি স্থানীয়ভাবে পর্যবেক্ষণ করি। পরবর্তীতে আমরা দেখব কীভাবে এটিকে ক্লাউড ট্রেসিং-এর সাথে একীভূত করা হয়, যাতে আমাদের কাছে সমস্ত অনুরোধের একটি কেন্দ্রীভূত ট্রেস থাকে।

৭. 🚀 ক্লাউড রান-এ ডেপ্লয় করা

এখন, চলুন এই এজেন্ট সার্ভিসটি ক্লাউড রান-এ ডেপ্লয় করি। এই ডেমোর জন্য, এই সার্ভিসটিকে একটি পাবলিক সার্ভিস হিসেবে উন্মুক্ত করা হবে যা অন্যরাও অ্যাক্সেস করতে পারবে। তবে, মনে রাখবেন যে এটি সর্বোত্তম পন্থা নয়, কারণ এটি সুরক্ষিত নয়।

20d503f01eaadfd.jpeg

এই ডেপ্লয়মেন্ট সিনারিওটি ​​আপনাকে আপনার এজেন্ট ব্যাকএন্ড সার্ভিস কাস্টমাইজ করার সুযোগ দেয়, আমরা আমাদের এজেন্টকে ক্লাউড রান-এ ডেপ্লয় করার জন্য ডকারফাইল ব্যবহার করব। এই পর্যায়ে, ক্লাউড রান-এ আমাদের অ্যাপ্লিকেশনগুলো ডেপ্লয় করার জন্য প্রয়োজনীয় সমস্ত ফাইল ( ডকারফাইল এবং server.py ) ইতিমধ্যেই আমাদের কাছে রয়েছে। এই দুটি আইটেম থাকার ফলে, আপনি আপনার এজেন্ট ডেপ্লয়মেন্টকে সুবিধাজনকভাবে কাস্টমাইজ করতে পারবেন (যেমন কাস্টম ব্যাকএন্ড রাউট যোগ করা এবং/অথবা মনিটরিংয়ের উদ্দেশ্যে অতিরিক্ত সাইডকার সার্ভিস যোগ করা)। আমরা এই বিষয়ে পরে বিস্তারিত আলোচনা করব।

এখন, প্রথমে সার্ভিসটি ডেপ্লয় করা যাক। এর জন্য ক্লাউড শেল টার্মিনালে যান এবং নিশ্চিত করুন যে বর্তমান প্রজেক্টটি আপনার সক্রিয় প্রজেক্ট হিসেবে কনফিগার করা আছে। এবার সেটআপ স্ক্রিপ্টটি আবার চালান। ঐচ্ছিকভাবে, আপনি আপনার সক্রিয় প্রজেক্ট কনফিগার করার জন্য gcloud config set project [PROJECT_ID] কমান্ডটিও ব্যবহার করতে পারেন।

bash setup_trial_project.sh && source .env

এখন, আমাদের আবার .env ফাইলটি খুলতে হবে এবং দেখতে পাবেন যে আমাদের DB_CONNECTION_NAME ভেরিয়েবলটির কমেন্ট তুলে দিয়ে সঠিক মানটি বসাতে হবে।

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-db-connection-name

DB_CONNECTION_NAME ভ্যালুটি পেতে, চলুন ক্লাউড এসকিউএল ড্যাশবোর্ডে যাই।

এরপর আপনার তৈরি করা ইনস্ট্যান্সটিতে ক্লিক করুন। ক্লাউড কনসোলের উপরের অংশে থাকা সার্চ বারে গিয়ে 'cloud sql' টাইপ করুন। তারপর ক্লাউড এসকিউএল (Cloud SQL) প্রোডাক্টটিতে ক্লিক করুন।

39dbcf39661a8b65.png

এরপর আপনি পূর্বে তৈরি করা ইনস্ট্যান্সটি দেখতে পাবেন, সেটিতে ক্লিক করুন।

8faf706622293e9a.png

ইনস্ট্যান্স পেজের ভিতরে, " এই ইনস্ট্যান্সে সংযোগ করুন " বিভাগ পর্যন্ত স্ক্রোল করুন এবং আপনি সংযোগের নামটি কপি করে DB_CONNECTION_NAME মানটিতে প্রতিস্থাপন করতে পারেন।

d669fc62ae37ab7d.png

এরপর নিচের কমান্ডটি দিয়ে .env ফাইলটি খুলুন।

cloudshell edit .env

এবং .env ফাইলে DB_CONNECTION_NAME ভেরিয়েবলটি পরিবর্তন করুন। আপনার env ফাইলটি নিচের উদাহরণের মতো দেখতে হবে।

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

এরপর ডেপ্লয়মেন্ট স্ক্রিপ্টটি চালান।

bash deploy_to_cloudrun.sh

ডকার রিপোজিটরির জন্য একটি আর্টিফ্যাক্ট রেজিস্ট্রি তৈরির বিষয়টি স্বীকার করতে বলা হলে, উত্তরে শুধু Y দিন।

ডেপ্লয়মেন্ট প্রক্রিয়ার জন্য অপেক্ষা করার ফাঁকে, চলুন deploy_to_cloudrun.sh ফাইলটি দেখে নেওয়া যাক।

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

এই স্ক্রিপ্টটি আপনার .env ভেরিয়েবল লোড করবে, তারপর ডিপ্লয়মেন্ট কমান্ডটি চালাবে।

আরও ভালোভাবে দেখলে বোঝা যায়, একটি সার্ভিস ডেপ্লয় করার জন্য প্রয়োজনীয় সমস্ত কাজ—যেমন ইমেজ বিল্ড করা, রেজিস্ট্রি-তে পুশ করা, সার্ভিস ডেপ্লয় করা, IAM পলিসি সেট করা, রিভিশন তৈরি করা, এমনকি ট্র্যাফিক রাউটিং—করতে আমাদের শুধুমাত্র একটি gcloud run deploy কমান্ডই যথেষ্ট। এই উদাহরণে, আমরা ইতিমধ্যেই Dockerfile দিয়ে দিয়েছি, তাই এই কমান্ডটি অ্যাপটি বিল্ড করার জন্য সেটিই ব্যবহার করবে।

ডেপ্লয়মেন্ট সম্পন্ন হলে, আপনি নীচের মতো একটি লিঙ্ক পাবেন:

https://weather-agent-*******.us-central1.run.app

এই URL-টি পাওয়ার পর, আপনি আপনার অ্যাপ্লিকেশনটি ইনকগনিটো উইন্ডো বা মোবাইল ডিভাইস থেকে ব্যবহার করে এজেন্ট ডেভ UI অ্যাক্সেস করতে পারবেন। ডিপ্লয়মেন্টের জন্য অপেক্ষা করার সময়, চলুন পরবর্তী বিভাগে আমরা এইমাত্র ডিপ্লয় করা সার্ভিসটির বিস্তারিত পরীক্ষা করে দেখি।

৮. 💡 ডকারফাইল এবং ব্যাকএন্ড সার্ভার স্ক্রিপ্ট

এজেন্টটিকে একটি সার্ভিস হিসেবে ব্যবহারযোগ্য করার জন্য, আমরা এটিকে একটি FastAPI অ্যাপের মধ্যে রাখব যা Dockerfile কমান্ডের মাধ্যমে চালানো হবে। নিচে Dockerfile- টির বিষয়বস্তু দেওয়া হলো।

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

এখানে আমরা এজেন্টকে সমর্থন করার জন্য প্রয়োজনীয় পরিষেবাগুলি কনফিগার করতে পারি, যেমন প্রোডাকশনের উদ্দেশ্যে সেশন , মেমরি বা আর্টিফ্যাক্ট পরিষেবা প্রস্তুত করা। নিচে server.py- এর কোড দেওয়া হলো যা ব্যবহার করা হবে।

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


# Example if you want to add your custom endpoint
@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

সার্ভার কোডের ব্যাখ্যা

server.py স্ক্রিপ্টে এই বিষয়গুলো সংজ্ঞায়িত করা আছে:

  1. get_fast_api_app মেথডটি ব্যবহার করে আমাদের এজেন্টকে একটি FastAPI অ্যাপে রূপান্তর করুন। এর মাধ্যমে আমরা সেই একই রাউট ডেফিনিশনটি পাব যা ওয়েব ডেভেলপমেন্ট UI-এর জন্য ব্যবহৃত হয়।
  2. get_fast_api_app মেথডে কীওয়ার্ড আর্গুমেন্ট যোগ করে প্রয়োজনীয় সেশন, মেমরি বা আর্টিফ্যাক্ট সার্ভিস কনফিগার করুন। এই টিউটোরিয়ালে, যদি আমরা SESSION_SERVICE_URI এনভ ভ্যারিয়েবলটি কনফিগার করি, তাহলে সেশন সার্ভিসটি সেটি ব্যবহার করবে, অন্যথায় এটি ইন-মেমরি সেশন ব্যবহার করবে।
  3. অন্যান্য ব্যাকএন্ড বিজনেস লজিক সমর্থন করার জন্য আমরা কাস্টম রুট যোগ করতে পারি, স্ক্রিপ্টে আমরা ফিডব্যাক ফাংশনালিটি রুটের উদাহরণ যোগ করি।
  4. Google Cloud Trace-এ ট্রেস পাঠাতে, get_fast_api_app আর্গুমেন্ট প্যারামিটারগুলিতে ক্লাউড ট্রেসিং সক্ষম করুন।
  5. uvicorn ব্যবহার করে FastAPI পরিষেবাটি চালান।

এখন, যদি আপনার ডেপ্লয়মেন্ট ইতিমধ্যেই সম্পন্ন হয়ে থাকে, তাহলে অনুগ্রহ করে ক্লাউড রান ইউআরএল (Cloud Run URL) অ্যাক্সেস করে ওয়েব ডেভ ইউআই (web Dev UI) থেকে এজেন্টের সাথে ইন্টারঅ্যাক্ট করার চেষ্টা করুন।

৯. 🚀 লোড টেস্টিং-এর মাধ্যমে ক্লাউড রান অটো স্কেলিং পরীক্ষা করা

এখন, আমরা ক্লাউড রানের অটো-স্কেলিং ক্ষমতা পরীক্ষা করব। এই ক্ষেত্রে, প্রতিটি ইনস্ট্যান্সের জন্য সর্বোচ্চ কনকারেন্সি সক্ষম করে নতুন রিভিশনটি ডেপ্লয় করা যাক। আগের অংশে, আমরা সর্বোচ্চ কনকারেন্সি ১০-এ সেট করেছিলাম (ফ্ল্যাগ --concurrency 10 )। সুতরাং আমরা আশা করতে পারি যে, যখন আমরা এই সংখ্যা অতিক্রম করে লোড টেস্ট করব, তখন ক্লাউড রান তার ইনস্ট্যান্স স্কেল করার চেষ্টা করবে।

চলুন load_test.py ফাইলটি পরীক্ষা করে দেখি। লোকাস্ট ফ্রেমওয়ার্ক ব্যবহার করে লোড টেস্টিং করার জন্য আমরা এই স্ক্রিপ্টটিই ব্যবহার করব। এই স্ক্রিপ্টটি নিম্নলিখিত কাজগুলো করবে:

  1. এলোমেলোভাবে user_id এবং session_id
  2. user_id-এর জন্য session_id তৈরি করুন
  3. তৈরি করা user_id এবং session_id দিয়ে "/run_sse" এন্ডপয়েন্টে হিট করুন।

আমাদের ডেপ্লয় করা সার্ভিসের URL জানতে হবে, যদি আপনি তা না জেনে থাকেন। আমরা ক্লাউড রান কনসোলে যেতে পারি।

তারপর, আপনার আবহাওয়া- পরিষেবাটি খুঁজুন এবং তাতে ক্লিক করুন।

6f0874f1e96cdbd6.png

সার্ভিসের URL-টি অঞ্চলের তথ্যের ঠিক পাশেই দেখানো হবে। যেমন:

6d0823829ee15d1.png

আপনার সুবিধার জন্য, আপনার সম্প্রতি ডেপ্লয় করা সার্ভিসের URL পেতে এবং সেটিকে SERVICE_URL এনভায়রনমেন্ট ভেরিয়েবলে সংরক্ষণ করতে নিচের স্ক্রিপ্টটি চালান।

export SERVICE_URL=$(gcloud run services describe weather-agent \
    --platform managed \
    --region us-central1 \
    --format 'value(status.url)')

এরপর আমাদের এজেন্ট অ্যাপটি লোড টেস্ট করার জন্য নিম্নলিখিত কমান্ডটি চালান।

uv run locust -f load_test.py \
              -H $SERVICE_URL \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

এটি চালালে আপনি এই ধরনের মেট্রিক্স প্রদর্শিত হতে দেখবেন। (এই উদাহরণে সমস্ত অনুরোধ সফল হয়েছে)

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00  

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

a23679982c072041.png

১০. 🚀 নতুন সংস্করণগুলো পর্যায়ক্রমে প্রকাশ করুন

এখন, নিম্নলিখিত পরিস্থিতিটি বিবেচনা করা যাক। আমরা এজেন্টের প্রম্পট আপডেট করতে চাই। নিম্নলিখিত কমান্ডটি দিয়ে weather_agent/agent.py ফাইলটি খুলুন।

cloudshell edit weather_agent/agent.py

এবং নিম্নলিখিত কোড দিয়ে এটিকে ওভাররাইট করুন:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
You only answer inquiries about the weather. Refuse all other user query
""",
    tools=[get_weather],
)

এরপর, আপনি নতুন সংস্করণ প্রকাশ করতে চান কিন্তু চান না যে সমস্ত অনুরোধ সরাসরি নতুন সংস্করণে চলে যাক। আমরা ক্লাউড রানের মাধ্যমে পর্যায়ক্রমিক প্রকাশ করতে পারি। প্রথমে, আমাদের একটি নতুন সংস্করণ স্থাপন করতে হবে, কিন্তু –no-traffic ফ্ল্যাগ সহ। পূর্ববর্তী এজেন্ট স্ক্রিপ্টটি সংরক্ষণ করুন এবং নিম্নলিখিত কমান্ডটি চালান।

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project $GOOGLE_CLOUD_PROJECT \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

কাজ শেষ হওয়ার পর, আপনি আগের ডেপ্লয়মেন্ট প্রক্রিয়ার মতোই একটি লগ পাবেন, তবে পরিবেশিত ট্র্যাফিকের সংখ্যার ক্ষেত্রে একটি পার্থক্য থাকবে। এতে পরিবেশিত ট্র্যাফিকের পরিমাণ ০ শতাংশ দেখানো হবে।

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

এরপর, চলুন ক্লাউড রান ড্যাশবোর্ডে যাই।

তারপর, আপনার আবহাওয়া- পরিষেবাটি খুঁজুন এবং তাতে ক্লিক করুন।

6f0874f1e96cdbd6.png

রিভিশন ট্যাবে যান এবং সেখানে আপনি ডেপ্লয় করা রিভিশনগুলোর তালিকা দেখতে পাবেন।

de00ac6870ed120b.png

আপনি দেখতে পাবেন যে নতুন ডেপ্লয় করা রিভিশনটি ০% সার্ভ করছে, এখান থেকে আপনি কাবাব বোতামে (⋮) ক্লিক করে 'ম্যানেজ ট্র্যাফিক' (Manage Traffic) বেছে নিতে পারেন।

f35344086aecc5e6.png

নতুন পপ-আপ উইন্ডোতে, আপনি কোন রিভিশনগুলিতে ট্র্যাফিকের শতাংশ যাবে তা সম্পাদনা করতে পারেন।

525ae793ebeee87f.png

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

১১. 🚀 এডিকে ট্রেসিং

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

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

এখানে, আমরা trace_to_cloud আর্গুমেন্টটিকে True- তে পাস করি। আপনি যদি অন্য বিকল্প ব্যবহার করে ডেপ্লয় করেন, তাহলে বিভিন্ন ডেপ্লয়মেন্ট বিকল্প থেকে কীভাবে ক্লাউড ট্রেসে ট্রেসিং সক্ষম করতে হয় সে সম্পর্কে আরও বিস্তারিত জানতে এই ডকুমেন্টেশনটি দেখতে পারেন।

আপনার সার্ভিস ওয়েব ডেভ UI-তে প্রবেশ করে এজেন্টের সাথে কথা বলুন। এরপর ট্রেস এক্সপ্লোরার পেজে যাওয়া যাক।

ট্রেস এক্সপ্লোরার পৃষ্ঠায়, আপনি দেখতে পাবেন যে এজেন্টের সাথে আমাদের কথোপকথনের ট্রেস জমা দেওয়া হয়েছে। আপনি 'স্প্যান নেম' বিভাগ থেকে আমাদের এজেন্টের জন্য নির্দিষ্ট স্প্যানটি (যার নাম agent_run [weather_agent] ) ফিল্টার করে বের করতে পারবেন।

63cb96b8d8c43425.png

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

db765dc868c3f8c0.png

প্রতিটি বিভাগে, আপনি নিচে দেখানো উপায়ে অ্যাট্রিবিউটগুলোর বিস্তারিত তথ্য দেখতে পারেন।

dcb3916cbdf3bda8.png

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

১২. 🎯 চ্যালেঞ্জ

লোডের অধীনে মাল্টি-এজেন্ট বা এজেন্টিক ওয়ার্কফ্লো কেমন পারফর্ম করে এবং ট্রেসটি কেমন দেখায় তা পরীক্ষা করতে সেগুলোর ব্যবহার করে দেখুন।

১৩. 🧹 পরিষ্কার করা

এই কোডল্যাবে ব্যবহৃত রিসোর্সগুলির জন্য আপনার গুগল ক্লাউড অ্যাকাউন্টে চার্জ হওয়া এড়াতে, এই ধাপগুলি অনুসরণ করুন:

  1. গুগল ক্লাউড কনসোলে, 'ম্যানেজ রিসোর্সেস' পৃষ্ঠায় যান।
  2. প্রজেক্ট তালিকা থেকে, আপনি যে প্রজেক্টটি মুছতে চান সেটি নির্বাচন করুন এবং তারপর ডিলিট বোতামে ক্লিক করুন।
  3. ডায়ালগ বক্সে প্রজেক্ট আইডি টাইপ করুন এবং তারপর প্রজেক্টটি মুছে ফেলার জন্য 'শাট ডাউন'-এ ক্লিক করুন।
  4. বিকল্পভাবে, আপনি কনসোলে Cloud Run- এ গিয়ে, এইমাত্র ডেপ্লয় করা সার্ভিসটি নির্বাচন করে ডিলিট করে দিতে পারেন।