Cloud Run पर ADK एजेंट को डिप्लॉय, मैनेज, और निगरानी करना

1. परिचय

इस ट्यूटोरियल में, Google Cloud Run पर Agent Development Kit (ADK) की मदद से बनाए गए एक पावरफ़ुल एजेंट को डिप्लॉय करने, मैनेज करने, और मॉनिटर करने के बारे में बताया गया है. ADK की मदद से, ऐसे एजेंट बनाए जा सकते हैं जो मुश्किल और एक से ज़्यादा एजेंट वाले वर्कफ़्लो को पूरा कर सकते हैं. Cloud Run का इस्तेमाल करके, अपने एजेंट को स्केल किए जा सकने वाले कंटेनर वाले ऐप्लिकेशन के तौर पर डिप्लॉय किया जा सकता है. Cloud Run, पूरी तरह से मैनेज किया जाने वाला सर्वरलेस प्लैटफ़ॉर्म है. इसमें आपको बुनियादी इंफ़्रास्ट्रक्चर के बारे में चिंता करने की ज़रूरत नहीं होती. इन दोनों को साथ में इस्तेमाल करने से, आपको अपने एजेंट के मुख्य लॉजिक पर फ़ोकस करने में मदद मिलती है. साथ ही, Google Cloud के मज़बूत और स्केलेबल एनवायरमेंट का फ़ायदा मिलता है.

इस ट्यूटोरियल में, हम Cloud Run के साथ ADK के इंटिग्रेशन के बारे में जानेंगे. आपको अपने एजेंट को डिप्लॉय करने का तरीका बताया जाएगा. इसके बाद, आपको प्रोडक्शन जैसी सेटिंग में अपने ऐप्लिकेशन को मैनेज करने के बारे में व्यावहारिक जानकारी दी जाएगी. हम आपको बताएंगे कि ट्रैफ़िक को मैनेज करके, अपने एजेंट के नए वर्शन को सुरक्षित तरीके से कैसे रोल आउट किया जाए. इससे आपको पूरी रिलीज़ से पहले, उपयोगकर्ताओं के एक सबसेट के साथ नई सुविधाओं को टेस्ट करने में मदद मिलेगी.

इसके अलावा, आपको अपने एजेंट की परफ़ॉर्मेंस को मॉनिटर करने का अनुभव मिलेगा. हम लोड टेस्ट करके, असल दुनिया की किसी स्थिति को सिम्युलेट करेंगे. इससे हमें Cloud Run की अपने-आप स्केल होने की क्षमताओं को ऐक्शन में देखने का मौका मिलेगा. हम Cloud Trace की मदद से, आपके एजेंट के व्यवहार और परफ़ॉर्मेंस के बारे में ज़्यादा जानकारी इकट्ठा करेंगे. इससे, आपको अनुरोधों की पूरी जानकारी मिलेगी. साथ ही, यह भी पता चलेगा कि अनुरोध आपके एजेंट तक कैसे पहुंचते हैं. इससे, आपको परफ़ॉर्मेंस से जुड़ी किसी भी समस्या का पता लगाने और उसे ठीक करने में मदद मिलेगी. इस ट्यूटोरियल के आखिर तक, आपको इस बारे में पूरी जानकारी मिल जाएगी कि Cloud Run पर ADK की मदद से बनाए गए एजेंट को असरदार तरीके से कैसे डिप्लॉय, मैनेज, और मॉनिटर किया जाता है.

कोडलैब के ज़रिए, आपको यहां दिया गया तरीका अपनाना होगा:

  1. ADK एजेंट डेटाबेस सेशन सेवा के लिए, CloudSQL पर PostgreSQL डेटाबेस बनाना
  2. बेसिक एडीके एजेंट सेट अप करना
  3. ADK रनर के लिए, डेटाबेस सेशन सेवा सेट अप करें
  4. एजेंट को Cloud Run पर डिप्लॉय करना
  5. लोड टेस्टिंग और Cloud Run की अपने-आप स्केलिंग की जांच करना
  6. एजेंट के नए वर्शन को डिप्लॉय करें और नए वर्शन पर ट्रैफ़िक को धीरे-धीरे बढ़ाएं
  7. क्लाउड ट्रेसिंग सेट अप करना और एजेंट रन ट्रेसिंग की जांच करना

आर्किटेक्चर की खास जानकारी

5e38fc5607fb4543.jpeg

ज़रूरी शर्तें

  • Python का इस्तेमाल करने में सहज
  • एचटीटीपी सेवा का इस्तेमाल करके, बुनियादी फ़ुल-स्टैक आर्किटेक्चर के बारे में जानकारी

