ADK: बुनियादी बातों से लेकर मल्टी-टूल एजेंट तक

1. परिचय

इस कोडलैब में, ADK की मदद से एजेंट बनाने के बारे में पूरी जानकारी दी गई है. इसमें बुनियादी बातों से लेकर, कई टूल वाले एजेंट बनाने तक की जानकारी शामिल है.

आसान शब्दों में कहें, तो एआई एजेंट एक ऐसा सॉफ़्टवेयर सिस्टम होता है जो लार्ज लैंग्वेज मॉडल (एलएलएम) का इस्तेमाल "रीज़निंग इंजन" के तौर पर करता है. इससे वह अपने-आप कई टास्क करके, किसी लक्ष्य को हासिल कर पाता है.

अगर एलएलएम एक बेहतरीन सलाहकार है, तो एआई एजेंट एक ऐसा इंजीनियर है जो सलाह को लागू करने के लिए टूल का इस्तेमाल कर सकता है.

एलएलएम बनाम एजेंट

ब्रेन (एलएलएम): यह तर्क समझने, प्लान बनाने, और नैचुरल लैंग्वेज को समझने की सुविधा देता है. यह तय करता है कि क्या करना है.

हाथ (टूल): ये एपीआई, एसडीके, और कस्टम फ़ंक्शन होते हैं. इनकी मदद से एजेंट, असल दुनिया के साथ इंटरैक्ट कर पाता है. यह प्लान को लागू करता है.

एजेंट डेवलपमेंट किट (एडीके)

एजेंट डेवलपमेंट किट (ADK) एक खास फ़्रेमवर्क है. इसे एआई एजेंट बनाने, डिप्लॉय करने, और व्यवस्थित करने की प्रोसेस को आसान बनाने के लिए डिज़ाइन किया गया है. यह स्टैंडर्ड बिल्डिंग ब्लॉक उपलब्ध कराता है. इनकी मदद से, स्टैटिक लार्ज लैंग्वेज मॉडल को डाइनैमिक एजेंट में बदला जा सकता है. यह एजेंट, कोड को लागू कर सकता है, एपीआई को कॉल कर सकता है, और कई चरणों वाले वर्कफ़्लो को मैनेज कर सकता है.

मल्टी-टूल एजेंट एक ऑर्केस्ट्रेटर होता है. यह जटिल समस्याओं को हल करने के लिए, अलग-अलग तरह के खास फ़ंक्शन चुन सकता है और उन्हें क्रम से लगा सकता है. जैसे, सर्च इंजन, डेटाबेस, और कैलकुलेटर. यह हर चरण के लिए, सही टूल का इस्तेमाल करता है. साथ ही, किसी कार्रवाई के आउटपुट को अगले चरण के इनपुट के तौर पर इस्तेमाल कर सकता है, ताकि फ़ाइनल लक्ष्य को हासिल किया जा सके.

आपको क्या बनाना है

इस कोडलैब में, आपको "सेहत से जुड़ी सलाह" देने वाला एक एजेंट बनाना होगा. यह एक बुद्धिमान पोषण सलाहकार है, जो सामान्य टेक्स्ट से तर्क देने से लेकर कई टूल का इस्तेमाल करने तक की सुविधा देता है. सबसे पहले, आपको बातचीत करने वाला एक ऐसा एजेंट बनाना होगा जिसे पोषण से जुड़े कॉन्सेप्ट की जानकारी हो. इसके बाद, आपको उसे Storage SDK टूल से लैस करना होगा, ताकि वह सामग्री की इमेज को संग्रहित कर सके. साथ ही, आपको उसे Vision टूल से लैस करना होगा, ताकि वह उन इमेज को "पढ़" सके और उनका विश्लेषण कर सके. इस लैब के आखिर तक, आपके पास पूरी तरह से काम करने वाला एक ऑर्केस्ट्रेटर होगा. यह ऑर्केस्ट्रेटर, खाने के लेबल की अपलोड की गई फ़ोटो को रिकॉर्ड रखने के लिए क्लाउड बकेट में सेव कर सकता है. साथ ही, हर सामग्री के लिए "सेहत से जुड़ी सलाह" तुरंत दे सकता है.

