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 की मदद से बनाए गए एजेंटों को असरदार तरीके से डिप्लॉय, मैनेज, और मॉनिटर करने के बारे में पूरी जानकारी मिल जाएगी.

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

ADK एजेंट डेटाबेस सेशन सेवा के लिए, CloudSQL पर PostgreSQL डेटाबेस बनाना
बेसिक एडीके एजेंट सेट अप करना
ADK रनर के लिए, डेटाबेस सेशन सेवा सेट अप करें
एजेंट को Cloud Run पर डिप्लॉय करना
लोड टेस्टिंग और Cloud Run की ऑटो स्केलिंग की जांच करना
एजेंट के नए वर्शन को डिप्लॉय करें और नए वर्शन पर ट्रैफ़िक को धीरे-धीरे बढ़ाएं
क्लाउड ट्रेसिंग सेट अप करना और एजेंट के रन की ट्रेसिंग की जांच करना

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

ज़रूरी शर्तें

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

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

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

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

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

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

2. 🚀 वर्कशॉप सेटअप करने की तैयारी की जा रही है

अहम जानकारी:

इस ट्यूटोरियल के लिए, चालू बिलिंग खाते वाला Google Cloud प्रोजेक्ट ज़रूरी है. अगर आपके पास अब तक कोई खाता नहीं है, तो कृपया इस ट्यूटोरियल के लिए बिलिंग का ट्रायल खाता पाने के लिए, यहां दिया गया तरीका अपनाएं:

गुप्त विंडो खोलें
अगर आपको किसी वर्कशॉप सेशन में शामिल होना है, तो आम तौर पर सेशन में रिडेंप्शन पोर्टल का यूआरएल दिया जाएगा. इसके अलावा, बिना शुल्क आज़माने वाले बिलिंग खाते के रिडेंप्शन पोर्टल पर जाकर भी इसे ऐक्सेस किया जा सकता है
अपने निजी Gmail खाते से लॉग इन करें ( Google Workspace / अन्य ईमेल पते काम नहीं करेंगे! )
इस ट्यूटोरियल के लिए, एक नया Google Cloud प्रोजेक्ट बनाएं, जो पहले से दावा किए गए ट्रायल बिलिंग खाते से लिंक हो. इसके लिए, रिडीम करने के निर्देशों का पालन करें

अब हम इस ट्यूटोरियल के लिए, Cloud Shell IDE का इस्तेमाल करेंगे. इस पर जाने के लिए, यहां दिए गए बटन पर क्लिक करें

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

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

इसके बाद, क्लोन की गई रिपॉज़िटरी को अपनी वर्किंग डायरेक्ट्री के तौर पर खोलने के लिए, टर्मिनल में यह कमांड चलाएं

cloudshell workspace ~/deploy_and_manage_adk && cd ~/deploy_and_manage_adk

इसके बाद, आपका इंटरफ़ेस कुछ ऐसा दिखना चाहिए

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

bash setup_trial_project.sh && source .env

इसे चलाने पर, आपको सुझाए गए प्रोजेक्ट आईडी का नाम दिखेगा. जारी रखने के लिए, Enter दबाएं

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

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

अब हम अगले चरण के लिए तैयार हैं

3. 🚀 एपीआई चालू करना

इस ट्यूटोरियल में, हम CloudSQL डेटाबेस, Gemini मॉडल, और Cloud Run के साथ इंटरैक्ट करेंगे. इन प्रॉडक्ट के लिए, नीचे दिए गए एपीआई को चालू करना होगा. इन्हें चालू करने के लिए, ये कमांड चलाएं

इसमें कुछ समय लग सकता है.

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

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

Operation "operations/..." finished successfully.

4. 🚀 Python एनवायरमेंट सेटअप और एनवायरमेंट वैरिएबल

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

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

uv sync --frozen

इसके बाद, हम इस प्रोजेक्ट के लिए ज़रूरी एनवायरमेंट वैरिएबल फ़ाइलों की जांच करेंगे. पहले इस फ़ाइल को setup_trial_project.sh स्क्रिप्ट सेट अप कर रही थी. एडिटर में .env फ़ाइल खोलने के लिए, यह कमांड चलाएं

cloudshell open .env

आपको .env फ़ाइल पर पहले से लागू किए गए ये कॉन्फ़िगरेशन दिखेंगे.

# .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. के लिए पहले से कॉन्फ़िगर की गई वैल्यू का इस्तेमाल कर रहे हैं

अब हम अगले चरण पर जा सकते हैं. इसमें, हमें एक ऐसा डेटाबेस बनाना है जिसका इस्तेमाल हमारा एजेंट, स्थिति और सेशन को बनाए रखने के लिए करेगा.

5. 🚀 CloudSQL डेटाबेस तैयार किया जा रहा है

हमें एक डेटाबेस की ज़रूरत होगी, जिसका इस्तेमाल ADK एजेंट बाद में करेगा. आइए, Cloud SQL पर PostgreSQL डेटाबेस बनाएं. डेटाबेस इंस्टेंस बनाने के लिए, पहले यह कमांड चलाएं. हम डिफ़ॉल्ट postgres डेटाबेस के नाम का इस्तेमाल करेंगे. इसलिए, हम यहां डेटाबेस बनाने की प्रोसेस को छोड़ देंगे. हमें अपने डिफ़ॉल्ट डेटाबेस के उपयोगकर्ता नाम को भी कॉन्फ़िगर करना होगा. इसे postgres भी कहा जाता है. ट्यूटोरियल के लिए, आइए हम ADK-deployment123 को अपने पासवर्ड के तौर पर इस्तेमाल करें

