ক্লাউড রানে একটি ADK এজেন্ট তৈরি এবং স্থাপন করুন

1. ভূমিকা

এই ল্যাবটি ক্লায়েন্ট এজেন্ট পরিষেবা বাস্তবায়ন এবং স্থাপনের উপর দৃষ্টি নিবদ্ধ করে। আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে এমন একটি AI এজেন্ট তৈরি করবেন যা সরঞ্জাম ব্যবহার করে।

এই ল্যাবে, আমরা একটি চিড়িয়াখানা এজেন্ট তৈরি করছি যারা উইকিপিডিয়া ব্যবহার করে প্রাণী সম্পর্কে প্রশ্নের উত্তর দেবে।

অবশেষে, আমরা কেবল স্থানীয়ভাবে চালানোর পরিবর্তে Google Cloud Run- এ ট্যুর গাইড এজেন্ট স্থাপন করব।

পূর্বশর্ত

• বিলিং সক্ষম করা একটি Google ক্লাউড প্রকল্প।

তুমি কি শিখবে

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

তোমার যা লাগবে

• একটি গুগল ক্লাউড অ্যাকাউন্ট এবং গুগল ক্লাউড প্রকল্প
• ক্রোমের মতো একটি ওয়েব ব্রাউজার

2. ক্লাউড রানে কেন মোতায়েন করবেন?

ADK এজেন্টদের হোস্ট করার জন্য ক্লাউড রান একটি দুর্দান্ত পছন্দ কারণ এটি একটি সার্ভারলেস প্ল্যাটফর্ম, যার অর্থ আপনি আপনার কোডের উপর মনোযোগ দিতে পারেন, অন্তর্নিহিত অবকাঠামো পরিচালনার উপর নয়। আমরা আপনার জন্য অপারেশনাল কাজ পরিচালনা করি।

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

মূল বৈশিষ্ট্য

যেকোনো জায়গায় কন্টেইনার চালায়:

• তুমি একটা কন্টেইনার (ডকার ইমেজ) আনবে যার ভেতরে তোমার অ্যাপ থাকবে।
• ক্লাউড রান এটি গুগলের পরিকাঠামোতে চালায়।
• কোনও OS প্যাচিং, VM সেটআপ, বা স্কেলিং মাথাব্যথা নেই।

স্বয়ংক্রিয় স্কেলিং:

• যদি ০ জন লোক আপনার অ্যাপ ব্যবহার করে → ০ টি ইন্সট্যান্স রান হয় (শূন্য ইন্সট্যান্সে নামিয়ে আনা হয় যা সাশ্রয়ী)।
• যদি ১০০০টি অনুরোধ আসে → এটি যতগুলি প্রয়োজন ততগুলি কপি ঘুরিয়ে দেয়।

ডিফল্টরূপে স্টেটলেস:

• প্রতিটি অনুরোধ ভিন্ন ভিন্ন ক্ষেত্রে যেতে পারে।
• যদি আপনার স্টোর স্টেট প্রয়োজন হয়, তাহলে ক্লাউড এসকিউএল, ফায়ারস্টোর, অথবা মেমোরিস্টোরের মতো একটি বহিরাগত পরিষেবা ব্যবহার করুন।

যেকোনো ভাষা বা ফ্রেমওয়ার্ক সমর্থন করে:

• যতক্ষণ এটি একটি লিনাক্স কন্টেইনারে চলে, ক্লাউড রান পাইথন, গো, নোড.জেএস, জাভা, নাকি .নেট তা বিবেচনা করে না।

আপনি যা ব্যবহার করেন তার জন্য অর্থ প্রদান করুন:

• অনুরোধ-ভিত্তিক বিলিং : প্রতি অনুরোধে বিল করা + গণনার সময় (১০০ মিলিসেকেন্ড পর্যন্ত)।
• ইনস্ট্যান্স-ভিত্তিক বিলিং : সম্পূর্ণ ইনস্ট্যান্স লাইফটাইমের জন্য বিল করা হবে (প্রতি-অনুরোধের জন্য কোনও ফি নেই)।

৩. প্রকল্প সেটআপ

গুগল অ্যাকাউন্ট

যদি আপনার ইতিমধ্যেই একটি ব্যক্তিগত Google অ্যাকাউন্ট না থাকে, তাহলে আপনাকে অবশ্যই একটি Google অ্যাকাউন্ট তৈরি করতে হবে।

কর্মক্ষেত্র বা স্কুল অ্যাকাউন্টের পরিবর্তে ব্যক্তিগত অ্যাকাউন্ট ব্যবহার করুন ।

কর্মক্ষেত্র এবং স্কুল অ্যাকাউন্টগুলিতে এমন বিধিনিষেধ থাকতে পারে যা আপনাকে এই ল্যাবের জন্য প্রয়োজনীয় API গুলি সক্ষম করতে বাধা দেয়।