2. ज़रूरी शर्तें

बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट
वेब ब्राउज़र

अपना प्रोजेक्ट बनाना

Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग की सुविधा चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.

Cloud Shell चालू करें

आपको Cloud Shell का इस्तेमाल करना होगा. यह Google Cloud Console में चलने वाला कमांड-लाइन एनवायरमेंट है. इसमें ज़रूरी भाषाएं पहले से इंस्टॉल होती हैं. Cloud Console में, सबसे ऊपर दाएं कोने में मौजूद Cloud Shell चालू करें पर क्लिक करें:

Cloud Shell से कनेक्ट होने के बाद, आपको दिखेगा कि आपकी पुष्टि पहले ही हो चुकी है और प्रोजेक्ट को आपके प्रोजेक्ट आईडी पर सेट किया गया है. पुष्टि करें कि आपने Cloud Shell में पुष्टि कर ली है. इसके लिए, यह कमांड चलाएं:

gcloud auth list

यह पुष्टि करने के लिए कि gcloud कमांड को आपके प्रोजेक्ट के बारे में पता है, Cloud Shell में यह कमांड चलाएं:

gcloud config list project

अगर आपका प्रोजेक्ट सेट नहीं है, तो इसे सेट करने के लिए इस निर्देश का इस्तेमाल करें:

gcloud config set project <YOUR_PROJECT_ID>

gcloud कमांड और उनके इस्तेमाल के बारे में जानने के लिए, दस्तावेज़ देखें.

एडिटर खोलें

इस कोडलैब के लिए, हम Cloud में पहले से मौजूद एडिटर का इस्तेमाल करेंगे. क्लाउड शेल विंडो में, सबसे ऊपर दाएं कोने में मौजूद 'एडिटर खोलें' बटन पर क्लिक करें. इससे आपके लिए VSCode Editor खुल जाएगा.

3. ADK सेटअप

चलिए, Cloud Shell टर्मिनल पर चलते हैं. हमने इसे पिछले सेक्शन में चालू किया था:

वर्चुअल एनवायरमेंट बनाएं और उसे चालू करें (सुझाया गया)

Cloud Shell टर्मिनल में, वर्चुअल एनवायरमेंट बनाएं:

python -m venv .venv

वर्चुअल एनवायरमेंट चालू करें:

source .venv/bin/activate

ADK इंस्टॉल करना

pip install google-adk

4. Google API Key

AI Studio का इस्तेमाल करके Google API पासकोड बनाएं:

https://aistudio.google.com/ पर जाएं और सबसे नीचे मौजूद मेन्यू में, Get API Key पर क्लिक करें

आपको एपीआई पासकोड की विंडो दिखेगी. इस विंडो में, 'एपीआई पासकोड बनाएं' पर क्लिक करें:

आपको नई कुंजी बनाने के लिए एक पॉप-अप दिखेगा. कुंजी का नाम यह रखें: healthy-hints-key

"इंपोर्ट किया गया कोई प्रोजेक्ट चुनें" ड्रॉपडाउन पर जाएं

Import Project पर क्लिक करें. इसके बाद, आपको एक साइड विंडो दिखेगी. इसमें आपके सभी Google Cloud प्रोजेक्ट की सूची होगी. वह प्रोजेक्ट चुनें जिस पर आपको काम करना है.

इंपोर्ट करें पर क्लिक करें

अब ड्रॉपडाउन में, इंपोर्ट किया गया प्रोजेक्ट दिखेगा. ड्रॉपडाउन से प्रोजेक्ट चुनें. 'अभी कुंजी बनाएं' पर क्लिक करें. अब आपको बनाए गए एपीआई पासकोड की सूची दिखेगी. अभी-अभी बनाए गए एपीआई पासकोड के कॉपी आइकॉन पर क्लिक करें.

