ऐसा एआई ऐप्लिकेशन बनाना जिससे आपका ग्राहक Telegram के ज़रिए इंटरैक्ट कर सके

1. परिचय

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

इस कोडलैब में, आपको यह बनाना है

इस कोडलैब में, आपको "रेस्टोरेंट कंसीयर्ज" को Telegram चैट ऐप्लिकेशन के साथ इंटिग्रेट करना है. "रेस्टोरेंट कंसीयर्ज", Gemini की मदद से काम करने वाला एडीके पर आधारित ऐप्लिकेशन है. इसकी मदद से, रेस्टोरेंट में खाना खाने वाले लोग, रेस्टोरेंट का मेन्यू ब्राउज़ कर सकते हैं और बुकिंग कर सकते हैं. Telegram बॉट के साथ इंटरैक्ट किया जा सकता है और नैचुरल भाषा में जानकारी मांगी जा सकती है. जैसे, "मुझे कुछ मसालेदार और वेज खाना है." इसके बाद, बॉट, एडीके एजेंट से कनेक्ट होगा. यह एजेंट, डेटाबेस के लिए MCP Toolbox की मदद से, Cloud SQL PostgreSQL डेटाबेस से डेटा पढ़ता है और उसमें डेटा लिखता है. यह टूलबॉक्स, डेटाबेस के सभी ऐक्सेस को मैनेज करता है. इसमें, वेक्टर खोज के लिए, अपने-आप एम्बेडिंग जनरेट करने की सुविधा भी शामिल है. इस दौरान, उपयोगकर्ता को दिखेगा कि बॉट, मैसेज को स्वीकार कर रहा है और जवाब के लिए ... typing दिखा रहा है. ऐसा तब तक दिखेगा, जब तक एडीके एजेंट से जवाब नहीं मिल जाता.

इस कोडलैब में, आपको यह सीखना है

• Gemini की मदद से काम करने वाले एडीके पर आधारित "रेस्टोरेंट कंसीयर्ज" ऐप्लिकेशन को डिप्लॉय करना
• BotFather का इस्तेमाल करके, Telegram चैट बॉट सेट अप करना
• बॉट के वेब हुक को सुनने के लिए, Python ऐप्लिकेशन लिखना
• उपयोगकर्ता के मैसेज पर Telegram में ... typing की सूचना देने के लिए, चैट ऐक्शन भेजना. साथ ही, असली जवाब मिलने तक, समय-समय पर ... typing भेजने के लिए पोलिंग करना
• उपयोगकर्ता की क्वेरी को प्रोसेस करने के लिए, Restaurant Concierge के Cloud Run एंडपॉइंट को कॉल करना
• एडीके एजेंट से मिले जवाब को मैनेज करना. साथ ही, Telegram पर मैसेज भेजना और बफ़र बंद करना
• Python ऐप्लिकेशन को Cloud Run पर डिप्लॉय करना
• अपने Telegram बॉट के साथ इंटरैक्ट करना

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

• मुफ़्त में आज़माने की सुविधा वाले बिलिंग खाते के साथ Google Cloud खाता
• Python की बुनियादी जानकारी
• एडीके और Cloud Run डिप्लॉयमेंट का अनुभव होना फ़ायदेमंद होगा
• Telegram खाता
• (सुझाया गया) ये कोडलैब पूरे करना :
• एडीके, MCP Toolbox, और Cloud SQL की मदद से एजेंटिक आरएजी -> इस कोडलैब से अपने एजेंट को बनाना जारी रखा जा सकता है. इसमें दिया गया शुरुआती कोड एक जैसा है
• (या) बड़े पैमाने पर एजेंट: एजेंट रनटाइम और एडीके इंटिग्रेशन पर A2A प्रोटोकॉल के साथ मल्टी-एजेंट आर्किटेक्चर -> अगर आपको मल्टी-एजेंट आर्किटेक्चर का इस्तेमाल करके, एजेंट को और बेहतर बनाना है

2. एनवायरमेंट सेटअप - पिछले कोडलैब से जारी

इस कोडलैब में दी गई जानकारी, असल में इस कोडलैब की ज़रूरी शर्तों वाले कोडलैब का अगला हिस्सा है: एडीके, MCP Toolbox, और Cloud SQL की मदद से एजेंटिक आरएजी या बड़े पैमाने पर एजेंट: एजेंट रनटाइम और एडीके इंटिग्रेशन पर A2A प्रोटोकॉल के साथ मल्टी-एजेंट आर्किटेक्चर. पिछले कोडलैब से अपना काम जारी रखा जा सकता है

अहम जानकारी: अगर आपको पक्का नहीं है कि आपने पिछला कोडलैब पूरा कर लिया है या नहीं, तो इस सेक्शन को छोड़ें और Environment Setup - Fresh start with the starter repo पर जाएं

हम पिछले कोडलैब की वर्किंग डायरेक्ट्री में बनाना शुरू कर सकते हैं. वर्किंग डायरेक्ट्री build-agent-adk-toolbox-cloudsql या adk-a2a-agent-runtime-starter होनी चाहिए. भ्रम से बचने के लिए, डायरेक्ट्री का नाम बदलकर वही नाम रखते हैं जिसका इस्तेमाल हम नए सिरे से शुरुआत करते समय करते हैं

अगर आप लैब एडीके, MCP Toolbox, और Cloud SQL की मदद से एजेंटिक आरएजी से जारी रख रहे हैं, तो :