গুগল ক্লাউড কনসোলে সাইন-ইন করুন

একটি ব্যক্তিগত গুগল অ্যাকাউন্ট ব্যবহার করে গুগল ক্লাউড কনসোলে সাইন-ইন করুন।

বিলিং সক্ষম করুন

একটি ব্যক্তিগত বিলিং অ্যাকাউন্ট সেট আপ করুন

আপনি যদি গুগল ক্লাউড ক্রেডিট ব্যবহার করে বিলিং সেট আপ করেন, তাহলে আপনি এই ধাপটি এড়িয়ে যেতে পারেন।

একটি ব্যক্তিগত বিলিং অ্যাকাউন্ট সেট আপ করতে, ক্লাউড কনসোলে বিলিং সক্ষম করতে এখানে যান ।

কিছু নোট:

• এই ল্যাবটি সম্পূর্ণ করতে ক্লাউড রিসোর্সে $1 USD এর কম খরচ হবে।
• আরও চার্জ এড়াতে আপনি এই ল্যাবের শেষে রিসোর্স মুছে ফেলার ধাপগুলি অনুসরণ করতে পারেন।
• নতুন ব্যবহারকারীরা $300 USD বিনামূল্যে ট্রায়ালের জন্য যোগ্য।

একটি প্রকল্প তৈরি করুন (ঐচ্ছিক)

যদি আপনার এই ল্যাবের জন্য ব্যবহার করতে চান এমন কোন বর্তমান প্রকল্প না থাকে, তাহলে এখানে একটি নতুন প্রকল্প তৈরি করুন ।

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

1. সরাসরি ক্লাউড শেল এডিটরে যেতে এই লিঙ্কে ক্লিক করুন।
2. আজই যদি যেকোনো সময় অনুমোদনের অনুরোধ করা হয়, তাহলে চালিয়ে যেতে অনুমোদন করুন- এ ক্লিক করুন।
3. যদি স্ক্রিনের নীচে টার্মিনালটি না দেখা যায়, তাহলে এটি খুলুন:
   • ভিউ ক্লিক করুন
   • টার্মিনাল ক্লিক করুন

৫. API গুলি সক্ষম করুন

ক্লাউড রান , আর্টিফ্যাক্ট রেজিস্ট্রি , ক্লাউড বিল্ড , ভার্টেক্স এআই এবং কম্পিউট ইঞ্জিন ব্যবহার করার জন্য, আপনাকে আপনার গুগল ক্লাউড প্রোজেক্টে তাদের নিজ নিজ API গুলি সক্ষম করতে হবে।

• টার্মিনালে , API গুলি সক্রিয় করুন:

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

  এটি চালানো শেষ হলে, আপনি নিম্নলিখিতটির মতো একটি আউটপুট দেখতে পাবেন:

  Operation "operations/acat.p2-[GUID]" finished successfully.
  

API গুলির সাথে পরিচয় করিয়ে দেওয়া হচ্ছে

• ক্লাউড রান অ্যাডমিন এপিআই ( run.googleapis.com ) আপনাকে সম্পূর্ণরূপে পরিচালিত পরিবেশে ফ্রন্টএন্ড এবং ব্যাকএন্ড পরিষেবা, ব্যাচ জব বা ওয়েবসাইট চালানোর অনুমতি দেয়। এটি আপনার কন্টেইনারাইজড অ্যাপ্লিকেশন স্থাপন এবং স্কেল করার জন্য অবকাঠামো পরিচালনা করে।
• আর্টিফ্যাক্ট রেজিস্ট্রি API ( artifactregistry.googleapis.com ) আপনার কন্টেইনার ছবি সংরক্ষণের জন্য একটি নিরাপদ, ব্যক্তিগত সংগ্রহস্থল প্রদান করে। এটি কন্টেইনার রেজিস্ট্রির বিবর্তন এবং ক্লাউড রান এবং ক্লাউড বিল্ডের সাথে নির্বিঘ্নে সংহত হয়।
• ক্লাউড বিল্ড এপিআই ( cloudbuild.googleapis.com ) হল একটি সার্ভারলেস সিআই/সিডি প্ল্যাটফর্ম যা গুগল ক্লাউড অবকাঠামোতে আপনার বিল্ডগুলি কার্যকর করে। এটি আপনার ডকারফাইল থেকে ক্লাউডে আপনার কন্টেইনার ইমেজ তৈরি করতে ব্যবহৃত হয়।
• ভার্টেক্স এআই এপিআই ( aiplatform.googleapis.com ) আপনার মোতায়েন করা অ্যাপ্লিকেশনটিকে মূল এআই কাজগুলি সম্পাদনের জন্য জেমিনি মডেলগুলির সাথে যোগাযোগ করতে সক্ষম করে। এটি গুগল ক্লাউডের সমস্ত এআই পরিষেবার জন্য একীভূত এপিআই সরবরাহ করে।
• কম্পিউট ইঞ্জিন এপিআই ( compute.googleapis.com ) গুগলের অবকাঠামোতে পরিচালিত নিরাপদ এবং কাস্টমাইজযোগ্য ভার্চুয়াল মেশিন সরবরাহ করে। ক্লাউড রান পরিচালিত হলেও, বিভিন্ন নেটওয়ার্কিং এবং কম্পিউট রিসোর্সের জন্য প্রায়শই একটি মৌলিক নির্ভরতা হিসাবে কম্পিউট ইঞ্জিন এপিআই প্রয়োজন হয়।

