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

1. परिचय

इस ट्यूटोरियल में, Google Cloud Run पर एजेंट डेवलपमेंट किट (एडीके) की मदद से बनाए गए एक पावरफ़ुल एजेंट को डिप्लॉय करने, मैनेज करने, और मॉनिटर करने के बारे में बताया गया है. 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. क्लाउड ट्रेसिंग सेट अप करना और एजेंट रन ट्रेसिंग की जांच करना

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

5cdb729288bf43de.jpeg

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

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

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

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

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

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

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

2. 🚀 वर्कशॉप डेवलपमेंट सेटअप तैयार किया जा रहा है

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

Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर जाकर, Google Cloud प्रोजेक्ट चुनें या बनाएं. (अपनी कंसोल के सबसे ऊपर बाईं ओर मौजूद सेक्शन देखें)

9803a4534597d962.png

इस पर क्लिक करने से, आपको अपने सभी प्रोजेक्ट की सूची दिखेगी. जैसे, इस उदाहरण में दिखाया गया है,

5b60dbeab4f9b524.png

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

पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. इसे देखने के लिए, सबसे ऊपर बाईं ओर मौजूद बर्गर आइकॉन ☰ पर क्लिक करें. इससे नेविगेशन मेन्यू दिखेगा. इसके बाद, बिलिंग मेन्यू ढूंढें

db49b5267c00cc33.png

अगर आपको बिलिंग / खास जानकारी टाइटल ( Cloud Console के सबसे ऊपर बाईं ओर मौजूद सेक्शन ) में, "Google Cloud Platform का ट्रायल बिलिंग खाता" दिखता है, तो इसका मतलब है कि आपका प्रोजेक्ट इस ट्यूटोरियल के लिए तैयार है. अगर ऐसा नहीं होता है, तो इस ट्यूटोरियल की शुरुआत पर वापस जाएं और बिना शुल्क वाले आज़माने के लिए उपलब्ध बिलिंग खाते को रिडीम करें

7f607aa026552bf5.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" और पासवर्ड के लिए "ADK-deployment123" का इस्तेमाल करेंगे

f9db3a2a923e988f.png

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

773e2ea11d97369d.png

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

तीसरा चरण: Cloud Shell के बारे में जानकारी

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

1829c3759227c19b.png

b8fe7df5c3c2b919.png

Cloud Shell से कनेक्ट होने के बाद, हमें यह देखना होगा कि शेल ( या टर्मिनल) की पुष्टि हमारे खाते से पहले ही हो चुकी है या नहीं

gcloud auth list

अगर आपको नीचे दिए गए उदाहरण के आउटपुट की तरह अपना निजी Gmail दिखता है, तो इसका मतलब है कि सब ठीक है

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

अगर ऐसा नहीं होता है, तो अपने ब्राउज़र को रीफ़्रेश करें. साथ ही, यह पक्का करें कि प्रॉम्प्ट मिलने पर आपने अनुमति दें पर क्लिक किया हो. ऐसा हो सकता है कि कनेक्शन की समस्या की वजह से, यह प्रोसेस बीच में रुक गई हो

इसके बाद, हमें यह भी जांच करनी होगी कि शेल को आपके पास मौजूद सही PROJECT ID के लिए पहले से कॉन्फ़िगर किया गया है या नहीं. अगर आपको टर्मिनल में $आइकॉन से पहले ( ) के अंदर वैल्यू दिखती है, तो इसका मतलब है कि शेल को पहले से कॉन्फ़िगर किया गया है. नीचे दिए गए स्क्रीनशॉट में, वैल्यू "adk-cloudrun-deployment-476504" है. यह वैल्यू, आपके चालू शेल सेशन के लिए कॉन्फ़िगर किए गए प्रोजेक्ट को दिखाती है.

5ccbc0cf16feaa0.png

अगर दिखाई गई वैल्यू पहले से ही सही है, तो अगले निर्देश को छोड़ा जा सकता है. हालांकि, अगर यह सही नहीं है या मौजूद नहीं है, तो यह कमांड चलाएं

gcloud config set project <YOUR_PROJECT_ID>

इसके बाद, इस कोडलैब के लिए टेंप्लेट की वर्किंग डायरेक्ट्री को Github से क्लोन करें और यहां दिया गया निर्देश चलाएं. इससे deploy_and_manage_adk डायरेक्ट्री में वर्किंग डायरेक्ट्री बन जाएगी

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

