ADK का एजेंटिक पैटर्न, जिसमें मेमोरी और एमसीपी शामिल हैं

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

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

आप एआई एजेंट की दिलचस्प दुनिया में कदम रखने वाले हैं. अब उन सामान्य चैटबॉट को भूल जाएं जो सिर्फ़ सवालों के जवाब देते हैं. हम Agent Development Kit (ADK) के बारे में गहराई से जानेंगे, ताकि ऐसे बेहतर और ऑटोनॉमस सिस्टम बनाए जा सकें जो तर्क दे सकें, प्लान बना सकें, और मुश्किल टास्क पूरे करने के लिए टूल का इस्तेमाल कर सकें.

इस पूरे कोडलैब में, आपको प्रैक्टिकल अनुभव मिलेगा. इसमें, हमारे सेशन के लिए सभी कोड और उदाहरण वाली यह 1 GitHub रिपो शामिल है. github repo

इस ट्यूटोरियल को पूरा करने के बाद, आपको ये काम करने में मदद मिलेगी:

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

चलिए शुरू करते हैं! 🚀

2. सेटअप: अपना एपीआई पासकोड पाना

Google AI Studio API पासकोड का सेटअप

यह कोडलैब, Google AI Studio के मुफ़्त एपीआई पासकोड पर पूरी तरह से काम करता है. इसके लिए, Google Cloud प्रोजेक्ट, बिलिंग खाता या क्रेडिट की ज़रूरत नहीं होती. मेमोरी (छठा सेशन) और एमसीपी (सातवां सेशन) सहित हर सेशन, आपके पासकोड के हिसाब से स्थानीय तौर पर काम करता है. हर सीखने वाला व्यक्ति, अपना पासकोड इस्तेमाल करता है. इसलिए, एपीआई कोटा हर व्यक्ति के लिए होता है, न कि शेयर किया जाता है.

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

• Python 3.9 या इससे नया वर्शन (वर्शन की जांच करने के लिए, python3 --version कमांड चलाएं)
• एक Google खाता (AI Studio पासकोड बनाने के लिए)
• एक टर्मिनल — स्थानीय मशीन या Cloud Shell , दोनों काम करते हैं
• ~10 मिनट

अपने एआई एजेंट को बेहतर बनाने के लिए, हमें Google AI Studio से Gemini API पासकोड की ज़रूरत है. यह सबसे तेज़ तरीका है.

पहला चरण — AI Studio से अपना Gemini API पासकोड पाना (एक मिनट)

1. ब्राउज़र के नए टैब में https://aistudio.google.com/app/apikey खोलें.
2. अपने Google खाते से साइन इन करें.
3. सबसे ऊपर दाएं कोने में मौजूद, "एपीआई पासकोड बनाएं" पर क्लिक करें.
4. प्रोजेक्ट के ड्रॉपडाउन के साथ एक डायलॉग बॉक्स खुलेगा:

• अगर आपने पहले से कोई Google प्रोजेक्ट बनाया है: उसे चुनें और "मौजूदा प्रोजेक्ट में एपीआई पासकोड बनाएं" पर क्लिक करें
• अगर सूची में कोई प्रोजेक्ट नहीं है: "प्रोजेक्ट बनाएं" पर क्लिक करें.

5. दिखने वाले एपीआई पासकोड को कॉपी करें. यह AIza... से शुरू होता है और इसमें करीब 40 वर्ण होते हैं.

✏️ इसे किसी सुरक्षित जगह पर चिपकाएं — आपको इसकी ज़रूरत चौथे चरण में पड़ेगी.

एपीआई पासकोड को पासवर्ड की तरह इस्तेमाल करें. इसे सार्वजनिक चैट, स्क्रीनशॉट में न चिपकाएं या सार्वजनिक GitHub रिपो में सबमिट न करें.

दूसरा चरण — रिपॉज़िटरी क्लोन करना (एक मिनट)

👉💻 अपना टर्मिनल (या Cloud Shell) खोलें और ट्यूटोरियल रिपो क्लोन करें:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

तीसरा चरण — वर्चुअल एनवायरमेंट बनाना और डिपेंडेंसी इंस्टॉल करना

👉💻 .adk_env नाम का वर्चुअल एनवायरमेंट बनाएं और उसे चालू करें. इसके बाद, डिपेंडेंसी इंस्टॉल करें:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

आपको अपने टर्मिनल प्रॉम्प्ट की शुरुआत में (.adk_env) दिखेगा.

चौथा चरण — 🔥 ज़रूरी: अपना एपीआई पासकोड जोड़ना

⚠️ इस चरण को छोड़ें नहीं! adk_tutorial फ़ोल्डर के रूट में .env फ़ाइल बनाएं. यह एक फ़ाइल, इस कोडलैब के हर सेशन के लिए काम करती है. ADK वेब सेशन (1–5) और कमांड-लाइन मेमोरी और एमसीपी सेशन (6–7) सभी इसे अपने-आप पढ़ते हैं.