৬. আপনার উন্নয়নের পরিবেশ প্রস্তুত করুন

ডিরেক্টরি তৈরি করুন

1. টার্মিনালে , প্রজেক্ট ডিরেক্টরি এবং প্রয়োজনীয় সাবডিরেক্টরি তৈরি করুন:

   cd && mkdir zoo_guide_agent && cd zoo_guide_agent
   

2. টার্মিনালে, ক্লাউড শেল এডিটর এক্সপ্লোরারে zoo_guide_agent ডিরেক্টরিটি খুলতে নিম্নলিখিত কমান্ডটি চালান:

   cloudshell open-workspace ~/zoo_guide_agent
   

3. বাম দিকের এক্সপ্লোরার প্যানেলটি রিফ্রেশ হবে। এখন আপনি আপনার তৈরি করা ডিরেক্টরিটি দেখতে পাবেন।
   
   

   যদি এটি করার সময় টার্মিনালটি অদৃশ্য হয়ে যায় , তাহলে আপনি উপরের মেনুতে View এবং তারপর Terminal-এ ক্লিক করে এটি পুনরায় খুলতে পারেন।

আপনার প্রকল্প সেট করুন

1. টার্মিনালে, এই কমান্ড দিয়ে আপনার প্রকল্পটি সেট করুন:

   gcloud config set project [PROJECT_ID]
   

   উদাহরণ: gcloud config set project lab-project-id-example

   যদি আপনি আপনার প্রজেক্ট আইডি মনে রাখতে না পারেন, তাহলে আপনি আপনার সমস্ত প্রজেক্ট আইডি তালিকাভুক্ত করতে পারেন: gcloud projects list

   
2. আপনার এই বার্তাটি দেখা উচিত:

   Updated property [core/project].
   

   যদি আপনি একটি WARNING দেখতে পান এবং জিজ্ঞাসা করা হয় Do you want to continue (Y/n)? , তাহলে সম্ভবত আপনি প্রজেক্ট আইডি ভুলভাবে প্রবেশ করেছেন। n টিপুন, Enter টিপুন, এবং আবার gcloud config set project কমান্ডটি চালানোর চেষ্টা করুন।

ইনস্টল করার প্রয়োজনীয়তা

1. requirements.txt ফাইল তৈরি করতে টার্মিনালে নিম্নলিখিত কমান্ডটি চালান।

   cloudshell edit requirements.txt
   

2. নতুন তৈরি requirements.txt ফাইলে নিম্নলিখিতগুলি যোগ করুন।

   google-adk==1.14.0
   langchain-community==0.3.27
   wikipedia==1.4.0
   

3. টার্মিনালে , uv ব্যবহার করে একটি ভার্চুয়াল পরিবেশ তৈরি এবং সক্রিয় করুন। এটি নিশ্চিত করে যে আপনার প্রকল্পের নির্ভরতাগুলি পাইথন সিস্টেমের সাথে বিরোধ না করে।

   uv venv
   source .venv/bin/activate
   

   দ্রষ্টব্য : যদি আপনার ক্লাউড শেল সেশন রিফ্রেশ হয় অথবা আপনি একটি নতুন টার্মিনাল ট্যাব খোলেন, তাহলে আপনাকে source .venv/bin/activate চালিয়ে ভার্চুয়াল পরিবেশ পুনরায় সক্রিয় করতে হতে পারে।

4. টার্মিনালে আপনার ভার্চুয়াল পরিবেশে প্রয়োজনীয় প্যাকেজগুলি ইনস্টল করুন।

   uv pip install -r requirements.txt
   

পরিবেশ ভেরিয়েবল সেট আপ করুন