चौथा चरण: Cloud Shell Editor के बारे में जानें और ऐप्लिकेशन की वर्किंग डायरेक्ट्री सेट अप करें

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

एडिटर खोलें बटन पर क्लिक करें. इससे Cloud Shell Editor b16d56e4979ec951.png खुल जाएगा

इसके बाद, Cloud Shell Editor के सबसे ऊपर वाले सेक्शन पर जाएं और File->Open Folder पर क्लिक करें. इसके बाद, अपनी username डायरेक्ट्री ढूंढें और deploy_and_manage_adk डायरेक्ट्री ढूंढें. इसके बाद, OK बटन पर क्लिक करें. इससे चुनी गई डायरेक्ट्री, मुख्य वर्किंग डायरेक्ट्री बन जाएगी. इस उदाहरण में, उपयोगकर्ता नाम alvinprayuda है. इसलिए, डायरेक्ट्री का पाथ यहां दिखाया गया है

ee00d484ff2f8351.png

b1fbf2dcd99c468b.png

अब आपकी Cloud Shell Editor की वर्किंग डायरेक्ट्री ऐसी दिखनी चाहिए ( deploy_and_manage_adk फ़ोल्डर में )

4068b1443241bfa1.png

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

55361099b2f56c79.png

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

.venv डायरेक्ट्री पर वर्चुअल एनवायरमेंट के लिए ज़रूरी डिपेंडेंसी इंस्टॉल करने के लिए, यह कमांड चलाएं

uv sync --frozen

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

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

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

Operation "operations/..." finished successfully.

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

.env.example फ़ाइल का नाम बदलकर .env करें

cp .env.example .env

.env फ़ाइल खोलें और GOOGLE_CLOUD_PROJECT वैल्यू को अपने प्रोजेक्ट-आईडी पर अपडेट करें

# .env

# 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
# DB_CONNECTION_NAME=your-db-connection-name

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

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

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

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

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

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

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

weather_agent/
├── __init__.py
├── agent.py
└── tool.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 weather_agent.tool import get_weather

# 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")

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. 🚀 Cloud Run पर डिप्लॉय किया जा रहा है

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

5cdb729288bf43de.jpeg

इस कोडलैब में, हम अपने एजेंट को Cloud Run पर डिप्लॉय करने के लिए Dockerfile का इस्तेमाल करेंगे. इस समय, हमारे पास Cloud Run पर ऐप्लिकेशन डिप्लॉय करने के लिए ज़रूरी सभी फ़ाइलें ( Dockerfile और server.py ) मौजूद हैं. हम इस बारे में बाद में विस्तार से बात करेंगे.

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

gcloud config set project [PROJECT_ID]

अब हमें .env फ़ाइल को फिर से खोलना होगा. इसे खोलने पर आपको दिखेगा कि हमें DB_CONNECTION_NAME वैरिएबल से टिप्पणी हटाने की ज़रूरत है. इसके बाद, इसमें सही वैल्यू भरें

# 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
DB_CONNECTION_NAME=your-db-connection-name

DB_CONNECTION_NAME वैल्यू पाने के लिए, Cloud SQL पर वापस जाएं और बनाए गए इंस्टेंस पर क्लिक करें. क्लाउड कंसोल के सबसे ऊपर मौजूद खोज बार पर जाएं और "cloud sql" टाइप करें. इसके बाद, Cloud SQL प्रॉडक्ट पर क्लिक करें

1005cb65520eb3fc.png

इसके बाद, आपको पहले से बनाया गया इंस्टेंस दिखेगा. उस पर क्लिक करें

ca69aefd116c0b23.png

इंस्टेंस पेज पर, नीचे की ओर स्क्रोल करके "इस इंस्टेंस से कनेक्ट करें" सेक्शन पर जाएं. यहां आपको DB_CONNECTION_NAME वैल्यू की जगह इस्तेमाल करने के लिए, कनेक्शन का नाम कॉपी करने का विकल्प मिलेगा.

5d7d6c6f17e559c1.png

इसके बाद, .env फ़ाइल खोलें और DB_CONNECTION_NAME वैरिएबल में बदलाव करें. आपकी env फ़ाइल, यहाँ दिए गए उदाहरण की तरह दिखनी चाहिए

# 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
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

इसके बाद, डिप्लॉयमेंट स्क्रिप्ट चलाएं

bash deploy_to_cloudrun.sh