5. सैंपल एजेंट

Cloud Shell टर्मिनल में, अपनी पसंद की प्रोजेक्ट लोकेशन में अपने एजेंट के लिए रूट डायरेक्ट्री बनाएं:

adk create healthy_hints

आपके पास कोई भी मॉडल चुनने का विकल्प है. हालांकि, इस कोडलैब के लिए हम gemini-2.5-flash का इस्तेमाल करेंगे

इस कोडलैब के लिए, हम Google के एआई का इस्तेमाल करेंगे. पिछले चरण में बनाई गई एपीआई पासकोड चिपकाएं.

आइए, अभी-अभी बनाए गए फ़ोल्डर को खोलें. सबसे बाईं ओर मौजूद मेन्यू में, आइकॉन पर क्लिक करें. इसके बाद, फ़ाइल -> फ़ोल्डर खोलें पर क्लिक करें. अभी-अभी बनाए गए फ़ोल्डर healthy_hints को चुनें. यह आम तौर पर /home/<username> फ़ोल्डर में होता है.
healthy_hints फ़ोल्डर का स्ट्रक्चर आम तौर पर ऐसा दिखता है:

आपको .env फ़ाइल दिखेगी, जिसमें आपकी Google API कुंजी होगी. इस फ़ाइल का इस्तेमाल, किसी भी एनवायरमेंट वैरिएबल को सेट करने के लिए किया जा सकता है.
agent.py नाम की एक और फ़ाइल भी बनाई जाती है. यह हमारी मुख्य एजेंट फ़ाइल होती है. यहां एक सैंपल रूट एजेंट बनाया जाता है. आइए, इस फ़ाइल के कॉन्टेंट को ध्यान से देखें. सबसे पहले, हम ADK से llm_agent इंपोर्ट करते हैं. इसके बाद, हम रूट एजेंट बनाने के लिए ADK DSL का इस्तेमाल करते हैं. हमने मॉडल का नाम Gemini-2.5-flash रखा है, एजेंट का नाम दिया है, और उसके बारे में अच्छी जानकारी दी है. यहां निर्देश सबसे अहम है. इसमें हम एजेंट को सामान्य भाषा में बताते हैं कि उसे क्या करना है.
यह सैंपल एजेंट काफ़ी सामान्य है. यह सिर्फ़ उपयोगकर्ता के किसी भी सवाल का जवाब देगा.
अब इस एजेंट को स्थानीय तौर पर चलाते हैं. इस एजेंट के साथ इंटरैक्ट करने के दो तरीके हैं : सीएलआई और वेब.
CLI: healthy_hints डायरेक्ट्री से बाहर यह कमांड चलाएं

adk run healthy_hints

इसके अलावा, अगर आप healthy_hints डायरेक्ट्री में हैं, तो यह कमांड चलाएं:

adk run .

आपको इससे मिलता-जुलता आउटपुट दिखेगा:

आगे बढ़ें और "नमस्ते" लिखें या अपना कोई सवाल पूछें. हर व्यक्ति के लिए जवाब अलग-अलग हो सकता है. यह GenAI की खासियत है.

वेब: healthy_hints की पैरंट डायरेक्ट्री से यह कमांड चलाएं :

adk web

6. मल्टी-टूल एजेंट

टूल, कोड का एक मॉड्यूलर हिस्सा होता है. आम तौर पर, यह एक फ़ंक्शन या एपीआई होता है. इसकी मदद से, एजेंट अपनी जानकारी के दायरे से बाहर की दुनिया से इंटरैक्ट कर पाता है.

ADK में टूल के टाइप