• .env ফাইল তৈরি করতে টার্মিনালে নিম্নলিখিত কমান্ডটি ব্যবহার করুন।

  # 1. Set the variables in your terminal first
  PROJECT_ID=$(gcloud config get-value project)
  PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
  SA_NAME=lab2-cr-service
  
  # 2. Create the .env file using those variables
  cat <<EOF > .env
  PROJECT_ID=$PROJECT_ID
  PROJECT_NUMBER=$PROJECT_NUMBER
  SA_NAME=$SA_NAME
  SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
  MODEL="gemini-2.5-flash"
  EOF
  

  .env ফাইলটি পরীক্ষা করে দেখুন এবং নিশ্চিত করুন যে PROJECT_ID , PROJECT_NUMBER , এবং SERVICE_ACCOUNT উভয়েরই মান নির্ধারিত আছে। যদি প্রকল্পের বিবরণ অনুপস্থিত থাকে, তাহলে gcloud projects list চালিয়ে সেগুলি খুঁজুন। যদি পরিষেবা অ্যাকাউন্ট অনুপস্থিত থাকে, তাহলে আপনি আপনার প্রকল্পের অ্যাকাউন্টগুলি তালিকাভুক্ত করে ইমেল ঠিকানাটি খুঁজে পেতে পারেন (এটি .iam.gserviceaccount.com দিয়ে শেষ হওয়া উচিত) gcloud iam service-accounts list চালিয়ে।

৭. এজেন্ট ওয়ার্কফ্লো তৈরি করুন

__init__.py ফাইল তৈরি করুন

1. টার্মিনালে নিম্নলিখিতটি চালিয়ে init .py ফাইলটি তৈরি করুন:

   cloudshell edit __init__.py
   

   এই ফাইলটি পাইথনকে বলে যে zoo_guide_agent ডিরেক্টরিটি একটি প্যাকেজ।
2. নতুন __init__.py ফাইলে নিম্নলিখিত কোডটি যোগ করুন:

   from . import agent
   

agent.py ফাইলটি তৈরি করুন।

1. টার্মিনালে নিম্নলিখিত কমান্ডটি পেস্ট করে প্রধান agent.py ফাইলটি তৈরি করুন।

   cloudshell edit agent.py
   

2. আমদানি এবং প্রাথমিক সেটআপ : আপনার বর্তমানে খালি agent.py ফাইলে নিম্নলিখিত কোডটি যোগ করুন:

   import os
   import logging
   import google.cloud.logging
   from dotenv import load_dotenv
   
   from google.adk import Agent
   from google.adk.agents import SequentialAgent
   from google.adk.tools.tool_context import ToolContext
   from google.adk.tools.langchain_tool import LangchainTool
   
   from langchain_community.tools import WikipediaQueryRun
   from langchain_community.utilities import WikipediaAPIWrapper
   
   import google.auth
   import google.auth.transport.requests
   import google.oauth2.id_token
   
   # --- Setup Logging and Environment ---
   
   cloud_logging_client = google.cloud.logging.Client()
   cloud_logging_client.setup_logging()
   
   load_dotenv()
   
   model_name = os.getenv("MODEL")
   

   agent.py ফাইলের এই প্রথম ব্লকটি ADK এবং Google ক্লাউড থেকে সমস্ত প্রয়োজনীয় লাইব্রেরি নিয়ে আসে। এটি লগিং সেট আপ করে এবং আপনার .env ফাইল থেকে পরিবেশগত ভেরিয়েবল লোড করে, যা আপনার মডেল এবং সার্ভার URL অ্যাক্সেস করার জন্য অত্যন্ত গুরুত্বপূর্ণ।
3. টুলসগুলো সংজ্ঞায়িত করুন : একটি এজেন্ট যতটা টুলস ব্যবহার করতে পারে ততটাই ভালো। টুলসগুলো সংজ্ঞায়িত করতে agent.py এর নীচে নিচের কোডটি যোগ করুন:

   # Greet user and save their prompt
   
   def add_prompt_to_state(
       tool_context: ToolContext, prompt: str
   ) -> dict[str, str]:
       """Saves the user's initial prompt to the state."""
       tool_context.state["PROMPT"] = prompt
       logging.info(f"[State updated] Added to PROMPT: {prompt}")
       return {"status": "success"}
   
   # Configuring the Wikipedia Tool
   wikipedia_tool = LangchainTool(
       tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
   )
   

   ব্যাখ্যা করা সরঞ্জামগুলি
   • add_prompt_to_state 📝: এই টুলটি একজন চিড়িয়াখানার দর্শনার্থীর জিজ্ঞাসা মনে রাখে। যখন একজন দর্শনার্থী জিজ্ঞাসা করে, "সিংহগুলো কোথায়?", তখন এই টুলটি সেই নির্দিষ্ট প্রশ্নটি এজেন্টের স্মৃতিতে সংরক্ষণ করে যাতে কর্মপ্রবাহের অন্যান্য এজেন্টরা জানতে পারে কী গবেষণা করতে হবে।
     কিভাবে: এটি একটি পাইথন ফাংশন যা shared tool_context.state অভিধানে ভিজিটরের প্রম্পট লিখে। এই টুল কনটেক্সট একটি একক কথোপকথনের জন্য এজেন্টের স্বল্পমেয়াদী মেমরির প্রতিনিধিত্ব করে। একজন এজেন্ট দ্বারা স্টেটে সংরক্ষিত ডেটা ওয়ার্কফ্লোতে পরবর্তী এজেন্ট দ্বারা পড়া যেতে পারে।
   • LangchainTool 🌍: এটি ট্যুর গাইড এজেন্টকে সাধারণ বিশ্ব জ্ঞান প্রদান করে। যখন কোনও দর্শনার্থী এমন কোনও প্রশ্ন জিজ্ঞাসা করে যা চিড়িয়াখানার ডাটাবেসে নেই, যেমন "বন্যে সিংহরা কী খায়?", এই টুলটি এজেন্টকে উইকিপিডিয়ায় উত্তরটি খুঁজতে দেয়।
     কিভাবে: এটি একটি অ্যাডাপ্টার হিসেবে কাজ করে, যা আমাদের এজেন্টকে LangChain লাইব্রেরি থেকে পূর্বে তৈরি WikipediaQueryRun টুল ব্যবহার করার অনুমতি দেয়।
     
     
