ADK: মৌলিক বিষয় থেকে মাল্টি-টুল এজেন্ট পর্যন্ত

১. ভূমিকা

একেবারে প্রাথমিক বিষয় থেকে শুরু করে মাল্টি-টুল এজেন্ট তৈরি পর্যন্ত, এই কোডল্যাবটি ADK ব্যবহার করে এজেন্ট তৈরির একটি বিশদ পরিচিতি প্রদান করে।

সহজভাবে বলতে গেলে, একটি এআই এজেন্ট হলো এমন একটি সফটওয়্যার সিস্টেম যা একটি বৃহৎ ভাষা মডেলকে (এলএলএম) তার 'যুক্তি ইঞ্জিন' হিসেবে ব্যবহার করে স্বয়ংক্রিয়ভাবে ধারাবাহিক কাজ সম্পাদনের মাধ্যমে কোনো লক্ষ্য অর্জন করে।

যদি একজন এলএলএম (LLM) একজন অত্যন্ত দক্ষ পরামর্শদাতা হন যিনি আপনাকে পরামর্শ দিতে পারেন, তবে একজন এআই এজেন্ট (AI Agent) হলো একজন সক্রিয় প্রকৌশলী যিনি সেই পরামর্শ বাস্তবায়নের জন্য বিভিন্ন সরঞ্জাম ব্যবহার করতে পারেন।

এলএলএম বনাম এজেন্ট

মস্তিষ্ক (এলএলএম): যুক্তি, পরিকল্পনা এবং স্বাভাবিক ভাষা বোঝার ক্ষমতা প্রদান করে। কী করা প্রয়োজন, তা এটি স্থির করে।

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

এজেন্ট ডেভেলপমেন্ট কিট (ADK)

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

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

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

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

২. পূর্বশর্তসমূহ

• বিলিং সক্ষম একটি গুগল ক্লাউড প্রজেক্ট
• একটি ওয়েব ব্রাউজার

আপনার প্রকল্প তৈরি করুন

• গুগল ক্লাউড কনসোলের প্রজেক্ট সিলেক্টর পেজে, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন।
• আপনার ক্লাউড প্রজেক্টে বিলিং চালু আছে কিনা তা নিশ্চিত করুন। কোনো প্রজেক্টে বিলিং চালু আছে কিনা তা কীভাবে পরীক্ষা করবেন, তা জানুন।

ক্লাউড শেল সক্রিয় করুন

• আপনি ক্লাউড শেল ব্যবহার করবেন, যা গুগল ক্লাউড কনসোলে চলমান একটি কমান্ড-লাইন পরিবেশ এবং এতে প্রয়োজনীয় ভাষাগুলো আগে থেকেই ইনস্টল করা থাকে। ক্লাউড কনসোল থেকে, উপরের ডান কোণায় থাকা ‘Activate Cloud Shell’- এ ক্লিক করুন:

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

gcloud auth list

• gcloud কমান্ডটি আপনার প্রজেক্ট সম্পর্কে জানে কিনা তা নিশ্চিত করতে ক্লাউড শেলে নিম্নলিখিত কমান্ডটি চালান:

gcloud config list project

• আপনার প্রজেক্টটি সেট করা না থাকলে, এটি সেট করতে নিম্নলিখিত কমান্ডটি ব্যবহার করুন:

gcloud config set project <YOUR_PROJECT_ID>

gcloud কমান্ড এবং এর ব্যবহার সম্পর্কে জানতে ডকুমেন্টেশন দেখুন।

ওপেন এডিটর

• এই কোডল্যাবের জন্য, আমরা ইনবিল্ট ক্লাউড এডিটর ব্যবহার করব। ক্লাউড শেল উইন্ডোতে, উপরের ডান কোণায় থাকা 'ওপেন এডিটর' বোতামটিতে ক্লিক করুন। এটি আপনার জন্য একটি ভিএসকোড এডিটর খুলে দেবে।

৩. ADK সেটআপ

চলুন, আগের অংশে আমরা যে ক্লাউড শেল টার্মিনালটি সক্রিয় করেছিলাম, সেখানে যাওয়া যাক:

• ভার্চুয়াল পরিবেশ তৈরি ও সক্রিয় করুন (প্রস্তাবিত)

আপনার ক্লাউড শেল টার্মিনাল থেকে একটি ভার্চুয়াল এনভায়রনমেন্ট তৈরি করুন:

python -m venv .venv

ভার্চুয়াল পরিবেশ সক্রিয় করুন:

source .venv/bin/activate

• ADK ইনস্টল করুন

pip install google-adk

