1. परिचय
इस कोडलैब में, ADK की मदद से एक ऐसा एजेंट बनाया जाएगा जो Gemini 3.0 Pro पर काम करता है. एजेंट के पास दो रिमोट (Google-होस्ट किए गए) एमसीपी सर्वर के टूल होंगे. इनकी मदद से, वह जनसांख्यिकी, कीमत, और बिक्री के डेटा के लिए BigQuery को सुरक्षित तरीके से ऐक्सेस कर पाएगा. साथ ही, असल दुनिया की लोकेशन का विश्लेषण और पुष्टि करने के लिए, Google Maps को ऐक्सेस कर पाएगा.
यह एजेंट, उपयोगकर्ता और Google Cloud की सेवाओं के बीच अनुरोधों को व्यवस्थित करता है. इससे, काल्पनिक बेकरी के डेटासेट से जुड़ी कारोबारी समस्याओं को हल किया जा सकता है.
आपको क्या करना होगा
- डेटा सेट अप करना: BigQuery में बेकरी का बुनियादी डेटासेट बनाएं.
- एजेंट डेवलप करना: एजेंट डेवलपमेंट किट (एडीके) का इस्तेमाल करके, एक इंटेलिजेंट एजेंट बनाएं.
- टूल इंटिग्रेट करें: एमसीपी सर्वर के ज़रिए, एजेंट को 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
- एजेंट डायरेक्ट्री पर जाएं:
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.0 Pro की झलक) को तय करने वाला मुख्य लॉजिक है.tools.py: इसमें कस्टम टूल की कोई भी डेफ़िनिशन शामिल होती है..env: इसमें आपके प्रोजेक्ट का कॉन्फ़िगरेशन और सीक्रेट (जैसे, एपीआई पासकोड) शामिल होते हैं. इन्हें सेटअप स्क्रिप्ट से बनाया जाता है.
1. MCP टूलसेट को शुरू करना:
अब, एडिटर में 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 Toolset: यह आपकी एपीआई कुंजी का इस्तेमाल करके, Maps MCP सर्वर से कनेक्शन कॉन्फ़िगर करता है.
- BigQuery टूलसेट: यह फ़ंक्शन, BigQuery MCP सर्वर से कनेक्शन को कॉन्फ़िगर करता है. यह google.auth का इस्तेमाल करके, आपके Cloud क्रेडेंशियल अपने-आप वापस पाता है. साथ ही, OAuth Bearer टोकन जनरेट करता है और उसे Authorization हेडर में डालता है.
2. एजेंट की परिभाषा:
अब एडिटर में adk_agent/mcp_bakery_app/agent.py खोलें और देखें कि एजेंट को कैसे तय किया गया है.
LlmAgent को gemini-3-pro-preview मॉडल के साथ शुरू किया जाता है.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3-pro-preview',
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
सर्वर शुरू होने के बाद, ADK वेब इंटरफ़ेस लॉन्च करने के लिए दिए गए यूआरएल पर क्लिक करके, अपने एजेंट से चैट की जा सकती है.
यहां दिए गए सवाल पूछकर, एजेंट से बातचीत करें. आपको काम के टूल कॉल होते हुए दिखेंगे.
- इलाके के हिसाब से जानकारी ढूंढना (मैक्रो): "मुझे लॉस एंजेलिस में बेकरी खोलनी है. उस पिन कोड का पता लगाओ जहां सुबह के समय सबसे ज़्यादा लोग आते हैं."
एजेंट को BigQuery में foot_traffic टेबल से क्वेरी करने के लिए, get_table_info और execute_sql जैसे टूल का इस्तेमाल करना चाहिए.
- जगह की जानकारी (माइक्रो) की पुष्टि करें: "क्या उस पिन कोड में ‘बेकरी' खोजकर देखा जा सकता है कि वहां पहले से ही बहुत ज़्यादा बेकरी मौजूद हैं?"
इस सवाल का जवाब देने के लिए, एजेंट को Maps के टूलसेट में मौजूद search places टूल का इस्तेमाल करना चाहिए.
इसे आज़माएं! अपने एडीके एजेंट को ऐक्शन में देखने के लिए, इन सैंपल सवालों को देखें:
- "मुझे लॉस एंजेलिस में अपनी चौथी बेकरी खोलनी है. मुझे ऐसा इलाका चाहिए जहां सुबह जल्दी गतिविधियां शुरू हो जाती हों. वह पिन कोड ढूंढो जहां 'सुबह' के समय फ़ुट ट्रैफ़िक स्कोर सबसे ज़्यादा है."
- "क्या उस पिन कोड में ‘बेकरी' की खोज करके यह पता लगाया जा सकता है कि वहां पहले से ही बहुत सारी बेकरी हैं? अगर बहुत ज़्यादा कॉफ़ी शॉप हैं, तो 'स्पेशलिटी कॉफ़ी' शॉप खोजो, ताकि मैं फ़ुट ट्रैफ़िक कैप्चर करने के लिए, उनके आस-पास खुद को पोज़िशन कर सकूं."
- "ठीक है और मुझे इसे एक प्रीमियम ब्रैंड के तौर पर पेश करना है. लॉस ऐंजेलिस मेट्रो इलाके में, ‘खट्टे आटे से बनी रोटी' के लिए ज़्यादा से ज़्यादा कितना शुल्क लिया जा रहा है?"
- "अब मुझे दिसंबर 2025 के लिए रेवेन्यू का अनुमान चाहिए. मेरी बिक्री का इतिहास देखो और ‘खट्टा मीठा ब्रेड' के लिए, सबसे अच्छा परफ़ॉर्म करने वाले स्टोर का डेटा इस्तेमाल करो. दिसंबर 2025 के लिए, बिक्री का अनुमान लगाने वाला पूर्वानुमान चलाओ, ताकि मुझे पता चल सके कि मेरे प्रॉडक्ट की कितनी यूनिट बिकेंगी. इसके बाद, प्रीमियम वर्शन के लिए तय की गई कीमत से थोड़ी कम कीमत (मान लें कि 18 डॉलर) का इस्तेमाल करके, अनुमानित कुल रेवेन्यू का हिसाब लगाओ"
- "इससे मेरा किराया चुकाया जा सकेगा. आखिर में, लॉजिस्टिक्स की पुष्टि करें. सुझाई गई जगह के सबसे नज़दीकी "Restaurant Depot" का पता लगाएं. साथ ही, यह पक्का करें कि रोज़ाना सामान भरने के लिए, वहां तक पहुंचने में 30 मिनट से ज़्यादा समय न लगे."
8. क्लीन अप करें
अपने Google Cloud खाते से शुल्क लिए जाने से बचने के लिए, इस Codelab के दौरान बनाई गई संसाधन मिटाएं.
क्लीनअप स्क्रिप्ट चलाएं. यह स्क्रिप्ट, BigQuery डेटासेट, Cloud Storage बकेट, और सेटअप के दौरान बनाए गए एपीआई पासकोड को मिटा देगी.
chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh
9. बधाई हो
मिशन पूरा हुआ! आपने एजेंट डेवलपमेंट किट (एडीके) का इस्तेमाल करके, लोकेशन इंटेलिजेंस एजेंट बना लिया है.
आपने BigQuery में मौजूद "एंटरप्राइज़" डेटा और Google Maps से मिले लोकेशन के असल डेटा को मिलाकर एक ऐसा टूल बनाया है जो कारोबार से जुड़ी मुश्किल समस्याओं को हल कर सकता है. यह टूल, मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) और Gemini की मदद से काम करता है.
आपको क्या मिला:
- इंफ़्रास्ट्रक्चर ऐज़ कोड: आपने Google Cloud CLI टूल का इस्तेमाल करके, डेटा स्टैक उपलब्ध कराया है.
- एमसीपी इंटिग्रेशन: आपने किसी एआई एजेंट को दो अलग-अलग रिमोट एमसीपी सर्वर (BigQuery और Maps) से कनेक्ट किया है. इसके लिए, आपको मुश्किल एपीआई रैपर लिखने की ज़रूरत नहीं पड़ी.
- एक साथ कई तरह की जानकारी का इस्तेमाल करना: आपने एक ऐसा एजेंट बनाया है जो कारोबार से जुड़ी किसी समस्या को हल करने के लिए, दो अलग-अलग डोमेन से मिली अहम जानकारी को रणनीतिक तरीके से जोड़ सकता है.