4. স্পেশালিস্ট এজেন্টদের সংজ্ঞা দিন : comprehensive_researcher এবং response_formatter এজেন্টদের সংজ্ঞায়িত করতে agent.py এর নীচে নিম্নলিখিত কোডটি যোগ করুন:

   # 1. Researcher Agent
   comprehensive_researcher = Agent(
       name="comprehensive_researcher",
       model=model_name,
       description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
       instruction="""
       You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
       You have access to two tools:
       1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
       2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).
   
       First, analyze the user's PROMPT.
       - If the prompt can be answered by only one tool, use that tool.
       - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
         you MUST use both tools to gather all necessary information.
       - Synthesize the results from the tool(s) you use into preliminary data outputs.
   
       PROMPT:
       { PROMPT }
       """,
       tools=[
           wikipedia_tool
       ],
       output_key="research_data" # A key to store the combined findings
   )
   
   # 2. Response Formatter Agent
   response_formatter = Agent(
       name="response_formatter",
       model=model_name,
       description="Synthesizes all information into a friendly, readable response.",
       instruction="""
       You are the friendly voice of the Zoo Tour Guide. Your task is to take the
       RESEARCH_DATA and present it to the user in a complete and helpful answer.
   
       - First, present the specific information from the zoo (like names, ages, and where to find them).
       - Then, add the interesting general facts from the research.
       - If some information is missing, just present the information you have.
       - Be conversational and engaging.
   
       RESEARCH_DATA:
       { research_data }
       """
   )
   

   • comprehensive_researcher এজেন্ট হল আমাদের অপারেশনের "মস্তিষ্ক"। এটি শেয়ার্ড State থেকে ব্যবহারকারীর প্রম্পট নেয়, এটির উইকিপিডিয়া টুলটি পরীক্ষা করে এবং উত্তর খুঁজে পেতে কোনটি ব্যবহার করতে হবে তা নির্ধারণ করে।
   • response_formatter এজেন্টের ভূমিকা হল উপস্থাপনা। এটি গবেষক এজেন্টের সংগৃহীত কাঁচা তথ্য (রাজ্যের মাধ্যমে প্রেরিত) গ্রহণ করে এবং LLM-এর ভাষা দক্ষতা ব্যবহার করে এটিকে একটি বন্ধুত্বপূর্ণ, কথোপকথনমূলক প্রতিক্রিয়ায় রূপান্তরিত করে।
     
5. ওয়ার্কফ্লো এজেন্ট সংজ্ঞায়িত করুন : agent.py এর নীচে এই কোড ব্লকটি যোগ করুন যাতে সিক্যুয়াল এজেন্ট tour_guide_workflow সংজ্ঞায়িত হয়:

   tour_guide_workflow = SequentialAgent(
       name="tour_guide_workflow",
       description="The main workflow for handling a user's request about an animal.",
       sub_agents=[
           comprehensive_researcher, # Step 1: Gather all data
           response_formatter,       # Step 2: Format the final response
       ]
   )
   

   চিড়িয়াখানা ভ্রমণের জন্য ওয়ার্কফ্লো এজেন্ট 'ব্যাক-অফিস' ম্যানেজার হিসেবে কাজ করে। এটি গবেষণার অনুরোধ গ্রহণ করে এবং উপরে সংজ্ঞায়িত দুটি এজেন্টকে সঠিক ক্রমে তাদের কাজ সম্পাদন নিশ্চিত করে: প্রথমে গবেষণা, তারপর ফর্ম্যাটিং। এটি একজন দর্শনার্থীর প্রশ্নের উত্তর দেওয়ার জন্য একটি অনুমানযোগ্য এবং নির্ভরযোগ্য প্রক্রিয়া তৈরি করে।
   কিভাবে: এটি একটি SequentialAgent , একটি বিশেষ ধরণের এজেন্ট যা নিজের জন্য চিন্তা করে না। এর একমাত্র কাজ হল একটি নির্দিষ্ট ক্রমানুসারে sub_agents (গবেষক এবং ফর্ম্যাটার) তালিকা চালানো, যা স্বয়ংক্রিয়ভাবে ভাগ করা মেমরিটিকে একটি থেকে অন্যটিতে প্রেরণ করে।
