ADK এবং গুগল ম্যাপস গ্রাউন্ডিং-এর সাহায্যে একটি ভ্রমণসূচী পরিকল্পনা এজেন্ট তৈরি করুন।

১. ভূমিকা

এই কোডল্যাবে, আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে এবং গুগল ম্যাপসের উপর ভিত্তি করে একটি ট্রিপ প্ল্যানিং এজেন্ট তৈরি করবেন। আপনি গুগল ম্যাপস থেকে প্রাপ্ত বাস্তব ডেটা কাজে লাগিয়ে এজেন্টটিকে মনোরম পথ এবং রেস্তোরাঁর সুপারিশ তৈরি করতে নির্দেশ দেবেন ।

আপনি যা করবেন

• এজেন্ট স্টার্টার প্যাক ব্যবহার করে একটি এজেন্ট প্রজেক্ট শুরু করুন।
• এজেন্টকে গুগল ম্যাপস গ্রাউন্ডিং টুল ব্যবহার করার জন্য কনফিগার করুন।
• ওয়েব ইন্টারফেস ব্যবহার করে স্থানীয়ভাবে প্রাপ্ত এজেন্টটি পরীক্ষা করুন।

আপনার যা যা লাগবে

• ক্রোমের মতো একটি ওয়েব ব্রাউজার
• বিলিং সক্ষম একটি গুগল ক্লাউড প্রজেক্ট

এই কোডল্যাবটি মধ্যবর্তী স্তরের ডেভেলপারদের জন্য, যাদের পাইথন এবং গুগল ক্লাউড সম্পর্কে কিছুটা ধারণা আছে, কিন্তু তাঁরা বিশেষজ্ঞ নন।

২. শুরু করার আগে

একটি গুগল ক্লাউড প্রজেক্ট তৈরি করুন

1. গুগল ক্লাউড কনসোলের প্রজেক্ট সিলেক্টর পেজে, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন ।
2. আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং চালু আছে কিনা তা নিশ্চিত করুন। কোনো প্রোজেক্টে বিলিং চালু আছে কিনা তা কীভাবে পরীক্ষা করবেন, তা জেনে নিন।

ক্লাউড শেল শুরু করুন

1. প্রমাণীকরণ যাচাই করুন:

gcloud auth list

2. আপনার প্রকল্পটি নিশ্চিত করুন:

gcloud config get project

3. প্রয়োজনে সেট করুন:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

এপিআই সক্ষম করুন

প্রয়োজনীয় সকল API সক্রিয় করতে এই কমান্ডটি চালান:

gcloud services enable \
  aiplatform.googleapis.com

৩. এজেন্ট স্টার্টার প্যাকটি ইনস্টল করুন

একটি ADK প্রোজেক্ট শুরু করার সবচেয়ে সহজ উপায় হলো এজেন্ট স্টার্টার প্যাক ব্যবহার করা। গুগল ক্লাউড এজেন্ট স্টার্টার প্যাক হলো একটি ওপেন-সোর্স কমান্ড-লাইন ইন্টারফেস (CLI) টুল, যা গুগল ক্লাউডে প্রোডাকশন-রেডি জেনারেটিভ এআই এজেন্টগুলোর উন্নয়ন এবং স্থাপন প্রক্রিয়াকে ত্বরান্বিত করার জন্য ডিজাইন করা হয়েছে।

1. uv ইনস্টল করা আছে কিনা তা নিশ্চিত করুন, তারপর একটি নতুন এজেন্ট প্রজেক্ট শুরু করতে create কমান্ডটি চালান:

uvx agent-starter-pack create

যদি আপনার uv ইনস্টল করা না থাকে, তাহলে আপনি pip ব্যবহার করতে পারেন:

# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create

আরও বিস্তারিত তথ্যের জন্য agent-starter-pack রিপোজিটরিটি দেখুন।

2. অনুরোধ করা হলে, React ফ্রন্টএন্ড সহ স্থানীয় ডেভেলপমেন্টের জন্য আপনার প্রজেক্ট কনফিগার করতে নিম্নলিখিত অপশনগুলো প্রদান করুন:

• এজেন্ট টেমপ্লেট : adk (সাধারণ রিঅ্যাক্ট এজেন্ট)
• ডেপ্লয়মেন্ট : none (ক্লাউড ডেপ্লয়মেন্ট আপাতত নিষ্ক্রিয়)
• অঞ্চল : us-central1

এটি একটি প্রজেক্ট ডিরেক্টরি কাঠামো তৈরি করবে, যেখানে আপনার মূল এজেন্ট লজিক, টেস্ট এবং একটি GEMINI.md গাইড থাকবে। আপনার নতুন ডিরেক্টরিতে প্রবেশ করুন:

cd my-agent

৪. গ্রাউন্ডিং কনফিগার করুন

এজেন্ট স্টার্টার প্যাকটি একটি GEMINI.md ফাইল তৈরি করে, যা আপনার প্রজেক্ট কীভাবে পরিচালনা করতে হবে সে বিষয়ে এআই-সহায়তাযুক্ত কোডিং টুলগুলোকে নির্দেশনা দেয়। আমরা এতে গুগল ম্যাপস গ্রাউন্ডিং ডকুমেন্টেশন অন্তর্ভুক্ত করার জন্য এটি আপডেট করব।

1. আপনার এডিটরে GEMINI.md খুলুন।
2. ## Reference Documentation বিভাগের অধীনে নিম্নলিখিত রেফারেন্স লিঙ্কটি যোগ করুন:

- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

