1. परिचय
इस कोडलैब में, ADK की मदद से एक एजेंट बनाया जाएगा. यह एजेंट, Gemini 3.5 Flash पर काम करता है. इस एजेंट में, दो रिमोट (Google से होस्ट किए गए) एमसीपी सर्वर के टूल शामिल होंगे. इनकी मदद से, जनसांख्यिकी, कीमत, और बिक्री के डेटा के लिए BigQuery को सुरक्षित तरीके से ऐक्सेस किया जा सकेगा. साथ ही, असल दुनिया की लोकेशन का विश्लेषण और पुष्टि करने के लिए, Google Maps को ऐक्सेस किया जा सकेगा.
यह एजेंट, काल्पनिक बेकरी के डेटासेट से जुड़ी कारोबार की समस्याओं को हल करने के लिए, उपयोगकर्ता और Google Cloud की सेवाओं के बीच अनुरोधों को व्यवस्थित करता है.
आप क्या करेंगे
- डेटा सेट अप करना: BigQuery में, बेकरी का बुनियादी डेटासेट बनाना.
- एजेंट डेवलप करना: Agent Development Kit (ADK) का इस्तेमाल करके, एक इंटेलिजेंट एजेंट बनाना.
- टूल इंटिग्रेट करना: एमसीपी सर्वर के ज़रिए, एजेंट में BigQuery और Maps की सुविधाएं जोड़ना.
- मार्केट का विश्लेषण करना: मार्केट के ट्रेंड और सैचुरेशन का आकलन करने के लिए, एजेंट के साथ इंटरैक्ट करना.
आपको क्या चाहिए
- Chrome जैसा वेब ब्राउज़र
- बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट या Gmail खाता.
यह कोडलैब, सभी लेवल के डेवलपर के लिए है. इसमें शुरुआती डेवलपर भी शामिल हैं. इसमें, ADK डेवलपमेंट के लिए, Google Cloud Shell में कमांड-लाइन इंटरफ़ेस और Python कोड का इस्तेमाल किया जाएगा. इसके लिए, Python के विशेषज्ञ होने की ज़रूरत नहीं है. हालांकि, कोड पढ़ने की बुनियादी जानकारी होने से, आपको कॉन्सेप्ट समझने में मदद मिलेगी.
2. शुरू करने से पहले
Google Cloud प्रोजेक्ट बनाएं
- Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर जाकर, कोई Google Cloud प्रोजेक्ट चुनें या बनाएं.
- पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. यह देखने का तरीका जानें कि किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं.
Cloud Shell शुरू करना
Cloud Shell , Google Cloud में चलने वाला कमांड-लाइन एनवायरमेंट है. इसमें ज़रूरी टूल पहले से लोड होते हैं.
- Google Cloud Console में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें:
- Cloud Shell से कनेक्ट होने के बाद, Cloud Shell में अपनी पुष्टि करने के लिए, यह कमांड चलाएं:
gcloud auth list
- यह पुष्टि करने के लिए कि आपका प्रोजेक्ट, gcloud के साथ इस्तेमाल करने के लिए कॉन्फ़िगर किया गया है, यह कमांड चलाएं:
gcloud config get project
- पुष्टि करें कि प्रोजेक्ट आपकी उम्मीद के मुताबिक है. इसके बाद, अपना प्रोजेक्ट आईडी सेट करने के लिए, यह कमांड चलाएं:
export PROJECT_ID=$(gcloud config get project)
3. कोड पाएं
रेपो का क्लोन बनाना
- रेपो का क्लोन बनाकर, उसे अपने Cloud Shell एनवायरमेंट में सेव करें:
git clone https://github.com/google/mcp.git
- डेमो डायरेक्ट्री पर जाएं:
cd mcp/examples/launchmybakery
पुष्टि करना
अपने Google Cloud खाते से पुष्टि करने के लिए, यह कमांड चलाएं. ADK को BigQuery ऐक्सेस करने के लिए, यह ज़रूरी है.
gcloud auth application-default login
पुष्टि की प्रोसेस पूरी करने के लिए, निर्देशों का पालन करें.
4. एनवायरमेंट और BigQuery को कॉन्फ़िगर करना
सेटअप स्क्रिप्ट चलाना
- एनवायरमेंट सेटअप स्क्रिप्ट चलाएं. इस स्क्रिप्ट से, BigQuery और Google Maps API चालू होते हैं. साथ ही, आपके प्रोजेक्ट आईडी और Maps API पासकोड के साथ एक
.envफ़ाइल बनती है.
chmod +x setup/setup_env.sh
./setup/setup_env.sh
- BigQuery सेटअप स्क्रिप्ट चलाएं. इस स्क्रिप्ट से, Cloud Storage बकेट बनाने, डेटा अपलोड करने, और BigQuery डेटासेट और टेबल उपलब्ध कराने की प्रोसेस अपने-आप पूरी हो जाती है.
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh
स्क्रिप्ट पूरी होने के बाद, mcp_bakery डेटासेट बन जाना चाहिए. साथ ही, इसमें ये टेबल मौजूद होनी चाहिए:
- जनसांख्यिकी - जनगणना का डेटा और पिन कोड के हिसाब से जनसंख्या की विशेषताएं.
- bakery_prices - अलग-अलग बेकरी प्रॉडक्ट के लिए, प्रतिस्पर्धियों की कीमतें और प्रॉडक्ट की जानकारी.
- sales_history_weekly - हर हफ़्ते की बिक्री की परफ़ॉर्मेंस (संख्या और रेवेन्यू), स्टोर और प्रॉडक्ट के हिसाब से.
- foot_traffic - पिन कोड और दिन के समय के हिसाब से, स्टोर या कारोबार की जगह पर आने वाले लोगों की संख्या का अनुमान.
- अपने Google Cloud प्रोजेक्ट में **BigQuery कंसोल** पर जाकर, पुष्टि करें कि डेटासेट और टेबल बन गई हैं या नहीं:
5. ADK इंस्टॉल करना
अब जब इन्फ़्रास्ट्रक्चर तैयार है, तो चलिए एक वर्चुअल Python एनवायरमेंट बनाते हैं और ADK के लिए ज़रूरी पैकेज इंस्टॉल करते हैं.
- वर्चुअल एनवायरमेंट बनाएं:
python3 -m venv .venv
- वर्चुअल एनवायरमेंट चालू करें:
source .venv/bin/activate
- ADK इंस्टॉल करें:
pip install "google-adk[mcp]"
- एजेंट डायरेक्ट्री पर जाएं:
cd adk_agent/
6. ADK ऐप्लिकेशन की जांच करना
Cloud Shell Editor खोलने के लिए, Cloud Shell में एडिटर खोलें बटन पर क्लिक करें. इसके बाद, mcp/examples/launchmybakery डायरेक्ट्री में क्लोन किया गया रेपो देखें.
एजेंट का कोड, adk_agent/ डायरेक्ट्री में पहले से मौजूद है. आइए, सलूशन स्ट्रक्चर के बारे में जानते हैं:
launchmybakery/
├── data/ # Pre-generated CSV files for BigQuery
├── adk_agent/ # AI Agent Application (ADK)
│ └── mcp_bakery_app/ # App directory
│ ├── agent.py # Agent definition
│ ├── tools.py # Custom tools for the agent
│ └── .env # Project configuration (created by setup script)
├── setup/ # Infrastructure setup scripts
└── cleanup/ # Infrastructure cleanup scripts
mcp_bakery_app में मौजूद मुख्य फ़ाइलें:
agent.py: एजेंट, उसके टूल, और मॉडल (Gemini 3.5 Flash) को तय करने वाली मुख्य लॉजिक फ़ाइल.tools.py: इसमें, कस्टम टूल की परिभाषाएं शामिल होती हैं..env: इसमें, सेटअप स्क्रिप्ट से बनाया गया आपका प्रोजेक्ट कॉन्फ़िगरेशन और सीक्रेट (जैसे, एपीआई पासकोड) शामिल होते हैं.
1. एमसीपी टूलसेट को शुरू करना:
अब, एमसीपी टूलसेट को शुरू करने का तरीका समझने के लिए, एडिटर में adk_agent/mcp_bakery_app/tools.py खोलें.
अपने एजेंट को BigQuery और Google Maps से कम्यूनिकेट करने की अनुमति देने के लिए, हमें मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) क्लाइंट को कॉन्फ़िगर करना होगा.
कोड, StreamableHTTPConnectionParams का इस्तेमाल करके, Google के रिमोट एमसीपी सर्वर से सुरक्षित कनेक्शन बनाता है.
def get_maps_mcp_toolset():
dotenv.load_dotenv()
maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=MAPS_MCP_URL,
headers={
"X-Goog-Api-Key": maps_api_key
}
)
)
print("MCP Toolset configured for Streamable HTTP connection.")
return tools
def get_bigquery_mcp_toolset():
credentials, project_id = google.auth.default(
scopes=["https://www.googleapis.com/auth/bigquery"]
)
credentials.refresh(google.auth.transport.requests.Request())
oauth_token = credentials.token
HEADERS_WITH_OAUTH = {
"Authorization": f"Bearer {oauth_token}",
"x-goog-user-project": project_id
}
tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=BIGQUERY_MCP_URL,
headers=HEADERS_WITH_OAUTH
)
)
print("MCP Toolset configured for Streamable HTTP connection.")
return tools
- Maps टूलसेट: यह आपके एपीआई पासकोड का इस्तेमाल करके, Maps एमसीपी सर्वर से कनेक्शन कॉन्फ़िगर करता है.
- BigQuery टूलसेट: यह फ़ंक्शन, BigQuery एमसीपी सर्वर से कनेक्शन कॉन्फ़िगर करता है. यह आपके Cloud क्रेडेंशियल को अपने-आप वापस पाने के लिए, google.auth का इस्तेमाल करता है. साथ ही, OAuth Bearer टोकन जनरेट करता है और उसे Authorization हेडर में डालता है.
2. एजेंट की परिभाषा:
अब, एजेंट को कैसे तय किया जाता है, यह देखने के लिए, एडिटर में adk_agent/mcp_bakery_app/agent.py खोलें.
LlmAgent को gemini-3.5-flash मॉडल के साथ शुरू किया जाता है.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3.5-flash',
name='root_agent',
instruction=f"""
Help the user answer questions by strategically combining insights from two sources:
1. **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the mcp_bakery dataset. Do not use any other dataset.
Run all query jobs from project id: {project_id}.
2. **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
Include a hyperlink to an interactive map in your response where appropriate.
""",
tools=[maps_toolset, bigquery_toolset]
)
- सिस्टम के निर्देश: एजेंट को खास निर्देश दिए जाते हैं, ताकि वह BigQuery (डेटा के लिए) और Maps (लोकेशन के विश्लेषण के लिए) से मिली अहम जानकारी को एक साथ इस्तेमाल कर सके.
- टूल: एजेंट को
maps_toolsetऔरbigquery_toolset, दोनों असाइन किए जाते हैं. इससे एजेंट को, दोनों सेवाओं की क्षमताओं का ऐक्सेस मिल जाता है.
एजेंट, रेपो में तय किए गए निर्देशों और टूल के मुताबिक काम करता है. निर्देशों में बदलाव करके देखें कि इससे एजेंट के व्यवहार पर क्या असर पड़ता है.
7. अपने एजेंट से चैट करें!
Cloud Shell में टर्मिनल पर वापस जाएं और adk_agent डायरेक्ट्री पर जाने के लिए, यह कमांड चलाएं. अगर आपने यह पहले ही कर लिया है, तो इस चरण को छोड़ दें:
cd adk_agent/
ADK के वेब इंटरफ़ेस को शुरू करने के लिए, यह कमांड चलाएं. यह कमांड, चैट ऐप्लिकेशन को होस्ट करने के लिए, एक हल्का वेब सर्वर शुरू करता है:
adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
सर्वर शुरू होने के बाद, आपको Cloud Shell में यह दिखेगा:
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
ADK यूज़र इंटरफ़ेस (यूआई) को ऐक्सेस करने के लिए, आपके पास दो विकल्प हैं:
पहला विकल्प: लोकल लिंक पर क्लिक करना अपने Cloud Shell टर्मिनल में दिखने वाले http://127.0.0.1:8000 लिंक पर क्लिक करें.
दूसरा विकल्प: वेब की झलक देखें सुविधा का इस्तेमाल करना
- Cloud Shell में सबसे ऊपर दाएं कोने में मौजूद, वेब की झलक देखें बटन पर क्लिक करें.
- पोर्ट बदलें को चुनें.
- पोर्ट नंबर के तौर पर 8000 डालें और बदलें और झलक देखें पर क्लिक करें.
वेब यूआई में ये सवाल पूछकर, एजेंट के साथ इंटरैक्ट करें. आपको दिखना चाहिए कि काम के टूल कॉल किए जा रहे हैं.
- आस-पास का इलाका ढूंढना (मैक्रो): "मुझे दिल्ली में एक बेकरी खोलनी है. ऐसा पिन कोड ढूंढें जहां सुबह के समय, पैदल आने-जाने वाले लोगों की संख्या सबसे ज़्यादा हो."
एजेंट को BigQuery में foot_traffic टेबल के लिए क्वेरी करने के लिए, get_table_info और execute_sql जैसे टूल का इस्तेमाल करना चाहिए.
- लोकेशन की पुष्टि करना (माइक्रो): "क्या आप उस पिन कोड में 'बेकरी' खोजकर बता सकते हैं कि वहां पहले से कितनी बेकरी मौजूद हैं?"
इस सवाल का जवाब देने के लिए, एजेंट को Maps टूलसेट में मौजूद search places टूल का इस्तेमाल करना चाहिए.
इसे आज़माएं! अपने ADK एजेंट को ऐक्शन में देखने के लिए, ये सैंपल सवाल देखें:
- "मुझे दिल्ली में अपनी चौथी बेकरी खोलनी है. मुझे ऐसा इलाका चाहिए जहां सुबह के समय ज़्यादा गतिविधि होती हो. ऐसा पिन कोड ढूंढें जहां 'सुबह' के समय, स्टोर या कारोबार की जगह पर आने वाले लोगों की संख्या सबसे ज़्यादा हो.
- "क्या आप उस पिन कोड में 'बेकरी' खोजकर बता सकते हैं कि वहां पहले से कितनी बेकरी मौजूद हैं? अगर वहां बहुत ज़्यादा बेकरी हैं, तो 'स्पेशलिटी कॉफ़ी' की दुकानें ढूंढें, ताकि मैं उनके आस-पास अपनी बेकरी खोल सकूं और पैदल आने-जाने वाले लोगों को अपनी ओर खींच सकूं."
- "ठीक है. मुझे इसे एक प्रीमियम ब्रैंड के तौर पर लॉन्च करना है. दिल्ली मेट्रो इलाके में, 'खट्टी रोटी' के लिए ज़्यादा से ज़्यादा कितनी कीमत ली जा रही है?"
- "अब मुझे दिसंबर 2025 के लिए रेवेन्यू का अनुमान चाहिए. मेरी बिक्री के इतिहास को देखें और 'खट्टी रोटी' के लिए, मेरे सबसे अच्छा परफ़ॉर्म करने वाले स्टोर का डेटा लें. दिसंबर 2025 के लिए अनुमान लगाएं, ताकि यह पता चल सके कि मैं कितनी मात्रा में बिक्री कर पाऊंगा. इसके बाद, प्रीमियम कीमत से थोड़ी कम कीमत (मान लें कि 18 डॉलर) का इस्तेमाल करके, अनुमानित कुल रेवेन्यू का हिसाब लगाएं."
- "इससे मेरा किराया निकल जाएगा. आखिर में, लॉजिस्टिक्स की पुष्टि करते हैं. प्रस्तावित इलाके के सबसे पास मौजूद "Restaurant Depot" ढूंढें और पक्का करें कि रोज़ाना सामान की रीस्टॉकिंग के लिए, वहां तक ड्राइव करने में 30 मिनट से कम समय लगता हो."
अपने एजेंट की जांच पूरी करने के बाद, Cloud Shell टर्मिनल में Ctrl+C दबाकर, ADK के वेब इंटरफ़ेस को बंद किया जा सकता है.
8. स्टोरेज में जगह बनाएं
अपने Google Cloud खाते पर लगने वाले शुल्क से बचने के लिए, इस कोडलैब के दौरान बनाए गए संसाधन मिटाएं.
क्लीनअप स्क्रिप्ट चलाएं. इस स्क्रिप्ट से, सेटअप के दौरान बनाया गया BigQuery डेटासेट, Cloud Storage बकेट, और एपीआई पासकोड मिट जाएंगे.
chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh
9. बधाई हो
मिशन पूरा हुआ! आपने Agent Development Kit (ADK) का इस्तेमाल करके, लोकेशन इंटेलिजेंस एजेंट बना लिया है.
आपने BigQuery में मौजूद "एंटरप्राइज़" डेटा और Google Maps से मिले असल दुनिया की लोकेशन के कॉन्टेक्स्ट के बीच का अंतर खत्म करके, एक ऐसा दमदार टूल बनाया है जो कारोबार से जुड़े मुश्किल सवालों के जवाब दे सकता है. यह टूल, मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) और Gemini की मदद से काम करता है.
आपने क्या हासिल किया:
- कोड के तौर पर इन्फ़्रास्ट्रक्चर: आपने Google Cloud CLI टूल का इस्तेमाल करके, डेटा स्टैक उपलब्ध कराया.
- एमसीपी इंटिग्रेशन: आपने एआई एजेंट को दो अलग-अलग रिमोट एमसीपी सर्वर (BigQuery और Maps) से कनेक्ट किया. इसके लिए, आपको मुश्किल एपीआई रैपर लिखने की ज़रूरत नहीं पड़ी.
- एक ही जगह से जवाब देना: आपने एक ऐसा एजेंट बनाया है जो कारोबार की किसी समस्या को हल करने के लिए, दो अलग-अलग डोमेन से मिली अहम जानकारी को रणनीतिक तरीके से एक साथ इस्तेमाल कर सकता है.
रेफ़रंस के लिए दस्तावेज़
- BigQuery एमसीपी सर्वर का इस्तेमाल करना
- Maps Groundling Lite एमसीपी सर्वर का इस्तेमाल करना
- Gemini Enterprise Agent Ready (GEAR) की मदद से, एंटरप्राइज़-ग्रेड के एजेंट बनाने और उन्हें डिप्लॉय करने के लिए, सीखने के संसाधन एक्सप्लोर करना.