mv ~/build-agent-adk-toolbox-cloudsql ~/build-agent-adk-telegram

इसके अलावा, अगर आप लैब बड़े पैमाने पर एजेंट: एजेंट रनटाइम और एडीके इंटिग्रेशन पर A2A प्रोटोकॉल के साथ मल्टी-एजेंट आर्किटेक्चर से जारी रख रहे हैं, तो

mv ~/adk-a2a-agent-runtime-starter ~/build-agent-adk-telegram

इसके बाद, अपनी वर्किंग डायरेक्ट्री को इसमें बदलें

cloudshell workspace ~/build-agent-adk-telegram && cd ~/build-agent-adk-telegram
source .env

अहम जानकारी: अगर आपका Cloud Shell सेशन रीसेट हो गया है, तो अपने प्रोजेक्ट के कॉन्फ़िगरेशन को वापस लाने के लिए, bash setup_verify_trial_project.sh && source .env चलाएं.

इसके बाद, पुष्टि करें कि आपका restaurant-agent पहले से ही डिप्लॉय किया गया है और इसे ऐक्सेस करने के लिए सार्वजनिक यूआरएल मौजूद है

AGENT_URL=$(gcloud run services describe restaurant-agent \
    --region="$REGION" \
    --format='value(status.url)')

echo "      ✓ Agent service deployed"
echo "      Agent URL: $AGENT_URL"
echo ""

अगर यूआरएल को ऐक्सेस किया जा सकता है, तो अगले सेक्शन Create Telegram Bot पर जाएं

अहम जानकारी: अगर इनमें से किसी भी जांच में गड़बड़ियां दिखती हैं, तो हमारा सुझाव है कि अगले सेक्शन में Environment Setup - Fresh start with the starter repo में बताया गया तरीका अपनाएं और साफ़ सेटअप के लिए शुरुआती रेपो का इस्तेमाल करें.

3. एनवायरमेंट सेटअप - शुरुआती रेपो के साथ नए सिरे से शुरुआत करना

अहम जानकारी:

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

अहम जानकारी: अगर आपने Environment Setup - Continuing from the previous codelab सेक्शन में बताया गया तरीका पहले ही अपना लिया है, तो इस सेक्शन को छोड़ें और अगले सेक्शन Create Telegram Bot पर जाएं

इस चरण में, आपका Cloud Shell एनवायरमेंट तैयार किया जाता है, Google Cloud प्रोजेक्ट को कॉन्फ़िगर किया जाता है, और शुरुआती रिपॉज़िटरी क्लोन की जाती है.

Cloud Shell खोलें

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

Cloud Shell खोलें

इसके बाद, टर्मिनल खोलने के लिए "देखें" -> "टर्मिनल" पर क्लिक करें.आपका इंटरफ़ेस, इस तरह दिखना चाहिए

यह हमारा मुख्य इंटरफ़ेस होगा. इसमें सबसे ऊपर आईडीई और सबसे नीचे टर्मिनल दिखेगा

अपनी वर्किंग डायरेक्ट्री सेट अप करना

शुरुआती रिपॉज़िटरी क्लोन करें. इस कोडलैब में लिखा गया सारा कोड यहां सेव होगा:

rm -rf ~/build-agent-adk-telegram
git clone https://github.com/alphinside/adk-a2a-agent-runtime-starter.git build-agent-adk-telegram
cloudshell workspace ~/build-agent-adk-telegram && cd ~/build-agent-adk-telegram

दी गई टेंप्लेट से .env फ़ाइल बनाएं:

cp .env.example .env

अहम जानकारी! नीचे दिया गया चरण, Google Cloud प्रोजेक्ट को जल्दी से सेट अप करने में मदद करने के लिए दिया गया है. यह प्रोजेक्ट, मुफ़्त में आज़माने की सुविधा वाले बिलिंग खाते से लिंक है (strict). अगर आपको अपना पिछला प्रोजेक्ट इस्तेमाल करना है, तो नीचे दिया गया चरण छोड़ें और इसके बजाय यह चरण पूरा करें:

• .env फ़ाइल में, अपने प्रोजेक्ट का नाम GOOGLE_CLOUD_PROJECT वैरिएबल के तौर पर जोड़ें
• gcloud config set project your-project-id का इस्तेमाल करके, टर्मिनल में अपना प्रोजेक्ट चालू करें

इसके बाद, सीधे शुरुआती इन्फ़्रास्ट्रक्चर सेटअप सेक्शन पर जाएं.

अगर आपको इस बारे में पक्का नहीं है, तो नीचे दिया गया सेक्शन जारी रखें

अपने टर्मिनल में प्रोजेक्ट सेटअप को आसान बनाने के लिए, इस प्रोजेक्ट सेटअप स्क्रिप्ट को अपनी वर्किंग डायरेक्ट्री में डाउनलोड करें:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

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

bash setup_verify_trial_project.sh && source .env

स्क्रिप्ट ये काम करेगी:

1. पुष्टि करेगी कि आपके पास मुफ़्त में आज़माने की सुविधा वाला चालू बिलिंग खाता है
2. .env में किसी मौजूदा प्रोजेक्ट की जांच करेगी (अगर कोई है, तो)
3. नया प्रोजेक्ट बनाएगी या मौजूदा प्रोजेक्ट का फिर से इस्तेमाल करेगी
4. मुफ़्त में आज़माने की सुविधा वाले बिलिंग खाते को आपके प्रोजेक्ट से लिंक करेगी
5. प्रोजेक्ट आईडी को .env में सेव करेगी
6. प्रोजेक्ट को चालू gcloud प्रोजेक्ट के तौर पर सेट करेगी