৪. গুগল এপিআই কী

এআই স্টুডিও ব্যবহার করে গুগল এপিআই কী তৈরি করুন:

• https://aistudio.google.com/ এ যান এবং বাম দিকের নিচের মেনু থেকে Get API Key তে ক্লিক করুন।

• আপনি একটি API Keys উইন্ডো দেখতে পাবেন, এই উইন্ডোতে Create API key-তে ক্লিক করুন:

• একটি নতুন কী তৈরি করার জন্য একটি পপ-আপ দেখতে পাবেন। কী-টির নাম দিন: healthy-hints-key

"একটি আমদানিকৃত প্রজেক্ট বেছে নিন" ড্রপডাউনে যান

• Import Project এ ক্লিক করুন, একটি সাইড উইন্ডো আসবে যেখানে আপনার সমস্ত গুগল ক্লাউড প্রজেক্টের তালিকা থাকবে, সেখান থেকে আপনি যেটি নিয়ে কাজ করতে চান সেটি বেছে নিন।

ইমপোর্ট-এ ক্লিক করুন

• আপনার এইমাত্র ইম্পোর্ট করা প্রজেক্টটি দিয়ে ড্রপডাউনটি এখন আপডেট হয়ে যাবে। ড্রপডাউন থেকে প্রজেক্টটি সিলেক্ট করুন। এবার 'Create Key'-তে ক্লিক করুন। আপনি এখন তৈরি করা API কী-গুলোর তালিকা দেখতে পাবেন। আপনার এইমাত্র তৈরি করা API কী-টির কপি আইকনে ক্লিক করুন।

৫. নমুনা এজেন্ট

• ক্লাউড শেল টার্মিনাল থেকে, আপনার পছন্দসই প্রজেক্ট লোকেশনে আপনার এজেন্টের জন্য একটি রুট ডিরেক্টরি তৈরি করুন:

adk create healthy_hints

আপনি যেকোনো মডেল বেছে নিতে পারেন, কিন্তু এই কোডল্যাবের জন্য আমরা gemini-2.5-flash ব্যবহার করব।

এই কোডল্যাবের জন্য আমরা গুগল এআই ব্যবহার করব। আগের ধাপে তৈরি করা এপিআই কী-টি পেস্ট করুন।

• চলুন, আমরা এইমাত্র তৈরি করা ফোল্ডারটি খুলি। একদম বাম দিকের মেনুতে থাকা আইকনটিতে ক্লিক করুন। ফাইল -> ওপেন ফোল্ডার-এ ক্লিক করুন। সদ্য তৈরি হওয়া healthy_hints ফোল্ডারটি নির্বাচন করুন, এটি সাধারণত /home/<username> ফোল্ডারে থাকবে।
• healthy_hints ফোল্ডারের কাঠামোটি সাধারণত দেখতে এইরকম হবে:

• আপনি একটি .env ফাইল দেখতে পাবেন, যেখানে আপনার গুগল এপিআই কী (Google API key) রয়েছে। আপনি এই ফাইলটি ব্যবহার করে যেকোনো এনভায়রনমেন্ট ভেরিয়েবল সেট করতে পারেন।
• agent.py নামে আরেকটি ফাইলও তৈরি হয় এবং এটিই আমাদের মূল এজেন্ট ফাইল। এখানেই একটি নমুনা রুট এজেন্ট তৈরি করা হয়। চলুন এই ফাইলটির বিষয়বস্তু ভালোভাবে দেখি, আমরা প্রথমে ADK থেকে llm_agent ইম্পোর্ট করি। এরপর আমরা ADK DSL ব্যবহার করে রুট এজেন্টটি তৈরি করি। আমরা মডেলের নাম হিসেবে Gemini-2.5-flash উল্লেখ করি, এজেন্টটির নাম দিই এবং এর একটি সুন্দর বিবরণ প্রদান করি। এখানে নির্দেশনাই সবচেয়ে গুরুত্বপূর্ণ বিষয়, এখানেই আমরা এজেন্টকে স্বাভাবিক ভাষায় বলে দিই যে তাকে কী করতে হবে।
• এই নমুনা এজেন্টটি বেশ সাধারণ, এটি ব্যবহারকারীর যেকোনো প্রশ্নের উত্তর দেবে।
• চলুন এখন এই এজেন্টটি স্থানীয়ভাবে চালাই। দুটি উপায়ে আপনি এই এজেন্টের সাথে যোগাযোগ করতে পারেন: CLI এবং ওয়েব।
• CLI : healthy_hints ডিরেক্টরির বাইরে থেকে নিম্নলিখিত কমান্ডটি চালান।