6. মূল কর্মপ্রবাহ একত্রিত করুন : root_agent সংজ্ঞায়িত করতে agent.py এর নীচে কোডের এই চূড়ান্ত ব্লকটি যুক্ত করুন:

   root_agent = Agent(
       name="greeter",
       model=model_name,
       description="The main entry point for the Zoo Tour Guide.",
       instruction="""
       - Let the user know you will help them learn about the animals we have in the zoo.
       - When the user responds, use the 'add_prompt_to_state' tool to save their response.
       After using the tool, transfer control to the 'tour_guide_workflow' agent.
       """,
       tools=[add_prompt_to_state],
       sub_agents=[tour_guide_workflow]
   )
   

   ADK ফ্রেমওয়ার্ক সকল নতুন কথোপকথনের শুরুর বিন্দু হিসেবে root_agent ব্যবহার করে। এর প্রাথমিক ভূমিকা হলো সামগ্রিক প্রক্রিয়াটি পরিচালনা করা। এটি প্রাথমিক নিয়ন্ত্রক হিসেবে কাজ করে, কথোপকথনের প্রথম পালা পরিচালনা করে।
   

সম্পূর্ণ agent.py ফাইল

আপনার agent.py ফাইলটি এখন সম্পূর্ণ! এইভাবে এটি তৈরি করে, আপনি দেখতে পাবেন কিভাবে প্রতিটি উপাদান - সরঞ্জাম, কর্মী এজেন্ট এবং ব্যবস্থাপক এজেন্ট - চূড়ান্ত, বুদ্ধিমান সিস্টেম তৈরিতে একটি নির্দিষ্ট ভূমিকা পালন করে।

সম্পূর্ণ ফাইলটি দেখতে এরকম হওয়া উচিত:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

এরপর, স্থাপনা!

৮. স্থাপনের জন্য আবেদনপত্র প্রস্তুত করুন

চূড়ান্ত কাঠামো পরীক্ষা করুন

স্থাপনের আগে, আপনার প্রকল্প ডিরেক্টরিতে সঠিক ফাইল রয়েছে কিনা তা যাচাই করুন।

• আপনার zoo_guide_agent ফোল্ডারটি এইরকম দেখাচ্ছে কিনা তা নিশ্চিত করুন:

  zoo_guide_agent/
  ├── .env
  ├── __init__.py
  ├── agent.py
  └── requirements.txt
  

IAM অনুমতি সেট আপ করুন

আপনার স্থানীয় কোড প্রস্তুত থাকা অবস্থায়, পরবর্তী ধাপ হল আপনার এজেন্ট ক্লাউডে যে পরিচয় ব্যবহার করবে তা সেট আপ করা।

1. টার্মিনালে , আপনার শেল সেশনে ভেরিয়েবলগুলি লোড করুন।

   source .env
   

   দ্রষ্টব্য: যদি আপনার ক্লাউড শেল সেশন রিফ্রেশ হয় অথবা আপনি একটি নতুন টার্মিনাল ট্যাব খোলেন, তাহলে এই ভেরিয়েবলগুলি পুনরায় লোড করার জন্য আপনাকে আবার source .env চালাতে হতে পারে।

2. আপনার ক্লাউড রান পরিষেবার জন্য একটি ডেডিকেটেড সার্ভিস অ্যাকাউন্ট তৈরি করুন যাতে এর নিজস্ব নির্দিষ্ট অনুমতি থাকে। টার্মিনালে নিম্নলিখিতটি পেস্ট করুন:

   gcloud iam service-accounts create ${SA_NAME} \
       --display-name="Service Account for lab 2 "
   

   এই নির্দিষ্ট অ্যাপ্লিকেশনের জন্য একটি ডেডিকেটেড পরিচয় তৈরি করে, আপনি নিশ্চিত করেন যে এজেন্টের কাছে কেবলমাত্র প্রয়োজনীয় অনুমতি রয়েছে, অতিরিক্ত বিস্তৃত অ্যাক্সেস সহ একটি ডিফল্ট অ্যাকাউন্ট ব্যবহার করার পরিবর্তে।
3. পরিষেবা অ্যাকাউন্টটিকে Vertex AI ব্যবহারকারীর ভূমিকা প্রদান করুন, যা এটিকে Google এর মডেলগুলিকে কল করার অনুমতি দেয়।

   # Grant the "Vertex AI User" role to your service account
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/aiplatform.user"
   