👉💻 अपने पासकोड के साथ .env फ़ाइल बनाएं. इसके लिए, your_actual_api_key_here की जगह पहले चरण में मिला पासकोड डालें:

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

अब आपके ~/adk_tutorial/.env में यह जानकारी होनी चाहिए:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 ज़रूरी: your_actual_api_key_here की जगह पहले चरण में मिला अपना एपीआई पासकोड डालें. यह AIza... से शुरू होता है.

⚠️ पक्का करें कि GOOGLE_GENAI_USE_VERTEXAI FALSE पर सेट हो. इससे ADK को Vertex AI के बजाय, Google AI Studio के एपीआई पासकोड से पुष्टि करने का निर्देश मिलता है.

✅ चेकपॉइंट: आपके पास .env फ़ाइल है, जिसमें आपका AIza... पासकोड है. साथ ही, आपके टर्मिनल प्रॉम्प्ट में (.adk_env) दिख रहा है.~/adk_tutorial/.env अब एजेंट बनाए जा सकते हैं!

3. पहला सेशन: ADK वेब में आपका पहला एजेंट

ADK वेब खोलने के लिए, यह कमांड चलाएं:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

कमांड चलाने के बाद, आपको अपने टर्मिनल में आउटपुट दिखेगा. इससे पता चलेगा कि ADK वेब सर्वर शुरू हो गया है. यह आउटपुट, इस तरह दिखना चाहिए:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 इसके बाद, ADK Dev UI ऐक्सेस करने के लिए, अपने ब्राउज़र में http://localhost:8000 खोलें.

स्थानीय तौर पर चलाने के बजाय, Cloud Shell में चलाएं? Cloud Shell टूलबार में मौजूद वेब प्रीव्यू आइकॉन (आम तौर पर, सबसे ऊपर दाएं कोने में) पर क्लिक करें. इसके बाद, पोर्ट बदलें को चुनें. पोर्ट को 8000 पर सेट करें और "बदलें और प्रीव्यू करें" पर क्लिक करें. Cloud Shell, ADK Dev UI को ब्राउज़र के नए टैब में खोलेगा.

👉 एजेंट को शुरू करने की प्रोसेस पूरी हो गई है और अब एजेंट काम कर रहा है. आपके ब्राउज़र में मौजूद ADK Dev UI , एजेंट से सीधे कनेक्ट करने का तरीका है.

अपना पहला एजेंट चुनें यूआई में सबसे ऊपर मौजूद ड्रॉपडाउन मेन्यू में, a_single_agent चुनें.

यहां a_single_agent चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

👉 टेस्ट प्रॉम्प्ट:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. दूसरा सेशन: वर्कफ़्लो एजेंट: सीक्वेंशियल एजेंट, पैरलल एजेंट, लूप एजेंट

पहले सेशन के चरणों को फ़ॉलो करके, अपना ADK वेब यूआई खोलें.

पैरलल एजेंट

पैरलल वर्कफ़्लो एजेंट चुनें यूआई में सबसे ऊपर मौजूद ड्रॉपडाउन मेन्यू में, b2_parallel_agent चुनें.

👉 टेस्ट प्रॉम्प्ट:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

यहां b2_parallel_agent चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

सीक्वेंशियल एजेंट

सीक्वेंशियल वर्कफ़्लो एजेंट चुनें यूआई में सबसे ऊपर मौजूद ड्रॉपडाउन मेन्यू में, b1_sequential_agent चुनें.

👉 टेस्ट प्रॉम्प्ट:

Find a good sushi near Standford and tell me how to get there.

यहां b1_sequential_agent चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

लूप एजेंट

लूप वर्कफ़्लो एजेंट चुनें यूआई में सबसे ऊपर मौजूद ड्रॉपडाउन मेन्यू में, b3_loop_agent चुनें.

👉 टेस्ट प्रॉम्प्ट:

Plan a trip from Sunnyvale to San Francisco today.

यहां b3_loop_agent चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

5. तीसरा सेशन: कस्टम एजेंट

पहले सेशन के चरणों को फ़ॉलो करके, अपना ADK वेब यूआई खोलें.

ADK वेब यूआई खुलने के बाद, ड्रॉपडाउन से c_custom_agent चुनें.

👉 टेस्ट प्रॉम्प्ट:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

यहां c_custom_agent चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

6. चौथा सेशन: ऑर्केस्ट्रेटर पैटर्न - राउटिंग एजेंट

पहले सेशन के चरणों को फ़ॉलो करके, अपना ADK वेब यूआई खोलें.

ADK वेब यूआई खुलने के बाद, ड्रॉपडाउन से d_routing_agent चुनें.

👉 टेस्ट प्रॉम्प्ट:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

यहां d_routing_agent चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

7. पांचवां सेशन: एजेंट-एज़-अ-टूल

पहले सेशन के चरणों को फ़ॉलो करके, अपना ADK वेब यूआई खोलें.

ADK वेब यूआई खुलने के बाद, ड्रॉपडाउन से e_agent_as_tool चुनें.

👉 टेस्ट प्रॉम्प्ट:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