gcloud sql instances create adk-deployment \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --tier=db-g1-small \
  --region=us-central1 \
  --availability-type=ZONAL \
  --project=${GOOGLE_CLOUD_PROJECT} && \
gcloud sql users set-password postgres \
  --instance=adk-deployment \
  --password=ADK-deployment123

ऊपर दिए गए निर्देश में, पहला सामान्य gcloud sql instances create adk-deployment एक ऐसा निर्देश है जिसका इस्तेमाल हम डेटाबेस इंस्टेंस बनाने के लिए करते हैं. इस ट्यूटोरियल के लिए, हम सैंडबॉक्स के कम से कम स्पेसिफ़िकेशन का इस्तेमाल कर रहे हैं. दूसरी कमांड gcloud sql users set-password postgres का इस्तेमाल, डिफ़ॉल्ट postgres उपयोगकर्ता नाम का पासवर्ड बदलने के लिए किया जाता है

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

Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/your-project-id/instances/adk-deployment].
NAME: adk-deployment
DATABASE_VERSION: POSTGRES_17
LOCATION: us-central1-a
TIER: db-g1-small
PRIMARY_ADDRESS: xx.xx.xx.xx
PRIVATE_ADDRESS: -
STATUS: RUNNABLE
Updating Cloud SQL user...done.

इस डेटाबेस को डिप्लॉय होने में कुछ समय लगेगा. इसलिए, CloudSQL डेटाबेस के डिप्लॉय होने का इंतज़ार करते समय, अगले सेक्शन पर चलते हैं.

6. 🚀 ADK और Gemini 2.5 की मदद से Weather Agent बनाना

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 पर प्रीव्यू करें को चुनें

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

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

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

7. 🚀 Cloud Run पर डिप्लॉय किया जा रहा है

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

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

अब, सबसे पहले सेवा को डिप्लॉय करते हैं. इसके लिए, Cloud Shell टर्मिनल पर जाएं और पक्का करें कि मौजूदा प्रोजेक्ट, आपके चालू प्रोजेक्ट के लिए कॉन्फ़िगर किया गया हो. इसके बाद, सेटअप स्क्रिप्ट को फिर से चलाएं. इसके अलावा, अपने चालू प्रोजेक्ट को कॉन्फ़िगर करने के लिए, gcloud config set project [PROJECT_ID] कमांड का भी इस्तेमाल किया जा सकता है

bash setup_trial_project.sh && source .env

अब हमें .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 प्रॉडक्ट पर क्लिक करें

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

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

इसके बाद, इस निर्देश का इस्तेमाल करके .env फ़ाइल खोलें

cloudshell edit .env

और .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 उपलब्ध कराई है. इसलिए, यह कमांड इसका इस्तेमाल करके ऐप्लिकेशन बनाएगी

ध्यान दें: डिप्लॉयमेंट स्क्रिप्ट पर, हम SESSION_SERVICE_URI एनवायरमेंट वैरिएबल सेट करते हैं. अगर यह वैरिएबल सेट अप किया जाता है, तो हमारा ADK एजेंट, सेवा के लिए यूआरआई का इस्तेमाल करेगा. इससे सेशन की जानकारी और स्थिति (हमारे server.py में तय की गई) को सेव किया जा सकेगा. इस ट्यूटोरियल में, हम pg8000 ड्राइवर के साथ PostgreSQL Unix सॉकेट कनेक्शन का इस्तेमाल कर रहे हैं.

ध्यान दें कि उदाहरण में, हमने डिफ़ॉल्ट उपयोगकर्ता postgres और डिफ़ॉल्ट डेटाबेस postgres (ADK-deployment123 पासवर्ड के साथ) का इस्तेमाल किया है.

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

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

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

8. 💡 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 स्क्रिप्ट में ये चीज़ें तय की गई हैं:

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

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

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

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

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

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

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

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

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

आपके लिए चीज़ों को आसान बनाने के लिए, आइए हम इस स्क्रिप्ट को चलाकर, हाल ही में डिप्लॉय किए गए सेवा के यूआरएल को पाएं और इसे SERVICE_URL एनवायरमेंट वैरिएबल में सेव करें

export SERVICE_URL=$(gcloud run services describe weather-agent \
    --platform managed \
    --region us-central1 \
    --format 'value(status.url)')

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

uv run locust -f load_test.py \
              -H $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 इंस्टेंस इस शर्त को पूरा करने के लिए, कंटेनर की संख्या को अपने-आप अडजस्ट करेगा.

10. 🚀 नई सुविधाओं को धीरे-धीरे रिलीज़ करना

अब, यहां दी गई स्थिति पर विचार करें. हमें एजेंट के प्रॉम्प्ट को अपडेट करना है. नीचे दिए गए निर्देश का इस्तेमाल करके, weather_agent/agent.py खोलें

cloudshell edit 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 $GOOGLE_CLOUD_PROJECT \
                  --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 डैशबोर्ड पर जाएं

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

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

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

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

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

11. 🚀 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 में ट्रेसिंग की सुविधा चालू करने के बारे में ज़्यादा जानने के लिए, यह दस्तावेज़ पढ़ें

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

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

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

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

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

12. 🎯 चैलेंज

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

13. 🧹 मिटाएं

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

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