ক্লাউড রানে একটি পেট পাসপোর্ট এজেন্ট তৈরি এবং স্থাপন করুন

১. সংক্ষিপ্ত বিবরণ

এই কোড ল্যাবে আপনি শিখবেন কীভাবে পেট পাসপোর্ট অ্যাপটি ডেপ্লয় করতে হয়; এটি একটি এআই এজেন্ট যা ডেটা বিশ্লেষণ এবং লোকেশন পরিষেবা একত্রিত করতে মডেল কনটেক্সট প্রোটোকল (MCP) ব্যবহার করে।

অ্যাপটি নিউ ইয়র্ক সিটিতে কুকুরের জাতের জনপ্রিয়তার উপর ভিত্তি করে ব্যবহারকারীদের তাদের কুকুরের সাথে একটি নিখুঁত দিন কাটানোর পরিকল্পনা করতে সাহায্য করে। এজেন্টটি একটি "ম্যাক্রো-টু-মাইক্রো" যুক্তির শৃঙ্খল ব্যবহার করে:

  1. কৌশলগত অনুসন্ধান (বিগকোয়েরি): একটি নির্দিষ্ট প্রজাতির জন্য সর্বোচ্চ জনসংখ্যা বিশিষ্ট নিউ ইয়র্ক সিটির জিপ কোড শনাক্ত করে।
  2. স্থানীয় কার্যকারিতা (মানচিত্র): 'পোষ্যবান্ধব ক্যাফে' এবং 'ডগ পার্ক' খুঁজে বের করার জন্য অবস্থানগত পক্ষপাত হিসেবে ঐ জিপ কোডটি ব্যবহার করে।
  3. ভ্রমণসূচী তৈরি: ডেটা একত্রিত করে ক্লিকযোগ্য লিঙ্ক এবং ছবি সহ একটি 'পেট পাসপোর্ট' ভ্রমণসূচী তৈরি করে।

এজেন্টটি google-adk ফ্রেমওয়ার্ক ব্যবহার করে তৈরি এবং Gemini দ্বারা চালিত।

দ্রষ্টব্য: ফ্রন্টএন্ড UI সহ সম্পূর্ণ প্রজেক্ট কোড গিটহাবে পাওয়া যাবে। এই কোডল্যাবে আমরা মূল এজেন্ট লজিক এবং অবকাঠামো সেটআপের উপর মনোযোগ দেব।

২. সেটআপ এবং প্রয়োজনীয়তা

প্রথমে, আপনার ডেভেলপমেন্ট এনভায়রনমেন্টটি সঠিকভাবে সেট আপ করা হয়েছে কিনা তা নিশ্চিত করে নেওয়া যাক।

১. গুগল ক্লাউড দিয়ে প্রমাণীকরণ করুন

আপনার সক্রিয় গুগল ক্লাউড প্রজেক্ট সেট করুন এবং প্রমাণীকরণ করুন। এজেন্টের BigQuery এবং অন্যান্য পরিষেবা অ্যাক্সেস করার জন্য এটি প্রয়োজন।

gcloud config set project [YOUR-PROJECT-ID]
gcloud auth application-default login --project [YOUR-PROJECT-ID]

দ্রষ্টব্য: প্রমাণীকরণের সময় যদি আপনি অন্য কোনো প্রকল্প সম্পর্কিত ত্রুটির সম্মুখীন হন, তাহলে আপনি কোটা প্রকল্পটি নিষ্ক্রিয় করে এবং ম্যানুয়ালি সেট করে এটি এড়িয়ে যেতে পারেন:

gcloud auth application-default login --disable-quota-project
gcloud auth application-default set-quota-project [YOUR-PROJECT-ID]

২. সফটওয়্যার প্রয়োজনীয়তা

আপনার লোকাল মেশিনে নিম্নলিখিত সফ্টওয়্যারগুলি ইনস্টল করা থাকতে হবে:

  • পাইথন (সংস্করণ ৩.১৩ বা উচ্চতর প্রয়োজন)
  • গিট (রিপোজিটরি ডাউনলোড করার জন্য)

রিপোজিটরি ডাউনলোড করুন