आपको क्या सीखने को मिलेगा

  • ADK का स्ट्रक्चर और लोकल यूटिलिटी
  • डेटाबेस सेशन सेवा के साथ ADK एजेंट सेट अप करना
  • डेटाबेस सेशन सेवा के इस्तेमाल के लिए, CloudSQL में PostgreSQL सेट अप करना
  • Dockerfile का इस्तेमाल करके, Cloud Run पर ऐप्लिकेशन डिप्लॉय करना और शुरुआती एनवायरमेंट वैरिएबल सेट अप करना
  • लोड टेस्टिंग की मदद से, Cloud Run की अपने-आप स्केल होने की सुविधा को कॉन्फ़िगर करना और उसकी जांच करना
  • Cloud Run की मदद से, धीरे-धीरे रिलीज़ करने की रणनीति
  • ADK एजेंट की ट्रेसिंग को Cloud Trace पर सेट अप करना

आपको इन चीज़ों की ज़रूरत होगी

  • Chrome वेब ब्राउज़र
  • Gmail खाता
  • ऐसा Cloud प्रोजेक्ट जिसमें बिलिंग की सुविधा चालू हो

यह कोडलैब, सभी लेवल के डेवलपर के लिए बनाया गया है. इसमें शुरुआती डेवलपर भी शामिल हैं. इसमें सैंपल ऐप्लिकेशन में Python का इस्तेमाल किया गया है. हालांकि, यहां दिए गए कॉन्सेप्ट को समझने के लिए, Python के बारे में जानकारी होना ज़रूरी नहीं है.

2. शुरू करने से पहले

Cloud Console में चालू प्रोजेक्ट चुनना

इस कोडलैब में यह माना गया है कि आपके पास पहले से ही बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट है. अगर आपके पास अब तक यह सुविधा नहीं है, तो इसे इस्तेमाल करने के लिए नीचे दिए गए निर्देशों का पालन करें.

  1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर जाकर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
  2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.

c714d4741fc97644.png

Cloud SQL डेटाबेस तैयार करना

हमें एक डेटाबेस की ज़रूरत होगी, जिसका इस्तेमाल ADK एजेंट बाद में करेगा. आइए, Cloud SQL पर PostgreSQL डेटाबेस बनाएं. सबसे पहले, क्लाउड कंसोल के सबसे ऊपर मौजूद खोज बार पर जाएं और "cloud sql" टाइप करें. इसके बाद, Cloud SQL प्रॉडक्ट पर क्लिक करें

1005cb65520eb3fc.png

इसके बाद, हमें एक नया डेटाबेस इंस्टेंस बनाना होगा. इसके लिए, इंस्टेंस बनाएं पर क्लिक करें और PostgreSQL चुनें

7f2ad19bc246895d.png

ead4a98e7a8d8a39.png

अगर आपने नया प्रोजेक्ट शुरू किया है, तो आपको Compute Engine API भी चालू करना पड़ सकता है. अगर यह प्रॉम्प्ट दिखता है, तो एपीआई चालू करें पर क्लिक करें

724cf67681535679.png

इसके बाद, हम डेटाबेस के स्पेसिफ़िकेशन चुनेंगे. सैंडबॉक्स वर्शन के प्रीसेट के साथ Enterprise वर्शन चुनें

24aa9defed93a3ef.png

इसके बाद, यहां उपयोगकर्ता postgres के लिए इंस्टेंस का नाम और डिफ़ॉल्ट पासवर्ड सेट करें. इसे अपनी पसंद के क्रेडेंशियल से सेट अप किया जा सकता है. हालांकि, इस ट्यूटोरियल के लिए हम इंस्टेंस के नाम और पासवर्ड, दोनों के लिए "adk-deployment" का इस्तेमाल करेंगे

573719a4582f541c.png

इस ट्यूटोरियल के लिए, हम एक ज़ोन के साथ us-central1 का इस्तेमाल करेंगे. इसके बाद, हम अपना डेटाबेस बना सकते हैं. साथ ही, इंस्टेंस बनाएं बटन पर क्लिक करके, ज़रूरी सेटअप पूरा कर सकते हैं

773e2ea11d97369d.png

इस प्रोसेस के पूरा होने तक, हम अगले सेक्शन पर जा सकते हैं

Cloud Shell टर्मिनल में क्लाउड प्रोजेक्ट सेट अप करना

  1. आपको Cloud Shell का इस्तेमाल करना होगा. यह Google Cloud में चलने वाला कमांड-लाइन एनवायरमेंट है. Google Cloud Console में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें.