अगर आपको Docker इमेज के लिए आर्टफ़ैक्ट रजिस्ट्री बनाने की पुष्टि करने के लिए कहा जाता है, तो बस Y जवाब दें.

जब तक डिप्लॉयमेंट की प्रोसेस पूरी नहीं हो जाती, तब तक deploy_to_cloudrun.sh पर एक नज़र डालते हैं

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

यह स्क्रिप्ट, आपके .env वैरिएबल को लोड करेगी. इसके बाद, डिप्लॉयमेंट कमांड चलाएगी.

अगर आप ध्यान से देखें, तो हमें सिर्फ़ एक gcloud run deploy कमांड की ज़रूरत होती है. इससे वे सभी ज़रूरी काम हो जाते हैं जो किसी सेवा को डिप्लॉय करने के लिए ज़रूरी होते हैं. जैसे, इमेज बनाना, रजिस्ट्री में पुश करना, सेवा को डिप्लॉय करना, आईएएम नीति सेट करना, वर्शन बनाना, और यहां तक कि ट्रैफ़िक को रूट करना. इस उदाहरण में, हमने पहले से ही Dockerfile उपलब्ध कराई है. इसलिए, यह कमांड इसका इस्तेमाल करके ऐप्लिकेशन बनाएगी

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

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

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

5. 💡 Dockerfile और बैकएंड सर्वर स्क्रिप्ट

एजेंट को सेवा के तौर पर ऐक्सेस करने के लिए, हम एजेंट को FastAPI ऐप्लिकेशन में रैप करेंगे. यह 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"]

हम यहां एजेंट की मदद करने के लिए ज़रूरी सेवाओं को कॉन्फ़िगर कर सकते हैं. जैसे, प्रोडक्शन के लिए सेशन, मेमोरी या आर्टफ़ैक्ट सेवा तैयार करना. यहां 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


# 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, "trace_to_cloud": 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",
    )

# 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 = ""


# Example if you want to add your custom endpoint
@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 env var को कॉन्फ़िगर करते हैं, तो सेशन सेवा इसका इस्तेमाल करेगी. ऐसा न करने पर, यह इन-मेमोरी सेशन का इस्तेमाल करेगी
  3. हम अन्य बैकएंड बिज़नेस लॉजिक के लिए, कस्टम रूट जोड़ सकते हैं. स्क्रिप्ट में, हम सुझाव/राय देने या शिकायत करने की सुविधा के रूट का उदाहरण जोड़ते हैं
  4. Google Cloud Trace को ट्रेस भेजने के लिए, get_fast_api_app आर्ग पैरामीटर में क्लाउड ट्रेसिंग चालू करें
  5. uvicorn का इस्तेमाल करके, FastAPI सेवा चलाएं

अगर आपका डिप्लॉयमेंट पहले ही पूरा हो चुका है, तो कृपया Cloud Run यूआरएल को ऐक्सेस करके, वेब Dev UI से एजेंट के साथ इंटरैक्ट करने की कोशिश करें

6. 🚀 लोड टेस्टिंग की मदद से, Cloud Run की ऑटो स्केलिंग की जांच करना

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

आइए, 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. 🚀 नई सुविधाओं को धीरे-धीरे रिलीज़ करना

अब यहां दिया गया उदाहरण देखें. हमें एजेंट के प्रॉम्प्ट को अपडेट करना है. weather_agent/agent.py खोलें और इसे इस कोड से बदलें:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# 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")

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.
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 प्रतिशत ट्रैफ़िक दिखाया जाएगा.

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

इसके बाद, 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

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

यहां, हम trace_to_cloud आर्ग्युमेंट को True पर सेट करते हैं. अगर आपको अन्य विकल्पों के साथ डिप्लॉय करना है, तो अलग-अलग डिप्लॉयमेंट विकल्पों से Cloud Trace में ट्रेसिंग की सुविधा चालू करने के बारे में ज़्यादा जानने के लिए, यह दस्तावेज़ पढ़ें

अपनी सेवा के वेब डेवलपर यूज़र इंटरफ़ेस (यूआई) को ऐक्सेस करने की कोशिश करें और एजेंट से चैट करें. इसके बाद, क्लाउड कंसोल के खोज बार में जाएं और "ट्रेस एक्सप्लोरर" टाइप करें. इसके बाद, वहां 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 पर जाकर, अभी-अभी डिप्लॉय की गई सेवा को चुनें और उसे मिटाएं.