এই প্রজেক্টের কোড গুগল এমসিপি রিপোজিটরিতে পাওয়া যাবে। রিপোজিটরিটি ক্লোন করুন এবং প্রজেক্ট ফোল্ডারে যান:

git clone https://github.com/google/mcp.git
cd examples/petpassport

৩. স্থাপন

এখন যেহেতু আপনার কাছে ফাইলগুলো আছে, চলুন পাইথন এনভায়রনমেন্ট সেট আপ করা যাক।

  1. একটি ভার্চুয়াল এনভায়রনমেন্ট তৈরি করুন: এটি আপনার ডিপেন্ডেন্সিগুলোকে বিচ্ছিন্ন রাখে। 
    python3 -m venv .venv
  2. ভার্চুয়াল পরিবেশ সক্রিয় করুন:
    • লিনাক্স/ম্যাকওএস-এ: 
      source .venv/bin/activate
    • উইন্ডোজে: 
      .venv\Scripts\activate
  3. নির্ভরতা ইনস্টল করুন: 
    pip install google-adk==1.28.0 python-dotenv google-genai pillow uvicorn

ক্লাউড এপিআইগুলি সক্রিয় করুন

আপনার প্রোজেক্টে নিম্নলিখিত API-গুলি সক্রিয় করুন:

gcloud services enable \
  bigquery.googleapis.com \
  aiplatform.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com \
  storage.googleapis.com

একটি অঞ্চল নির্বাচন করুন

আপনার শেলে অঞ্চলটিকে একটি এনভায়রনমেন্ট ভেরিয়েবল হিসেবে সেট করুন:

export REGION=us-central1

৪. এপিআই কী সংগ্রহ করুন

Maps এবং Gemini পরিষেবাগুলো ব্যবহার করার জন্য, আপনাকে API কী সংগ্রহ করে প্রজেক্ট রুটের একটি .env ফাইলে সংরক্ষণ করতে হবে।

১. গুগল ম্যাপস এপিআই কী

  1. গুগল ক্লাউড কনসোলে যান।
  2. এপিআই ও পরিষেবা > পরিচয়পত্র- এ যান।
  3. ক্রেডেনশিয়াল তৈরি করুন > এপিআই কী-তে ক্লিক করুন।
  4. তৈরি হওয়া কী-টি কপি করে আপনার .env ফাইলে MAPS_API_KEY=[YOUR_KEY] হিসেবে যোগ করুন।
  5. (সুপারিশকৃত) কী-টি এমনভাবে সীমাবদ্ধ করুন যাতে শুধুমাত্র MCP সার্ভার দ্বারা ব্যবহৃত Maps API-গুলোই অনুমোদিত হয়।

২. জেমিনি এপিআই কী (এআই স্টুডিও)

  1. গুগল এআই স্টুডিও -তে যান।
  2. Get API key-তে ক্লিক করুন অথবা API key সেকশনে যান।
  3. API কী তৈরি করুন -এ ক্লিক করুন।
  4. কী-টি কপি করে আপনার .env ফাইলে GEMINI_API_KEY=[YOUR_KEY] হিসেবে যোগ করুন।

৫. নির্ভরতা ইনস্টল করুন

petpassport/ ফোল্ডারে requirements.txt একটি ফাইল তৈরি করুন: 

google-adk==1.28.0
python-dotenv
google-genai
pillow

৬. এমসিপি সার্ভারগুলো প্রমাণীকরণ করুন

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

  1. গুগল ম্যাপস এমসিপি: এর জন্য X-Goog-Api-Key হেডারে একটি বৈধ ম্যাপস এপিআই কী প্রদান করতে হবে।
  2. BigQuery MCP: BigQuery পরিষেবাতে অ্যাক্সেসের জন্য OAuth ক্রেডেনশিয়াল প্রয়োজন। Cloud Run-এ চলার সময় এজেন্টটি ডিফল্ট কম্পিউট সার্ভিস অ্যাকাউন্ট ব্যবহার করে, অথবা স্থানীয়ভাবে চলার সময় আপনার লোকাল ক্রেডেনশিয়াল ব্যবহার করে।

