1. ভূমিকা
এই টিউটোরিয়ালটি আপনাকে গুগল ক্লাউড রানে এজেন্ট ডেভেলপমেন্ট কিট (ADK) দিয়ে তৈরি একটি শক্তিশালী এজেন্ট স্থাপন, পরিচালনা এবং পর্যবেক্ষণের ক্ষেত্রে নির্দেশনা দেবে। ADK আপনাকে জটিল, বহু-এজেন্ট কর্মপ্রবাহে সক্ষম এজেন্ট তৈরি করার ক্ষমতা দেয়। সম্পূর্ণরূপে পরিচালিত সার্ভারলেস প্ল্যাটফর্ম ক্লাউড রান ব্যবহার করে, আপনি অন্তর্নিহিত অবকাঠামো সম্পর্কে চিন্তা না করেই আপনার এজেন্টকে একটি স্কেলেবল, কন্টেইনারাইজড অ্যাপ্লিকেশন হিসাবে স্থাপন করতে পারেন। এই শক্তিশালী সমন্বয় আপনাকে গুগল ক্লাউডের শক্তিশালী এবং স্কেলেবল পরিবেশ থেকে উপকৃত হওয়ার সাথে সাথে আপনার এজেন্টের মূল যুক্তির উপর ফোকাস করতে দেয়।
এই টিউটোরিয়ালে, আমরা ADK-এর ক্লাউড রান-এর সাথে নিরবচ্ছিন্ন ইন্টিগ্রেশন অন্বেষণ করব। আপনি শিখবেন কীভাবে আপনার এজেন্ট স্থাপন করবেন এবং তারপরে একটি উৎপাদন-সদৃশ পরিবেশে আপনার অ্যাপ্লিকেশন পরিচালনার ব্যবহারিক দিকগুলিতে ডুব দেবেন। আমরা ট্রাফিক পরিচালনা করে কীভাবে নিরাপদে আপনার এজেন্টের নতুন সংস্করণগুলি চালু করবেন তা কভার করব, যাতে আপনি সম্পূর্ণ প্রকাশের আগে ব্যবহারকারীদের একটি উপসেটের সাথে নতুন বৈশিষ্ট্যগুলি পরীক্ষা করতে পারেন।
তদুপরি, আপনি আপনার এজেন্টের কর্মক্ষমতা পর্যবেক্ষণের ক্ষেত্রে ব্যবহারিক অভিজ্ঞতা অর্জন করবেন। ক্লাউড রানের স্বয়ংক্রিয় স্কেলিং ক্ষমতা পর্যবেক্ষণ করার জন্য আমরা একটি লোড পরীক্ষা পরিচালনা করে একটি বাস্তব-বিশ্বের দৃশ্যকল্প অনুকরণ করব। আপনার এজেন্টের আচরণ এবং কর্মক্ষমতা সম্পর্কে আরও গভীর অন্তর্দৃষ্টি পেতে, আমরা ক্লাউড ট্রেস দিয়ে ট্রেসিং সক্ষম করব। এটি আপনার এজেন্টের মধ্য দিয়ে যাওয়ার সময় অনুরোধগুলির একটি বিশদ, এন্ড-টু-এন্ড ভিউ প্রদান করবে, যা আপনাকে যেকোনো কর্মক্ষমতা বাধা সনাক্ত করতে এবং সমাধান করতে সহায়তা করবে। এই টিউটোরিয়ালের শেষে, আপনি ক্লাউড রানে আপনার ADK-চালিত এজেন্টগুলিকে কীভাবে কার্যকরভাবে স্থাপন, পরিচালনা এবং পর্যবেক্ষণ করবেন সে সম্পর্কে একটি বিস্তৃত ধারণা পাবেন।
কোডল্যাবের মাধ্যমে, আপনি নিম্নরূপ ধাপে ধাপে পদ্ধতি ব্যবহার করবেন:
- ADK এজেন্ট ডাটাবেস সেশন পরিষেবার জন্য ব্যবহার করার জন্য CloudSQL-এ একটি PostgreSQL ডাটাবেস তৈরি করুন।
- একটি বেসিক ADK এজেন্ট সেট আপ করুন
- ADK রানার দ্বারা ব্যবহৃত ডাটাবেস সেশন পরিষেবা সেটআপ করুন
- প্রাথমিকভাবে এজেন্টটিকে ক্লাউড রানে স্থাপন করুন
- লোড টেস্টিং এবং ক্লাউড রান অটো স্কেলিং পরিদর্শন করুন
- নতুন এজেন্ট রিভিশন স্থাপন করুন এবং ধীরে ধীরে নতুন রিভিশনে ট্র্যাফিক বাড়ান
- ক্লাউড ট্রেসিং সেটআপ করুন এবং এজেন্ট রান ট্রেসিং পরিদর্শন করুন
স্থাপত্যের সংক্ষিপ্ত বিবরণ
পূর্বশর্ত
- পাইথনের সাথে কাজ করা আরামদায়ক
- HTTP পরিষেবা ব্যবহার করে মৌলিক ফুল-স্ট্যাক আর্কিটেকচার সম্পর্কে ধারণা
তুমি কি শিখবে
- ADK কাঠামো এবং স্থানীয় উপযোগিতা
- ডাটাবেস সেশন পরিষেবার সাথে ADK এজেন্ট সেটআপ করুন
- ডাটাবেস সেশন পরিষেবা দ্বারা ব্যবহারের জন্য CloudSQL-এ PostgreSQL সেটআপ করুন
- ডকারফাইল ব্যবহার করে ক্লাউড রানে অ্যাপ্লিকেশন স্থাপন করুন এবং প্রাথমিক পরিবেশ ভেরিয়েবল সেটআপ করুন
- লোড টেস্টিং সহ ক্লাউড রান অটো স্কেলিং কনফিগার এবং পরীক্ষা করুন
- ক্লাউড রানের মাধ্যমে ধীরে ধীরে মুক্তির কৌশল
- ক্লাউড ট্রেসে ADK এজেন্ট ট্রেসিং সেটআপ করুন
তোমার যা লাগবে
- ক্রোম ওয়েব ব্রাউজার
- একটি জিমেইল অ্যাকাউন্ট
- বিলিং সক্ষম করা একটি ক্লাউড প্রকল্প
সকল স্তরের ডেভেলপারদের জন্য (নতুনদের সহ) তৈরি এই কোডল্যাবটি তার নমুনা অ্যাপ্লিকেশনে পাইথন ব্যবহার করে। তবে, উপস্থাপিত ধারণাগুলি বোঝার জন্য পাইথন জ্ঞানের প্রয়োজন নেই।
২. 🚀 ওয়ার্কশপ ডেভেলপমেন্ট সেটআপ প্রস্তুত করা
ধাপ ১: ক্লাউড কনসোলে অ্যাক্টিভ প্রজেক্ট নির্বাচন করুন
গুগল ক্লাউড কনসোলে , প্রজেক্ট সিলেক্টর পৃষ্ঠায়, একটি গুগল ক্লাউড প্রোজেক্ট নির্বাচন করুন বা তৈরি করুন (আপনার কনসোলের উপরের বাম অংশটি দেখুন)
এটিতে ক্লিক করুন, এবং আপনি আপনার সমস্ত প্রকল্পের তালিকা দেখতে পাবেন যেমন এই উদাহরণে,
লাল বাক্সে যে মানটি নির্দেশিত তা হল PROJECT ID এবং এই মানটি পুরো টিউটোরিয়াল জুড়ে ব্যবহার করা হবে।
আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং সক্ষম আছে কিনা তা নিশ্চিত করুন। এটি পরীক্ষা করতে, আপনার উপরের বাম বারে বার্গার আইকন ☰ এ ক্লিক করুন যা নেভিগেশন মেনু দেখায় এবং বিলিং মেনুটি খুঁজে বের করুন।
যদি আপনি বিলিং / ওভারভিউ শিরোনামের অধীনে "গুগল ক্লাউড প্ল্যাটফর্ম ট্রায়াল বিলিং অ্যাকাউন্ট" দেখতে পান ( আপনার ক্লাউড কনসোলের উপরের বাম অংশ ), তাহলে আপনার প্রকল্পটি এই টিউটোরিয়ালের জন্য ব্যবহারের জন্য প্রস্তুত। যদি না হয়, তাহলে এই টিউটোরিয়ালের শুরুতে ফিরে যান এবং ট্রায়াল বিলিং অ্যাকাউন্টটি রিডিম করুন।
ধাপ ২: ক্লাউড SQL ডাটাবেস প্রস্তুত করা
পরবর্তীতে ADK এজেন্টের ব্যবহারের জন্য আমাদের একটি ডাটাবেসের প্রয়োজন হবে। ক্লাউড SQL-এ একটি PostgreSQL ডাটাবেস তৈরি করা যাক। প্রথমে, ক্লাউড কনসোলের উপরের অংশে সার্চ বারে যান এবং "cloud sql" টাইপ করুন। তারপর ক্লাউড SQL পণ্যটিতে ক্লিক করুন।
এর পরে, আমাদের একটি নতুন ডাটাবেস ইনস্ট্যান্স তৈরি করতে হবে, Create Instance এ ক্লিক করতে হবে এবং PostgreSQL নির্বাচন করতে হবে।
নতুন প্রজেক্ট শুরু করার সময় আপনাকে কম্পিউট ইঞ্জিন এপিআই সক্ষম করতে হতে পারে, যদি এই প্রম্পটটি প্রদর্শিত হয় তবে কেবল এপিআই সক্ষম করুন এ ক্লিক করুন।
এরপর, আমরা ডাটাবেসের স্পেসিফিকেশন নির্বাচন করব, স্যান্ডবক্স সংস্করণ প্রিসেট সহ এন্টারপ্রাইজ সংস্করণ নির্বাচন করব।
এরপর, এখানে ব্যবহারকারী পোস্টগ্রেসের জন্য ইনস্ট্যান্স নাম এবং ডিফল্ট পাসওয়ার্ড সেট করুন। আপনি যেকোনো শংসাপত্র দিয়ে এটি সেট আপ করতে পারেন, তবে এই টিউটোরিয়ালের জন্য আমরা এখানে " adk-deployment " উদাহরণের নাম এবং " ADK-deployment123 " পাসওয়ার্ড ব্যবহার করব।
এই টিউটোরিয়ালের জন্য single zone সহ us-central1 ব্যবহার করা যাক, আমরা তখন আমাদের ডাটাবেস তৈরি চূড়ান্ত করতে পারি এবং Create Instance বোতামে ক্লিক করে সমস্ত প্রয়োজনীয় সেটআপ সম্পন্ন করতে পারি।
এটি শেষ হওয়ার জন্য অপেক্ষা করার সময়, আমরা পরবর্তী বিভাগে যেতে পারি।
ধাপ ৩: ক্লাউড শেলের সাথে পরিচিত হোন
আপনি বেশিরভাগ টিউটোরিয়ালের জন্য ক্লাউড শেল ব্যবহার করবেন, গুগল ক্লাউড কনসোলের উপরে অ্যাক্টিভেট ক্লাউড শেল ক্লিক করুন। যদি এটি আপনাকে অনুমোদনের জন্য অনুরোধ করে, তাহলে অনুমোদনে ক্লিক করুন।
ক্লাউড শেলের সাথে সংযুক্ত হয়ে গেলে, আমাদের পরীক্ষা করতে হবে যে শেল (অথবা টার্মিনাল) ইতিমধ্যেই আমাদের অ্যাকাউন্টের সাথে প্রমাণীকরণ করা হয়েছে কিনা।
gcloud auth list
যদি আপনি নীচের উদাহরণের মতো আপনার ব্যক্তিগত জিমেইল আউটপুট দেখতে পান, তাহলে সবকিছু ঠিক আছে।
Credentialed Accounts
ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
যদি না হয়, তাহলে আপনার ব্রাউজার রিফ্রেশ করার চেষ্টা করুন এবং অনুরোধ করা হলে Authorize- এ ক্লিক করুন (সংযোগ সমস্যার কারণে এটি ব্যাহত হতে পারে)
এরপর, আমাদের শেলটি ইতিমধ্যেই আপনার কাছে থাকা সঠিক PROJECT ID- তে কনফিগার করা আছে কিনা তা পরীক্ষা করতে হবে। যদি আপনি দেখেন যে টার্মিনালে $ আইকনের আগে ( ) এর ভিতরে একটি মান আছে (নীচের স্ক্রিনশটে, মানটি "adk-cloudrun-deployment-476504" ) তাহলে এই মানটি আপনার সক্রিয় শেল সেশনের জন্য কনফিগার করা প্রকল্পটি দেখায়।
যদি দেখানো মানটি ইতিমধ্যেই সঠিক থাকে, তাহলে আপনি পরবর্তী কমান্ডটি এড়িয়ে যেতে পারেন। তবে যদি এটি সঠিক না হয় বা অনুপস্থিত থাকে, তাহলে নিম্নলিখিত কমান্ডটি চালান।
gcloud config set project <YOUR_PROJECT_ID>
তারপর, Github থেকে এই কোডল্যাবের জন্য টেমপ্লেট ওয়ার্কিং ডিরেক্টরিটি ক্লোন করুন, নিম্নলিখিত কমান্ডটি চালান। এটি deploy_and_manage_adk ডিরেক্টরিতে ওয়ার্কিং ডিরেক্টরি তৈরি করবে।
git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk
ধাপ ৪: ক্লাউড শেল এডিটরের সাথে পরিচিত হোন এবং অ্যাপ্লিকেশন ওয়ার্কিং ডিরেক্টরি সেটআপ করুন
এখন, আমরা কিছু কোডিং কাজ করার জন্য আমাদের কোড এডিটর সেট আপ করতে পারি। এর জন্য আমরা ক্লাউড শেল এডিটর ব্যবহার করব।
ওপেন এডিটর বোতামে ক্লিক করুন, এটি একটি ক্লাউড শেল এডিটর খুলবে। 
এরপর, ক্লাউড শেল এডিটরের উপরের অংশে যান এবং File->Open Folder এ ক্লিক করুন, আপনার ব্যবহারকারীর নাম ডিরেক্টরিটি খুঁজুন এবং deploy_and_manage_adk ডিরেক্টরিটি খুঁজুন তারপর OK বোতামে ক্লিক করুন। এটি নির্বাচিত ডিরেক্টরিটিকে প্রধান কার্যকরী ডিরেক্টরি হিসাবে পরিণত করবে। এই উদাহরণে, ব্যবহারকারীর নাম হল alvinprayuda , তাই ডিরেক্টরি পাথটি নীচে দেখানো হয়েছে।
এখন, আপনার ক্লাউড শেল এডিটর ওয়ার্কিং ডিরেক্টরিটি দেখতে এইরকম হওয়া উচিত ( deploy_and_manage_adk এর ভিতরে)
এবার এডিটরের জন্য টার্মিনাল খুলুন। মেনু বারে Terminal -> New Terminal এ ক্লিক করে অথবা Ctrl + Shift + C ব্যবহার করে এটি করতে পারেন। এটি ব্রাউজারের নীচের অংশে একটি টার্মিনাল উইন্ডো খুলবে।
আপনার বর্তমান সক্রিয় টার্মিনালটি deploy_and_manage_adk ওয়ার্কিং ডিরেক্টরির মধ্যে থাকা উচিত। আমরা এই কোডল্যাবে Python 3.12 ব্যবহার করব এবং Python সংস্করণ এবং ভার্চুয়াল পরিবেশ তৈরি এবং পরিচালনা করার প্রয়োজনীয়তা সহজ করার জন্য uv python প্রজেক্ট ম্যানেজার ব্যবহার করব। এই uv প্যাকেজটি ইতিমধ্যেই Cloud Shell-এ প্রি-ইন্সটল করা আছে।
.venv ডিরেক্টরিতে ভার্চুয়াল পরিবেশের জন্য প্রয়োজনীয় নির্ভরতা ইনস্টল করতে এই কমান্ডটি চালান।
uv sync --frozen
এখন, আমাদের নীচে দেখানো কমান্ডের মাধ্যমে প্রয়োজনীয় API গুলি সক্রিয় করতে হবে। এতে কিছুটা সময় লাগতে পারে।
gcloud services enable aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com \
sqladmin.googleapis.com
কমান্ডটি সফলভাবে কার্যকর করার পরে, আপনি নীচের দেখানো বার্তার মতো একটি বার্তা দেখতে পাবেন:
Operation "operations/..." finished successfully.
এরপর, আমাদের এই প্রকল্পের জন্য কনফিগারেশন ফাইল সেট আপ করতে হবে।
.env.example ফাইলটির নাম পরিবর্তন করে .env করুন।
cp .env.example .env
.env ফাইলটি খুলুন এবং আপনার প্রোজেক্ট-আইডিতে GOOGLE_CLOUD_PROJECT মান আপডেট করুন।
# .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. আপাতত, আমরা DB_CONNECTION_NAME মন্তব্য করা বাদ দেব।
এখন আমরা পরবর্তী ধাপে যেতে পারি, এজেন্ট লজিক পরীক্ষা করে এটি স্থাপন করতে পারি।
৩. 🚀 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)
এখন, এটি পরীক্ষা করতে, আপনার ক্লাউড শেল এডিটরের উপরের অংশে ওয়েব প্রিভিউ বোতামে ক্লিক করুন এবং পোর্ট 8080-এ প্রিভিউ নির্বাচন করুন।
আপনি নিম্নলিখিত ওয়েব পৃষ্ঠাটি দেখতে পাবেন যেখানে আপনি উপরের বাম ড্রপ ডাউন বোতামে (আমাদের ক্ষেত্রে এটি weather_agent হওয়া উচিত) উপলব্ধ এজেন্ট নির্বাচন করতে পারবেন এবং বটের সাথে ইন্টারঅ্যাক্ট করতে পারবেন। আপনি বাম উইন্ডোতে এজেন্ট রানটাইম চলাকালীন লগের বিবরণ সম্পর্কে অনেক তথ্য দেখতে পাবেন।
এখন, এটির সাথে ইন্টারঅ্যাক্ট করার চেষ্টা করুন। বাম বারে, আমরা প্রতিটি ইনপুটের ট্রেস পরীক্ষা করতে পারি, যাতে আমরা বুঝতে পারি যে এজেন্ট দ্বারা চূড়ান্ত উত্তর তৈরি করার আগে প্রতিটি পদক্ষেপের জন্য কত সময় লাগে।
এটি ADK-তে নির্মিত পর্যবেক্ষণযোগ্যতা বৈশিষ্ট্যগুলির মধ্যে একটি, বর্তমানে আমরা এটি স্থানীয়ভাবে পরীক্ষা করছি। পরে আমরা দেখব কিভাবে এটি ক্লাউড ট্রেসিং-এ একীভূত করা হয়েছে যাতে আমরা সমস্ত অনুরোধের কেন্দ্রীভূত ট্রেস পেতে পারি।
৪. 🚀 ক্লাউড রানে মোতায়েন করা
এবার, এই এজেন্ট পরিষেবাটি ক্লাউড রানে স্থাপন করা যাক। এই ডেমোর জন্য, এই পরিষেবাটিকে একটি পাবলিক পরিষেবা হিসাবে প্রকাশ করা হবে যা অন্যরা অ্যাক্সেস করতে পারে। তবে, মনে রাখবেন যে এটি সর্বোত্তম অনুশীলন নয় কারণ এটি নিরাপদ নয়।
এই কোডল্যাবে, আমরা ক্লাউড রানে আমাদের এজেন্ট স্থাপন করতে Dockerfile ব্যবহার করব। এই মুহুর্তে, ক্লাউড রানে আমাদের অ্যাপ্লিকেশন স্থাপন করার জন্য প্রয়োজনীয় সমস্ত ফাইল ( Dockerfile এবং server.py ) ইতিমধ্যেই আমাদের কাছে রয়েছে। আমরা পরে এটি সম্পর্কে বিস্তারিত আলোচনা করব।
এখন, প্রথমে পরিষেবাটি স্থাপন করা যাক, ক্লাউড শেল টার্মিনালে নেভিগেট করুন এবং নিশ্চিত করুন যে বর্তমান প্রকল্পটি আপনার সক্রিয় প্রকল্পের সাথে কনফিগার করা আছে, যদি না হয় তবে আপনাকে প্রকল্প আইডি সেট করতে gcloud configure কমান্ড ব্যবহার করতে হবে:
gcloud config set project [PROJECT_ID]
এখন, আমাদের .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 মান পেতে, আপনি আবার ক্লাউড SQL-এ যেতে পারেন এবং আপনার তৈরি করা ইনস্ট্যান্সে ক্লিক করতে পারেন। ক্লাউড কনসোলের উপরের অংশে অনুসন্ধান বারে নেভিগেট করুন এবং "cloud sql" টাইপ করুন। তারপর ক্লাউড SQL পণ্যটিতে ক্লিক করুন।
এর পরে আপনি পূর্বে তৈরি করা উদাহরণটি দেখতে পাবেন, এটিতে ক্লিক করুন
ইনস্ট্যান্স পৃষ্ঠার ভেতরে, " এই ইনস্ট্যান্সে সংযোগ করুন " বিভাগে স্ক্রোল করুন এবং আপনি DB_CONNECTION_NAME মানটি প্রতিস্থাপন করতে সংযোগের নামটি অনুলিপি করতে পারেন।
এরপর .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 ভেরিয়েবল লোড করবে, তারপর ডিপ্লয়মেন্ট কমান্ডটি চালাবে।
যদি আপনি আরও ভালোভাবে লক্ষ্য করেন, তাহলে বুঝতে হবে যে, কোনও পরিষেবা স্থাপন করতে হলে যে সমস্ত প্রয়োজনীয় কাজগুলি করতে হবে সেগুলি করার জন্য আমাদের কেবল একটি gcloud run deploy কমান্ডের প্রয়োজন: ছবি তৈরি করা, রেজিস্ট্রিতে পুশ করা, পরিষেবা স্থাপন করা, IAM নীতি সেট করা, সংশোধন তৈরি করা এবং এমনকি ট্র্যাফিক রাউটিং করা। এই উদাহরণে, আমরা ইতিমধ্যেই 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"]
আমরা এখানে এজেন্টকে সহায়তা করার জন্য প্রয়োজনীয় পরিষেবাগুলি কনফিগার করতে পারি যেমন উৎপাদনের উদ্দেশ্যে Session , Memory , অথবা Artifact পরিষেবা প্রস্তুত করা। এখানে 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 স্ক্রিপ্টে এই জিনিসগুলি সংজ্ঞায়িত করা হয়েছে:
-
get_fast_api_appপদ্ধতি ব্যবহার করে আমাদের এজেন্টকে একটি FastAPI অ্যাপে রূপান্তর করুন। এইভাবে আমরা ওয়েব ডেভেলপমেন্ট UI এর জন্য ব্যবহৃত একই রুট সংজ্ঞা উত্তরাধিকার সূত্রে পাব। -
get_fast_api_appপদ্ধতিতে কীওয়ার্ড আর্গুমেন্ট যোগ করে প্রয়োজনীয় সেশন, মেমোরি, অথবা আর্টিফ্যাক্ট পরিষেবা কনফিগার করুন। এই টিউটোরিয়ালে, যদি আমরাSESSION_SERVICE_URIenv var কনফিগার করি, তাহলে সেশন পরিষেবাটি সেটি ব্যবহার করবে অন্যথায় এটি ইন-মেমোরি সেশন ব্যবহার করবে। - আমরা অন্যান্য ব্যাকএন্ড ব্যবসায়িক যুক্তি সমর্থন করার জন্য কাস্টম রুট যোগ করতে পারি, স্ক্রিপ্টে আমরা প্রতিক্রিয়া কার্যকারিতা রুটের উদাহরণ যোগ করি
- Google Cloud Trace-এ ট্রেস পাঠাতে,
get_fast_api_apparg প্যারামিটারে ক্লাউড ট্রেসিং সক্ষম করুন। - uvicorn ব্যবহার করে FastAPI পরিষেবা চালান
এখন, যদি আপনার স্থাপনা ইতিমধ্যেই সম্পন্ন হয়ে থাকে, তাহলে অনুগ্রহ করে ক্লাউড রান URL অ্যাক্সেস করে ওয়েব ডেভেলপার UI থেকে এজেন্টের সাথে ইন্টারঅ্যাক্ট করার চেষ্টা করুন।
৬. 🚀 লোড টেস্টিং সহ ক্লাউড রান অটো স্কেলিং পরিদর্শন করা
এখন, আমরা ক্লাউড রানের অটো-স্কেলিং ক্ষমতা পরীক্ষা করব। এই পরিস্থিতিতে, আসুন প্রতি ইনস্ট্যান্সে সর্বাধিক কনকারেন্সি সক্ষম করে নতুন সংস্করণ স্থাপন করি। পূর্ববর্তী বিভাগে, আমরা সর্বোচ্চ কনকারেন্সি 10 (flag --concurrency 10 ) এ সেট করেছি। তাই আমরা আশা করতে পারি যে যখন আমরা এই সংখ্যা অতিক্রম করে লোড পরীক্ষা করব তখন ক্লাউড রান তার ইনস্ট্যান্স স্কেল করার চেষ্টা করবে।
load_test.py ফাইলটি পরীক্ষা করা যাক। locust framework ব্যবহার করে লোড টেস্টিং করার জন্য আমরা এই স্ক্রিপ্টটি ব্যবহার করব। এই স্ক্রিপ্টটি নিম্নলিখিত কাজগুলি করবে:
- এলোমেলোভাবে ব্যবহারকারীর আইডি এবং সেশনের আইডি
- ব্যবহারকারীর আইডির জন্য session_id তৈরি করুন
- তৈরি করা user_id এবং session_id দিয়ে এন্ডপয়েন্ট "/run_sse" টিপুন।
যদি আপনি এটি মিস করে থাকেন, তাহলে আমাদের ডিপ্লয় করা পরিষেবার URL জানতে হবে। ক্লাউড রান কনসোলে যান এবং আপনার আবহাওয়া-এজেন্ট পরিষেবাতে ক্লিক করুন।
তারপর, আপনার আবহাওয়া-এজেন্ট পরিষেবাটি খুঁজুন এবং এটিতে ক্লিক করুন।
পরিষেবা URLটি অঞ্চলের তথ্যের ঠিক পাশে প্রদর্শিত হবে। যেমন
তারপর লোড পরীক্ষা করার জন্য নিম্নলিখিত কমান্ডটি চালান
uv run locust -f load_test.py \
-H {YOUR_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
তাহলে দেখা যাক ক্লাউড রানে কী ঘটেছিল, আবার আপনার ডিপ্লয় করা পরিষেবাতে যান এবং ড্যাশবোর্ডটি দেখুন। এটি দেখাবে কিভাবে ক্লাউড রান স্বয়ংক্রিয়ভাবে ইনস্ট্যান্স স্কেল করে ইনস্ট্যান্সকে ইনস্ট্যান্স হ্যান্ডেল করে। যেহেতু আমরা প্রতি ইনস্ট্যান্সে সর্বোচ্চ কনকারেন্সি ১০-এর মধ্যে সীমাবদ্ধ রাখছি, তাই ক্লাউড রান ইনস্ট্যান্স স্বয়ংক্রিয়ভাবে এই শর্ত পূরণ করার জন্য কন্টেইনারের সংখ্যা সামঞ্জস্য করার চেষ্টা করবে।
৭. 🚀 ধীরে ধীরে নতুন সংস্করণ প্রকাশ
এবার, নিচের দৃশ্যপটটি দেখা যাক। আমরা এজেন্টের প্রম্পট আপডেট করতে চাই। 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 {YOUR_PROJECT_ID} \
--allow-unauthenticated \
--region us-central1 \
--no-traffic
কাজ শেষ করার পর, আপনি পূর্ববর্তী স্থাপনার প্রক্রিয়ার মতো একই ধরণের লগ পাবেন যেখানে পরিবেশিত ট্র্যাফিকের সংখ্যার পার্থক্য থাকবে। এটি 0 শতাংশ ট্র্যাফিক পরিবেশিত দেখাবে।
Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.
এরপর, ক্লাউড রান প্রোডাক্ট পেজে যাই এবং আপনার ডিপ্লয় করা ইনস্ট্যান্সটি খুঁজে বের করি। সার্চ বারে ক্লাউড রান টাইপ করুন এবং ক্লাউড রান প্রোডাক্টে ক্লিক করুন।
তারপর, আপনার আবহাওয়া-এজেন্ট পরিষেবাটি খুঁজুন এবং এটিতে ক্লিক করুন।
রিভিশন ট্যাবে যান এবং আপনি সেখানে ডিপ্লয় করা রিভিশনের তালিকা দেখতে পাবেন।
আপনি দেখতে পাবেন যে নতুন মোতায়েন করা সংশোধনগুলি 0% পরিবেশন করছে, এখান থেকে আপনি কাবাব বোতাম (⋮) ক্লিক করতে পারেন এবং ট্র্যাফিক পরিচালনা করুন নির্বাচন করতে পারেন।
নতুন পপ আপ উইন্ডোতে, আপনি কোন সংশোধনগুলিতে যাচ্ছেন তার ট্র্যাফিকের শতাংশ সম্পাদনা করতে পারেন।
কিছুক্ষণ অপেক্ষা করার পর, শতাংশ কনফিগারেশনের উপর ভিত্তি করে ট্র্যাফিক আনুপাতিকভাবে পরিচালিত হবে। এইভাবে, নতুন রিলিজে কিছু ঘটলে আমরা সহজেই পূর্ববর্তী সংস্করণগুলিতে ফিরে যেতে পারি।
৮. 🚀 ADK ট্রেসিং
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] ) ফিল্টার করতে পারেন।
স্প্যানগুলি ইতিমধ্যেই ফিল্টার করা হয়ে গেলে, আপনি প্রতিটি ট্রেস সরাসরি পরিদর্শন করতে পারেন। এটি এজেন্ট দ্বারা গৃহীত প্রতিটি পদক্ষেপের বিস্তারিত সময়কাল দেখাবে। উদাহরণস্বরূপ, নীচের ছবিগুলি দেখুন।
প্রতিটি বিভাগে, আপনি নীচের দেখানো বৈশিষ্ট্যগুলির বিবরণ পরিদর্শন করতে পারেন।
এই নাও, এখন আমাদের কাছে ব্যবহারকারীর সাথে আমাদের এজেন্টের প্রতিটি মিথস্ক্রিয়া সম্পর্কে ভালো পর্যবেক্ষণযোগ্যতা এবং তথ্য রয়েছে যা সমস্যাগুলি ডিবাগ করতে সাহায্য করবে। বিভিন্ন টুলিং বা ওয়ার্কফ্লো চেষ্টা করে দেখতে দ্বিধা করবেন না!
৯. 🎯 চ্যালেঞ্জ
মাল্টি-এজেন্ট বা এজেন্টিক ওয়ার্কফ্লো ব্যবহার করে দেখুন লোডের নিচে কীভাবে কাজ করে এবং ট্রেসটি কেমন দেখাচ্ছে।
১০. 🧹 পরিষ্কার করা
এই কোডল্যাবে ব্যবহৃত রিসোর্সের জন্য আপনার Google ক্লাউড অ্যাকাউন্টে চার্জ এড়াতে, এই পদক্ষেপগুলি অনুসরণ করুন:
- গুগল ক্লাউড কনসোলে, রিসোর্স পরিচালনা পৃষ্ঠায় যান।
- প্রকল্পের তালিকায়, আপনি যে প্রকল্পটি মুছতে চান তা নির্বাচন করুন এবং তারপরে মুছুন ক্লিক করুন।
- ডায়ালগে, প্রজেক্ট আইডি টাইপ করুন, এবং তারপর প্রজেক্টটি মুছে ফেলতে Shut down এ ক্লিক করুন।
- বিকল্পভাবে আপনি কনসোলের ক্লাউড রানে যেতে পারেন, আপনার সবেমাত্র স্থাপন করা পরিষেবাটি নির্বাচন করতে পারেন এবং মুছে ফেলতে পারেন।