फ़ंक्शन टूल: कस्टम लॉजिक, जिसे आपको खुद लिखना होता है. उदाहरण के लिए, ऐसा फ़ंक्शन जो आपके डेटाबेस से कनेक्ट होता है या आपकी कंपनी के यूनीक फ़ॉर्मैट के लिए कस्टम "Log Parser" होता है.
पहले से मौजूद टूल: Google या ADK की ओर से उपलब्ध कराई गई ऐसी सुविधाएं जिन्हें तुरंत इस्तेमाल किया जा सकता है. जैसे, Google Search, Code Interpreter या Google RAG Engine.
Agents-as-Tools: "मल्टी-टूल" या "मल्टी-एजेंट" सिस्टम के ऐडवांस वर्शन में, कोई खास एजेंट दूसरे एजेंट के लिए टूल के तौर पर काम कर सकता है. उदाहरण के लिए, "सर्च एजेंट" एक ऐसा टूल हो सकता है जिसका इस्तेमाल "रिसर्च मैनेजर एजेंट" करता है.

इस कोडलैब में, हम फ़ंक्शन टूल के बारे में जानेंगे. अब हम अपने एजेंट को बेहतर बनाएंगे और उसे कई टूल इस्तेमाल करने की सुविधा देंगे.

आइए, 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],
)

हमने ब्यौरे, निर्देश, और टूल में ज़रूरी बदलाव किए हैं. अब इस अपडेट किए गए एजेंट को चलाते हैं. इस बार, एजेंट आपको मौजूदा समय और मौसम की जानकारी भी देगा.

7. SDK टूल इंटिग्रेशन

अब हमें कई टूल इस्तेमाल करने का तरीका पता चल गया है. आइए, कुछ असल उदाहरणों के साथ काम करें. आइए, सेहतमंद खाने के बारे में सलाह देने वाला एजेंट बनाएं. हमारा मकसद यह है कि हम ऐसी इमेज अपलोड करें जिसमें सामग्री की सूची दी गई हो. हम यह इमेज अपने एजेंट को भेजेंगे. इसके बाद, एजेंट हमें बताएगा कि कौनसी सामग्री सेहत के लिए अच्छी है और कौनसी नहीं.

Google Cloud Storage में इमेज अपलोड करने के लिए, सबसे पहले एक बकेट बनाते हैं. आइए, एक नया टैब खोलें और https://console.cloud.google.com/ पर जाएं. इसके बाद, खोज बार में Cloud Storage टाइप करें. अब, प्रॉडक्ट और पेज में जाकर Cloud Storage को चुनें:

इससे आपको Google Cloud Storage के खास जानकारी वाले पेज पर ले जाया जाएगा. 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],
)

8. नतीजा

'सेहत से जुड़ी सलाह' कोडलैब पूरा करने के लिए बधाई! आपने टेक्स्ट जनरेट करने वाले स्टैंडर्ड एआई को, कई टूल इस्तेमाल करने वाले एक ऐसे एजेंट में बदल दिया है जो अपने-आप काम करता है. ADK का इस्तेमाल करके, Vision API और Cloud Storage SDK को इंटिग्रेट किया गया है. इससे आपके एजेंट को लेबल पढ़ने के लिए "आंखें" और उन्हें संग्रहित करने के लिए "मेमोरी" मिल गई है. आपने देखा कि एजेंट, फ़ाइल को सेव करने का फ़ैसला खुद कैसे लेता है. साथ ही, आपने यह भी देखा कि एजेंट, असल दुनिया में स्वास्थ्य से जुड़ी सलाह देने के लिए, रॉ डेटा को कैसे समझता है.

आने वाले समय में, ये सिद्धांत किसी भी ऑटोमेटेड सिस्टम के लिए ब्लूप्रिंट के तौर पर काम करेंगे. चाहे आपको क्लाउड इंफ़्रास्ट्रक्चर मैनेज करना हो या पर्सनल असिस्टेंट बनानी हो, मुख्य सिद्धांत एक ही रहता है: खास टूल तय करें और एजेंट को लॉजिक व्यवस्थित करने दें. अगले चरण के तौर पर, "पोषण संबंधी डेटाबेस" या "ईमेल टूल" जैसे ज़्यादा टूल जोड़ें, ताकि आपके एजेंट का असर बढ़ सके.