আমরা রিপোজিটরিতে setup/setup_env.sh নামে একটি সেটআপ স্ক্রিপ্ট দিয়েছি, যা আপনার .env ফাইলে এই ভেরিয়েবলগুলো কনফিগার করতে সাহায্য করে।

৭. BigQuery টেবিল তৈরি করা

এজেন্ট কুকুরের লাইসেন্সের ডেটা কোয়েরি করার আগে, আমাদের BigQuery-তে ডেটাসেট ও টেবিল তৈরি করে ডেটা লোড করতে হবে।

আমরা setup/setup_bigquery.sh নামে একটি সেটআপ স্ক্রিপ্ট প্রদান করি যা নিম্নলিখিত ধাপগুলো সম্পাদন করে:

  1. কাঁচা ডেটা সংরক্ষণের জন্য pet-passport-data-[PROJECT_ID] নামে একটি ক্লাউড স্টোরেজ বাকেট তৈরি করে।
  2. নিউ ইয়র্ক সিটি ডগ লাইসেন্সিং-এর পাবলিক ডেটাসেট (CSV) ডাউনলোড করে।
  3. CSV ফাইলটি বাকেটে আপলোড করে।
  4. nyc_dogs নামে একটি BigQuery ডেটাসেট তৈরি করে।
  5. বাকেট থেকে ডেটা ডেটাসেটের licenses নামের টেবিলে লোড করে।

সেটআপ স্ক্রিপ্টটি চালানোর জন্য, আপনার টার্মিনালে নিম্নলিখিত কমান্ডটি চালান: 

bash setup/setup_bigquery.sh

৮. এমসিপি সার্ভারগুলির সাথে সংযোগ করুন

এই অ্যাপটির একটি গুরুত্বপূর্ণ অংশ হলো ডেটা ও পরিষেবাগুলোর সাথে সংযোগ স্থাপনের জন্য MCP ব্যবহার করা। এই অংশে, আপনি petpassport/tools.py নামের একটি ফাইলে BigQuery এবং Google Maps-এর জন্য MCP টুলসেটগুলো কনফিগার করবেন।

tools.py সম্পূর্ণ কোড

এখানে tools.py এর সম্পূর্ণ বাস্তবায়ন দেওয়া হলো, যার মধ্যে MCP টুলসেট এবং ছবি ও ডেটা সংরক্ষণের জন্য কাস্টম টুল অন্তর্ভুক্ত রয়েছে। আমরা বাকেট রেজোলিউশনকে মডিউল স্তরে সরিয়ে নিয়ে পুনরাবৃত্তি কমাতে এই কোডটিকে অপ্টিমাইজ করেছি: 

import os
import dotenv
import google.auth
import time
import datetime
from google.cloud import storage
from PIL import Image
from google import genai
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

MAPS_MCP_URL = "https://mapstools.googleapis.com/mcp" 
BIGQUERY_MCP_URL = "https://bigquery.googleapis.com/mcp" 

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
BUCKET_NAME = f"pet-passport-data-{PROJECT_ID}" 

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
            },
            timeout=30.0,          
            sse_read_timeout=300.0
        )
    )
    print("Maps MCP Toolset configured.")
    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,
            timeout=30.0,          
            sse_read_timeout=300.0
        )
    )
    print("BigQuery MCP Toolset configured.")
    return tools

def generate_pet_passport_photo(prompt: str, image_path: str = None) -> str:
    """Generates an image using gemini-3.1-flash-image-preview based on a prompt and a reference image."""
    client = genai.Client()
    output_path = f"/tmp/pet_passport_{int(time.time())}.png"
    
    try:
        image = Image.open(image_path)
        response = client.models.generate_content(
            model="gemini-3.1-flash-image-preview",
            contents=[prompt, image],
        )
        
        for part in response.parts:
            if part.inline_data is not None:
                generated_image = part.as_image()
                generated_image.save(output_path)
                
                # Upload to GCS and generate signed URL
                try:
                    storage_client = storage.Client()
                    bucket = storage_client.bucket(BUCKET_NAME)
                    blob_name = os.path.basename(output_path)
                    blob = bucket.blob(blob_name)
                    
                    blob.upload_from_filename(output_path)
                    
                    url = blob.generate_signed_url(
                        version="v4",
                        expiration=datetime.timedelta(hours=24),
                        method="GET",
                    )
                    return url
                except Exception as e:
                    print(f"Error uploading image to GCS: {e}")
                    return output_path
                
        raise ValueError("No image was returned by the model.")
    except Exception as e:
        print(f"Error generating image: {e}")
        raise