अहम जानकारी: अगर .env में पहले से कोई प्रोजेक्ट कॉन्फ़िगर किया गया है, तो स्क्रिप्ट पुष्टि करती है कि वह किसी चालू बिलिंग खाते से लिंक है. अगर सब कुछ ठीक है, तो यह प्रोजेक्ट बनाने की प्रोसेस को छोड़ देती है और मुफ़्त में आज़माने की सुविधा वाले बिलिंग खाते की पुष्टि करने की ज़रूरत नहीं होती

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

अहम जानकारी: अगर इस कोडलैब के दौरान किसी भी समय आपका Cloud Shell सेशन रीसेट हो जाता है, तो अपनी वर्किंग डायरेक्ट्री पर वापस जाएं और अपने प्रोजेक्ट के कॉन्फ़िगरेशन को वापस लाने के लिए, bash setup_verify_trial_project.sh && source .env को फिर से चलाएं. पुष्टि करें कि टर्मिनल प्रॉम्प्ट में पीले रंग का प्रोजेक्ट आईडी टेक्स्ट फिर से दिखता है.

शुरुआती इन्फ़्रास्ट्रक्चर सेटअप

सबसे पहले, हमें uv का इस्तेमाल करके, Python की डिपेंडेंसी इंस्टॉल करनी होंगी. यह Rust में लिखा गया, Python पैकेज और प्रोजेक्ट मैनेजर है. यह तेज़ी से काम करता है ( uv के दस्तावेज़ ). इस कोडलैब में, Python प्रोजेक्ट को बनाए रखने के लिए, इसका इस्तेमाल तेज़ी से और आसानी से किया जाता है

uv sync

इसके बाद, पूरा सेटअप स्क्रिप्ट चलाएं. इससे Cloud SQL इंस्टेंस बनता है, डेटा सीड किया जाता है, और Toolbox सेवा डिप्लॉय की जाती है. यह सेवा, हमारे रेस्टोरेंट एजेंट की शुरुआती स्थिति के तौर पर काम करेगी

bash scripts/full_setup.sh > logs/full_setup.log 2>&1 &

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

यह स्क्रिप्ट ये काम करेगी:

• Cloud SQL इंस्टेंस बनाएगी और डेटाबेस सीड करेगी (पहला चरण)
• एजेंट एनवायरमेंट कॉन्फ़िगरेशन जनरेट करेगी और लोकल Toolbox सेवा शुरू करेगी (दूसरा चरण)
• Toolbox और एजेंट सेवाओं को Cloud Run पर डिप्लॉय करेगी (तीसरा चरण)

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

source .env
AGENT_URL=$(gcloud run services describe restaurant-agent \
    --region="$REGION" \
    --format='value(status.url)')

echo "      ✓ Agent service deployed"
echo "      Agent URL: $AGENT_URL"
echo ""

एडीके Dev UI खोलें, restaurant_agent चुनें, और इन क्वेरी के साथ टेस्ट करें. जैसे, यह उदाहरण:

What Italian dishes do you have?

या,

I want something spicy and creamy

अब, अगला चरण यह है कि हम सिर्फ़ वेब डेवलपमेंट इंटरफ़ेस से Telegram मैसेजिंग चैनल पर कैसे जा सकते हैं

4. Telegram बॉट बनाना

Telegram, मैसेजिंग का एक लोकप्रिय और मुफ़्त प्लैटफ़ॉर्म है. इसका इस्तेमाल, कम्यूनिटी के साथ जुड़ने के लिए बड़े पैमाने पर किया जा रहा है. इसकी एक वजह यह है कि इसे आसानी से इंटिग्रेट किया जा सकता है. इसलिए, लोग अलग-अलग तरह के फ़ंक्शन वाले बॉट आसानी से बना सकते हैं.

हम पहली बार अपना बॉट बनाने के लिए, BotFather का इस्तेमाल करेंगे. ध्यान रखें कि इस सेशन के लिए हम Telegram का इस्तेमाल कर रहे हैं. हालांकि, WhatsApp या अपनी पसंद के अन्य मैसेजिंग प्लैटफ़ॉर्म के लिए भी इसी तरीके का इस्तेमाल किया जा सकता है.

अपना बॉट बनाने के लिए, BotFather का इस्तेमाल करना

अपना Telegram बॉट बनाने के लिए, वेब ब्राउज़र में https://telegram.me/BotFather पर जाएं.

BotFather के साथ इंटरैक्ट करना

/start निर्देश भेजना

BotFather का इस्तेमाल शुरू करने और अपना पहला बॉट बनाने के लिए, आपको BotFather को /start मैसेज भेजना होगा. इसके बाद, यह आपके साथ इंटरैक्ट करने के लिए, अपने सभी निर्देश शेयर करेगा.

/start

/newbot निर्देश से बॉट बनाना शुरू करना

BotFather को /newbot निर्देश भेजकर, अपना नया बॉट बनाते हैं. यह आपसे अपने बॉट का नाम पूछेगा. इसके बाद, यह आपसे बॉट का username देने के लिए कहेगा. इसके आखिर में हमेशा bot होना ज़रूरी है. उदाहरण के लिए, TetrisBot या tetris_bot. यह यूनीक होना चाहिए.

बॉट के बन जाने के बाद, आपको BotFather से यह मैसेज मिलेगा