यहां e_agent_as_tool चुना जा सकता है:

यहां ट्रेसिंग देखी जा सकती है:

8. छठा सेशन: लंबे समय तक मेमोरी रखने वाला एजेंट

यह पूरी तरह से स्थानीय तौर पर काम करता है. इस सेशन में, बातचीत की मेमोरी को स्थानीय SQLite डेटाबेस (~/.adk/ में) में सेव किया जाता है. इसलिए, रीस्टार्ट करने पर भी आपकी प्राथमिकताएं बनी रहती हैं. इसके लिए, Google Cloud, बिलिंग या क्रेडिट की ज़रूरत नहीं होती. एजेंट, सेटअप के दौरान बनाए गए ~/adk_tutorial/.env से आपका AI Studio पासकोड पढ़ता है.

👉💻 लंबे समय तक मेमोरी रखने की सुविधा की जांच करने के लिए, फ़ोल्डर पर जाएं और एजेंट को शुरू करने के लिए रनर का इस्तेमाल करें:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 टेस्ट प्रॉम्प्ट:

I like Art and Italian food.

इसके बाद, Ctrl+C दबाकर सेशन खत्म करें. सेशन रीस्टार्ट करें:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 टेस्ट प्रॉम्प्ट:

Plan a trip to San Francisco based on my preference.

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

9. सातवां सेशन: एमसीपी की मदद से अपने एजेंट को बेहतर बनाना

यह पूरी तरह से स्थानीय तौर पर काम करता है. इस सेशन में, स्थानीय एमसीपी टूलबॉक्स सर्वर शुरू होता है, जो स्थानीय SQLite डेटाबेस (destinations.db) को पढ़ता है. इसके लिए, Google Cloud, बिलिंग या क्रेडिट की ज़रूरत नहीं होती. सिर्फ़ ओपन-सोर्स एमसीपी टूलबॉक्स बाइनरी को डाउनलोड करना होता है.

पहला चरण: स्थानीय डेटाबेस तैयार करना

👉💻 रिपो रूट से, सैंपल डेटाबेस बनाएं:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

इससे ~/adk_tutorial/ में destinations.db बनता है.

⚠️ सैंपल डेटाबेस में सिर्फ़ चार शहर शामिल हैं — पेरिस, रोम, न्यूयॉर्क, और टोक्यो (आकर्षण के टाइप: लैंडमार्क, म्यूज़ियम, पार्क). दूसरे शहरों (जैसे, सैन फ़्रांसिस्को या सनीवेल) के बारे में जानकारी मांगने वाले प्रॉम्प्ट के लिए, कोई नतीजा नहीं मिलेगा, क्योंकि उन शहरों की जानकारी मौजूद नहीं है. इस सेशन की जांच करते समय, ऊपर दिए गए चार शहरों का इस्तेमाल करें.

दूसरा चरण: एमसीपी टूलबॉक्स सर्वर इंस्टॉल और रन करना

👉💻 अपने ऑपरेटिंग सिस्टम के लिए, एमसीपी टूलबॉक्स बाइनरी डाउनलोड करें:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

डाउनलोड पूरा होने के बाद, इसे रन करें

chmod +x toolbox

क्या आपको नहीं पता कि आपके पास कौनसा Mac है? uname -m कमांड चलाएं — arm64 = Apple Silicon, x86_64 = Intel. Windows पर, .../windows/amd64/toolbox.exe डाउनलोड करें और इसे PowerShell से रन करें.

तीसरा चरण

एक टर्मिनल में यह कमांड चलाएं. इसे चलने दें, क्योंकि एजेंट इससे http://127.0.0.1:7001 पर कनेक्ट होता है:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

दूसरे टर्मिनल में यह कमांड चलाएं

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 टेस्ट प्रॉम्प्ट (सैंपल डेटाबेस में मौजूद शहरों — पेरिस, रोम, न्यूयॉर्क या टोक्यो का इस्तेमाल करें):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

सातवें सेशन की समस्याएं हल करना

• " कनेक्शन अस्वीकार किया गया" / एजेंट को कोई टूल नहीं मिलता: पहले टर्मिनल में टूलबॉक्स सर्वर नहीं चल रहा है. इसे रीस्टार्ट करें और पुष्टि करें कि यह पोर्ट 7001 पर सुन रहा है.
• हर क्वेरी के लिए खाली नतीजे मिलते हैं: पुष्टि करें कि आपने पहला चरण पूरा कर लिया है, ताकि ~/adk_tutorial/destinations.db मौजूद हो. साथ ही, पुष्टि करें कि आपके प्रॉम्प्ट में चार शहरों (पेरिस, रोम, न्यूयॉर्क, टोक्यो) में से किसी एक का इस्तेमाल किया गया हो.
• toolbox: cannot execute binary file macOS पर: आपने Linux बिल्ड डाउनलोड किया है. इसलिए, दूसरा चरण फिर से चलाएं. इसके लिए, OS=darwin/arm64 (Apple Silicon) या OS=darwin/amd64 (Intel) का इस्तेमाल करें.