এই প্রেক্ষাপটটি যেকোনো এআই কোডিং সহকারীকে মূল বৈশিষ্ট্যটি বুঝতে সাহায্য করবে।

৫. এজেন্ট আপডেট করুন

এখন আমরা এজেন্টটিকে একটি ভ্রমণপথ পরিকল্পনাকারী হিসেবে কনফিগার করব, যার সাথে গুগল ম্যাপস গ্রাউন্ডিং টুলও থাকবে।

1. app/agent.py ফাইলটি খুলুন।
2. 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 ডকুমেন্টেশন দেখুন।

৬. এজেন্টটি চালান

আপনার এজেন্ট লজিক তৈরি হয়ে গেলে, আপনার স্থানীয় ওয়েব ইন্টারফেসে এটি পরীক্ষা করে দেখুন।

1. আপনার my-agent ডিরেক্টরির রুট থেকে, ওয়েব অ্যাপটি চালু করতে নিম্নলিখিত কমান্ডটি চালান:

uv run adk web

অথবা, ভার্চুয়াল পরিবেশ ব্যবহার করলে:

adk web

2. টার্মিনাল আউটপুটে দেওয়া URL-টি আপনার ব্রাউজারে খুলুন।
3. এজেন্টটিকে একটি প্রশ্ন জিজ্ঞাসা করে পরীক্ষা করুন। উদাহরণস্বরূপ:

• সান ফ্রান্সিসকোতে একটি ভালো ইতালীয় রেস্তোরাঁসহ একদিনের ভ্রমণসূচি পরিকল্পনা করুন।
• আমি টোকিও যাচ্ছি, আপনি কি আমাকে আকর্ষণীয় ঐতিহাসিক স্থান এবং আরামদায়ক পরিবেশের একটি উচ্চ রেটিং প্রাপ্ত রামেন রেস্তোরাঁর তালিকা সহ একটি ভ্রমণসূচী দিতে পারবেন?

আপনি এমন একটি আউটপুট দেখতে পাবেন যা বাস্তব পর্যালোচনা এবং সরাসরি গুগল ম্যাপস থেকে নেওয়া পথের বিবরণ দ্বারা সমৃদ্ধ একটি বিশদ ভ্রমণসূচীর অনুরূপ।

৭. কোডে গ্রাউন্ডিং যাচাই করুন

আপনার এজেন্ট সফলভাবে ম্যাপস গ্রাউন্ডিং ব্যবহার করছে কিনা, তা প্রোগ্রাম্যাটিকভাবে নিশ্চিত করতে আপনি রেসপন্স ইভেন্টগুলোতে ম্যাপস-নির্দিষ্ট মেটাডেটা পরীক্ষা করতে পারেন।

যখন আপনি আপনার এজেন্ট চালান (উদাহরণস্বরূপ, একটি টেস্ট স্ক্রিপ্টে), তখন এজেন্টটি এমন ইভেন্ট তৈরি করে যেগুলিতে 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!")

৮. এনকোডেড পলিলাইনগুলো নিষ্কাশন করুন

গ্রাউন্ডিং ঘটেছে কিনা তা যাচাই করার পাশাপাশি, আপনি রুটের পথের মতো নির্দিষ্ট ডেটাও বের করতে চাইতে পারেন। যখন ম্যাপস গ্রাউন্ডিং টুল রুটের তথ্য ফেরত দেয়, তখন এতে প্রায়শই একটি "এনকোডেড পলিলাইন" অন্তর্ভুক্ত থাকে, যা ম্যাপ ফ্রন্টএন্ডে রুটটি রেন্ডার করতে ব্যবহার করা যেতে পারে।

আপনি 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!")

৯. পরিষ্কার করুন

আপনার গুগল ক্লাউড অ্যাকাউন্টে চলমান চার্জ এড়াতে, এই কোডল্যাব চলাকালীন তৈরি করা রিসোর্সগুলো মুছে ফেলুন।

1. আপনি যদি এই কোডল্যাবের জন্য একটি বিশেষ প্রজেক্ট তৈরি করে থাকেন, তবে সেটি সম্পূর্ণভাবে মুছে ফেলুন:

gcloud projects delete $PROJECT_ID

আপনি যদি কোনো বিদ্যমান প্রজেক্ট ব্যবহার করে থাকেন এবং সেটি রাখতে চান, তাহলে আপনার নির্দিষ্ট কোনো রিসোর্স মুছে ফেলার প্রয়োজন নেই, কারণ এজেন্টটি স্থানীয়ভাবে চলেছে এবং ব্যবহৃত এপিআইগুলো সার্ভারবিহীন।

১০. অভিনন্দন

অভিনন্দন! আপনি সফলভাবে একটি ভ্রমণসূচী পরিকল্পনাকারী এজেন্ট তৈরি করেছেন এবং গুগল ম্যাপস ইনসাইটস ব্যবহার করে এটিকে কার্যকর করেছেন।

আপনি যা শিখেছেন

• এজেন্ট স্টার্টার প্যাক ব্যবহার করে কীভাবে একটি নতুন এজেন্ট তৈরি করবেন
• একটি ADK এজেন্ট সংজ্ঞায় কীভাবে গ্রাউন্ডিং টুল যোগ করবেন
• বিল্ট-ইন ওয়েব রানার ব্যবহার করে কীভাবে একটি ADK এজেন্ট পরীক্ষা করবেন

পরবর্তী পদক্ষেপ

• অন্যান্য ADK টুল এবং ইন্টিগ্রেশন প্যাটার্নগুলি অন্বেষণ করুন

রেফারেন্স নথি

• ADK ডকুমেন্টেশন
• গুগল ম্যাপস গ্রাউন্ডিং