৯. ADK CLI ব্যবহার করে এজেন্ট স্থাপন করুন

আপনার স্থানীয় কোড প্রস্তুত এবং আপনার Google ক্লাউড প্রকল্প প্রস্তুত থাকায়, এজেন্ট স্থাপনের সময় এসেছে। আপনি adk deploy cloud_run কমান্ড ব্যবহার করবেন, এটি একটি সুবিধাজনক টুল যা সম্পূর্ণ স্থাপনার কর্মপ্রবাহকে স্বয়ংক্রিয় করে তোলে। এই একক কমান্ডটি আপনার কোড প্যাকেজ করে, একটি কন্টেইনার ইমেজ তৈরি করে, এটিকে Artifact Registry এ পুশ করে এবং Cloud Run এ পরিষেবা চালু করে, যা এটিকে ওয়েবে অ্যাক্সেসযোগ্য করে তোলে।

1. আপনার এজেন্ট স্থাপন করতে টার্মিনালে নিম্নলিখিত কমান্ডটি চালান।

   # Run the deployment command
   uvx --from google-adk \
   adk deploy cloud_run \
     --project=$PROJECT_ID \
     --region=europe-west1 \
     --service_name=zoo-tour-guide \
     --with_ui \
     . \
     -- \
     --labels=dev-tutorial=codelab-adk \
     --service-account=$SERVICE_ACCOUNT
   

   uvx কমান্ড আপনাকে পাইথন প্যাকেজ হিসেবে প্রকাশিত কমান্ড লাইন টুলগুলি চালানোর অনুমতি দেয়, কোনও গ্লোবাল ইনস্টলেশনের প্রয়োজন ছাড়াই।

   দ্রষ্টব্য: নীচের এই ডিপ্লয় কমান্ডটি চালানো শেষ হতে কয়েক মিনিট সময় লাগবে।

2. যদি আপনাকে নিম্নলিখিতগুলি জিজ্ঞাসা করা হয়:

   Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
   [europe-west1] will be created.
   
   Do you want to continue (Y/n)?
   

   যদি তাই হয়, তাহলে Y টাইপ করুন এবং ENTER টিপুন।