Done! Congratulations on your new bot. You will find it at t.me/AdkTelegramTest_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.

Use this token to access the HTTP API:

<YOUR_TELEGRAM_API_KEY>

Keep your token secure and store it safely, it can be used by anyone to control your bot.

For a description of the Bot API, see this page: https://core.telegram.org/bots/api

YOUR_TELEGRAM_API_KEY नोट करें. हम इसका इस्तेमाल अगले सेक्शन में करेंगे.

5. Telegram वेबहुक ऐप्लिकेशन डेवलप करना

Telegram वेबहुक ऐप्लिकेशन डेवलप करने के लिए, वर्किंग डायरेक्ट्री तैयार करते हैं

mkdir ~/build-agent-adk-telegram/telegram-integration
cd ~/build-agent-adk-telegram

ज़रूरी डिपेंडेंसी जोड़ना

Telegram वेबहुक लिसनर स्क्रिप्ट के लिए ज़रूरी डिपेंडेंसी उपलब्ध कराने के लिए, requirements.txt स्क्रिप्ट बनाएं. इसमें यह कॉन्टेंट शामिल करें.

cloudshell edit ./telegram-integration/requirements.txt

इसके बाद, ये डिपेंडेंसी जोड़ें

python-telegram-bot[webhooks]
httpx

Telegram वेबहुक लिसनर के लिए स्क्रिप्ट बनाना

डिपेंडेंसी इंस्टॉल हो जाने के बाद. अब हम इंटिग्रेशन ऐप्लिकेशन के लिए, Python स्क्रिप्ट main.py बना सकते हैं

cloudshell edit ~/build-agent-adk-telegram/telegram-integration/main.py

इसके बाद, इसमें यह कोड कॉपी करें

# ./telegram-integration/main.py

import asyncio
import os
import sys
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, CallbackContext
from telegram.constants import ChatAction
import httpx

# Read token from environment variable
TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")
ADK_SERVER_URL = os.environ.get("ADK_SERVER_URL", "http://localhost:8000")
ADK_APP_NAME = os.environ.get("ADK_APP_NAME", "restaurant_agent")

# Parse base URL out of ADK_SERVER_URL
BASE_URL = ADK_SERVER_URL.rstrip('/')
if BASE_URL.endswith('/run'):
    BASE_URL = BASE_URL[:-4]
elif BASE_URL.endswith('/query'):
    BASE_URL = BASE_URL[:-6]

if not TOKEN:
    print("Error: TELEGRAM_BOT_TOKEN environment variable not set.")
    print("Please set it before running the application.")
    sys.exit(1)

async def start(update: Update, context: CallbackContext) -> None:
    """Send a message when the command /start is issued."""
    await update.message.reply_text('Hi! I am your ADK Integration Bot. Send me a message and I will forward it to the ADK server.')

async def send_typing_loop(chat_id: int, bot, stop_event: asyncio.Event):
    """Send typing action periodically until the stop event is set."""
    while not stop_event.is_set():
        try:
            await bot.send_chat_action(chat_id=chat_id, action=ChatAction.TYPING)
            # The research suggested repeating every 4 seconds
            await asyncio.sleep(4)
        except Exception as e:
            print(f"Error sending chat action: {e}")
            await asyncio.sleep(1) # Wait a bit before retrying if error

async def handle_message(update: Update, context: CallbackContext) -> None:
    """Handle incoming user messages."""
    user_message = update.message.text
    chat_id = update.message.chat_id
    raw_user_id = str(update.message.from_user.id)
    
    # Derive unique user_id and session_id for this user
    user_id = f"tg_{raw_user_id}"
    session_id = f"tg_sess_{raw_user_id}"

    print(f"Received message from {user_id}: {user_message}")

    # Create a stop event for the typing loop
    stop_event = asyncio.Event()
    
    # Start the typing loop as a background task
    typing_task = asyncio.create_task(send_typing_loop(chat_id, context.bot, stop_event))

    try:
        async with httpx.AsyncClient() as client:
            # 1. Check if the session exists
            session_url = f"{BASE_URL}/apps/{ADK_APP_NAME}/users/{user_id}/sessions/{session_id}"
            session_check = await client.get(session_url, timeout=10.0)
            
            if session_check.status_code == 404:
                # 2. If session doesn't exist, create it
                print(f"Session {session_id} not found. Creating session...")
                session_create = await client.post(session_url, json={}, timeout=10.0)
                if session_create.status_code != 200:
                    raise Exception(f"Failed to create session: {session_create.status_code} {session_create.text}")
            elif session_check.status_code != 200:
                raise Exception(f"Error checking session: {session_check.status_code} {session_check.text}")
            
            # 3. Run the ADK agent
            run_url = f"{BASE_URL}/run"
            payload = {
                "appName": ADK_APP_NAME,
                "userId": user_id,
                "sessionId": session_id,
                "newMessage": {
                    "role": "user",
                    "parts": [{"text": user_message}]
                }
            }
            response = await client.post(run_url, json=payload, timeout=60.0)
            
        if response.status_code == 200:
            events = response.json()
            if isinstance(events, list) and len(events) > 0:
                # The last event contains the final text response
                last_event = events[-1]
                content = last_event.get("content", {})
                parts = content.get("parts", [])
                if parts and "text" in parts[0]:
                    reply_text = parts[0]["text"]
                else:
                    reply_text = "ADK agent returned an empty or non-text response."
            else:
                reply_text = "No events returned from ADK agent."
        else:
            reply_text = f"Error communicating with ADK server (Status: {response.status_code})."
            
    except Exception as e:
        reply_text = f"Failed to connect to ADK server: {e}"
    finally:
        # Stop the typing loop
        stop_event.set()
        await typing_task

    # Send the final response back to the user
    await update.message.reply_text(reply_text)

