Cloud Run पर ADK एजेंट बनाना और उसे डिप्लॉय करना

1. परिचय

इस लैब में, क्लाइंट एजेंट सेवा को लागू करने और डिप्लॉय करने पर फ़ोकस किया गया है. आपको टूल इस्तेमाल करने वाले एआई एजेंट को बनाने के लिए, Agent Development Kit (ADK) का इस्तेमाल करना होगा.

इस लैब में, हम एक चिड़ियाघर एजेंट बना रहे हैं. यह एजेंट, जानवरों के बारे में सवालों के जवाब देने के लिए Wikipedia का इस्तेमाल करता है.

बाईं से दाईं ओर, एक शेर, दो पेंग्विन, सफ़ारी हैट पहने हुए एक व्यक्ति, एक हाथी, और एक भालू खड़े हैं. ये सभी दर्शक की ओर पीठ करके खड़े हैं और ऊपर की ओर देख रहे हैं. ऊपर, नीले आसमान में सफ़ेद बादलों के बीच, लाल और सफ़ेद रंग का एक बड़ा रॉकेट लॉन्च हो रहा है. दूर से दो छोटे रॉकेट भी लॉन्च होते हुए दिख रहे हैं. इस सीन में, चिड़ियाघर के एक बाड़े को दिखाया गया है. इसमें लकड़ी की बाड़ और पथरीली चट्टानें हैं.

आखिर में, हम टूर गाइड एजेंट को सिर्फ़ स्थानीय तौर पर चलाने के बजाय, Google Cloud Run पर डिप्लॉय करेंगे.

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

  • Python और कमांड-लाइन इंटरफ़ेस के बारे में जानकारी होना.
  • बिलिंग की सुविधा वाला Google क्लाउड प्रोजेक्ट.
  • इंस्टॉल किए गए सीएलआई टूल: gcloud, gsutil, uv.

आपको क्या सीखने को मिलेगा

  • ADK को डिप्लॉय करने के लिए, Python प्रोजेक्ट को स्ट्रक्चर करने का तरीका.
  • google-adk की मदद से, टूल का इस्तेमाल करने वाले एजेंट को लागू करने का तरीका.
  • Python ऐप्लिकेशन को Cloud Run पर सर्वरलेस कंटेनर के तौर पर डिप्लॉय करने का तरीका.
  • आईएएम भूमिकाओं का इस्तेमाल करके, सेवा से सेवा के बीच सुरक्षित पुष्टि करने की सुविधा को कॉन्फ़िगर करने का तरीका.
  • आने वाले समय में लगने वाले शुल्क से बचने के लिए, Cloud संसाधनों को मिटाने का तरीका.

आपको किन चीज़ों की ज़रूरत होगी

  • Google Cloud खाता और Google Cloud प्रोजेक्ट
  • कोई वेब ब्राउज़र, जैसे कि Chrome

2. Cloud Run पर डिप्लॉय क्यों करें?

ADK एजेंट को होस्ट करने के लिए, Cloud Run एक बेहतरीन विकल्प है. ऐसा इसलिए, क्योंकि यह बिना सर्वर वाला प्लैटफ़ॉर्म है. इसका मतलब है कि आपको कोड पर ध्यान देने का मौका मिलता है. साथ ही, आपको बुनियादी इंफ़्रास्ट्रक्चर को मैनेज करने की ज़रूरत नहीं पड़ती. हम आपके लिए ऑपरेशनल काम करते हैं.

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

मुख्य सुविधाएं

'कंटेनर को किसी भी जगह पर चलाने की सुविधा' का इस्तेमाल करता है:

  • आपको एक कंटेनर (Docker इमेज) लाना होगा, जिसमें आपका ऐप्लिकेशन मौजूद हो.
  • Cloud Run, इसे Google के इंफ़्रास्ट्रक्चर पर चलाता है.
  • ओएस पैचिंग, वीएम सेटअप या स्केलिंग से जुड़ी कोई समस्या नहीं होती.

