डेटाबेस और एजेंट डेवलपमेंट किट (ADK) के लिए एमसीपी टूलबॉक्स का इस्तेमाल करके, ट्रैवल एजेंट बनाएं
इस कोडलैब (कोड बनाना सीखने के लिए ट्यूटोरियल) के बारे में जानकारी
1. परिचय
इस कोडलैब में, एजेंट डेवलपमेंट किट (एडीके) का इस्तेमाल करके एक एजेंट बनाया जाएगा. यह एजेंट, डेटाबेस के लिए एमसीपी टूलबॉक्स का इस्तेमाल करता है.
कोडलैब में, आपको सिलसिलेवार तरीके से यह तरीका अपनाना होगा:
- 'PostgreSQL के लिए Cloud SQL' डेटाबेस सेट अप करें. इसमें होटलों का डेटाबेस और सैंपल डेटा होगा.
- डेटाबेस के लिए एमसीपी टूलबॉक्स सेट अप करें, जो डेटा का ऐक्सेस देता है.
- एजेंट डेवलपमेंट किट (ADK) का इस्तेमाल करके, एक एजेंट डिज़ाइन और डेवलप करें. यह एजेंट, उपयोगकर्ता की क्वेरी का जवाब देने के लिए एमसीपी टूलबॉक्स का इस्तेमाल करेगा.
- डेटाबेस के लिए, एजेंट और एमसीपी टूलबॉक्स को स्थानीय तौर पर और Cloud Run सेवा की मदद से Google Cloud पर टेस्ट करने के विकल्प एक्सप्लोर करें.
आपको क्या करना होगा
- ऐसा एजेंट डिज़ाइन, बनाएं, और डिप्लॉय करें जो किसी जगह के होटलों के बारे में उपयोगकर्ता की क्वेरी का जवाब दे या नाम के हिसाब से होटल खोजें.
आपको क्या सीखने को मिलेगा
- 'PostgreSQL के लिए Cloud SQL' डेटाबेस को सैंपल डेटा के साथ प्रोवाइड और पॉप्युलेट करना.
- 'PostgreSQL के लिए Cloud SQL' डेटाबेस इंस्टेंस के लिए, डेटाबेस के लिए MCP टूलबॉक्स सेटअप करें.
- उपयोगकर्ता की क्वेरी का जवाब देने के लिए, एजेंट डेवलपमेंट किट (ADK) का इस्तेमाल करके एजेंट डिज़ाइन और डेवलप करें.
- स्थानीय एनवायरमेंट में, डेटाबेस के लिए एजेंट और एमसीपी टूलबॉक्स को टेस्ट करें.
- (ज़रूरी नहीं) Google Cloud में डेटाबेस के लिए एजेंट और एमसीपी टूलबॉक्स डिप्लॉय करें.
आपको इन चीज़ों की ज़रूरत होगी
- Chrome वेब ब्राउज़र
- Gmail खाता
- बिलिंग की सुविधा वाला Cloud प्रोजेक्ट
यह कोडलैब, सभी लेवल के डेवलपर (शुरुआती डेवलपर भी) के लिए डिज़ाइन किया गया है. इसमें सैंपल ऐप्लिकेशन के लिए Python का इस्तेमाल किया गया है. हालांकि, यहां दिए गए कॉन्सेप्ट को समझने के लिए, Python के बारे में जानकारी होना ज़रूरी नहीं है.
2. शुरू करने से पहले
प्रोजेक्ट बनाना
- Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
- पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग की सुविधा चालू हो. किसी प्रोजेक्ट के लिए बिलिंग की सुविधा चालू है या नहीं, यह देखने का तरीका जानें .
- इसके लिए, आपको Cloud Shell का इस्तेमाल करना होगा. यह Google Cloud में चलने वाला कमांड-लाइन एनवायरमेंट है, जिसमें bq पहले से लोड होता है. Google Cloud कंसोल में सबसे ऊपर, 'Cloud Shell चालू करें' पर क्लिक करें.
- Cloud Shell से कनेक्ट होने के बाद, यह जांच करें कि आपकी पुष्टि पहले ही हो चुकी है या नहीं. साथ ही, यह भी देखें कि प्रोजेक्ट आपके प्रोजेक्ट आईडी पर सेट है या नहीं. इसके लिए, यह कमांड इस्तेमाल करें:
gcloud auth list
- Cloud Shell में यह कमांड चलाकर पुष्टि करें कि gcloud कमांड को आपके प्रोजेक्ट के बारे में पता है.
gcloud config list project
- अगर आपका प्रोजेक्ट सेट नहीं है, तो इसे सेट करने के लिए इस निर्देश का इस्तेमाल करें:
gcloud config set project <YOUR_PROJECT_ID>
- नीचे दिए गए निर्देश का इस्तेमाल करके, ज़रूरी एपीआई चालू करें. इसमें कुछ मिनट लग सकते हैं. इसलिए, कृपया इंतज़ार करें.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
निर्देश पूरा होने पर, आपको यहां दिखाए गए मैसेज जैसा मैसेज दिखेगा:
Operation "operations/..." finished successfully.
gcloud कमांड के विकल्प के तौर पर, कंसोल में जाकर हर प्रॉडक्ट को खोजें या इस लिंक का इस्तेमाल करें.
अगर कोई एपीआई छूट जाता है, तो उसे लागू करने के दौरान कभी भी चालू किया जा सकता है.
gcloud के निर्देशों और इस्तेमाल के बारे में जानने के लिए, दस्तावेज़ देखें.
3. Cloud SQL इंस्टेंस बनाना
हम अपने होटलों का डेटा सेव करने के लिए, PostgreSQL के लिए Google Cloud SQL इंस्टेंस का इस्तेमाल करेंगे. 'PostgreSQL के लिए Cloud SQL' पूरी तरह से मैनेज की गई डेटाबेस सेवा है. इसकी मदद से, Google Cloud Platform पर अपने मिलते-जुलते PostgreSQL डेटाबेस को आसानी से सेट अप किया जा सकता है. साथ ही, उसे बनाए रखने, मैनेज करने, और सही तरीके से चलाने में भी मदद मिलती है.
इंस्टेंस बनाने के लिए, Cloud Shell में यह कमांड चलाएं:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
इस निर्देश को लागू होने में करीब 3 से 5 मिनट लगते हैं. कमांड पूरा होने के बाद, आपको एक आउटपुट दिखेगा. इससे पता चलेगा कि कमांड पूरा हो गया है. साथ ही, आपको अपने Cloud SQL इंस्टेंस की जानकारी भी दिखेगी. जैसे, NAME, DATABASE_VERSION, LOCATION वगैरह.
4. होटल डेटाबेस तैयार करना
अब हमारा काम अपने होटल एजेंट के लिए कुछ सैंपल डेटा बनाना होगा.
Cloud Console में, Cloud SQL पेज पर जाएं.आपको hoteldb-instance तैयार और बनाया गया दिखेगा. इंस्टेंस के नाम (hoteldb-instance) पर क्लिक करें, जैसा कि यहां दिखाया गया है:
Cloud SQL के बाएं मेन्यू में, Cloud SQL Studio मेन्यू विकल्प पर जाएं, जैसा कि यहां दिखाया गया है:
इसके बाद, आपसे Cloud SQL Studio में साइन इन करने के लिए कहा जाएगा. इसके बाद, हम आपको कुछ SQL कमांड देंगे. डेटाबेस के विकल्प के लिए postgres चुनें. साथ ही, उपयोगकर्ता और पासवर्ड, दोनों के लिए इस्तेमाल की जाने वाली वैल्यू postgres है. AUTHENTICATE पर क्लिक करें.
सबसे पहले, यहां दिए गए स्कीमा के मुताबिक होटल टेबल बनाएं. Cloud SQL Studio के एडिटर पैनल में से किसी एक में, यह SQL चलाएं:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
अब, होटल टेबल में सैंपल डेटा डालते हैं. यह एसक्यूएल चलाएं:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
आइए, नीचे दिखाए गए SELECT SQL को चलाकर डेटा की पुष्टि करें:
SELECT * FROM hotels;
आपको होटल टेबल में कई रिकॉर्ड दिखेंगे, जैसा कि यहां दिखाया गया है:
हमने Cloud SQL इंस्टेंस सेट अप करने की प्रोसेस पूरी कर ली है और अपना सैंपल डेटा बना लिया है. अगले सेक्शन में, हम डेटाबेस के लिए एमसीपी टूलबॉक्स सेट अप करेंगे.
5. डेटाबेस के लिए एमसीपी टूलबॉक्स सेटअप करना
डेटाबेस के लिए एमसीपी टूलबॉक्स, डेटाबेस के लिए एक ओपन सोर्स एमसीपी सर्वर है. इसे एंटरप्राइज़-ग्रेड और प्रोडक्शन-क्वालिटी को ध्यान में रखकर डिज़ाइन किया गया था. इससे, कनेक्शन पूल करने, पुष्टि करने वगैरह जैसी मुश्किल प्रक्रियाओं को मैनेज करके, टूल को आसानी से, तेज़ी से, और ज़्यादा सुरक्षित तरीके से बनाया जा सकता है.
टूलबॉक्स की मदद से, जनरेटिव एआई टूल बनाए जा सकते हैं. इनकी मदद से, आपके एजेंट आपके डेटाबेस में मौजूद डेटा को ऐक्सेस कर सकते हैं. टूलबॉक्स में ये सुविधाएं मिलती हैं:
- डेवलपमेंट को आसान बनाना: 10 लाइनों से भी कम कोड में अपने एजेंट में टूल इंटिग्रेट करें. साथ ही, कई एजेंट या फ़्रेमवर्क के बीच टूल का फिर से इस्तेमाल करें और टूल के नए वर्शन को आसानी से डिप्लॉय करें.
- बेहतर परफ़ॉर्मेंस: कनेक्शन पूल करने, पुष्टि करने वगैरह जैसे सबसे सही तरीके.
- बेहतर सुरक्षा: आपके डेटा को ज़्यादा सुरक्षित तरीके से ऐक्सेस करने के लिए, इंटिग्रेट किया गया पुष्टि करने का तरीका
- एंड-टू-एंड निगरानी: OpenTelemetry के लिए पहले से मौजूद सहायता के साथ, पहले से तैयार मेट्रिक और ट्रैकिंग.
टूलबॉक्स, आपके ऐप्लिकेशन के ऑर्केस्ट्रेशन फ़्रेमवर्क और डेटाबेस के बीच में होता है. यह एक कंट्रोल प्लेन उपलब्ध कराता है, जिसका इस्तेमाल टूल में बदलाव करने, उन्हें डिस्ट्रिब्यूट करने या उन्हें चालू करने के लिए किया जाता है. यह आपके टूल को मैनेज करने की प्रोसेस को आसान बनाता है. इसके लिए, यह टूल को सेव और अपडेट करने की एक ही जगह उपलब्ध कराता है. साथ ही, यह एजेंट और ऐप्लिकेशन के बीच टूल शेयर करने की सुविधा देता है. साथ ही, ऐप्लिकेशन को फिर से डिप्लॉय किए बिना, उन टूल को अपडेट करने की सुविधा भी देता है.
आप देख सकते हैं कि डेटाबेस के लिए एमसीपी टूलबॉक्स के साथ काम करने वाला एक डेटाबेस, Cloud SQL है. हमने पिछले सेक्शन में इसके लिए प्रावधान किया है.
टूलबॉक्स इंस्टॉल करना
Cloud Shell टर्मिनल खोलें और mcp-toolbox नाम का फ़ोल्डर बनाएं.
mkdir mcp-toolbox
नीचे दिए गए कमांड का इस्तेमाल करके, mcp-toolbox फ़ोल्डर पर जाएं:
cd mcp-toolbox
यहां दी गई स्क्रिप्ट की मदद से, डेटाबेस के लिए MCP टूलबॉक्स का बाइनरी वर्शन इंस्टॉल करें:
export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
अब हमारे पास टूलबॉक्स का बाइनरी वर्शन इस्तेमाल के लिए तैयार है. अगला चरण, टूलबॉक्स को हमारे डेटा सोर्स और अन्य कॉन्फ़िगरेशन के साथ कॉन्फ़िगर करना है.
tools.yaml कॉन्फ़िगर करना
टूलबॉक्स को कॉन्फ़िगर करने का मुख्य तरीका, tools.yaml फ़ाइल का इस्तेमाल करना है. उसी फ़ोल्डर में tools.yaml नाम की एक फ़ाइल बनाएं, यानी mcp-toolbox. इस फ़ाइल में मौजूद कॉन्टेंट नीचे दिखाया गया है.
Cloud Shell में मौजूद nano एडिटर का इस्तेमाल किया जा सकता है. nano कमांड इस तरह का होता है: "nano tools.yaml".
YOUR_PROJECT_ID वैल्यू को अपने Google Cloud प्रोजेक्ट आईडी से बदलना न भूलें.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
आइए, इस फ़ाइल के बारे में कम शब्दों में जानते हैं:
Sourcesआपके अलग-अलग डेटा सोर्स दिखाता है जिनके साथ कोई टूल इंटरैक्ट कर सकता है. सोर्स, उस डेटा सोर्स को दिखाता है जिससे कोई टूल इंटरैक्ट कर सकता है. tools.yaml फ़ाइल के सोर्स सेक्शन में,Sourcesको मैप के तौर पर तय किया जा सकता है. आम तौर पर, सोर्स कॉन्फ़िगरेशन में वह सारी जानकारी होती है जो डेटाबेस से कनेक्ट करने और उससे इंटरैक्ट करने के लिए ज़रूरी होती है. हमारे मामले में, हमने एक सोर्स कॉन्फ़िगर किया है, जो क्रेडेंशियल के साथ 'PostgreSQL के लिए Cloud SQL' इंस्टेंस पर ले जाता है. ज़्यादा जानकारी के लिए, सोर्स रेफ़रंस देखें.Toolsसे यह तय होता है कि एजेंट कौनसी कार्रवाइयां कर सकता है. जैसे, किसी सोर्स को पढ़ना और उसमें डेटा डालना. टूल से उस कार्रवाई के बारे में पता चलता है जो आपका एजेंट कर सकता है. जैसे, SQL स्टेटमेंट चलाना. tools.yaml फ़ाइल के टूल सेक्शन में,Toolsको मैप के तौर पर तय किया जा सकता है. आम तौर पर, किसी टूल को काम करने के लिए सोर्स की ज़रूरत होती है. हमारे मामले में, हम दो टूल तय कर रहे हैं:search-hotels-by-nameऔरsearch-hotels-by-location. साथ ही, एसक्यूएल और पैरामीटर के साथ उस सोर्स के बारे में बता रहे हैं जिस पर यह काम कर रहा है. ज़्यादा जानकारी के लिए, टूल रेफ़रंस देखें.- आखिर में, हमारे पास
Toolsetहै. इसकी मदद से, उन टूल के ग्रुप तय किए जा सकते हैं जिन्हें आपको एक साथ लोड करना है. यह एजेंट या ऐप्लिकेशन के आधार पर अलग-अलग ग्रुप तय करने के लिए मददगार हो सकता है. हमारे मामले में, हमारे पासmy_first_toolsetनाम का एक टूलसेट है. इसमें वे दो टूल शामिल हैं जिन्हें हमने तय किया है.
डेटाबेस सर्वर के लिए MCP टूलबॉक्स चलाना
सर्वर को शुरू करने के लिए, mcp-toolbox फ़ोल्डर में जाकर यह कमांड चलाएं:
./toolbox --tools-file "tools.yaml"
आम तौर पर, आपको यह आउटपुट दिखना चाहिए कि सर्वर हमारे डेटा सोर्स से कनेक्ट हो गया है और उसने टूलसेट और टूल लोड कर लिए हैं. आउटपुट का सैंपल यहां दिया गया है:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
एमसीपी टूलबॉक्स सर्वर, डिफ़ॉल्ट रूप से 5000 पोर्ट पर चलता है. अगर आपको पता चलता है कि पोर्ट 5000 पहले से ही इस्तेमाल में है, तो यहां दिए गए निर्देश के मुताबिक किसी दूसरे पोर्ट (जैसे, 7000) का इस्तेमाल करें. इसके बाद, कृपया अगले निर्देशों में 5000 पोर्ट के बजाय 7000 का इस्तेमाल करें.
./toolbox --tools-file "tools.yaml" --port 7000
आइए, इसकी जांच करने के लिए Cloud Shell का इस्तेमाल करें.
Cloud Shell में, वेब की झलक पर क्लिक करें, जैसा कि यहां दिखाया गया है:
पोर्ट बदलें पर क्लिक करें और पोर्ट को 5000 पर सेट करें, जैसा कि नीचे दिखाया गया है. इसके बाद, बदलें और झलक देखें पर क्लिक करें.
इससे यह आउटपुट दिखेगा:
ब्राउज़र के यूआरएल में, यूआरएल के आखिर में यह जोड़ें:
/api/toolset
ऐसा करने पर, आपको वे टूल दिखेंगे जो फ़िलहाल कॉन्फ़िगर किए गए हैं. आउटपुट का सैंपल यहां दिया गया है:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
डेटाबेस के लिए एमसीपी टूलकिट में, टूल की पुष्टि करने और उन्हें टेस्ट करने के लिए Pythonic तरीके के बारे में बताया गया है. इस बारे में यहां जानकारी दी गई है. हम इस सेक्शन को छोड़कर, अगले सेक्शन में सीधे एजेंट डेवलपमेंट किट (ADK) पर जाएंगे. इस सेक्शन में इन टूल का इस्तेमाल किया जाएगा.
6. Agent Development Kit (ADK) की मदद से एजेंट लिखना
एजेंट डेवलपमेंट किट (ADK) इंस्टॉल करना
Cloud Shell में नया टर्मिनल टैब खोलें और यहां दिए गए तरीके से my-agents नाम का फ़ोल्डर बनाएं. my-agents फ़ोल्डर पर भी जाएं.
mkdir my-agents
cd my-agents
अब, venv का इस्तेमाल करके, वर्चुअल Python एनवायरमेंट बनाएं. इसके लिए, यह तरीका अपनाएं:
python -m venv .venv
वर्चुअल एनवायरमेंट को इस तरह चालू करें:
source .venv/bin/activate
डेटाबेस पैकेज के लिए ADK और MCP टूलबॉक्स के साथ-साथ, लैंगचैन डिपेंडेंसी को इस तरह इंस्टॉल करें:
pip install google-adk toolbox-core
अब adk यूटिलिटी को इस तरह से चालू किया जा सकता है.
adk
इससे आपको निर्देशों की सूची दिखेगी.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
हमारा पहला एजेंट ऐप्लिकेशन बनाना
अब हम अपने होटल एजेंट ऐप्लिकेशन के लिए स्कैफ़ोल्ड बनाने के लिए, adk का इस्तेमाल करने जा रहे हैं. इसके लिए, adk create कमांड का इस्तेमाल करके, ऐप्लिकेशन का नाम **(hotel-agent-app)**डालें, जैसा कि यहां बताया गया है.
adk create hotel-agent-app
यह तरीका अपनाएं और नीचे दिए गए विकल्प चुनें:
- रूट एजेंट के लिए मॉडल चुनने के लिए Gemini मॉडल.
- बैकएंड के लिए Vertex AI चुनें.
- आपको अपना डिफ़ॉल्ट Google प्रोजेक्ट आईडी और क्षेत्र दिखेगा. डिफ़ॉल्ट विकल्प को खुद चुनें.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
उस फ़ोल्डर की समीक्षा करें जिसमें एजेंट के लिए डिफ़ॉल्ट टेंप्लेट और ज़रूरी फ़ाइलें बनाई गई हैं.
सबसे पहले .env फ़ाइल है. इनमें शामिल कॉन्टेंट नीचे दिया गया है:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
इन वैल्यू से पता चलता है कि हम Vertex AI के ज़रिए Gemini का इस्तेमाल करेंगे. साथ ही, Google Cloud प्रोजेक्ट आईडी और जगह की वैल्यू का भी इस्तेमाल किया जाएगा.
इसके बाद, हमारे पास __init__.py फ़ाइल है, जो फ़ोल्डर को मॉड्यूल के तौर पर मार्क करती है. इसमें एक स्टेटमेंट है, जो agent.py फ़ाइल से एजेंट इंपोर्ट करता है.
from . import agent
आखिर में, agent.py फ़ाइल के बारे में जानें. कॉन्टेंट यहां दिखाए गए हैं:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
यह सबसे आसान एजेंट है, जिसे ADK की मदद से लिखा जा सकता है. ADK दस्तावेज़ के पेज के मुताबिक, एजेंट एक ऐसी यूनिट है जो अपने-आप काम करती है. इसे खास लक्ष्यों को हासिल करने के लिए, अपने हिसाब से काम करने के लिए डिज़ाइन किया गया है. एजेंट, टास्क पूरे कर सकते हैं, उपयोगकर्ताओं के साथ इंटरैक्ट कर सकते हैं, बाहरी टूल का इस्तेमाल कर सकते हैं, और दूसरे एजेंट के साथ काम कर सकते हैं.
खास तौर पर, LLMAgent, जिसे आम तौर पर एजेंट कहा जाता है, अपने मुख्य इंजन के तौर पर लार्ज लैंग्वेज मॉडल (एलएलएम) का इस्तेमाल करता है. इससे, यह सामान्य भाषा को समझने, तर्क करने, प्लान बनाने, जवाब जनरेट करने, और आगे कैसे बढ़ना है या किन टूल का इस्तेमाल करना है, यह फ़ैसला डाइनैमिक तरीके से ले पाता है. इस वजह से, यह भाषा पर आधारित आसान टास्क के लिए आदर्श है. एलएलएम एजेंट के बारे में ज़्यादा जानने के लिए, यहां जाएं.
agent.py के लिए कोड में इस तरह बदलाव करें:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
एजेंट ऐप्लिकेशन को लोकल तौर पर टेस्ट करना
मौजूदा टर्मिनल विंडो से, यह कमांड दें. पक्का करें कि आप उस पैरंट फ़ोल्डर (my-agents) में हों जिसमें hotel-agent-app फ़ोल्डर मौजूद है.
adk web
इसे लागू करने का सैंपल यहां दिया गया है:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| 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)
आखिरी लिंक पर क्लिक करें. इसके बाद, आपको एजेंट की जांच करने के लिए एक वेब कंसोल दिखेगा. आपको ब्राउज़र में, यहां दिखाए गए विकल्प दिखेंगे:
ध्यान दें कि सबसे ऊपर बाईं ओर, hotel-agent-app की पहचान की गई है. अब एजेंट से बातचीत शुरू की जा सकती है. शहरों के बारे में पूछताछ करने के लिए कुछ प्रॉम्प्ट दें. बातचीत का उदाहरण यहां दिया गया है:
Cloud Shell टर्मिनल में चल रही प्रोसेस को बंद किया जा सकता है (Ctrl-C).
एजेंट की जांच करने का एक और तरीका है, adk run कमांड का इस्तेमाल करना. इसके लिए, my-agents फ़ोल्डर में जाकर, नीचे दिया गया तरीका अपनाएं.
adk run hotel-agent-app
कमांड आज़माएं और कमांड लाइन (टर्मिनल) के ज़रिए एजेंट से बातचीत करें. बातचीत को बंद करने के लिए, exit लिखें.
7. अपने एजेंट को टूल से कनेक्ट करना
अब हम एजेंट लिखने और उसे स्थानीय तौर पर टेस्ट करने का तरीका जानते हैं. हम इस एजेंट को टूल से कनेक्ट करने जा रहे हैं. एडीके के संदर्भ में, टूल किसी एआई एजेंट को दी गई खास सुविधा को दिखाता है. इससे एजेंट, टेक्स्ट जनरेट करने और तर्क करने की मुख्य क्षमताओं के अलावा, कार्रवाइयां कर सकता है और दुनिया के साथ इंटरैक्ट कर सकता है.
हमारे मामले में, हम अपने एजेंट को उन टूल से लैस करने जा रहे हैं जिन्हें हमने डेटाबेस के लिए MCP टूलबॉक्स में कॉन्फ़िगर किया है.
नीचे दिए गए कोड की मदद से, agent.py फ़ाइल में बदलाव करें. ध्यान दें कि हम कोड में डिफ़ॉल्ट पोर्ट 5000 का इस्तेमाल कर रहे हैं. हालांकि, अगर आपने कोई दूसरा पोर्ट नंबर इस्तेमाल किया है, तो कृपया उसका इस्तेमाल करें.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
अब हम उस एजेंट की जांच कर सकते हैं जो डेटाबेस के लिए MCP टूलबॉक्स के साथ कॉन्फ़िगर किए गए हमारे PostgreSQL डेटाबेस से रीयल डेटा फ़ेच करेगा.
इसके लिए, यह तरीका अपनाएं:
Cloud Shell के एक टर्मिनल में, डेटाबेस के लिए MCP टूलबॉक्स लॉन्च करें. हो सकता है कि आपने इसे पहले ही पोर्ट 5000 पर स्थानीय तौर पर चला रखा हो, क्योंकि हमने पहले इसकी जांच की थी. अगर ऐसा नहीं है, तो सर्वर को शुरू करने के लिए, mcp-toolbox फ़ोल्डर में जाकर यह कमांड चलाएं:
./toolbox --tools_file "tools.yaml"
आम तौर पर, आपको यह आउटपुट दिखना चाहिए कि सर्वर हमारे डेटा सोर्स से कनेक्ट हो गया है और उसने टूलसेट और टूल लोड कर लिए हैं. आउटपुट का सैंपल यहां दिया गया है:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
एमसीपी सर्वर के शुरू होने के बाद, किसी दूसरे टर्मिनल में एजेंट को लॉन्च करें. इसके लिए, यहां दिए गए adk run (my-agents फ़ोल्डर से) कमांड का इस्तेमाल करें. अगर आप चाहें, तो adk web निर्देश का भी इस्तेमाल किया जा सकता है.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
ध्यान दें कि एजेंट अब उन दो टूल का इस्तेमाल कर रहा है जिन्हें हमने डेटाबेस के लिए एमसीपी टूलबॉक्स (search-hotels-by-name और search-hotels-by-location) में कॉन्फ़िगर किया है. साथ ही, वह हमें सही विकल्प दे रहा है. इसके बाद, यह PostgreSQL इंस्टेंस डेटाबेस से डेटा को आसानी से वापस पा सकता है और जवाब को उसके हिसाब से फ़ॉर्मैट कर सकता है.
इससे, एजेंट डेवलपमेंट किट (एडीके) का इस्तेमाल करके बनाए गए हमारे होटल एजेंट के लोकल डेवलपमेंट और टेस्टिंग की प्रोसेस पूरी हो जाती है. यह एजेंट, डेटाबेस के लिए एमसीपी टूलबॉक्स में कॉन्फ़िगर किए गए टूल की मदद से काम करता है.
8. (ज़रूरी नहीं) डेटाबेस और एजेंट के लिए एमसीपी टूलबॉक्स को Cloud Run पर डिप्लॉय करना
पिछले सेक्शन में, हमने MCP टूलबॉक्स सर्वर को लॉन्च करने के लिए Cloud Shell टर्मिनल का इस्तेमाल किया था. साथ ही, एजेंट के साथ टूल की जांच की थी. यह Cloud Shell एनवायरमेंट में लोकल तौर पर चल रहा था.
आपके पास Google Cloud की उन सेवाओं में एमसीपी टूलबॉक्स सर्वर और एजेंट, दोनों को डिप्लॉय करने का विकल्प है जो हमारे लिए इन ऐप्लिकेशन को होस्ट कर सकती हैं.
Cloud Run पर MCP टूलबॉक्स सर्वर को होस्ट करना
सबसे पहले, हम MCP टूलबॉक्स सर्वर से शुरुआत कर सकते हैं और इसे Cloud Run पर होस्ट कर सकते हैं. इससे हमें एक सार्वजनिक एंडपॉइंट मिलेगा, जिसे हम किसी भी दूसरे ऐप्लिकेशन और/या एजेंट ऐप्लिकेशन के साथ इंटिग्रेट कर सकते हैं. Cloud Run पर इसे होस्ट करने के निर्देश यहां दिए गए हैं. अब हम ज़रूरी चरणों के बारे में बताएंगे.
नया Cloud Shell टर्मिनल लॉन्च करें या किसी मौजूदा Cloud Shell टर्मिनल का इस्तेमाल करें. उस mcp-toolbox फ़ोल्डर पर जाएं जिसमें toolbox बाइनरी और tools.yaml मौजूद हैं.
ये कमांड चलाएं (हर कमांड के लिए जानकारी दी गई है):
PROJECT_ID वैरिएबल को अपने Google Cloud प्रोजेक्ट आईडी पर ले जाने के लिए सेट करें.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
इसके बाद, पुष्टि करें कि प्रोजेक्ट में Google Cloud की ये सेवाएं चालू हों.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
आइए, एक अलग सेवा खाता बनाएं. यह Google Cloud Run पर डिप्लॉय की जाने वाली टूलबॉक्स सेवा की पहचान के तौर पर काम करेगा. हम यह भी पक्का कर रहे हैं कि इस सेवा खाते के पास सही भूमिकाएं हों. जैसे, Secret Manager को ऐक्सेस करने और Cloud SQL से बातचीत करने की अनुमति.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
हम tools.yaml फ़ाइल को सीक्रेट के तौर पर अपलोड करेंगे. साथ ही, हमें Cloud Run में टूलबॉक्स इंस्टॉल करना है, इसलिए हम टूलबॉक्स के लिए सबसे नई कंटेनर इमेज का इस्तेमाल करेंगे और उसे IMAGE वैरिएबल में सेट करेंगे.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Cloud Run में डिप्लॉय करने के लिए, जाने-पहचाने निर्देश का आखिरी चरण:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
इससे, Cloud Run पर कॉन्फ़िगर किए गए tools.yaml के साथ टूलबॉक्स सर्वर को डिप्लॉय करने की प्रोसेस शुरू हो जाएगी. डिप्लॉयमेंट पूरा होने पर, आपको इस तरह का मैसेज दिखेगा:
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
अब ब्राउज़र में ऊपर दिए गए Service URL पर जाएं. इसमें, हमें पहले जैसा "नमस्ते दुनिया" मैसेज दिखेगा. इसके अलावा, उपलब्ध टूल देखने के लिए, इस यूआरएल पर भी जाएं:
SERVICE URL/api/toolset
Google Cloud Console से Cloud Run पर भी जाया जा सकता है. यहां आपको Cloud Run में सेवाओं की सूची में टूलबॉक्स सेवा दिखेगी.
ध्यान दें: अगर आपको अब भी अपने होटल एजेंट को स्थानीय तौर पर चलाना है और साथ ही, हाल ही में डिप्लॉय की गई Cloud Run सेवा से कनेक्ट करना है, तो आपको my-agents/hotel-agent-app/agent.py फ़ाइल में सिर्फ़ एक बदलाव करना होगा.
इनके बजाय:
toolbox = ToolboxTool("http://127.0.0.1:5000")
इसे Cloud Run सेवा के यूआरएल में बदलें. इसके लिए, यहां दिया गया तरीका अपनाएं:
toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")
जैसा कि हमने पहले देखा था, adk run या adk web का इस्तेमाल करके, एजेंट ऐप्लिकेशन की जांच करें.
Cloud Run पर Hotel Agent ऐप्लिकेशन को डिप्लॉय करना
सबसे पहले, यह पक्का करें कि आपने ऊपर दिए गए निर्देशों के मुताबिक, my-agents/hotel-agent-app/agent.py में बदलाव किया हो. इससे, टूलबॉक्स सेवा के उस यूआरएल पर पहुंचा जा सकेगा जो Cloud Run पर चल रहा है, न कि लोकल होस्ट पर.
नए Cloud Shell टर्मिनल या मौजूदा टर्मिनल सेशन में, पक्का करें कि आप सही Python वर्चुअल एनवायरमेंट में हों. हमने इसे पहले सेट अप किया है.
सबसे पहले, my-agents/hotel-agent-app फ़ोल्डर में requirements.txt फ़ाइल बनाएं, जैसा कि यहां दिखाया गया है:
google-adk
toolbox-core
my-agents फ़ोल्डर पर जाएं और सबसे पहले, इन एनवायरमेंट वैरिएबल को सेट करें:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
आखिर में, नीचे दिए गए adk deploy cloud_run कमांड की मदद से, एजेंट ऐप्लिकेशन को Cloud Run पर डिप्लॉय करें. अगर आपसे सेवा को बिना पुष्टि वाले अनुरोधों की अनुमति देने के लिए कहा जाता है, तो कृपया फ़िलहाल वैल्यू के तौर पर "y" डालें.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
इससे, Cloud Run में होटल एजेंट ऐप्लिकेशन को डिप्लॉय करने की प्रोसेस शुरू हो जाएगी. यह सोर्स को अपलोड करेगा, उन्हें Docker कंटेनर में पैकेज करेगा, और आर्टफ़ैक्ट रजिस्ट्री में पुश करेगा. इसके बाद, Cloud Run पर सेवा को डिप्लॉय करेगा. इसमें कुछ मिनट लग सकते हैं. इसलिए, कृपया इंतज़ार करें.
आपको नीचे दिए गए मैसेज जैसा मैसेज दिखेगा:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
डिप्लॉयमेंट पूरा होने पर, आपको सेवा के यूआरएल की वैल्यू दी जाएगी. इसके बाद, उस वेब ऐप्लिकेशन को ब्राउज़र में ऐक्सेस किया जा सकता है जिसकी मदद से, होटल एजेंट से चैट की जा सकती है. जैसा कि हमने पहले लोकल सेटअप में देखा था.
9. साफ़-सफ़ाई सेवा
अपने Google Cloud खाते से शुल्क लगने से रोकने के लिए, इस वर्कशॉप के दौरान बनाए गए संसाधनों को मिटाना ज़रूरी है. हम Cloud SQL इंस्टेंस को मिटा देंगे. इसके अलावा, अगर आपने Toolbox और Hotels ऐप्लिकेशन को Cloud Run पर डिप्लॉय किया है, तो हम उन सेवाओं को भी मिटा देंगे.
पक्का करें कि आपके प्रोजेक्ट और इलाके के हिसाब से, यहां दिए गए एनवायरमेंट वैरिएबल सही तरीके से सेट हों:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
नीचे दिए गए दो कमांड, हमारी डिप्लॉय की गई Cloud Run सेवाओं को मिटा देते हैं:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
यह कमांड, Cloud SQL इंस्टेंस को मिटा देता है:
gcloud sql instances delete hoteldb-instance
10. बधाई हो
बधाई हो, आपने एजेंट डेवलपमेंट किट (ADK) का इस्तेमाल करके, एक एजेंट बना लिया है. यह एजेंट, डेटाबेस के लिए एमसीपी टूलबॉक्स का इस्तेमाल करता है.