adk run healthy_hints

অথবা আপনি যদি healthy_hints ডিরেক্টরির ভিতরে থাকেন, তাহলে নিম্নলিখিত কমান্ডটি চালান:

adk run .

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

এগিয়ে যান এবং 'হাই' বা আপনার মনে আসা যেকোনো প্রশ্ন লিখুন। উত্তরটি প্রত্যেকের জন্য ভিন্ন হতে পারে, এটাই জেনএআই-এর স্বভাব।

• ওয়েব : healthy_hints এর প্যারেন্ট ডিরেক্টরি থেকে নিম্নলিখিত কমান্ডটি চালান:

adk web

৬. মাল্টি-টুল এজেন্ট

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

ADK-তে টুলের প্রকারভেদ

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

এই কোডল্যাবে আমরা ফাংশন টুলস নিয়ে আলোচনা করব। এখন, চলুন আমাদের এজেন্টকে আরও উন্নত করে এটিকে মাল্টি-টুলযুক্ত করে তুলি।

চলুন agent.py ফাইলে get_weather নামে একটি নতুন মেথড যোগ করি।

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

চলুন agent.py ফাইলটি পরিবর্তন করে এজেন্টের নাম, বিবরণ ও নির্দেশনা বদলে ফেলি:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

এখন পর্যন্ত আমরা কেবল একটি টুল তৈরি করেছি। এখন চলো একাধিক টুল তৈরি করি:

চলুন get_current_time নামে আরেকটি মেথড তৈরি করি:

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

এবং চলুন আমাদের এজেন্টকেও পরিবর্তন করি যাতে এটি এই টুলটিকেও আহ্বান করতে পারে:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

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

৭. এসডিকে ইন্টিগ্রেশন

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

• ছবিটি আপলোড করার জন্য প্রথমে গুগল ক্লাউড স্টোরেজে একটি বাকেট তৈরি করা যাক। একটি নতুন ট্যাব খুলে https://console.cloud.google.com/ এ যান এবং সার্চ বারে 'cloud storage' টাইপ করুন। এবার, 'Products & pages' এর অধীনে 'Cloud Storage' নির্বাচন করুন।

এটি আপনাকে গুগল ক্লাউড স্টোরেজের ওভারভিউ পেজে নিয়ে যাবে। Create bucket বোতামে ক্লিক করুন। 'Create bucket' পেজে, বাকেটটির নাম লিখুন। নামটি যেকোনো কিছু হতে পারে, কিন্তু এই কোডল্যাবের জন্য আমরা এর নাম healthy-hints-bucket-kolkata ' রাখব। বাকি সবকিছু অপরিবর্তিত রেখে Create বোতামে ক্লিক করুন।

• চলুন requirements.txt নামে একটি নতুন ফাইল তৈরি করি এবং এতে google-cloud-storage যোগ করি। আমরা স্টোরেজে ইমেজ আপলোড করার জন্য পাইথন স্টোরেজ এসডিকে (Python Storage SDK) ব্যবহার করব।

চলুন প্রথমে প্রয়োজনীয় নির্ভরতাগুলো ইনস্টল করে নিই:

pip install -r requirements.txt

আপনাকে প্রথমে স্টোরেজ এপিআই (Storage API) সক্রিয় করতে হতে পারে। এটি করার জন্য আপনার টার্মিনালে নিম্নলিখিত কমান্ডটি চালান:

gcloud services enable storage.googleapis.com 

এবার ছবি আপলোড করার জন্য একটি নতুন টুল যোগ করা যাক।

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

• এখন, আমাদের এজেন্টকে আপডেট করা যাক যাতে এটি নতুন টুলটি ব্যবহার করে:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

• এখন আমরা ইমেজ থেকে উপাদানগুলো পড়ার জন্য আরেকটি টুল যোগ করব। চলুন requirements.txt এ google-cloud-vision যোগ করি এবং নতুন ডিপেন্ডেন্সিটি ইনস্টল করি।

pip install -r requirements.txt

আবার, আপনাকে প্রথমে ভিশন এপিআই (Vision API) সক্রিয় করতে হতে পারে। এটি করার জন্য আপনার টার্মিনালে নিম্নলিখিত কমান্ডটি চালান:

gcloud services enable vision.googleapis.com

এখন read_ingredients একটি নতুন টুল যোগ করা যাক:

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

এবং চলুন এখন আমাদের এজেন্টকে এই টুলটি ব্যবহার করার জন্য আপডেট করি।

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

৮. উপসংহার

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

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