def save_pet_passport(user_id: str, breed: str, postal_code: str, route_details: str, image_paths: list[str] = None) -> str:
    """Appends the generated itinerary to the user's history in GCS."""
    try:
        storage_client = storage.Client()
        bucket = storage_client.bucket(BUCKET_NAME)
        blob = bucket.blob(f"user-{user_id}.json")
        
        # Download existing or start fresh
        # ... (Implementation details hidden for brevity) ...
        return "Success"
    except Exception as e:
        print(f"Error saving path: {e}")
        raise

কোডের ব্যাখ্যা: tools.py

  • get_maps_mcp_toolset এবং get_bigquery_mcp_toolset সঠিক এন্ডপয়েন্ট ও অথেনটিকেশন হেডার দিয়ে এমসিপি ক্লায়েন্টগুলোকে কনফিগার করে।
  • generate_pet_passport_photo Gemini ব্যবহার করে একটি সিন তৈরি করে এবং ফলাফলটি Google Cloud Storage-এ আপলোড করে, যা সার্ভার রিস্টার্টের পরেও অক্ষত থাকার জন্য ফ্রন্টএন্ডে একটি Signed URL ফেরত পাঠায়।

৯. এজেন্ট তৈরি করা

আপনার টুলগুলো কনফিগার করা হয়ে গেলে, এবার এজেন্টের 'মস্তিষ্ক' তৈরি করার পালা। আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে petpassport/agent.py নামের একটি ফাইলে এজেন্টটি তৈরি করবেন।

agent.py কোডটি সম্পূর্ণ করুন

এখানে agent.py এর সম্পূর্ণ বাস্তবায়ন দেওয়া হলো, যেখানে আমরা এজেন্ট এবং তার নির্দেশাবলী সংজ্ঞায়িত করেছি: 

import os
import dotenv
import tools
from google.adk.agents import LlmAgent

dotenv.load_dotenv()

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-2.5-pro',
    name='root_agent',
    instruction=f"""
        You are the Pet Passport Agent. Your goal is to help users find a fun walking route for their dog in NYC.
        
        When given a breed and a postal code, follow this flow:
        1. **Strategic Discovery:** Use BigQuery to find the most popular neighborhood for that breed in NYC.
        2. **Local Execution:** Use Maps to build a walking route with specific places (parks, cafes) in that area.
        
        **NO DIRECTIONS LINKS:** You must NOT include a Google Maps directions link (e.g., `https://www.google.com/maps/dir/...`) in your final response. Only provide links to individual places.
        
        After generating the itinerary, you MUST call the `save_pet_passport` tool to save this path to the user's profile. Pass a clean summary of the itinerary as `route_details`. The summary should include details (like rating, description from maps).
    """,
    tools=[maps_toolset, bigquery_toolset, tools.generate_pet_passport_photo, tools.save_pet_passport]
)

কোডের ব্যাখ্যা: agent.py

  • কন্টেইনার পরিবেশকে সমর্থন করার জন্য আমরা tools সরাসরি (সরলীকৃত কাঠামোতে) ইম্পোর্ট করি।
  • এজেন্টটি gemini-2.5-pro দিয়ে ইনিশিয়ালাইজ করা হয়েছে।
  • নির্দেশাবলীতে একটি কঠোর বহু-ধাপের চিন্তাধারা (প্রথমে BigQuery, তারপর Maps) নির্ধারণ করা হয়েছে এবং এমন কোনো চলার পথের কল্পনা বা রেন্ডারিং কঠোরভাবে নিষিদ্ধ করা হয়েছে যা বিশৃঙ্খলা সৃষ্টি করে।