अपने-आप स्केल होने की सुविधा:

  • अगर कोई भी व्यक्ति आपके ऐप्लिकेशन का इस्तेमाल नहीं कर रहा है, तो 0 इंस्टेंस चलेंगे. इससे इंस्टेंस की संख्या कम होकर शून्य हो जाएगी, जिससे लागत कम हो जाएगी.
  • अगर इस पर 1,000 अनुरोध आते हैं, तो यह ज़रूरत के हिसाब से उतनी कॉपी बना लेता है.

डिफ़ॉल्ट रूप से स्टेटलेस:

  • हर अनुरोध अलग-अलग इंस्टेंस पर जा सकता है.
  • अगर आपको स्थिति को सेव करना है, तो Cloud SQL, Firestore या Memorystore जैसी किसी बाहरी सेवा का इस्तेमाल करें.

किसी भी भाषा या फ़्रेमवर्क के साथ काम करता है:

  • Cloud Run को इससे कोई फ़र्क़ नहीं पड़ता कि वह Python, Go, Node.js, Java या .Net है. हालांकि, यह ज़रूरी है कि वह Linux कंटेनर में चलता हो.

इस्तेमाल के हिसाब से पेमेंट करें:

3. प्रोजेक्ट सेटअप करना

Google खाता

अगर आपके पास पहले से कोई निजी Google खाता नहीं है, तो आपको Google खाता बनाना होगा.

ऑफ़िस या स्कूल वाले खाते के बजाय, निजी खाते का इस्तेमाल करें.

Google Cloud Console में साइन इन करना

किसी निजी Google खाते का इस्तेमाल करके, Google Cloud Console में साइन इन करें.

बिलिंग चालू करें

निजी बिलिंग खाता सेट अप करना

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

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

ध्यान दें:

  • इस लैब को पूरा करने में, Cloud संसाधनों पर 1 डॉलर से कम का खर्च आना चाहिए.
  • ज़्यादा शुल्क से बचने के लिए, इस लैब के आखिर में दिए गए निर्देशों का पालन करके संसाधनों को मिटाया जा सकता है.
  • नए उपयोगकर्ताओं को 300 डॉलर का क्रेडिट मुफ़्त में आज़माने के लिए मिलता है.

प्रोजेक्ट बनाना (ज़रूरी नहीं)

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

4. Cloud Shell Editor खोलें

  1. Cloud Shell Editor पर सीधे जाने के लिए, इस लिंक पर क्लिक करें
  2. अगर आज किसी भी समय अनुमति देने के लिए कहा जाता है, तो जारी रखने के लिए अनुमति दें पर क्लिक करें. Cloud Shell को अनुमति देने के लिए क्लिक करें
  3. अगर टर्मिनल स्क्रीन पर सबसे नीचे नहीं दिखता है, तो इसे खोलें:
    • देखें पर क्लिक करें
    • टर्मिनलCloud Shell Editor में नया टर्मिनल खोलें पर क्लिक करें

5. अपना प्रोजेक्ट सेट करना

  1. टर्मिनल में, इस निर्देश का इस्तेमाल करके अपना प्रोजेक्ट सेट करें:
    gcloud config set project [PROJECT_ID]
    उदाहरण: gcloud config set project lab-project-id-example Cloud Shell Editor के टर्मिनल में प्रोजेक्ट आईडी सेट करना
  2. आपको यह मैसेज दिखेगा:
    Updated property [core/project].

6. एपीआई चालू करें

Cloud Run, Artifact Registry, Cloud Build, Gemini Enterprise Agent Platform, और Compute Engine का इस्तेमाल करने के लिए, आपको अपने Google Cloud प्रोजेक्ट में इनसे जुड़े एपीआई चालू करने होंगे.

  • टर्मिनल में, इन एपीआई को चालू करें:
    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.