def main() -> None:
    """Start the bot."""
    # Create the Application and pass it your bot's token.
    application = Application.builder().token(TOKEN).build()

    # on different commands - answer in Telegram
    application.add_handler(CommandHandler("start", start))

    # on non command i.e message - echo the message on Telegram
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))

    # Check if running in webhook mode (e.g., on Cloud Run)
    port = os.environ.get("PORT")
    service_url = os.environ.get("SERVICE_URL")

    if port and service_url:
        if not service_url.startswith("http"):
            service_url = f"https://{service_url}"
        
        print(f"Starting bot in WEBHOOK mode on port {port} with url {service_url}")
        
        application.run_webhook(
            listen="0.0.0.0",
            port=int(port),
            url_path=TOKEN,
            webhook_url=f"{service_url}/{TOKEN}",
            allowed_updates=Update.ALL_TYPES
        )
    else:
        print("Starting bot in POLLING mode")
        # Run the bot until the user presses Ctrl-C
        application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

Telegram बॉट इंटिग्रेशन कोड को समझना

जब कोई उपयोगकर्ता मैसेज भेजता है, तो handle_message() के तहत यह पाइपलाइन चलती है

पहला चरण: पहचान और सेशन की जानकारी पाना

बॉट, Telegram के उपयोगकर्ता आईडी को एडीके के यूनीक आइडेंटिफ़ायर से मैप करता है, ताकि उपयोगकर्ता के सेशन अलग-अलग रहें:

user_id = f"tg_{raw_user_id}"
session_id = f"tg_sess_{raw_user_id}"

दूसरा चरण: "टाइप किया जा रहा है" स्टेटस (लाइन 53–58)

एडीके एजेंट, प्रॉम्प्ट को प्रोसेस करने में कुछ सेकंड ले सकता है. इस दौरान, उपयोगकर्ता को बेहतर अनुभव देने के लिए, बॉट बैकग्राउंड में एसिंक्रोनस लूप शुरू करता है:

• asyncio.Event को stop_event के तौर पर इंस्टैंशिएट किया जाता है.
• asyncio.create_task बैकग्राउंड में send_typing_loop(...) को स्पॉन करता है.
• जब तक stop_event सेट नहीं हो जाता, तब तक लूप हर चार सेकंड में Telegram को ChatAction.TYPING ऐक्शन भेजता है.

तीसरा चरण: एडीके सेशन की पुष्टि करना और सेशन बनाना (लाइन 61–72)

एजेंट को एक्ज़ीक्यूट करने से पहले, बॉट यह जांचता है कि कोई सेशन पहले से मौजूद है या नहीं:

1. /apps/{appName}/users/{userId}/sessions/{sessionId} को GET अनुरोध भेजता है.
2. अगर जवाब 404 Not Found है, तो यह खाली JSON बॉडी के साथ, उसी यूआरएल को POST अनुरोध भेजकर सेशन बनाता है.
3. अगर 200 या 404 के अलावा कोई और स्टेटस मिलता है, तो एक अपवाद दिखता है.

चौथा चरण: एजेंट को अनुरोध भेजना (लाइन 74–85)

मैसेज पेलोड को एडीके /run एंडपॉइंट पर फ़ॉरवर्ड किया जाता है:

• एंडपॉइंट: POST /run
• अनुरोध का टाइम आउट 60.0 सेकंड पर सेट किया जाता है, ताकि जटिल तर्क या अपस्ट्रीम लेटेन्सी के लिए समय मिल सके.
• पेलोड स्ट्रक्चर:

{
  "appName": "restaurant_agent",
  "userId": "tg_<user_id>",
  "sessionId": "tg_sess_<user_id>",
  "newMessage": {
    "role": "user",
    "parts": [{"text": "<user_message>"}]
  }
}

पांचवां चरण: जवाब को पार्स करना (लाइन 87–101)

एडीके सर्वर, मैसेज इवेंट की सूची दिखाता है. बॉट, दिखाए गए अरे की जांच करता है:

• यह सूची में मौजूद आखिरी इवेंट (events[-1]) को वापस लाता है.
• यह event["content"]["parts"][0]["text"] के ज़रिए, टेक्स्ट कॉन्टेंट पर जाता है.
• अगर कोई इवेंट नहीं दिखाया जाता है या टेक्स्ट स्ट्रक्चर मौजूद नहीं है, तो जानकारी देने वाला प्लेसहोल्डर टेक्स्ट सेट किया जाता है.

छठा चरण: बंद करना और जवाब भेजना (लाइन 103–111)

• finally ब्लॉक में, stop_event सेट किया जाता है. इससे, टाइपिंग ऐक्शन लूप बंद हो जाता है.
• बॉट, संसाधनों को साफ़ रखने के लिए, typing_task के पूरा होने का इंतज़ार करता है.
• आखिर में, बॉट, पार्स किए गए जवाब के टेक्स्ट के साथ Telegram चैट का जवाब देता है.

6. Telegram वेबहुक ऐप्लिकेशन को Cloud Run पर डिप्लॉय करना

इसके बाद, हम Telegram वेबहुक लिसनर को Cloud Run पर डिप्लॉय करेंगे, ताकि हमारा बॉट उससे कम्यूनिकेट कर सके