1829c3759227c19b.png

  1. Cloud Shell से कनेक्ट होने के बाद, यह देखने के लिए कि आपकी पुष्टि हो चुकी है और प्रोजेक्ट को आपके प्रोजेक्ट आईडी पर सेट किया गया है, इस कमांड का इस्तेमाल करें:
gcloud auth list
  1. यह पुष्टि करने के लिए कि gcloud कमांड को आपके प्रोजेक्ट के बारे में पता है, Cloud Shell में यह कमांड चलाएं.
gcloud config list project
  1. अगर आपका प्रोजेक्ट सेट नहीं है, तो इसे सेट करने के लिए इस निर्देश का इस्तेमाल करें:
gcloud config set project <YOUR_PROJECT_ID>

इसके अलावा, PROJECT_ID आईडी को कंसोल में भी देखा जा सकता है

4032c45803813f30.jpeg

इस पर क्लिक करने से, आपको अपने सभी प्रोजेक्ट और प्रोजेक्ट आईडी दाईं ओर दिखेंगे

8dc17eb4271de6b5.jpeg

  1. नीचे दिए गए निर्देश का इस्तेमाल करके, ज़रूरी एपीआई चालू करें. इसमें कुछ मिनट लग सकते हैं. इसलिए, कृपया इंतज़ार करें.
gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

कमांड के सही तरीके से लागू होने पर, आपको यहां दिखाए गए मैसेज जैसा कोई मैसेज दिखेगा:

Operation "operations/..." finished successfully.

gcloud कमांड के बजाय, कंसोल का इस्तेमाल करके भी ऐसा किया जा सकता है. इसके लिए, हर प्रॉडक्ट को खोजें या इस लिंक का इस्तेमाल करें.

अगर कोई एपीआई छूट जाता है, तो उसे लागू करने के दौरान कभी भी चालू किया जा सकता है.

gcloud कमांड और उनके इस्तेमाल के बारे में जानने के लिए, दस्तावेज़ देखें.

Cloud Shell Editor पर जाएं और ऐप्लिकेशन की वर्किंग डायरेक्ट्री सेट अप करें

अब हम कोडिंग से जुड़े कुछ काम करने के लिए, कोड एडिटर सेट अप कर सकते हैं. इसके लिए, हम Cloud Shell Editor का इस्तेमाल करेंगे

  1. 'एडिटर खोलें' बटन पर क्लिक करें. इससे Cloud Shell Editor खुल जाएगा. यहां हम अपना कोड लिख सकते हैं b16d56e4979ec951.png
  2. पक्का करें कि Cloud Code प्रोजेक्ट, Cloud Shell एडिटर के सबसे नीचे बाईं ओर (स्टेटस बार) में सेट हो. जैसा कि नीचे दी गई इमेज में हाइलाइट किया गया है. साथ ही, यह उस चालू Google Cloud प्रोजेक्ट पर सेट हो जिसके लिए बिलिंग की सुविधा चालू है. अगर कहा जाए, तो अनुमति दें पर क्लिक करें. अगर आपने पहले से ही पिछले निर्देश का पालन किया है, तो हो सकता है कि बटन, साइन इन बटन के बजाय सीधे आपके चालू किए गए प्रोजेक्ट पर ले जाए

f5003b9c38b43262.png

  1. इसके बाद, कोड सीखने की इस लैब के लिए, टेंप्लेट की वर्किंग डायरेक्ट्री को Github से क्लोन करें. इसके लिए, यहां दिया गया निर्देश चलाएं. इससे deploy_and_manage_adk डायरेक्ट्री में वर्किंग डायरेक्ट्री बन जाएगी
git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk
  1. इसके बाद, Cloud Shell Editor के सबसे ऊपर वाले सेक्शन पर जाएं और File->Open Folder पर क्लिक करें. इसके बाद, अपनी username डायरेक्ट्री ढूंढें और deploy_and_manage_adk डायरेक्ट्री ढूंढें. इसके बाद, OK बटन पर क्लिक करें. इससे चुनी गई डायरेक्ट्री, मुख्य वर्किंग डायरेक्ट्री बन जाएगी. इस उदाहरण में, उपयोगकर्ता नाम alvinprayuda है. इसलिए, डायरेक्ट्री का पाथ यहां दिखाया गया है

2c53696f81d805cc.png

a51615f22ba1690f.png

अब आपका Cloud Shell Editor ऐसा दिखना चाहिए

228d4c1844790573.png

इसके बाद, हम Python एनवायरमेंट सेटअप को कॉन्फ़िगर कर सकते हैं

एनवायरमेंट सेटअप करना

Python वर्चुअल एनवायरमेंट तैयार करना