पेश है एपीआई

  • Cloud Run Admin API (run.googleapis.com) की मदद से, पूरी तरह से मैनेज किए गए एनवायरमेंट में फ़्रंटएंड और बैकएंड सेवाओं, बैच जॉब या वेबसाइटों को चलाया जा सकता है. यह कंटेनर वाले ऐप्लिकेशन को डिप्लॉय करने और उन्हें स्केल करने के लिए, इन्फ़्रास्ट्रक्चर को मैनेज करता है.
  • Artifact Registry API (artifactregistry.googleapis.com) आपकी कंटेनर इमेज को सेव करने के लिए, सुरक्षित और निजी रिपॉज़िटरी उपलब्ध कराता है. यह Container Registry का नया वर्शन है. यह Cloud Run और Cloud Build के साथ आसानी से इंटिग्रेट हो जाता है.
  • Cloud Build API (cloudbuild.googleapis.com) एक सर्वरलेस CI/CD प्लैटफ़ॉर्म है. यह Google Cloud के इन्फ़्रास्ट्रक्चर पर आपकी बिल्ड प्रोसेस को पूरा करता है. इसका इस्तेमाल, Dockerfile से क्लाउड में कंटेनर इमेज बनाने के लिए किया जाता है.
  • Gemini Enterprise Agent Platform API (aiplatform.googleapis.com) की मदद से, डिप्लॉय किया गया आपका ऐप्लिकेशन, Gemini मॉडल के साथ कम्यूनिकेट कर सकता है. इससे एआई से जुड़े मुख्य टास्क पूरे किए जा सकते हैं. यह Google Cloud की सभी एआई सेवाओं के लिए, यूनिफ़ाइड एपीआई उपलब्ध कराता है.
  • Compute Engine API (compute.googleapis.com) की मदद से, सुरक्षित और पसंद के मुताबिक बनाई जा सकने वाली वर्चुअल मशीनें मिलती हैं. ये मशीनें, Google के इन्फ़्रास्ट्रक्चर पर काम करती हैं. Cloud Run को मैनेज किया जाता है. हालांकि, Compute Engine API की ज़रूरत अक्सर कई नेटवर्किंग और कंप्यूट संसाधनों के लिए बुनियादी डिपेंडेंसी के तौर पर पड़ती है.

7. डेवलपमेंट एनवायरमेंट तैयार करना

डायरेक्ट्री बनाना

  1. टर्मिनल में, प्रोजेक्ट डायरेक्ट्री और ज़रूरी सबडायरेक्ट्री बनाएं:
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. Cloud Shell Editor एक्सप्लोरर में zoo_guide_agent डायरेक्ट्री खोलने के लिए, टर्मिनल में यह कमांड चलाएं:
    cloudshell open-workspace ~/zoo_guide_agent
  3. बाईं ओर मौजूद एक्सप्लोरर पैनल रीफ़्रेश हो जाएगा. अब आपको बनाई गई डायरेक्ट्री दिखेगी.
    एक्सप्लोरर साइड पैनल में नई डायरेक्ट्री का स्क्रीनशॉट
    CRITICAL: नया वर्कस्पेस खोलने पर, Cloud Shell Editor रीसेट हो जाता है और आपका टर्मिनल सेशन फिर से शुरू हो जाता है. आपको टर्मिनल को फिर से खोलना होगा. साथ ही, यह पुष्टि करनी होगी कि आप सही डायरेक्ट्री ~/zoo_guide_agent में हैं. अगर ज़रूरी हो, तो pwd और cd ~/zoo_guide_agent चलाएं. इसके अलावा, यह भी पुष्टि करें कि आपका gcloud प्रोजेक्ट अब भी चुना गया है. अगर ज़रूरी हो, तो gcloud config set project [PROJECT_ID] चलाएं.