Dockerfile बनाना

सबसे पहले, हमें Dockerfile बनाना होगा.

cloudshell edit ~/build-agent-adk-telegram/telegram-integration/Dockerfile

इसके बाद, इसमें यह कोड कॉपी करें

# Use an official Python runtime as a parent image
FROM python:3.11-slim

# Prevent Python from writing pyc files to disc and buffering stdout/stderr
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

# Set the working directory in the container
WORKDIR /app

# Install system dependencies if needed
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy the dependencies file to the working directory
COPY requirements.txt .

# Install any needed packages specified in requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Copy the rest of the application code
COPY main.py .

# Expose the port that Cloud Run will provide via environment variable
EXPOSE 8080

# Run main.py when the container launches
CMD ["python", "main.py"]

इमेज के फ़ुप्रिंट को छोटा रखने के लिए, सेवा को python:3.11-slim का इस्तेमाल करके कंटेनर में रखा जाता है:

• requirements.txt (python-telegram-bot[webhooks] और httpx) से डिपेंडेंसी इंस्टॉल करता है.
• स्टैंडर्ड पोर्ट 8080 को दिखाता है.
• python main.py लॉन्च करता है.

एनवायरमेंट वैरिएबल तैयार करना

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

AGENT_URL=$(gcloud run services describe restaurant-agent \
    --region="$REGION" \
    --format='value(status.url)')

echo "      ✓ Agent service deployed"
echo "      Agent URL: $AGENT_URL"
echo ""

इसके बाद, आइए TELEGRAM_BOT_TOKEN को .env में डालें. यह टोकन हमें पहले मिला था

ध्यान दें: YOUR_TELEGRAM_API_KEY को अपनी असली कुंजी से बदलना न भूलें

echo "TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_API_KEY" >> .env

इसके बाद, आइए .env डेटा में वे अन्य वैल्यू डालें जिनकी हमें ज़रूरत है.

echo "ADK_SERVER_URL=$AGENT_URL" >> .env
echo "ADK_APP_NAME=restaurant_agent" >> .env
echo "SERVICE_NAME=telegram-integration" >> .env
source .env

डिप्लॉयमेंट स्क्रिप्ट बनाना

आइए डिप्लॉयमेंट स्क्रिप्ट बनाएं. इससे पूरी जांच की जाएगी और ऐप्लिकेशन को Cloud Run पर डिप्लॉय किया जाएगा

cloudshell edit ~/build-agent-adk-telegram/telegram-integration/deploy.sh

इसके बाद, फ़ाइल में यह कोड कॉपी करें

#!/usr/bin/env bash
# ./telegram-integration/deploy.sh

# Exit immediately if a command exits with a non-zero status
set -euo pipefail

# Color codes for neat terminal output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0;37m' # No Color
# Load environment variables from .env if it exists
if [ -f .env ]; then
    echo -e "${GREEN}✔ Loading environment variables from .env...${NC}"
    export $(grep -v '^#' .env | xargs)
fi

echo -e "${BLUE}====================================================${NC}"
echo -e "${BLUE}   Google Cloud Run Deployment: Telegram Bot        ${NC}"
echo -e "${BLUE}====================================================${NC}"

# 1. Check for gcloud CLI
if ! command -v gcloud &> /dev/null; then
    echo -e "${RED}Error: 'gcloud' CLI is not installed.${NC}"
    echo "Please install the Google Cloud SDK and try again."
    echo "See: https://cloud.google.com/sdk/docs/install"
    exit 1
fi

# 2. Check active gcloud account/auth
ACTIVE_ACCOUNT=$(gcloud auth list --filter=status:ACTIVE --format="value(account)" 2>/dev/null || true)
if [ -z "$ACTIVE_ACCOUNT" ]; then
    echo -e "${RED}Error: No active Google Cloud account found.${NC}"
    echo "Please run: gcloud auth login"
    exit 1
fi

# 3. Detect / Prompt for GCP Project
DEFAULT_PROJECT=${GCP_PROJECT_ID:-$(gcloud config get-value project 2>/dev/null || true)}
if [ -n "${DEFAULT_PROJECT}" ]; then
    echo -e "${GREEN}✔ Using GCP Project: $DEFAULT_PROJECT${NC}"
    GCP_PROJECT="$DEFAULT_PROJECT"
else
    echo -n "Enter GCP Project ID: "
    read -r GCP_PROJECT
fi

if [ -z "$GCP_PROJECT" ]; then
    echo -e "${RED}Error: GCP Project ID is required.${NC}"
    exit 1
fi

# Set active project
gcloud config set project "$GCP_PROJECT" &> /dev/null

# 4. Configure Service Parameters
DEFAULT_SERVICE=${SERVICE_NAME:-"telegram-integration"}
if [ -n "${SERVICE_NAME:-}" ]; then
    echo -e "${GREEN}✔ Using Cloud Run Service Name: $SERVICE_NAME${NC}"
else
    echo -n "Enter Cloud Run Service Name [Default: $DEFAULT_SERVICE]: "
    read -r SERVICE_NAME
    SERVICE_NAME=${SERVICE_NAME:-$DEFAULT_SERVICE}
fi

DEFAULT_REGION=${REGION:-"us-central1"}
if [ -n "${REGION:-}" ]; then
    echo -e "${GREEN}✔ Using Cloud Run Region: $REGION${NC}"
