1. परिचय
इस कोडलैब में, Agent Development Kit (ADK) का इस्तेमाल करके, यात्रा की योजना बनाने वाला एजेंट बनाया जाएगा. साथ ही, उसे Google Maps के साथ इंटिग्रेट किया जाएगा. आपको एजेंट को, सुंदर रास्तों और रेस्टोरेंट के सुझाव जनरेट करने के लिए प्रॉम्प्ट करना होगा. इसके लिए, Google Maps से मिले असल डेटा का इस्तेमाल किया जाएगा.
आपको क्या करना होगा
- एजेंट स्टार्टर पैक का इस्तेमाल करके, एजेंट प्रोजेक्ट शुरू करना
- Google Maps से जानकारी लेने की सुविधा टूल का इस्तेमाल करने के लिए, एजेंट को कॉन्फ़िगर करना
- वेब इंटरफ़ेस की मदद से, जनरेट हुए एजेंट को स्थानीय तौर पर टेस्ट करना
आपको किन चीज़ों की ज़रूरत होगी
- कोई वेब ब्राउज़र, जैसे कि Chrome
- बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट
यह कोडलैब, उन डेवलपर के लिए है जिन्हें Python और Google Cloud के बारे में कुछ जानकारी है, लेकिन वे विशेषज्ञ नहीं हैं.
2. शुरू करने से पहले
Google Cloud प्रोजेक्ट बनाना
- Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
- पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.
Cloud Shell शुरू करना
- पुष्टि करें:
gcloud auth list
- अपने प्रोजेक्ट की पुष्टि करें:
gcloud config get project
- अगर ज़रूरी हो, तो इसे सेट करें:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
एपीआई चालू करें
सभी ज़रूरी एपीआई चालू करने के लिए, यह निर्देश चलाएं:
gcloud services enable \
aiplatform.googleapis.com
3. एजेंट स्टार्टर पैक इंस्टॉल करना
ADK प्रोजेक्ट शुरू करने का सबसे आसान तरीका, एजेंट स्टार्टर पैक का इस्तेमाल करना है. Google Cloud Agent Starter Pack, ओपन-सोर्स कमांड-लाइन इंटरफ़ेस (सीएलआई) टूल है. इसे Google Cloud पर, प्रोडक्शन के लिए तैयार जनरेटिव एआई एजेंट के डेवलपमेंट और डिप्लॉयमेंट को बेहतर बनाने के लिए डिज़ाइन किया गया है.
- पक्का करें कि
uvइंस्टॉल हो गया हो. इसके बाद, नया एजेंट प्रोजेक्ट शुरू करने के लिए, create कमांड चलाएं:
uvx agent-starter-pack create
- जब आपसे पूछा जाए, तो React फ़्रंटएंड के साथ लोकल डेवलपमेंट के लिए अपने प्रोजेक्ट को कॉन्फ़िगर करने के लिए, यहां दिए गए विकल्प चुनें:
- एजेंट टेंप्लेट:
adk(सिंपल रिएक्ट एजेंट) - डिप्लॉयमेंट:
none(फ़िलहाल, क्लाउड डिप्लॉयमेंट की सुविधा बंद है) - रीजन:
us-central1
इससे एक प्रोजेक्ट डायरेक्ट्री स्ट्रक्चर जनरेट होगा. इसमें आपके मुख्य एजेंट का लॉजिक, टेस्ट, और GEMINI.md गाइड शामिल होगी. अपनी नई डायरेक्ट्री पर जाएं:
cd my-agent
4. ग्राउंडिंग की सुविधा कॉन्फ़िगर करना
Agent Starter Pack, GEMINI.md फ़ाइल जनरेट करता है. इसमें एआई की मदद से कोडिंग करने वाले टूल को, आपके प्रोजेक्ट को मैनेज करने के बारे में निर्देश दिए जाते हैं. हम इसे अपडेट करके, Google Maps Grounding के दस्तावेज़ शामिल करेंगे.
- अपने एडिटर में
GEMINI.mdखोलें. ## Reference Documentationसेक्शन में यह रेफ़रंस लिंक जोड़ें:
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
इस कॉन्टेक्स्ट से, एआई की मदद से कोडिंग करने वाले किसी भी असिस्टेंट को, भरोसेमंद सोर्स से जानकारी पाने की सुविधा के बारे में समझने में मदद मिलेगी.
5. एजेंट को अपडेट करना
अब हम एजेंट को यात्रा की योजना बनाने वाले टूल के तौर पर कॉन्फ़िगर करेंगे. इसमें Google Maps Grounding टूल भी शामिल होगा.
app/agent.pyफ़ाइल खोलें.app/agent.pyके पूरे कॉन्टेंट की जगह यह कोड डालें:
"""Agent application for the itinerary planner codelab."""
import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types
# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
# Define the root agent
root_agent = Agent(
name="itinerary_planner_agent",
model=Gemini(
model="gemini-2.5-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=(
"You are an itinerary planner agent. Help users plan their trips by"
" recommending restaurants and scenic routes. Use the"
" google_maps_grounding tool to get both restaurant recommendations and"
" route recommendations based on user preferences. When calling for"
" restaurant recommendation, prompt the tool to tell you about the vibe"
" of the place. When calling for routes with multiple legs, describe"
" each of those legs with a brief sentence. Always describe the key"
" landmarks along the route in one brief sentence."
),
# Add the Google Maps Grounding tool to the agent
tools=[google_maps_grounding],
)
app = App(
root_agent=root_agent,
name="app",
)
यह कोड, gemini-2.5-flash पर आधारित एक ऐसे एजेंट को कॉन्फ़िगर करता है जो जगहों और रास्तों के बारे में मौजूदा जानकारी पाने के लिए, google_maps_grounding टूल का इस्तेमाल करता है.
सभी उपलब्ध मॉडल देखने के लिए, Vertex AI का दस्तावेज़ देखें.
6. एजेंट को चलाना
एजेंट लॉजिक को लागू करने के बाद, इसे अपने लोकल वेब इंटरफ़ेस में आज़माएं.
- वेब ऐप्लिकेशन शुरू करने के लिए, अपनी
my-agentडायरेक्ट्री के रूट से यह कमांड चलाएं:
uv run adk web
इसके अलावा, अगर वर्चुअल एनवायरमेंट का इस्तेमाल किया जा रहा है, तो:
adk web
- टर्मिनल आउटपुट में दिए गए यूआरएल को अपने ब्राउज़र में खोलें.
- एजेंट से कोई सवाल पूछकर, उसे आज़माएं. उदाहरण के लिए:
- "सैन फ़्रांसिस्को में एक दिन की यात्रा के लिए योजना बनाओ. इसमें एक अच्छा इटैलियन रेस्टोरेंट भी शामिल करो."
- "मुझे टोक्यो जाना है. क्या तुम मुझे ऐतिहासिक जगहों और अच्छी रेटिंग वाले ऐसे रामेन रेस्तरां की यात्रा का प्लान दे सकते हो जहां का माहौल आरामदायक हो?"
आपको Google Maps से ली गई, रास्ते की जानकारी और असली समीक्षाओं के साथ, यात्रा की पूरी योजना के जैसा आउटपुट दिखेगा.
7. कोड में ग्राउंडिंग की पुष्टि करना
प्रोग्राम के हिसाब से यह पुष्टि करने के लिए कि आपका एजेंट, Maps के डेटा का इस्तेमाल कर रहा है, Maps से जुड़े मेटाडेटा के लिए जवाब वाले इवेंट की जांच करें.
जब एजेंट को चलाया जाता है (उदाहरण के लिए, टेस्ट स्क्रिप्ट में), तो एजेंट ऐसे इवेंट जनरेट करता है जिनमें grounding_metadata शामिल होता है. इस मेटाडेटा में मौजूद grounding_chunks पर जाकर, maps एट्रिब्यूट की जांच की जा सकती है.
यहां एक उदाहरण दिया गया है, जिसमें maps एट्रिब्यूट की जांच करने का तरीका बताया गया है. यह तरीका, ऑटोमेटेड टेस्ट में इस्तेमाल किए जाने वाले तरीके जैसा ही है:
async for event in runner.run_async(
user_id="test_user",
session_id=session.id,
new_message=content,
):
if event.grounding_metadata:
if event.grounding_metadata.grounding_chunks:
for chunk in event.grounding_metadata.grounding_chunks:
# Check for the maps attribute to confirm maps grounding
if hasattr(chunk, "maps") and chunk.maps:
print("SUCCESS: Maps grounding chunks detected in the response!")
8. कोड में बदली गई पॉलीलाइन एक्सट्रैक्ट करें
ग्राउंडिंग की पुष्टि करने के साथ-साथ, आपको रूट के पाथ जैसे कुछ खास डेटा को एक्सट्रैक्ट करने की ज़रूरत पड़ सकती है. Maps grounding टूल, रास्ते की जानकारी देते समय अक्सर "Encoded Polyline" शामिल करता है. इसका इस्तेमाल, मैप के फ़्रंटएंड पर रास्ते को रेंडर करने के लिए किया जा सकता है.
आपको यह पॉलीलाइन, grounding_chunks के maps एट्रिब्यूट में मौजूद टेक्स्ट को देखकर मिल सकती है. यहां एक उदाहरण दिया गया है कि इसका पता कैसे लगाया जा सकता है:
async for event in runner.run_async(
user_id="test_user",
session_id=session.id,
new_message=content,
):
if event.grounding_metadata:
if event.grounding_metadata.grounding_chunks:
for chunk in event.grounding_metadata.grounding_chunks:
# Extract the encoded polyline from the maps chunk text
if (
hasattr(chunk, "maps")
and chunk.maps
and hasattr(chunk.maps, "text")
and chunk.maps.text
and "Encoded Polyline" in chunk.maps.text
):
print("SUCCESS: Encoded Polyline detected in the response!")
9. व्यवस्थित करें
अपने Google Cloud खाते से लगातार शुल्क लिए जाने से बचने के लिए, इस कोडलैब के दौरान बनाई गई संसाधन मिटाएं.
- अगर आपने इस कोडलैब के लिए कोई प्रोजेक्ट बनाया है, तो उसे पूरी तरह से मिटा दें:
gcloud projects delete $PROJECT_ID
अगर आपने किसी मौजूदा प्रोजेक्ट का इस्तेमाल किया है और आपको उसे बनाए रखना है, तो आपको कोई संसाधन मिटाने की ज़रूरत नहीं है. ऐसा इसलिए, क्योंकि एजेंट स्थानीय तौर पर चलता है और इस्तेमाल किए गए एपीआई सर्वरलेस होते हैं.
10. बधाई हो
बधाई हो! आपने यात्रा का प्लान बनाने वाले एजेंट को बना लिया है और Google Maps की अहम जानकारी का इस्तेमाल करके उसे बेहतर बना लिया है.
आपको क्या सीखने को मिला
- स्मार्ट एआई एजेंट स्टार्टर पैक का इस्तेमाल करके, नया एजेंट बनाने का तरीका
- ADK एजेंट की परिभाषा में ग्राउंडिंग टूल जोड़ने का तरीका
- वेब रनर की सुविधा का इस्तेमाल करके, ADK एजेंट की जांच करने का तरीका
अगले चरण
- ADK टूल और इंटिग्रेशन के अन्य पैटर्न के बारे में जानें