ऐप्लिकेशन इंस्टॉल करने से जुड़ी ज़रूरी शर्तें

  1. requirements.txt फ़ाइल बनाने के लिए, टर्मिनल में यह कमांड चलाएं.
    cloudshell edit requirements.txt
  2. नई बनाई गई requirements.txt फ़ाइल में यह जानकारी जोड़ें
    google-adk==2.4.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. टर्मिनल में, uv का इस्तेमाल करके वर्चुअल एनवायरमेंट बनाएं और उसे चालू करें. इससे यह पक्का होता है कि आपके प्रोजेक्ट की डिपेंडेंसी, सिस्टम Python से मेल खाती हों.
    uv venv
source .venv/bin/activate
  4. टर्मिनल में, अपने वर्चुअल एनवायरमेंट में ज़रूरी पैकेज इंस्टॉल करें.
    uv pip install -r requirements.txt

सेवा खाता बनाना और आईएएम अनुमतियां कॉन्फ़िगर करना

एजेंट बनाने से पहले, आपको एक सेवा खाता बनाना होगा और ज़रूरी अनुमतियां कॉन्फ़िगर करनी होंगी. इससे यह पक्का किया जा सकता है कि आपका एजेंट, Gemini Enterprise के एजेंट प्लैटफ़ॉर्म के मॉडल को कॉल कर सकता है और Cloud Build आपके ऐप्लिकेशन को सही तरीके से डिप्लॉय कर सकता है.

  1. टर्मिनल में, अपनी Cloud Run सेवा के लिए एक सेवा खाता बनाएं:
    SA_NAME=lab-service-account
PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for Zoo Agent"
  2. सेवा खाते को Gemini Enterprise Agent Platform User की भूमिका असाइन करें, ताकि आपका एजेंट Gemini को कॉल कर सके:
    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
  3. Cloud Build की अनुमतियां कॉन्फ़िगर करें. Google Cloud के नए प्रोजेक्ट में, डिफ़ॉल्ट सेवा खाते की अनुमतियों को सीमित कर दिया जाता है. इसलिए, आपको Compute Engine के डिफ़ॉल्ट सेवा खाते को, कंटेनर बनाने और उसे डिप्लॉय करने के लिए ज़रूरी भूमिकाएं देनी होंगी. टर्मिनल में ये कमांड चलाएं:
    PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant Artifact Registry Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

# Grant Storage Object Viewer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Grant Logs Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/logging.logWriter"

एनवायरमेंट वैरिएबल सेट अप करना

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

  1. पिछले चरण में, आपने अपने टर्मिनल सेशन में वैरिएबल पहले ही तय कर लिए थे. इसलिए, सीधे तौर पर .env फ़ाइल बनाई जा सकती है:
    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-3.5-flash"
EOF

8. एजेंट वर्कफ़्लो बनाना

__init__.py फ़ाइल बनाएं

  1. टर्मिनल में यह कमांड चलाकर, init.py फ़ाइल बनाएं:
    cloudshell edit __init__.py
    इस फ़ाइल से Python को पता चलता है कि 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
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 ---

load_dotenv()