else
    echo -n "Enter Cloud Run Region [Default: $DEFAULT_REGION]: "
    read -r REGION
    REGION=${REGION:-$DEFAULT_REGION}
fi

DEFAULT_ADK_APP=${ADK_APP_NAME:-"restaurant_agent"}
if [ -n "${ADK_APP_NAME:-}" ]; then
    echo -e "${GREEN}✔ Using ADK App Name: $ADK_APP_NAME${NC}"
    ADK_APP="$ADK_APP_NAME"
else
    echo -n "Enter ADK App Name [Default: $DEFAULT_ADK_APP]: "
    read -r ADK_APP
    ADK_APP=${ADK_APP:-$DEFAULT_ADK_APP}
fi

# 5. Retrieve/Prompt for Telegram Bot Token
if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
    echo -e "${GREEN}✔ Found TELEGRAM_BOT_TOKEN in environment.${NC}"
    BOT_TOKEN="$TELEGRAM_BOT_TOKEN"
else
    echo -e "${YELLOW}TELEGRAM_BOT_TOKEN is not set in your environment.${NC}"
    echo -n "Enter your Telegram Bot Token (input will be hidden): "
    read -s -r BOT_TOKEN
    echo ""
fi

if [ -z "$BOT_TOKEN" ]; then
    echo -e "${RED}Error: Telegram Bot Token is required.${NC}"
    exit 1
fi

# 6. Retrieve/Prompt for ADK Server URL
DEFAULT_ADK_URL="http://localhost:8000"
if [ -n "${ADK_SERVER_URL:-}" ]; then
    echo -e "${GREEN}✔ Found ADK_SERVER_URL in environment: $ADK_SERVER_URL${NC}"
    ADK_URL="$ADK_SERVER_URL"
else
    echo -n "Enter your ADK Server URL [Default: $DEFAULT_ADK_URL]: "
    read -r ADK_URL
    ADK_URL=${ADK_URL:-$DEFAULT_ADK_URL}
fi

# Enable required GCP services
echo -e "\n${YELLOW}Checking and enabling required GCP services...${NC}"
gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com --project "$GCP_PROJECT"

# Determine source directory dynamically
SOURCE_DIR="."
if [ -d "telegram-integration" ]; then
    SOURCE_DIR="telegram-integration"
    echo -e "${GREEN}✔ Found source directory: telegram-integration${NC}"
elif [ -f "Dockerfile" ]; then
    SOURCE_DIR="."
    echo -e "${GREEN}✔ Dockerfile found in current directory. Using current directory as source.${NC}"
else
    echo -e "${RED}Error: Could not find source directory 'telegram-integration' or Dockerfile in current directory.${NC}"
    exit 1
fi

# 7. First-pass Deployment with placeholder SERVICE_URL
# This boots the container in Webhook mode (so health check binds to port)
# but uses a high-reliability placeholder URL (google.com) to pass DNS verification checks.
echo -e "\n${YELLOW}Deploying to Cloud Run (Step 1/2: Initial Deploy)...${NC}"
gcloud run deploy "$SERVICE_NAME" \
  --source "$SOURCE_DIR" \
  --region "$REGION" \
  --allow-unauthenticated \
  --set-env-vars "TELEGRAM_BOT_TOKEN=$BOT_TOKEN,ADK_SERVER_URL=$ADK_URL,ADK_APP_NAME=$ADK_APP,SERVICE_URL=https://google.com" \
  --project "$GCP_PROJECT"

# 8. Retrieve the actual service URL
echo -e "\n${YELLOW}Retrieving service URL...${NC}"
SERVICE_URL=$(gcloud run services describe "$SERVICE_NAME" --region "$REGION" --project "$GCP_PROJECT" --format 'value(status.url)')
echo -e "${GREEN}✔ Service URL is: $SERVICE_URL${NC}"

# 9. Update service environment variables with the real SERVICE_URL
# This triggers a rolling update and registers the correct webhook with Telegram automatically!
echo -e "\n${YELLOW}Updating configuration with final Webhook URL (Step 2/2)...${NC}"
gcloud run services update "$SERVICE_NAME" \
  --region "$REGION" \
  --set-env-vars "TELEGRAM_BOT_TOKEN=$BOT_TOKEN,ADK_SERVER_URL=$ADK_URL,ADK_APP_NAME=$ADK_APP,SERVICE_URL=$SERVICE_URL" \
  --project "$GCP_PROJECT"

echo -e "\n${GREEN}====================================================${NC}"
echo -e "${GREEN}   Deployment Completed Successfully! 🎉            ${NC}"
echo -e "${GREEN}====================================================${NC}"
echo -e "Service Name:   ${BLUE}$SERVICE_NAME${NC}"
echo -e "Region:         ${BLUE}$REGION${NC}"
echo -e "Active URL:     ${BLUE}$SERVICE_URL${NC}"
echo -e "Webhook Path:   ${BLUE}$SERVICE_URL/<bot-token>${NC}"
echo -e "ADK Backend:    ${BLUE}$ADK_URL${NC}"
echo -e "ADK App Name:   ${BLUE}$ADK_APP${NC}"
echo -e "${GREEN}====================================================${NC}"
echo "Your Telegram Bot has been configured to use webhooks."
echo "Any message sent to your bot will now trigger this Cloud Run instance."

डबल-डिप्लॉय स्क्रिप्ट (deploy.sh)