১০. অ্যাপ্লিকেশনটি স্থানীয়ভাবে চালানো

ক্লাউড রান-এ ডেপ্লয় করার আগে অ্যাপ্লিকেশনটি স্থানীয়ভাবে পরীক্ষা করে নেওয়া ভালো।

  1. নিশ্চিত করুন যে আপনি প্রজেক্ট ডিরেক্টরিতে আছেন: 
    cd examples/petpassport
  2. FastAPI সার্ভার চালু করুন: আমরা অ্যাপটি চালানোর জন্য uvicorn ব্যবহার করি। এর এন্ট্রি পয়েন্ট হলো petpassport ফোল্ডারের ভেতরের main.py । 
    uvicorn petpassport.main:app --reload
  3. ইউআই খুলুন: পেট পাসপোর্ট ইন্টারফেসটি ব্যবহার করার জন্য আপনার ব্রাউজারে http://127.0.0.1:8000/ui/ -এ যান।

১১. ক্লাউড রানে ডেপ্লয় করা

আপনার এজেন্ট প্রস্তুত হয়ে গেলে, এবার এটিকে ক্লাউড রান-এ ডেপ্লয় করার পালা। কন্টেইনার এনভায়রনমেন্টের উপর কঠোর নিয়ন্ত্রণ বজায় রাখতে আমরা সরাসরি স্ট্যান্ডার্ড gcloud কমান্ড ব্যবহার করি।

প্রজেক্ট ডিরেক্টরি থেকে নিম্নলিখিত কমান্ডটি চালান: 

gcloud run deploy petpassport \
  --source petpassport \
  --region $REGION \
  --allow-unauthenticated \
  --labels dev-tutorial=google-mcp

পরিবেশ ভেরিয়েবল কনফিগার করুন

ডেপ্লয়মেন্টের পরে, Google Cloud Console-এ Cloud Run সার্ভিসে যান এবং Variables & Secrets ট্যাবের অধীনে নিম্নলিখিত এনভায়রনমেন্ট ভেরিয়েবলগুলি সেট করুন:

  • MAPS_API_KEY : আপনার গুগল ম্যাপস এপিআই কী।
  • GOOGLE_CLOUD_PROJECT : আপনার প্রজেক্ট আইডি।
  • PROJECT_ID : আপনার প্রজেক্ট আইডি (পুরানো মডিউলগুলির জন্য রিডানডেন্সি সমর্থিত)।

১২. নমুনা প্রম্পট

এই প্রম্পটগুলো ব্যবহার করে ডেপ্লয় করা এজেন্টের সাথে ইন্টারঅ্যাক্ট করার চেষ্টা করুন:

  1. সাধারণ: "আমি আমার গোল্ডেন রিট্রিভারটিকে নিয়ে নিউ ইয়র্ক সিটিতে ১০০২১-এর কাছাকাছি হাঁটতে যেতে চাই। আমাদের জন্য এমন একটি রাস্তা খুঁজে দিন যেখানে একটি ক্যাফে আছে।"
  2. ভিন্ন প্রজাতি: "আমার একটি ফ্রেঞ্চ বুলডগ আছে এবং আমরা আপার ওয়েস্ট সাইডে (10024-এর কাছে) থাকি। এমন একটি ছোট হাঁটার পথের পরামর্শ দিন যেখানে একটি জনপ্রিয় ডগ পার্ক আছে।"
  3. ছবি সহ: (আপনার কুকুরের একটি ছবি আপলোড করুন) "এই যে আমার কর্গি কুকুরটির একটি ছবি! আমরা ১০০১৩-এর কাছাকাছি থাকি। আমাদের জন্য বেড়ানোর একটি চমৎকার দিনের পরিকল্পনা করুন।"

১৩. পরিষ্কার করা

এই টিউটোরিয়ালে ব্যবহৃত উপকরণগুলির জন্য চার্জ এড়াতে:

  • Cloud Run সার্ভিসটি মুছে ফেলুন: gcloud run services delete petpassport --region=$REGION
  • GCS বাকেটটি মুছে ফেলুন: gcloud storage rm -r gs://pet-passport-data-$PROJECT_ID