model_name = os.getenv("MODEL")
    agent.py फ़ाइल का यह पहला ब्लॉक, ADK और Google Cloud से सभी ज़रूरी लाइब्रेरी लाता है. यह लॉगिंग भी सेट अप करता है और आपकी .env फ़ाइल से एनवायरमेंट वैरिएबल लोड करता है. यह आपके मॉडल और सर्वर यूआरएल को ऐक्सेस करने के लिए ज़रूरी है.
  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
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)
    टूल के बारे में जानकारी
    • add_prompt_to_state 📝: यह टूल, चिड़ियाघर आने वाले व्यक्ति के सवालों को याद रखता है. जब कोई व्यक्ति पूछता है कि "शेर कहां हैं?", तो यह टूल उस सवाल को एजेंट की मेमोरी में सेव कर लेता है. इससे वर्कफ़्लो में शामिल अन्य एजेंट को पता चलता है कि उन्हें किस बारे में रिसर्च करनी है.
      कैसे: यह एक Python फ़ंक्शन है. यह वेबसाइट पर आने वाले व्यक्ति के प्रॉम्प्ट को शेयर की गई tool_context.state डिक्शनरी में लिखता है. इस टूल के कॉन्टेक्स्ट से, एजेंट को किसी बातचीत के दौरान कुछ समय के लिए जानकारी याद रखने में मदद मिलती है. किसी एजेंट के सेव किए गए डेटा को, वर्कफ़्लो में मौजूद अगला एजेंट पढ़ सकता है.
    • LangchainTool 🌍: इससे टूर गाइड एजेंट को दुनिया के बारे में सामान्य जानकारी मिलती है. जब कोई व्यक्ति ऐसा सवाल पूछता है जिसका जवाब चिड़ियाघर के डेटाबेस में मौजूद नहीं है, जैसे कि "जंगल में शेर क्या खाते हैं?", तो यह टूल एजेंट को Wikipedia पर जवाब खोजने की सुविधा देता है. (Wikipedia टूल का इस्तेमाल करना गाइड में, Wikipedia टूल को कॉन्फ़िगर करने और कॉल करने के बारे में ज़्यादा जानकारी दी गई है).
      कैसे: यह एक अडैप्टर के तौर पर काम करता है. इससे हमारा एजेंट, 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 से उपयोगकर्ता का प्रॉम्प्ट लेता है. इसके बाद, यह जांच करता है कि यह Wikipedia टूल है या नहीं. इसके बाद, यह तय करता है कि जवाब ढूंढने के लिए किन टूल का इस्तेमाल करना है.
    • response_formatter एजेंट की भूमिका प्रज़ेंटेशन की है. यह Researcher एजेंट से इकट्ठा किए गए रॉ डेटा को लेता है. यह डेटा, State के ज़रिए पास किया जाता है. इसके बाद, यह एलएलएम की भाषा से जुड़ी क्षमताओं का इस्तेमाल करके, इस डेटा को बातचीत वाले जवाब में बदलता है.
      इस इमेज में, नीली आंखों वाला एक रोबोट दिखाया गया है. यह एक बड़े और घुमावदार मॉनिटर के सामने बैठा है. मॉनिटर की बाईं ओर MCP ZOO SERVER और दाईं ओर ZOO का Wikipedia पेज दिख रहा है. सर्वर इंटरफ़ेस पर जानवरों के आइकॉन दिखते हैं. डेस्क पर नीले रंग के कई टचपैड चमक रहे हैं. बैकग्राउंड में, बड़ी-बड़ी खिड़कियों से शहर की ऊंची इमारतें दिख रही हैं.
  5. वर्कफ़्लो एजेंट तय करना: क्रम से काम करने वाले एजेंट tour_guide_workflow को तय करने के लिए, इस कोड ब्लॉक को agent.py के सबसे नीचे जोड़ें:
    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 का इस्तेमाल करता है. इसकी मुख्य भूमिका, पूरी प्रोसेस को मैनेज करना है. यह शुरुआती कंट्रोलर के तौर पर काम करता है. यह बातचीत के पहले चरण को मैनेज करता है.
    इस इमेज में तीन रोबोट दिखाए गए हैं: बाईं ओर एक Greeter-Bot है, जो एक नोटपैड पर लिख रहा है. इसके ऊपर एक शेर का थॉट बबल है. बीच में एक Researcher-Bot है, जो एक डेस्क पर बैठा है. इसके सामने एक कंप्यूटर है, जिसमें डेटा दिख रहा है. साथ ही, एक क्वेरी ऐरो है, जो इसकी ओर इशारा कर रहा है. दाईं ओर एक Presenter-Bot है, जो मुस्कुरा रहा है. इसके हाथ में एक चार्ट है, जिस पर 'विश्लेषण किया गया डेटा' लिखा है. Researcher-Bot से एक ऐरो इसकी ओर इशारा कर रहा है. बैकग्राउंड में जिराफ़ और हाथी दिख रहे हैं. साथ ही, ताड़ के पेड़ों से सीन को फ़्रेम किया गया है.

