1. परिचय
इस कोडलैब में, ADK की मदद से एक ऐसा एजेंट बनाया जाएगा जो Gemini 3.1 Pro पर काम करता है. एजेंट के पास दो रिमोट (Google के होस्ट किए गए) MCP सर्वर के टूल होंगे. इनकी मदद से, वह जनसांख्यिकी, कीमत, और बिक्री के डेटा के लिए 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==1.28.0
- एजेंट डायरेक्ट्री पर जाएं:
cd adk_agent/
6. ADK ऐप्लिकेशन की जांच करना
Cloud Shell Editor खोलने के लिए, Cloud Shell में Open Editor बटन पर क्लिक करें. इसके बाद, 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.1 Pro Preview) को तय करने वाला मुख्य लॉजिक है.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 server से कनेक्शन कॉन्फ़िगर करता है.
- BigQuery टूलसेट: यह फ़ंक्शन, BigQuery MCP सर्वर से कनेक्शन को कॉन्फ़िगर करता है. यह google.auth का इस्तेमाल करके, आपके Cloud क्रेडेंशियल अपने-आप वापस पाता है. साथ ही, OAuth Bearer टोकन जनरेट करता है और उसे Authorization हेडर में डालता है.
2. एजेंट की परिभाषा:
अब एडिटर में adk_agent/mcp_bakery_app/agent.py खोलें और देखें कि एजेंट को कैसे तय किया गया है.
LlmAgent को gemini-3.1-pro-preview मॉडल के साथ शुरू किया जाता है.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3.1-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 --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 टूल का इस्तेमाल करना चाहिए.
इसे आज़माएं! अपने एडीके एजेंट को ऐक्शन में देखने के लिए, इन सैंपल सवालों को देखें:
- "मुझे लॉस एंजेलिस में अपनी चौथी बेकरी खोलनी है. मुझे ऐसे इलाके में घर चाहिए जहां सुबह जल्दी गतिविधियां शुरू हो जाती हैं. वह पिन कोड ढूंढो जहां 'सुबह' के समय फ़ुट ट्रैफ़िक का स्कोर सबसे ज़्यादा है."
- "क्या उस पिन कोड में ‘बेकरी' की खोज की जा सकती है, ताकि यह पता चल सके कि वहां पहले से ही बहुत सारी बेकरी हैं या नहीं? अगर बहुत ज़्यादा कॉफ़ी शॉप हैं, तो ‘स्पेशलिटी कॉफ़ी' शॉप खोजो, ताकि मैं उनके आस-पास अपनी दुकान लगा सकूं और ज़्यादा लोगों को अपनी दुकान पर ला सकूं."
- "ठीक है और मुझे इसे एक प्रीमियम ब्रैंड के तौर पर पेश करना है. लॉस ऐंजेलिस मेट्रो इलाके में, ‘खट्टी रोटी' के लिए ज़्यादा से ज़्यादा कितना शुल्क लिया जा रहा है?"
- "अब मुझे दिसंबर 2025 के लिए रेवेन्यू का अनुमान चाहिए. मेरी बिक्री का इतिहास देखो और ‘खट्टा पाव' के लिए, सबसे अच्छा परफ़ॉर्म करने वाले स्टोर का डेटा इस्तेमाल करो. दिसंबर 2025 के लिए अनुमान चलाओ, ताकि मुझे पता चल सके कि मेरे कितने प्रॉडक्ट बिकेंगे. इसके बाद, हमने जो प्रीमियम कीमत पता लगाई है उससे थोड़ी कम कीमत (मान लें कि 18 डॉलर) का इस्तेमाल करके, अनुमानित कुल रेवेन्यू का हिसाब लगाओ"
- "इससे मेरा किराया चुकाया जा सकेगा. आखिर में, लॉजिस्टिक्स की पुष्टि करते हैं. सुझाई गई जगह के सबसे नज़दीकी "Restaurant Depot" का पता लगाएं. साथ ही, यह पक्का करें कि रोज़ाना सामान भरने के लिए, वहां पहुंचने में 30 मिनट से ज़्यादा समय न लगे."
एजेंट की जांच पूरी होने के बाद, Cloud Shell टर्मिनल में Ctrl+C दबाकर, ADK के वेब इंटरफ़ेस को बंद किया जा सकता है.
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) से कनेक्ट किया.
- यूनिफ़ाइड रीज़निंग: आपने एक ऐसा एजेंट बनाया है जो कारोबार से जुड़ी समस्या को हल करने के लिए, दो अलग-अलग डोमेन से मिली अहम जानकारी को रणनीतिक तरीके से जोड़ सकता है.