3. যদি আপনাকে নিম্নলিখিতগুলি জিজ্ঞাসা করা হয়:

   Allow unauthenticated invocations to [your-service-name] (y/N)?.
   

   y টাইপ করুন এবং ENTER টিপুন। এটি সহজে পরীক্ষার জন্য এই ল্যাবের জন্য অপ্রমাণিত আহ্বানগুলিকে অনুমতি দেয়।

   দ্রষ্টব্য: URL সহ যে কেউ এই এজেন্টে অ্যাক্সেস করতে পারবেন, তাই পরীক্ষার জন্য এটিই সবচেয়ে ভালো।

   সফলভাবে কার্যকর করার পর, কমান্ডটি মোতায়েন করা ক্লাউড রান পরিষেবার URL প্রদান করবে। (এটি দেখতে https://zoo-tour-guide-123456789.europe-west1.run.app এর মতো হবে)।
4. পরবর্তী কাজের জন্য মোতায়েন করা ক্লাউড রান পরিষেবার URL কপি করুন।

১০. মোতায়েন করা এজেন্ট পরীক্ষা করুন

আপনার এজেন্ট এখন Cloud Run- এ লাইভ হওয়ার সাথে সাথে, আপনাকে একটি পরীক্ষা করতে হবে যাতে নিশ্চিত করা যায় যে স্থাপনা সফল হয়েছে এবং এজেন্টটি প্রত্যাশা অনুযায়ী কাজ করছে। ADK-এর ওয়েব ইন্টারফেস অ্যাক্সেস করতে এবং এজেন্টের সাথে যোগাযোগ করতে আপনি পাবলিক সার্ভিস URL ( https://zoo-tour-guide-123456789.europe-west1.run.app/ এর মতো কিছু) ব্যবহার করবেন।

1. আপনার ওয়েব ব্রাউজারে পাবলিক ক্লাউড রান সার্ভিস URL খুলুন। যেহেতু আপনি --with_ui flag ব্যবহার করেছেন, তাই আপনার ADK ডেভেলপার UI দেখা উচিত।
2. উপরের ডানদিকে Token Streaming চালু করুন।
   আপনি এখন চিড়িয়াখানার এজেন্টের সাথে যোগাযোগ করতে পারেন।
3. নতুন কথোপকথন শুরু করতে hello টাইপ করুন এবং এন্টার টিপুন।
4. ফলাফল লক্ষ্য করুন। এজেন্টের দ্রুত সাড়া দিয়ে শুভেচ্ছা জানানো উচিত, যা এরকম কিছু হবে:

   "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
   

5. এজেন্টকে এই ধরনের প্রশ্ন জিজ্ঞাসা করুন:

   Where can I find the polar bears in the zoo and what is their diet?
   

   

এজেন্ট ফ্লো ব্যাখ্যা করা হয়েছে

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

১. দ্য চিড়িয়াখানা গ্রিটার (স্বাগতম ডেস্ক)

সম্পূর্ণ প্রক্রিয়াটি শুরু হয় অভিবাদনকারী এজেন্ট দিয়ে।

• এর কাজ: কথোপকথন শুরু করা। এর নির্দেশ হল ব্যবহারকারীকে অভ্যর্থনা জানানো এবং জিজ্ঞাসা করা যে তারা কোন প্রাণী সম্পর্কে জানতে চায়।
• এর টুল: যখন ব্যবহারকারী উত্তর দেয়, তখন গ্রিটার তার add_prompt_to_state টুল ব্যবহার করে তাদের সঠিক শব্দগুলি ক্যাপচার করে (যেমন, "সিংহ সম্পর্কে আমাকে বলুন") এবং সেগুলি সিস্টেমের মেমরিতে সংরক্ষণ করে।
• হ্যান্ডঅফ: প্রম্পটটি সংরক্ষণ করার পর, এটি তাৎক্ষণিকভাবে তার সাব-এজেন্ট, tour_guide_workflow-এর কাছে নিয়ন্ত্রণ হস্তান্তর করে।

২. দ্য কম্প্রিহেনসিভ রিসার্চার (সুপার-রিসার্চার)

এটি মূল কর্মপ্রবাহের প্রথম ধাপ এবং অপারেশনের "মস্তিষ্ক"। একটি বৃহৎ দলের পরিবর্তে, এখন আপনার কাছে একটি একক, অত্যন্ত দক্ষ এজেন্ট রয়েছে যে সমস্ত উপলব্ধ তথ্য অ্যাক্সেস করতে পারে।

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

৩. রেসপন্স ফর্ম্যাটার (উপস্থাপক)

একবার বিস্তৃত গবেষক সমস্ত তথ্য সংগ্রহ করলে, এটিই চূড়ান্ত এজেন্ট যা চালানো হবে।

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

আপনি যদি এজেন্ট তৈরি সম্পর্কে আরও জানতে আগ্রহী হন , তাহলে নিম্নলিখিত সংস্থানগুলি দেখুন:

1. ADK ডক্স
2. ADK এজেন্টদের জন্য কাস্টম টুল তৈরি করা

১১. পরিবেশ পরিষ্কার করুন

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

ক্লাউড রান পরিষেবা এবং ছবিগুলি মুছুন

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

• টার্মিনালে নিম্নলিখিত কমান্ডগুলি চালান:

  gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
  gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
  

প্রকল্পটি মুছুন (ঐচ্ছিক)

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

• টার্মিনালে , নিম্নলিখিত কমান্ডটি চালান ([YOUR_PROJECT_ID] কে আপনার প্রকৃত প্রজেক্ট আইডি দিয়ে প্রতিস্থাপন করুন)

  gcloud projects delete $PROJECT_ID
  

  কোনও প্রকল্প মুছে ফেলা অপরিবর্তনীয়। এগিয়ে যাওয়ার আগে দয়া করে নিশ্চিত করুন যে এই প্রকল্পটি অন্য কোনও কাজে ব্যবহৃত হচ্ছে না।

১২. অভিনন্দন

আপনি গুগল ক্লাউডে একটি মাল্টি-এজেন্ট এআই অ্যাপ্লিকেশন সফলভাবে তৈরি এবং স্থাপন করেছেন!

সংক্ষিপ্তসার

এই ল্যাবে, আপনি একটি খালি ডিরেক্টরি থেকে একটি লাইভ, সর্বজনীনভাবে অ্যাক্সেসযোগ্য AI পরিষেবাতে চলে গেছেন। আপনি কী তৈরি করেছেন তা এখানে দেখুন:

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

আমরা যা কভার করেছি

• ADK এর সাথে স্থাপনার জন্য একটি পাইথন প্রকল্প কীভাবে গঠন করবেন।
• [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/) ব্যবহার করে কিভাবে একটি মাল্টি-এজেন্ট ওয়ার্কফ্লো বাস্তবায়ন করবেন।
• উইকিপিডিয়া এপিআই-এর মতো বহিরাগত সরঞ্জামগুলিকে কীভাবে একীভূত করা যায়।
• adk deploy কমান্ড ব্যবহার করে ক্লাউড রানে এজেন্ট কীভাবে স্থাপন করবেন।

১৩. জরিপ

আউটপুট:

আপনি এই টিউটোরিয়ালটি কীভাবে ব্যবহার করবেন?

শুধু এটি পড়ুন এটি পড়ুন এবং অনুশীলনগুলি সম্পূর্ণ করুন।