पूरी agent.py फ़ाइल

आपकी agent.py फ़ाइल अब पूरी हो गई है! इस तरह से इसे बनाने पर, यह देखा जा सकता है कि हर कॉम्पोनेंट—टूल, वर्कर एजेंट, और मैनेजर एजेंट—की, फ़ाइनल और बेहतर सिस्टम बनाने में क्या भूमिका है.

पूरी फ़ाइल ऐसी दिखनी चाहिए:

import os
import 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 ---

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
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

# 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]
)

अगला चरण है, डिप्लॉयमेंट!

9. ऐप्लिकेशन को डिप्लॉय करने के लिए तैयार करना

फ़ाइनल स्ट्रक्चर की जांच करना

डिप्लॉय करने से पहले, पुष्टि करें कि आपकी प्रोजेक्ट डायरेक्ट्री में सही फ़ाइलें मौजूद हों.

  • पक्का करें कि आपका zoo_guide_agent फ़ोल्डर ऐसा दिखता हो:
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

.gcloudignore फ़ाइल को कॉन्फ़िगर करना और एनवायरमेंट वैरिएबल लोड करना

  1. Google Cloud पर वर्चुअल एनवायरमेंट (.venv/) और अन्य गैर-ज़रूरी फ़ाइलों को अपलोड होने से रोकने के लिए, zoo_guide_agent डायरेक्ट्री में .gcloudignore फ़ाइल बनाएं:
    cloudshell edit .gcloudignore
  2. .gcloudignore में यह कॉन्टेंट जोड़ें:
    .gcloudignore
.git
.gitignore
.venv/
venv/
__pycache__/
.env
  3. टर्मिनल सेशन में एनवायरमेंट वैरिएबल लोड करें:
    source .env

10. ADK CLI का इस्तेमाल करके एजेंट को डिप्लॉय करना

लोकल कोड तैयार होने और Google Cloud प्रोजेक्ट सेट अप होने के बाद, एजेंट को डिप्लॉय करने का समय आ गया है. आपको adk deploy cloud_run कमांड का इस्तेमाल करना होगा. यह एक सुविधाजनक टूल है, जो पूरे डिप्लॉयमेंट वर्कफ़्लो को अपने-आप पूरा करता है. इस एक कमांड से, आपका कोड पैकेज हो जाता है, कंटेनर इमेज बन जाती है, और उसे Artifact Registry पर पुश कर दिया जाता है. साथ ही, Cloud Run पर सेवा लॉन्च हो जाती है, ताकि इसे वेब पर ऐक्सेस किया जा सके.

  1. अपने एजेंट को डिप्लॉय करने के लिए, टर्मिनल में यह कमांड चलाएं:
    # Run the deployment command