अगला चरण, डेवलपमेंट एनवायरमेंट तैयार करना है. आपकी मौजूदा ऐक्टिव टर्मिनल वर्किंग डायरेक्ट्री, deploy_and_manage_adk वर्किंग डायरेक्ट्री के अंदर होनी चाहिए. इस कोडलैब में, हम Python 3.12 का इस्तेमाल करेंगे. साथ ही, Python के वर्शन और वर्चुअल एनवायरमेंट को बनाने और मैनेज करने की ज़रूरत को आसान बनाने के लिए, हम uv python project manager का इस्तेमाल करेंगे

  1. अगर आपने अब तक टर्मिनल नहीं खोला है, तो टर्मिनल -> नया टर्मिनल पर क्लिक करके इसे खोलें. इसके अलावा, Ctrl + Shift + C का इस्तेमाल करें. इससे ब्राउज़र के सबसे नीचे एक टर्मिनल विंडो खुलेगी

f8457daf0bed059e.jpeg

  1. uv डाउनलोड करें और python 3.12 को इस कमांड के साथ इंस्टॉल करें
curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
  1. अब uv का इस्तेमाल करके वर्चुअल एनवायरमेंट को शुरू करें. इस निर्देश को चलाएं
uv sync --frozen

इससे .venv डायरेक्ट्री बन जाएगी और डिपेंडेंसी इंस्टॉल हो जाएंगी. pyproject.toml की झलक से, आपको इस तरह दिखाई गई डिपेंडेंसी के बारे में जानकारी मिलेगी

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]
  1. वर्चुअल एनवायरमेंट की जांच करने के लिए, नई फ़ाइल main.py बनाएं और इस कोड को कॉपी करें
def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()
  1. इसके बाद, यह कमांड चलाएं
uv run main.py

आपको नीचे दिए गए उदाहरण जैसा आउटपुट मिलेगा

Using CPython 3.12
Creating virtual environment at: .venv
Hello from deploy_and_manage_adk!

इससे पता चलता है कि Python प्रोजेक्ट को सही तरीके से सेट अप किया जा रहा है.

कॉन्फ़िगरेशन फ़ाइलें सेट अप करना

अब हमें इस प्रोजेक्ट के लिए कॉन्फ़िगरेशन फ़ाइलें सेट अप करनी होंगी.

.env.example फ़ाइल का नाम बदलकर .env करें. इसके बाद, आपको नीचे दी गई वैल्यू दिखेगी. GOOGLE_CLOUD_PROJECT की वैल्यू को अपने प्रोजेक्ट-आईडी में अपडेट करें

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432

इस कोडलैब के लिए, हम GOOGLE_CLOUD_LOCATION और GOOGLE_GENAI_USE_VERTEXAI. के लिए पहले से कॉन्फ़िगर की गई वैल्यू का इस्तेमाल करेंगे. फ़िलहाल, हम SESSION_SERVICE_URI को टिप्पणी के तौर पर रखेंगे.

अब हम अगले चरण पर जा सकते हैं. इसमें एजेंट के लॉजिक की जांच की जाती है और उसे डिप्लॉय किया जाता है

3. ADK और Gemini 2.5 की मदद से, मौसम की जानकारी देने वाला एजेंट बनाना

ADK डायरेक्ट्री स्ट्रक्चर के बारे में जानकारी

आइए, सबसे पहले यह जानते हैं कि ADK में क्या-क्या सुविधाएं मिलती हैं और एजेंट कैसे बनाया जाता है. ADK के पूरे दस्तावेज़ को इस यूआरएल पर ऐक्सेस किया जा सकता है . ADK, सीएलआई कमांड को लागू करने के लिए कई सुविधाएं देता है. इनमें से कुछ यहां दिए गए हैं :

  • एजेंट डायरेक्ट्री स्ट्रक्चर सेट अप करना
  • सीएलआई इनपुट आउटपुट के ज़रिए, बातचीत करने की सुविधा को तुरंत आज़माएं
  • लोकल डेवलपमेंट यूज़र इंटरफ़ेस (यूआई) वेब इंटरफ़ेस को तुरंत सेटअप करना

अब weather_agent डायरेक्ट्री में एजेंट का स्ट्रक्चर देखते हैं

weather_agent/
├── __init__.py
├── agent.py

init.py और agent.py की जांच करने पर, आपको यह कोड दिखेगा

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.cloud import logging as google_cloud_logging

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)

# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")