Google Cloud Run पर डिप्लॉय करते समय, बॉट को अपने एनवायरमेंट में अपना यूआरएल (SERVICE_URL) बताना होता है, ताकि वह इसे Telegram के साथ वेबहुक टारगेट के तौर पर रजिस्टर कर सके. इस सर्कुलर डिपेंडेंसी को हल करने के लिए, deploy.sh दो चरणों में डिप्लॉयमेंट करता है. डिप्लॉयमेंट होने तक यूआरएल की जानकारी नहीं होती. हालांकि, सेवा को हेल्थ चेक में गड़बड़ी के बिना बूट अप करने के लिए, यूआरएल की ज़रूरत होती है:

1. पहला चरण: शुरुआती डिप्लॉयमेंट: कंटेनर को प्लेसहोल्डर डीएनएस (https://google.com) के साथ बूट करता है, ताकि सेवा सही तरीके से शुरू हो सके, लोकल पोर्ट से बाइंड हो सके, और शुरुआती Cloud Run हेल्थ चेक पास कर सके.
2. दूसरा चरण: यूआरएल फ़ेच करना: प्रोग्राम के ज़रिए, Cloud Run के नए एंडपॉइंट को एक्सट्रैक्ट करता है.gcloud run services describe
3. तीसरा चरण: कॉन्फ़िगरेशन अपडेट करना: एनवायरमेंट वैरिएबल को, लाइव सेवा के असली यूआरएल से अपडेट करता है. इससे Cloud Run में, रोलिंग अपडेट सही तरीके से ट्रिगर होता है और Telegram API के साथ सही वेबहुक टारगेट सुरक्षित तरीके से रजिस्टर होता है.

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

डिप्लॉयमेंट स्क्रिप्ट, एजेंट का यूआरएल प्रिंट करती है. Cloud Run पर चल रहे उसी एडीके Dev UI को ऐक्सेस करने के लिए, इसे अपने ब्राउज़र में खोलें.

cd ~/build-agent-adk-telegram
bash ./telegram-integration/deploy.sh

अगर सब कुछ ठीक रहा, तो अब Telegram चैट ऐप्लिकेशन से सीधे अपने बॉट से चैट की जा सकती है. इसके लिए, आपने जो बॉट बनाया है उसे ढूंढें और उसके साथ इंटरैक्ट करना शुरू करें:

What Italian dishes do you have?

या,

I want something spicy and creamy

देखें कि बॉट, "...टाइप किया जा रहा है" स्टेटस भेज रहा है. इसके बाद, यह एडीके से वह मैसेज वापस लाएगा जिसे आपने पहले बनाया था!

7. बधाई हो!

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

इस कोडलैब में, आपको यह सीखना है

• रेस्टोरेंट कंसीयर्ज, एडीके पर आधारित एजेंट, और MCP Toolbox को Cloud Run पर डिप्लॉय और कॉन्फ़िगर करना
• BotFather का इस्तेमाल करके, Telegram बॉट सेट अप करने का तरीका
• Telegram वेबहुक को सुनने और एडीके एजेंट के साथ इंटरैक्ट करने के लिए, Python स्क्रिप्ट लिखने का तरीका. इससे उपयोगकर्ताओं की क्वेरी और जवाब को आगे बढ़ाया जा सकता है
• Telegram में "... typing" को लागू करने का तरीका. इससे उपयोगकर्ताओं को रीयल टाइम में फ़ीडबैक मिलता है कि मैसेज प्रोसेस किए जा रहे हैं. ऐसा तब तक दिखता है, जब तक एडीके एजेंट से जवाब नहीं मिल जाता.
• Python स्क्रिप्ट को Cloud Run पर डिप्लॉय करने और उसके साथ इंटरैक्ट करने का तरीका

खाली करने के लिए जगह

अपने Google Cloud खाते पर शुल्क लगने से बचने के लिए, इस कोडलैब में बनाए गए संसाधन मिटाएं.

पहला विकल्प: प्रोजेक्ट मिटाना (सुझाया गया)

gcloud projects delete $GOOGLE_CLOUD_PROJECT

अहम जानकारी: इस मिटाने की कार्रवाई को सीमित समय के लिए वापस लाया जा सकता है. इसके लिए, यह निर्देश इस्तेमाल करें gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}

दूसरा विकल्प: एक-एक करके संसाधन मिटाना

# If you follow from previous A2A Agent Runtime codelab
# Delete the Agent Runtime deployment (skip if not found)
uv run python -c "
import vertexai
from google.genai import types
vertexai.init(project='$GOOGLE_CLOUD_PROJECT', location='$REGION')
client = vertexai.Client(
    project='$GOOGLE_CLOUD_PROJECT', location='$REGION',
    http_options=types.HttpOptions(api_version='v1beta1'),
)
try:
    agent = client.agent_engines.get(name='$RESERVATION_AGENT_RESOURCE_NAME')
    agent.delete(force=True)
    print('Agent Runtime deployment deleted.')
except Exception as e:
    print(f'No agent deployment found or already deleted, skipping. ({e})')
"

# Delete GCS staging bucket (skip if STAGING_BUCKET is not set)
if [ -n "$STAGING_BUCKET" ]; then
  gsutil rm -r gs://$STAGING_BUCKET
else
  echo "STAGING_BUCKET not set, skipping bucket deletion."
fi

# Delete Cloud Run services
gcloud run services delete restaurant-agent --region=$REGION --quiet
gcloud run services delete toolbox-service --region=$REGION --quiet
gcloud run services delete telegram-integration --region=$REGION --quiet

# Delete Cloud SQL instance
gcloud sql instances delete $DB_INSTANCE --quiet