uvx --from google-adk==2.4.0 \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --allow-unauthenticated \
  --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_ENTERPRISE=true,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    uvx कमांड की मदद से, Python पैकेज के तौर पर पब्लिश किए गए कमांड लाइन टूल को चलाया जा सकता है. इसके लिए, इन टूल को ग्लोबल तौर पर इंस्टॉल करने की ज़रूरत नहीं होती.
  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. कमांड के पूरा होने पर, यह डिप्लॉय की गई Cloud Run सेवा का यूआरएल उपलब्ध कराएगी. (यह कुछ ऐसा दिखेगा: https://zoo-tour-guide-123456789.europe-west1.run.app).
  4. अगले टास्क के लिए, डिप्लॉय की गई Cloud Run सेवा का यूआरएल कॉपी करें.

11. डिप्लॉय किए गए एजेंट को टेस्ट करना

आपका एजेंट अब Cloud Run पर लाइव हो गया है. इसलिए, आपको एक टेस्ट करना होगा. इससे यह पुष्टि की जा सकेगी कि एजेंट को सही तरीके से डिप्लॉय किया गया है और वह उम्मीद के मुताबिक काम कर रहा है. ADK के वेब इंटरफ़ेस को ऐक्सेस करने और एजेंट के साथ इंटरैक्ट करने के लिए, सार्वजनिक सेवा के यूआरएल (https://zoo-tour-guide-123456789.europe-west1.run.app/ जैसा कुछ) का इस्तेमाल किया जाएगा.

  1. अपने वेब ब्राउज़र में, Cloud Run की सार्वजनिक सेवा का यूआरएल खोलें. आपने --with_ui flag का इस्तेमाल किया है. इसलिए, आपको ADK डेवलपर यूज़र इंटरफ़ेस (यूआई) दिखना चाहिए.
  2. सबसे ऊपर दाईं ओर मौजूद, Token Streaming को टॉगल करके चालू करें.
    अब ज़ू एजेंट से इंटरैक्ट किया जा सकता है.
  3. नई बातचीत शुरू करने के लिए, hello टाइप करें और Enter दबाएं.
  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?
    ADK एजेंट के कार्रवाइयों के क्रम का स्क्रीनशॉट: add_prompt_to_state, transfer_to_agent, wikipedia, और get_animals_by_species. पहले जवाब में कहा गया है, 'मैं आपको यह नहीं बता सकती कि इस चिड़ियाघर में ध्रुवीय भालू कहां मिलेंगे. हालांकि, मैं आपको उनके खाने के बारे में बता सकती हूं.' दूसरे जवाब में बताया गया है कि 'ध्रुवीय भालू, पोलर पाथ पर मौजूद आर्कटिक एक्ज़िबिट में हैं. मौजूद टूल की मदद से, मुझे उनके खाने-पीने की आदतों के बारे में जानकारी नहीं मिल पा रही है.' तीसरे और सबसे ज़्यादा जानकारी वाले जवाब में कहा गया है, 'हमें आपको ध्रुवीय भालुओं के बारे में जानकारी देने में खुशी होगी! हमारे ध्रुवीय भालू, पोलर पाथ पर मौजूद आर्कटिक एक्ज़िबिट में देखे जा सकते हैं. यहां तीन ध्रुवीय भालू हैं: स्नोफ़्लेक, जिसकी उम्र सात साल है. Blizzard, जिसकी उम्र पांच साल है. आइसबर्ग, जिसकी उम्र नौ साल है. ध्रुवीय भालू मांसाहारी होते हैं. ये सील का शिकार करने में माहिर होते हैं. खास तौर पर, ये रिंग्ड सील का शिकार करते हैं. ये वॉलरस, बेलुगा व्हेल, और कुछ ज़मीनी जानवरों को भी खाते हैं.'

एजेंट फ़्लो के बारे में जानकारी

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

1. ज़ू में स्वागत करने वाला (वेलकम डेस्क)

पूरी प्रोसेस, ग्रीटर एजेंट से शुरू होती है.

  • इसका काम: बातचीत शुरू करना. इसमें उपयोगकर्ता का अभिवादन करने और यह पूछने का निर्देश दिया गया है कि उसे किस जानवर के बारे में जानना है.
  • इसका टूल: जब उपयोगकर्ता जवाब देता है, तो Greeter अपने add_prompt_to_state टूल का इस्तेमाल करके, उसके शब्दों को कैप्चर करता है.जैसे, "मुझे शेरों के बारे में बताओ". इसके बाद, वह इन शब्दों को सिस्टम की मेमोरी में सेव करता है.
  • हैंडऑफ़: प्रॉम्प्ट सेव करने के बाद, यह तुरंत कंट्रोल को अपने सब-एजेंट, tour_guide_workflow को पास कर देता है.

2. रिसर्च के बारे में पूरी जानकारी देने वाला (सुपर-रिसर्चर)

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

  • इसका काम: उपयोगकर्ता के सवाल का विश्लेषण करना और एक बेहतर प्लान बनाना. यह भाषा मॉडल के टूल इस्तेमाल करने की सुविधा का इस्तेमाल करके यह तय करता है कि इसे इनकी ज़रूरत है या नहीं:
    • वेब से सामान्य जानकारी (Wikipedia API के ज़रिए).
    • इसके अलावा, मुश्किल सवालों के लिए दोनों का इस्तेमाल किया जा सकता है.

3. जवाब को फ़ॉर्मैट करने वाला (प्रज़ेंटर)

जब Comprehensive Researcher सभी तथ्यों को इकट्ठा कर लेता है, तब यह एजेंट काम करता है.

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

अगर आपको एजेंट बनाने के बारे में ज़्यादा जानना है, तो यहां दिए गए संसाधन देखें:

  1. ADK के दस्तावेज़
  2. ADK एजेंट के लिए कस्टम टूल बनाना

12. स्टोरेज में जगह बनाएं

इस ट्यूटोरियल में इस्तेमाल किए गए संसाधनों के लिए, अपने Google Cloud खाते से शुल्क न लिए जाने के लिए, संसाधनों वाला प्रोजेक्ट मिटाएं. इसके अलावा, प्रोजेक्ट को बनाए रखकर अलग-अलग संसाधनों को भी मिटाया जा सकता है.

Cloud Run की सेवाओं, इमेज, और संसाधनों को मिटाना

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

  • टर्मिनल में ये कमांड चलाएं:
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --quiet

प्रोजेक्ट मिटाना (ज़रूरी नहीं)

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

  • टर्मिनल में, यह कमांड चलाएं. [YOUR_PROJECT_ID] की जगह अपना असल प्रोजेक्ट आईडी डालें
    gcloud projects delete $PROJECT_ID

13. बधाई हो

आपने Google Cloud पर, मल्टी-एजेंट एआई ऐप्लिकेशन को बना लिया है और उसे डिप्लॉय कर दिया है!

रीकैप

इस लैब में, आपने एक खाली डायरेक्ट्री से लेकर, लाइव और सार्वजनिक तौर पर ऐक्सेस की जा सकने वाली एआई सेवा तक का सफ़र तय किया. यहां देखें कि आपने क्या बनाया है:

  • आपने एक खास टीम बनाई: आपने एक सामान्य एआई के बजाय, तथ्यों का पता लगाने के लिए "रिसर्चर" और जवाब को बेहतर बनाने के लिए "फ़ॉर्मेटर" बनाया.
  • आपने उन्हें टूल दिए: आपने Wikipedia API का इस्तेमाल करके, अपने एजेंट को बाहरी दुनिया से कनेक्ट किया.
  • आपने इसे शिप किया: आपने अपने लोकल Python कोड को Cloud Run पर सर्वरलेस कंटेनर के तौर पर डिप्लॉय किया. साथ ही, इसे एक खास सेवा खाते से सुरक्षित किया.

हमने क्या-क्या कवर किया है

  • ADK की मदद से डिप्लॉयमेंट के लिए, Python प्रोजेक्ट को स्ट्रक्चर करने का तरीका.
  • [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/) का इस्तेमाल करके, मल्टी-एजेंट वर्कफ़्लो को लागू करने का तरीका.
  • Wikipedia API जैसे बाहरी टूल को इंटिग्रेट करने का तरीका.
  • adk deploy कमांड का इस्तेमाल करके, किसी एजेंट को Cloud Run पर डिप्लॉय करने का तरीका.

14. सर्वे

आउटपुट:

इस ट्यूटोरियल का इस्तेमाल कैसे किया जाएगा?

सिर्फ़ इसे पढ़ें इसे पढ़ें और एक्सरसाइज़ पूरी करें