def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city (e.g., "New York", "London", "Tokyo").

    Returns:
        dict: A dictionary containing the weather information.
              Includes a 'status' key ('success' or 'error').
              If 'success', includes a 'report' key with weather details.
              If 'error', includes an 'error_message' key.
    """
    logger.log_text(
        f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
    )  # Log tool execution
    city_normalized = city.lower().replace(" ", "")  # Basic normalization

    # Mock weather data
    mock_weather_db = {
        "newyork": {
            "status": "success",
            "report": "The weather in New York is sunny with a temperature of 25°C.",
        },
        "london": {
            "status": "success",
            "report": "It's cloudy in London with a temperature of 15°C.",
        },
        "tokyo": {
            "status": "success",
            "report": "Tokyo is experiencing light rain and a temperature of 18°C.",
        },
    }

    if city_normalized in mock_weather_db:
        return mock_weather_db[city_normalized]
    else:
        return {
            "status": "error",
            "error_message": f"Sorry, I don't have weather information for '{city}'.",
        }


root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather],
)

ADK कोड के बारे में जानकारी

इस स्क्रिप्ट में, एजेंट को शुरू करने की सुविधा शामिल है. इसमें हम इन चीज़ों को शुरू करते हैं:

  • इस्तेमाल किए जाने वाले मॉडल को gemini-2.5-flash पर सेट करें
  • मौसम की जानकारी देने वाले एजेंट के तौर पर काम करने के लिए, एजेंट को टूल get_weather उपलब्ध कराएं

वेब यूज़र इंटरफ़ेस (यूआई) चलाना

अब हम एजेंट के साथ इंटरैक्ट कर सकते हैं और स्थानीय तौर पर उसके व्यवहार की जांच कर सकते हैं. ADK की मदद से, हमें डेवलपमेंट वेब यूज़र इंटरफ़ेस (यूआई) मिलता है. इससे हम इंटरैक्ट कर सकते हैं और यह देख सकते हैं कि इंटरैक्शन के दौरान क्या हो रहा है. लोकल डेवलपमेंट यूज़र इंटरफ़ेस (यूआई) सर्वर शुरू करने के लिए, यह कमांड चलाएं

uv run adk web --port 8080

इससे आपको इस उदाहरण जैसा आउटपुट मिलेगा. इसका मतलब है कि अब वेब इंटरफ़ेस को ऐक्सेस किया जा सकता है

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

अब इसे देखने के लिए, Cloud Shell Editor के सबसे ऊपर मौजूद वेब प्रीव्यू बटन पर क्लिक करें. इसके बाद, पोर्ट 8080 पर झलक देखें को चुनें

e7c9f56c2463164.png

आपको यह वेब पेज दिखेगा. इसमें सबसे ऊपर बाईं ओर मौजूद ड्रॉप-डाउन बटन से, उपलब्ध एजेंट चुने जा सकते हैं. हमारे मामले में, यह weather_agent होना चाहिए. इसके बाद, बॉट से इंटरैक्ट किया जा सकता है. आपको बाईं ओर मौजूद विंडो में, एजेंट के रनटाइम के दौरान लॉग की जानकारी के बारे में कई तरह की जानकारी दिखेगी

d95b1e057315fee2.png

अब इससे इंटरैक्ट करके देखें. बाईं ओर मौजूद बार में, हम हर इनपुट के लिए ट्रेस की जांच कर सकते हैं. इससे हमें यह समझने में मदद मिलती है कि एजेंट को फ़ाइनल जवाब देने से पहले, हर कार्रवाई में कितना समय लगता है.

39c0a06ace937683.png

यह निगरानी से जुड़ी सुविधाओं में से एक है, जिसे ADK में बनाया गया है. फ़िलहाल, हम इसकी जांच स्थानीय तौर पर करते हैं. बाद में हम देखेंगे कि इसे Cloud Tracing में कैसे इंटिग्रेट किया जाता है, ताकि हमारे पास सभी अनुरोधों का सेंट्रलाइज़्ड ट्रेस हो

4. बैकएंड सर्वर स्क्रिप्ट

एजेंट को सेवा के तौर पर ऐक्सेस करने के लिए, हम एजेंट को FastAPI ऐप्लिकेशन में रैप करेंगे. यहां हम एजेंट को सपोर्ट करने के लिए ज़रूरी सेवाओं को कॉन्फ़िगर कर सकते हैं. जैसे, प्रोडक्शन के लिए सेशन, मेमोरी या आर्टफ़ैक्ट सेवा तैयार करना. यहां server.py का कोड दिया गया है, जिसका इस्तेमाल

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

सर्वर कोड के बारे में जानकारी

server.py स्क्रिप्ट में ये चीज़ें तय की गई हैं:

  1. get_fast_api_app तरीके का इस्तेमाल करके, हमारे एजेंट को FastAPI ऐप्लिकेशन में बदलें. इस तरह, हमें वही रूट डेफ़िनिशन मिलेगा जिसका इस्तेमाल वेब डेवलपमेंट यूज़र इंटरफ़ेस (यूआई) के लिए किया जाता है.
  2. get_fast_api_app तरीके में कीवर्ड आर्ग्युमेंट जोड़कर, ज़रूरी सेशन, मेमोरी या आर्टफ़ैक्ट सेवा को कॉन्फ़िगर करें. इस ट्यूटोरियल में, अगर हम SESSION_SERVICE_URI एनवायरमेंट वैरिएबल को कॉन्फ़िगर करते हैं, तो सेशन सेवा इसका इस्तेमाल करेगी. ऐसा न करने पर, यह इन-मेमोरी सेशन का इस्तेमाल करेगी
  3. हम अन्य बैकएंड बिज़नेस लॉजिक के लिए, कस्टम रूट जोड़ सकते हैं. स्क्रिप्ट में, हम सुझाव/राय देने या शिकायत करने की सुविधा के रूट का उदाहरण जोड़ते हैं
  4. Google Cloud Trace को ट्रेस भेजने के लिए, क्लाउड ट्रेसिंग चालू करें

5. Cloud Run पर डिप्लॉय करना

अब इस एजेंट सेवा को Cloud Run पर डिप्लॉय करते हैं. इस डेमो के लिए, इस सेवा को सार्वजनिक सेवा के तौर पर दिखाया जाएगा. इसे अन्य लोग ऐक्सेस कर सकते हैं. हालांकि, ध्यान रखें कि यह सबसे सही तरीका नहीं है, क्योंकि यह सुरक्षित नहीं है

5e38fc5607fb4543.jpeg

इस कोडलैब में, हम अपने एजेंट को Cloud Run पर डिप्लॉय करने के लिए Dockerfile का इस्तेमाल करेंगे. नीचे Dockerfile का वह कॉन्टेंट दिया गया है जिसका इस्तेमाल किया जाएगा

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

इस समय, हमारे पास Cloud Run पर ऐप्लिकेशन डिप्लॉय करने के लिए ज़रूरी सभी फ़ाइलें मौजूद हैं. इसलिए, अब हम इसे डिप्लॉय करते हैं. Cloud Shell टर्मिनल पर जाएं और पक्का करें कि मौजूदा प्रोजेक्ट, आपके ऐक्टिव प्रोजेक्ट के लिए कॉन्फ़िगर किया गया हो. अगर ऐसा नहीं है, तो प्रोजेक्ट आईडी सेट करने के लिए, gcloud configure कमांड का इस्तेमाल करें:

gcloud config set project [PROJECT_ID]

इसके बाद, इसे Cloud Run पर डिप्लॉय करने के लिए, यहां दिया गया कमांड चलाएं.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
                  --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --region us-central1

{YOUR_DB_CONNECTION_NAME} वैल्यू पाने के लिए, Cloud SQL पर वापस जाएं और बनाए गए इंस्टेंस पर क्लिक करें. इंस्टेंस पेज पर, नीचे की ओर स्क्रोल करके "इस इंस्टेंस से कनेक्ट करें" सेक्शन पर जाएं. यहां से, कनेक्शन का नाम कॉपी करके {YOUR_DB_CONNECTION_NAME} वैल्यू की जगह इस्तेमाल किया जा सकता है. उदाहरण के लिए, यहां दी गई इमेज देखें

5d7d6c6f17e559c1.png

अगर आपको Docker इमेज के लिए Artifact Registry बनाने की पुष्टि करने के लिए कहा जाता है, तो बस Y पर क्लिक करें. ध्यान दें कि हम यहां बिना पुष्टि किए ऐक्सेस करने की अनुमति दे रहे हैं, क्योंकि यह एक डेमो ऐप्लिकेशन है. हमारा सुझाव है कि आप अपने एंटरप्राइज़ और प्रोडक्शन ऐप्लिकेशन के लिए, पुष्टि करने के सही तरीके का इस्तेमाल करें.

डप्लॉयमेंट पूरा होने के बाद, आपको यहां दिए गए लिंक जैसा लिंक मिलेगा:

https://weather-agent-*******.us-central1.run.app

अब गुप्त विंडो या अपने मोबाइल डिवाइस से ऐप्लिकेशन का इस्तेमाल करें. यह पहले से लाइव होना चाहिए.

6. लोड टेस्टिंग की मदद से, Cloud Run की अपने-आप स्केलिंग की सुविधा की जांच करना

अब हम Cloud Run की ऑटो-स्केलिंग की क्षमताओं की जांच करेंगे. इस उदाहरण के लिए, हर इंस्टेंस के लिए ज़्यादा से ज़्यादा एक साथ होने वाले अनुरोधों को चालू करते समय, नया वर्शन डिप्लॉय करते हैं. यह कमांड चलाएं

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --concurrency 10

इसके बाद, load_test.py फ़ाइल की जांच करते हैं. यह वह स्क्रिप्ट होगी जिसका इस्तेमाल हम locust फ़्रेमवर्क का इस्तेमाल करके लोड टेस्टिंग के लिए करेंगे. यह स्क्रिप्ट ये काम करेगी :

  1. user_id और session_id को रैंडम किया गया
  2. user_id के लिए session_id बनाएं
  3. बनाए गए user_id और session_id के साथ "/run_sse" एंडपॉइंट को हिट करें

अगर आपने सेवा का यूआरएल नहीं दिया है, तो हमें इसकी जानकारी दें. Cloud Run Console पर जाएं और weather-agent सेवा पर क्लिक करें

f5cc953cc422de6d.png

इसके बाद, मौसम की जानकारी देने वाली सेवा ढूंढें और उस पर क्लिक करें

ddd0df8544aa2bfb.png

सेवा का यूआरएल, क्षेत्र की जानकारी के ठीक बगल में दिखेगा. उदाहरण के लिए,

41b1276616379ee8.png

इसके बाद, लोड टेस्ट करने के लिए यह कमांड चलाएं

uv run locust -f load_test.py \
              -H {YOUR_SERVICE_URL} \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

इसे चलाने पर, आपको इस तरह की मेट्रिक दिखेंगी. ( इस उदाहरण में सभी अनुरोध पूरे किए गए हैं )

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00

इसके बाद, Cloud Run में क्या हुआ, यह देखते हैं. इसके लिए, फिर से डिप्लॉय की गई सेवा पर जाएं और डैशबोर्ड देखें. इससे पता चलेगा कि क्लाउड, आने वाले अनुरोधों को मैनेज करने के लिए इंस्टेंस को अपने-आप कैसे स्केल करता है. हम हर इंस्टेंस के लिए, एक साथ प्रोसेस किए जा सकने वाले अनुरोधों की संख्या को 10 तक सीमित कर रहे हैं. इसलिए, Cloud Run इंस्टेंस इस शर्त को पूरा करने के लिए, कंटेनर की संख्या को अपने-आप अडजस्ट करेगा.

1ad41143eb9d95df.png

7. नए बदलावों को धीरे-धीरे रिलीज़ करना

अब यहां दी गई स्थिति देखें. हमें एजेंट के प्रॉम्प्ट को इस तरह अपडेट करना है :

# agent.py

...

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash-preview-05-20",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information. You only answer inquiries about the weather. Refuse all other user query",
    tools=[get_weather],
)

इसके बाद, आपको नए वर्शन रिलीज़ करने हैं, लेकिन आपको यह नहीं चाहिए कि अनुरोध करने वाले सभी लोगों को सीधे नए वर्शन पर रीडायरेक्ट किया जाए. Cloud Run की मदद से, हम रिलीज़ को धीरे-धीरे रोल आउट कर सकते हैं. सबसे पहले, हमें –no-traffic फ़्लैग के साथ नया वर्शन डिप्लॉय करना होगा. पिछली एजेंट स्क्रिप्ट सेव करें और यह कमांड चलाएं

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

यह प्रोसेस पूरी होने के बाद, आपको पिछले डिप्लॉयमेंट प्रोसेस की तरह ही एक लॉग मिलेगा. हालांकि, इसमें दिखाए गए ट्रैफ़िक की संख्या अलग होगी. इसमें 0 प्रतिशत ट्रैफ़िक दिखाया जाएगा.

इसके बाद, Cloud Run के प्रॉडक्ट पेज पर जाएं और डिप्लॉय किया गया अपना इंस्टेंस ढूंढें. खोज बार में cloud run टाइप करें और Cloud Run प्रॉडक्ट पर क्लिक करें

f5cc953cc422de6d.png

इसके बाद, मौसम की जानकारी देने वाली सेवा ढूंढें और उस पर क्लिक करें

ddd0df8544aa2bfb.png

बदलाव टैब पर जाएं. यहां आपको लागू किए गए बदलावों की सूची दिखेगी

8519c5a59bc7efa6.png

आपको दिखेगा कि डिप्लॉय किए गए नए वर्शन को 0% ट्रैफ़िक मिल रहा है. यहां से, केबाब बटन (⋮) पर क्लिक करके ट्रैफ़िक मैनेज करें चुनें

d4d224e20813c303.png

नई पॉप-अप विंडो में, यह बदला जा सकता है कि किस वर्शन को कितना ट्रैफ़िक मिलेगा.

6df497c3d5847f14.png

कुछ समय बाद, ट्रैफ़िक को प्रतिशत के कॉन्फ़िगरेशन के आधार पर, समानुपातिक रूप से रीडायरेक्ट किया जाएगा. इस तरह, नई रिलीज़ में कोई समस्या होने पर, हम आसानी से पिछले वर्शन पर वापस जा सकते हैं

8. ADK ट्रेसिंग

ADK की मदद से बनाए गए एजेंट, पहले से ही ट्रेसिंग की सुविधा के साथ काम करते हैं. इसके लिए, एजेंट में ओपन टेलीमेट्री एम्बेड की जाती है. हमारे पास Cloud Trace है, जो ट्रेसिंग को कैप्चर करता है और उसे दिखाता है. आइए, server.py की जांच करें. इससे पता चलेगा कि हमने पहले से डिप्लॉय की गई सेवा में इसे कैसे चालू किया है

# server.py

from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export

...

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

...

यहां, हम ट्रेसर और एक्सपोर्टर को शुरू करते हैं. एक्सपोर्टर की जानकारी, tracing.py पर देखी जा सकती है . यहां हम एक कस्टम एक्सपोर्टर बनाते हैं, क्योंकि क्लाउड ट्रेस में एक्सपोर्ट किए जा सकने वाले ट्रेस डेटा की एक सीमा होती है. हम इस ट्रेसिंग सुविधा के लिए, https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html से लागू किए गए तरीके का इस्तेमाल कर रहे हैं.

अपनी सेवा के वेब डेवलपर यूज़र इंटरफ़ेस (यूआई) को ऐक्सेस करने की कोशिश करें और एजेंट से चैट करें. इसके बाद, क्लाउड कंसोल के खोज बार में जाएं और "ट्रेस एक्सप्लोरर" टाइप करें. इसके बाद, वहां Trace Explorer प्रॉडक्ट चुनें

4353c0f8982361ab.png

ट्रेस एक्सप्लोरर पेज पर, आपको दिखेगा कि एजेंट ट्रेस के साथ हमारी बातचीत सबमिट कर दी गई है. स्पैन का नाम सेक्शन में जाकर, हमारे एजेंट से जुड़ा स्पैन देखा जा सकता है. इसे agent_run [weather_agent] नाम दिया गया है

c4336d117a3d2f6a.png

स्पैन पहले से ही फ़िल्टर किए जाने पर, हर ट्रेस की सीधे तौर पर जांच भी की जा सकती है. इससे एजेंट की हर कार्रवाई की अवधि के बारे में पूरी जानकारी मिलेगी. उदाहरण के लिए, यहां दी गई इमेज देखें

76a56dff77979037.png

1a3ce0a803d6061a.png

हर सेक्शन में, एट्रिब्यूट में दी गई जानकारी की जांच की जा सकती है. जैसे, यहां दिखाया गया है

2c87b6d67b0164a8.png

अब हमारे पास, उपयोगकर्ता के साथ एजेंट के हर इंटरैक्शन की अच्छी जानकारी है. इससे हमें समस्याओं को डीबग करने में मदद मिलेगी. अलग-अलग टूल या वर्कफ़्लो आज़माएं!

9. चुनौती

मल्टी-एजेंट या एजेंटिक वर्कफ़्लो आज़माएं. इससे आपको यह पता चलेगा कि ये वर्कफ़्लो, लोड के दौरान कैसा परफ़ॉर्म करते हैं और इनका ट्रेस कैसा दिखता है

10. व्यवस्थित करें

इस कोडलैब में इस्तेमाल किए गए संसाधनों के लिए, अपने Google Cloud खाते से शुल्क न लिए जाने के लिए, यह तरीका अपनाएं:

  1. Google Cloud Console में, संसाधन मैनेज करें पेज पर जाएं.
  2. प्रोजेक्ट की सूची में, वह प्रोजेक्ट चुनें जिसे आपको मिटाना है. इसके बाद, मिटाएं पर क्लिक करें.
  3. डायलॉग बॉक्स में, प्रोजेक्ट आईडी डालें. इसके बाद, प्रोजेक्ट मिटाने के लिए बंद करें पर क्लिक करें.
  4. इसके अलावा, कंसोल पर Cloud Run पर जाकर, अभी-अभी डिप्लॉय की गई सेवा को चुनें और उसे मिटाएं.