Vertex AI Agents को Google Workspace के साथ इंटिग्रेट करना

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

Vertex AI क्या है?

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

Model Garden को ऐक्सेस करें: इसमें 150 से ज़्यादा फ़ाउंडेशन मॉडल उपलब्ध हैं. इनमें Gemini के सभी मॉडल, तीसरे पक्ष के मॉडल, और खास ओपन-सोर्स मॉडल शामिल हैं. इनसे आपको एजेंट के खास कामों के लिए सही मॉडल चुनने में मदद मिलेगी.
मुश्किल ऑर्केस्ट्रेशन तैयार करना: Vertex AI, अपने-आप काम करने वाले एजेंट डिज़ाइन करने के लिए फ़्रेमवर्क उपलब्ध कराता है. ये एजेंट, तर्क का इस्तेमाल करके कई चरणों वाले टास्क को प्लान करते हैं, उन्हें पूरा करते हैं, और बाहरी एपीआई को कॉल करते हैं.
एंटरप्राइज़-ग्रेड ग्राउंडिंग: एजेंट को कारोबार के लाइव डेटा से कनेक्ट करें. इसमें बेहतर परफ़ॉर्मेंस वाला आरएजी (रीट्रिवल-ऑगमेंटेड जनरेशन) शामिल है, ताकि भ्रम वाली जानकारी को हटाया जा सके और तथ्यों की पुष्टि की जा सके.
DevOps: एजेंट डेवलपमेंट को मौजूदा CI/CD पाइपलाइन में आसानी से इंटिग्रेट करें. इसके लिए, मज़बूत एसडीके, एपीआई, और आकलन टूल का इस्तेमाल करें. इससे, एजेंट की परफ़ॉर्मेंस और सुरक्षा को बड़े पैमाने पर मेज़र किया जा सकता है.
बेहद मज़बूत सुरक्षा: Vertex AI यह पक्का करता है कि ट्रेनिंग या ग्राउंडिंग के लिए इस्तेमाल किया गया ग्राहक का डेटा निजी, एन्क्रिप्ट (सुरक्षित) किया गया हो. साथ ही, यह डेटा रेज़िडेंसी से जुड़ी वैश्विक शर्तों का पालन करता हो.
ऑप्टिमाइज़ किया गया इंफ़्रास्ट्रक्चर: Google के वर्ल्ड-क्लास टीपीयू और जीपीयू क्लस्टर पर, एजेंटिक वर्कलोड को आसानी से स्केल करें. इससे, दुनिया भर में इस्तेमाल होने वाले सबसे ज़्यादा मांग वाले ऐप्लिकेशन के लिए भी, कम-लेटेंसी वाली परफ़ॉर्मेंस मिलती है.

Google Workspace क्या है?

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

कम्यूनिकेशन: प्रोफ़ेशनल ईमेल सेवाएं (Gmail), वीडियो कॉन्फ़्रेंसिंग (Meet), और टीम मैसेजिंग (Chat).
कॉन्टेंट बनाना: दस्तावेज़ लिखने (Docs), स्प्रेडशीट बनाने (Sheets), और प्रज़ेंटेशन डिज़ाइन करने (Slides) के लिए टूल.
संगठन: शेयर किए गए कैलेंडर (Calendars) और डिजिटल नोट लेने की सुविधा (Keep).
स्टोरेज: फ़ाइलों को सुरक्षित तरीके से सेव और शेयर करने के लिए, क्लाउड स्टोरेज की सुविधा (Drive).
मैनेजमेंट: उपयोगकर्ताओं और सुरक्षा सेटिंग को मैनेज करने के लिए एडमिन कंट्रोल (Workspace Admin Console).

किस तरह के कस्टम इंटिग्रेशन?

Google Workspace और Vertex AI मिलकर, एक बेहतरीन फ़ीडबैक लूप बनाते हैं. इसमें Workspace, रीयल-टाइम डेटा और साथ मिलकर काम करने से जुड़ा कॉन्टेक्स्ट उपलब्ध कराता है. वहीं, Vertex AI, स्मार्ट वर्कफ़्लो को ऑटोमेट करने के लिए ज़रूरी मॉडल, एजेंटिक रीज़निंग, और ऑर्केस्ट्रेशन उपलब्ध कराता है.

स्मार्ट कनेक्टिविटी: Google के मैनेज किए गए डेटा स्टोर, एपीआई, और एमसीपी सर्वर (Google के मैनेज किए गए और कस्टम) की मदद से एजेंट, Workspace डेटा को सुरक्षित और आसानी से ऐक्सेस कर सकते हैं. साथ ही, उपयोगकर्ताओं की ओर से कार्रवाइयां कर सकते हैं.
कस्टम एजेंट: नो-कोड डिज़ाइनर या प्रो-कोड फ़्रेमवर्क का इस्तेमाल करके, टीमें खास एजेंट बना सकती हैं. ये एजेंट, एडमिन के कंट्रोल वाले Workspace डेटा और कार्रवाइयों पर आधारित होते हैं.
नेटिव इंटिग्रेशन: Workspace ऐड-ऑन, एआई सिस्टम और Chat और Gmail जैसे ऐप्लिकेशन के बीच के अंतर को कम करते हैं. ऐसा, यूज़र इंटरफ़ेस (यूआई) के कॉम्पोनेंट या बैकग्राउंड प्रोसेस के ज़रिए किया जाता है. इससे एजेंट, उपयोगकर्ताओं को उसी जगह पर तुरंत मदद दे पाते हैं जहां वे मौजूद हैं. साथ ही, उन्हें संदर्भ के हिसाब से सहायता मिलती है.

Google Workspace के प्रॉडक्टिविटी बढ़ाने वाले दमदार ईकोसिस्टम को Vertex AI की बेहतर एजेंटिक क्षमताओं के साथ जोड़कर, संगठन अपने कामकाज में बदलाव कर सकते हैं. इसके लिए, वे डेटा पर आधारित कस्टम एआई एजेंट का इस्तेमाल कर सकते हैं. ये एजेंट, मुश्किल वर्कफ़्लो को सीधे तौर पर उन टूल में ऑटोमेट करते हैं जिन्हें उनकी टीमें रोज़ाना इस्तेमाल करती हैं.

ज़रूरी शर्तें

अगर आपको अपने एनवायरमेंट में सभी चरणों को फ़ॉलो करना है, तो आपको इनकी ज़रूरत होगी:

Google Cloud और Python की बुनियादी जानकारी.
आपके पास बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट होना चाहिए. यह देखने के लिए कि किसी मौजूदा प्रोजेक्ट के लिए बिलिंग की सुविधा चालू है या नहीं, अपने प्रोजेक्ट के बिलिंग स्टेटस की पुष्टि करना लेख पढ़ें. प्रोजेक्ट बनाने और बिलिंग सेट अप करने के लिए, Google Cloud प्रोजेक्ट बनाना लेख पढ़ें. प्रोजेक्ट का मालिकाना हक बदलने के लिए, प्रोजेक्ट के सदस्यों को मैनेज करना या प्रोजेक्ट का मालिकाना हक बदलना लेख पढ़ें.
आपके पास Business या Enterprise वर्शन वाला Google Workspace खाता होना चाहिए. साथ ही, आपके पास Google Chat का ऐक्सेस होना चाहिए और स्मार्ट सुविधाएं चालू होनी चाहिए.
Google Cloud प्रोजेक्ट के लिए, Google Cloud CLI इंस्टॉल और शुरू किया गया हो.
Python 3.11+ इंस्टॉल किया गया हो. इसके लिए, Python की आधिकारिक वेबसाइट पर दिए गए निर्देश देखें.

आपको क्या बनाना है

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

Vertex AI Search ऐप्लिकेशन

इस एजेंट की मदद से, उपयोगकर्ता अपनी आम भाषा में Workspace के डेटा को खोज सकते हैं और कार्रवाइयां कर सकते हैं. यह इन एलिमेंट पर निर्भर करता है:

मॉडल: Gemini.
डेटा और कार्रवाइयां: Google Workspace (Calendar, Gmail, Drive) के लिए Vertex AI डेटा स्टोर.
एजेंट होस्ट: Vertex AI Search.
यूज़र इंटरफ़ेस (यूआई): Vertex AI Search का वेब विजेट.

कस्टम एजेंट

इस एजेंट की मदद से, उपयोगकर्ता अपनी आम भाषा में Workspace का डेटा खोज सकते हैं और कस्टम टूल और नियमों का इस्तेमाल करके कार्रवाइयां कर सकते हैं. यह इन एलिमेंट पर निर्भर करता है:

मॉडल: Gemini.
डेटा और कार्रवाइयां: Google Workspace (Calendar, Gmail, Drive) के लिए Vertex AI डेटा स्टोर, Google के मैनेज किए गए Vertex AI Search Model Context Protocol (MCP) सर्वर, Google Chat के मैसेज भेजने के लिए कस्टम टूल फ़ंक्शन (Google Chat API के ज़रिए).
एजेंट बनाने के टूल: एजेंट डेवलपमेंट किट (एडीके).
एजेंट होस्ट: Vertex AI Agent Engine.
यूज़र इंटरफ़ेस (यूआई): ADK Web.

Google Workspace ऐड-ऑन के तौर पर एजेंट

इस एजेंट की मदद से उपयोगकर्ता, Workspace ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) में, Workspace के लिए अपनी भाषा में डेटा खोज सकते हैं. यह इन एलिमेंट पर निर्भर करता है:

मॉडल: Gemini.
डेटा और कार्रवाइयां: Google Workspace (Calendar, Gmail, Drive) के लिए Vertex AI डेटा स्टोर, Google के मैनेज किए गए Vertex AI Search Model Context Protocol (MCP) सर्वर, Google Chat के मैसेज भेजने के लिए कस्टम टूल फ़ंक्शन (Google Chat API के ज़रिए).
एजेंट बनाने के टूल: एजेंट डेवलपमेंट किट (एडीके).
एजेंट होस्ट: Vertex AI Agent Engine.
यूज़र इंटरफ़ेस (यूआई): Chat और Gmail के लिए Google Workspace ऐड-ऑन. इसे Calendar, Drive, Docs, Sheets, और Slides के लिए आसानी से बढ़ाया जा सकता है.
Google Workspace ऐड-ऑन: Apps Script, Vertex AI Agent Engine API, कॉन्टेक्स्ट के हिसाब से (चुनिंदा Gmail मैसेज).

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

Vertex AI Search और Google Workspace के बीच इंटिग्रेशन पॉइंट, जो डेटा और कार्रवाइयों को चालू करते हैं.
Vertex AI में होस्ट किए गए कस्टम एजेंट बनाने के विकल्प.
उपयोगकर्ता, Vertex AI Search के वेब विजेट और Google Workspace ऐप्लिकेशन जैसे एजेंट को कैसे ऐक्सेस कर सकते हैं.

2. सेट अप करें

समाधान बनाने से पहले, हमें प्रोजेक्ट की Vertex AI Applications सेटिंग को शुरू करना होगा. साथ ही, ज़रूरी एपीआई चालू करने होंगे और Vertex AI Workspace डेटा स्टोर बनाने होंगे.

कॉन्सेप्ट की समीक्षा करें

Vertex AI ऐप्लिकेशन

Vertex AI ऐप्लिकेशन, Google Cloud पर मैनेज किया जाने वाला एंड-टू-एंड समाधान है. यह मशीन लर्निंग मॉडल (जैसे कि जनरेटिव एआई एजेंट या सर्च इंजन) को एंटरप्राइज़ डेटा और खास टूल के साथ इंटिग्रेट करता है. इससे सिमैंटिक सर्च, कॉन्टेंट जनरेट करने या ग्राहकों से अपने-आप बातचीत करने जैसे मुश्किल टास्क किए जा सकते हैं.

Vertex AI data store

Vertex AI डेटा स्टोर एक ऐसी इकाई होती है जिसमें पहले पक्ष (ग्राहक) के डेटा सोर्स से लिया गया डेटा होता है. जैसे, Google Workspace या तीसरे पक्ष के ऐप्लिकेशन, जैसे कि Jira या Shopify. डेटा कनेक्टर, ऐसे डेटा स्टोर होते हैं जिनमें तीसरे पक्ष के ऐप्लिकेशन का डेटा होता है.

Vertex AI Applications की सेटिंग शुरू करना

एजेंट बनाने की सुविधा चालू करने के लिए, Vertex AI Applications की सेटिंग शुरू करें.

Google Cloud Console को नए टैब में खोलें. इसके बाद, यह तरीका अपनाएं:

अपना प्रोजेक्ट चुनें.
Google Cloud के खोज फ़ील्ड में, एआई ऐप्लिकेशन पर जाएं

नियमों को पढ़ने और उनसे सहमत होने के बाद, जारी रखें और एपीआई चालू करें पर क्लिक करें.
Settings पर जाएं.
पुष्टि टैब में जाकर, global में बदलाव करें.

Google Identity को चुनें. इसके बाद, सेव करें पर क्लिक करें.

एपीआई चालू करें

Vertex AI Workspace के डेटा स्टोर के लिए, इन एपीआई को चालू करना ज़रूरी है:

Google Cloud console में जाकर, Calendar, Gmail, और People API चालू करें:

मेन्यू ☰ > एपीआई और सेवाएं > चालू किए गए एपीआई और सेवाएं पर क्लिक करें. इसके बाद, पुष्टि करें कि सूची में Google Calendar API, Gmail API, और People API मौजूद हैं.

डेटा स्टोर बनाना

Google Drive डेटा स्टोर बनाएं:

Google Cloud Console में, एआई ऐप्लिकेशन पर जाएं. इसके बाद, डेटा स्टोर पर जाएं.

+ डेटा स्टोर बनाएं पर क्लिक करें.
सोर्स में, Google Drive में जाकर, चुनें पर क्लिक करें.

डेटा में जाकर, सभी चुनें. इसके बाद, जारी रखें पर क्लिक करें.

कॉन्फ़िगरेशन में, डेटा कनेक्टर का नाम को drive पर सेट करें. इसके बाद, लागू होने वाले शुल्क की समीक्षा करें और उनसे सहमत हों. इसके बाद, जारी रखें पर क्लिक करें.

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

Google Calendar डेटा स्टोर बनाएं:

+ डेटा स्टोर बनाएं पर क्लिक करें.
सोर्स में, Google Calendar खोजें और चुनें पर क्लिक करें.
कार्रवाइयां सेक्शन में, स्किप करें पर क्लिक करें.
कॉन्फ़िगरेशन सेक्शन में, डेटा कनेक्टर का नाम calendar पर सेट करें.
बनाएं पर क्लिक करें.
आपको अपने-आप डेटा स्टोर पर रीडायरेक्ट कर दिया जाएगा. यहां आपको नया जोड़ा गया डेटा स्टोर दिखेगा.

Google Gmail डेटा स्टोर बनाएं:

+ नया डेटा स्टोर पर क्लिक करें.
सोर्स में, Google Gmail खोजें और चुनें पर क्लिक करें.
कार्रवाइयां सेक्शन में, स्किप करें पर क्लिक करें.
कॉन्फ़िगरेशन सेक्शन में, डेटा कनेक्टर का नाम gmail पर सेट करें.
बनाएं पर क्लिक करें.
आपको अपने-आप डेटा स्टोर पर रीडायरेक्ट कर दिया जाएगा. यहां आपको नया जोड़ा गया डेटा स्टोर दिखेगा.

3. Vertex AI Search ऐप्लिकेशन

मॉडल: Gemini.
डेटा और कार्रवाइयां: Google Workspace (Calendar, Gmail, Drive) के लिए Vertex AI डेटा स्टोर.
एजेंट होस्ट: Vertex AI Search.
यूज़र इंटरफ़ेस (यूआई): Vertex AI Search का वेब विजेट.

कॉन्सेप्ट की समीक्षा करना

Vertex AI Search ऐप्लिकेशन

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

Vertex AI Search Web Widget, पहले से तैयार किया गया यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट है. इसे पसंद के मुताबिक बनाया जा सकता है. इसकी मदद से डेवलपर, एआई की मदद से काम करने वाले सर्च बार और नतीजों के इंटरफ़ेस को सीधे तौर पर किसी वेबसाइट में एम्बेड कर सकते हैं. इसके लिए, उन्हें बहुत कम कोडिंग करनी पड़ती है.

Vertex AI Search की झलक

Vertex AI Search की झलक दिखाने की सुविधा, Google Cloud Console में पहले से मौजूद टेस्टिंग एनवायरमेंट है. इसकी मदद से डेवलपर, सर्च कॉन्फ़िगरेशन और जनरेटिव जवाबों की पुष्टि कर सकते हैं. इसके बाद, वे उन सेटिंग को प्रोडक्शन के लिए तैयार Vertex AI Search वेब विजेट में आसानी से डिप्लॉय कर सकते हैं.

समाधान के आर्किटेक्चर की समीक्षा करना

ऐप्लिकेशन बनाएं

अपने डेटा स्टोर को ऐंकर करने के लिए, एक नया सर्च ऐप्लिकेशन बनाएं.

Cloud Console में जाकर, एआई ऐप्लिकेशन > ऐप्लिकेशन खोलें. इसके बाद, यह तरीका अपनाएं:

+ ऐप्लिकेशन बनाएं पर क्लिक करें.
टाइप में जाकर, कस्टम खोज (सामान्य) में जाकर, बनाएं पर क्लिक करें.

कॉन्फ़िगरेशन में जाकर, Enterprise Edition की सुविधाएं और जनरेटिव जवाब को चुनें. इससे पहले, इनकी कीमत की समीक्षा कर लें और उसे स्वीकार कर लें.
ऐप्लिकेशन का नाम को codelab पर सेट करें.
नाम के आधार पर एक आईडी जनरेट होता है और उसे फ़ील्ड में दिखाया जाता है. इसे कॉपी करें.
कंपनी का नाम को Codelab पर सेट करें.
एक से ज़्यादा क्षेत्र को global (Global) पर सेट करें.
जारी रखें पर क्लिक करें.

डेटा में जाकर, Drive, Gmail, और Calendar डेटा स्टोर चुनें. इसके बाद, जारी रखें पर क्लिक करें.

कीमत में जाकर, अपने हिसाब से कीमत का मॉडल चुनें. इसके बाद, बनाएं पर क्लिक करें. इस कोडलैब के हिसाब से, सामान्य कीमत तय करने का सुझाव दिया जाता है.
ऐप्लिकेशन बन जाता है. इसके बाद, आपको एआई ऐप्लिकेशन > ऐप्लिकेशन > codelab > ऐप्लिकेशन की खास जानकारी पर अपने-आप रीडायरेक्ट कर दिया जाता है.
कनेक्ट किए गए डेटा स्टोर पर जाएं.
कुछ मिनट बाद, कनेक्ट किए गए सभी डेटा स्टोर का स्टेटस चालू है होना चाहिए.

Search विजेट के दिखने के तरीके और उसके काम करने के तरीके को कॉन्फ़िगर करें.

कॉन्फ़िगरेशन पर जाएं.
यूज़र इंटरफ़ेस टैब में, खोज का टाइप को फ़ॉलो-अप के साथ खोजें पर सेट करें. इसके बाद, सेव करें और पब्लिश करें पर क्लिक करें.

ऐप्लिकेशन आज़माएँ

Google Cloud Console में जाकर, सीधे तौर पर Search ऐप्लिकेशन को टेस्ट करें.

झलक देखें पर जाएं. यहां आपको वेब विजेट दिखेगा.
चैट में, Do I have any meetings today? टाइप करें और enter दबाएं.
चैट में, Did I receive an email on March 1st 2026? टाइप करें और enter दबाएं.
चैट में, Give me the title of the latest Drive file I created टाइप करें और enter दबाएं.

4. कस्टम एजेंट

मॉडल: Gemini.
डेटा और कार्रवाइयां: Google Workspace (Calendar, Gmail, Drive) के लिए Vertex AI डेटा स्टोर, Google के मैनेज किए गए Vertex AI Search Model Context Protocol (MCP) सर्वर, Google Chat के मैसेज भेजने के लिए कस्टम टूल फ़ंक्शन (Google Chat API के ज़रिए).
एजेंट बनाने के टूल: एजेंट डेवलपमेंट किट (एडीके).
एजेंट होस्ट: Vertex AI Agent Engine.
यूज़र इंटरफ़ेस (यूआई): ADK Web.

कॉन्सेप्ट की समीक्षा करें

Agent Development Kit (ADK)

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

मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी)

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

फ़ंक्शन टूल

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

ADK Web

ADK web, ADK SDK के साथ आने वाला एक बिल्ट-इन देव यूज़र इंटरफ़ेस (यूआई) है. इससे डेवलपमेंट और डीबग करना आसान हो जाता है.

समाधान के आर्किटेक्चर की समीक्षा करना

सोर्स कोड की समीक्षा करना

agent.py

नीचे दिए गए कोड से, Vertex AI की पुष्टि होती है. साथ ही, Vertex AI Search MCP और Chat API टूल शुरू होते हैं. इसके अलावा, इससे एजेंट के व्यवहार के बारे में पता चलता है.

पुष्टि करना: यह एनवायरमेंट वैरिएबल से ACCESS_TOKEN को वापस पाता है, ताकि एमसीपी और एपीआई कॉल की पुष्टि की जा सके.
टूल सेटअप: यह vertexai_mcp को शुरू करता है. यह टूलसेट, Vertex AI Search के मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर और send_direct_message टूल से कनेक्ट होता है. इससे एजेंट को, कनेक्ट किए गए डेटा स्टोर में खोजने और Google Chat पर मैसेज भेजने की सुविधा मिलती है.
एजेंट की परिभाषा: इसमें gemini-2.5-flash मॉडल का इस्तेमाल करके, root_agent के बारे में बताया गया है. इन निर्देशों में एजेंट को बताया जाता है कि जानकारी पाने के लिए, खोज टूल का इस्तेमाल सबसे पहले किया जाए. साथ ही, कार्रवाइयां करने के लिए send_direct_message टूल का इस्तेमाल किया जाए. इससे एजेंट को आपके एंटरप्राइज़ डेटा के बारे में सटीक जानकारी मिलती है.

...
MODEL = "gemini-2.5-flash"

# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
    raise ValueError("ACCESS_TOKEN environment variable must be set")

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def send_direct_message(email: str, message: str) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=ACCESS_TOKEN)
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT,
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    ),
    tool_filter=['search']
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

सोर्स कोड डाउनलोड करना

शुरू करने के लिए, सैंपल कोड को अपने लोकल एनवायरमेंट में डाउनलोड करें.

GitHub की इस रिपॉज़िटरी को डाउनलोड करें.

टर्मिनल में, solutions/enterprise-ai-agent-local डायरेक्ट्री खोलें.

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

इस समाधान के लिए, इन एपीआई को चालू करना ज़रूरी है:

Google Cloud Console में जाकर, Vertex AI, Cloud Resource Manager, और Google Chat API चालू करें:

मेन्यू ☰ > एपीआई और सेवाएं > चालू किए गए एपीआई और सेवाएं पर क्लिक करें. इसके बाद, पुष्टि करें कि Vertex AI API, Cloud Resource Manager API, और Google Chat API सूची में शामिल हैं.

इस समाधान के लिए, सहमति वाली स्क्रीन को कॉन्फ़िगर करना ज़रूरी है:

Google Cloud console में, मेन्यू ☰ > Google Auth platform > ब्रैंडिंग पर क्लिक करें.

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

कॉन्फ़िगरेशन सेव हो जाता है और आपको Google Auth Platform > खास जानकारी पर अपने-आप रीडायरेक्ट कर दिया जाता है.

ज़्यादा जानने के लिए, OAuth की सहमति कॉन्फ़िगर करना गाइड पढ़ें.

OAuth क्लाइंट के क्रेडेंशियल बनाना

लोकल एनवायरमेंट में उपयोगकर्ता की पुष्टि करने के लिए, नया डेस्कटॉप ऐप्लिकेशन OAuth क्लाइंट बनाएं:

Google Cloud console में, मेन्यू ☰ > Google Auth platform > क्लाइंट पर क्लिक करें.

+ क्लाइंट बनाएं पर क्लिक करें.
ऐप्लिकेशन टाइप के लिए, डेस्कटॉप ऐप्लिकेशन चुनें.
नाम को codelab पर सेट करें.
बनाएं पर क्लिक करें. आपको नया क्रेडेंशियल दिखेगा.
JSON फ़ाइल डाउनलोड करें पर क्लिक करें. इसके बाद, फ़ाइल को solutions/enterprise-ai-agent-local डायरेक्ट्री में client_secret.json के तौर पर सेव करें.

Vertex AI Search MCP चालू करना

टर्मिनल में, यह कमांड चलाएं:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

Chat ऐप्लिकेशन को कॉन्फ़िगर करना

Google Chat ऐप्लिकेशन को बुनियादी जानकारी के साथ कॉन्फ़िगर करें.

Google Cloud Console में, Google Cloud के खोज फ़ील्ड में Google Chat API खोजें. इसके बाद, Google Chat API पर क्लिक करें. इसके बाद, मैनेज करें पर क्लिक करें और फिर कॉन्फ़िगरेशन पर क्लिक करें.

ऐप्लिकेशन का नाम और ब्यौरे को Vertex AI पर सेट करें.
अवतार का यूआरएल एट्रिब्यूट की वैल्यू को https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png पर सेट करें.
इंटरैक्टिव सुविधाएं चालू करें से चुने का निशान हटाएं. इसके बाद, दिखने वाले मोडल डायलॉग में बंद करें पर क्लिक करें.
Log errors to Logging को चुनें.
सेव करें पर क्लिक करें.

ADK वेब में एजेंट को चलाना

ADK के वेब इंटरफ़ेस का इस्तेमाल करके, एजेंट को स्थानीय तौर पर लॉन्च करें.

टर्मिनल में, solutions/enterprise-ai-agent-local डायरेक्ट्री खोलें. इसके बाद, यह कमांड चलाएं:

# 1. Authenticate with all the required scopes
gcloud auth application-default login \
  --client-id-file=client_secret.json \
   --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.messages

# 2. Configure environment
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1

# 3. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 4. Install poetry and project dependencies
pip install poetry
poetry install

# 5. Start ADK Web
adk web

एजेंट आज़माएँ

अपने कस्टम एजेंट से चैट करके, फ़्लो की पुष्टि करें.

अपने इंटरनेट ब्राउज़र में, ADK की वेबसाइट खोलें.
चैट में, Please find my meetings for today, I need their titles and links टाइप करें और enter दबाएं.
एजेंट, उपयोगकर्ता के खाते के हिसाब से कैलेंडर इवेंट की सूची के साथ जवाब देता है.
चैट में, Please send a Chat message to someone@example.com with the following text: Hello! टाइप करें और enter दबाएं.
एजेंट, पुष्टि करने वाले मैसेज के साथ जवाब देता है.

5. Google Workspace ऐड-ऑन के तौर पर एजेंट

मॉडल: Gemini.
डेटा और कार्रवाइयां: Google Workspace (Calendar, Gmail, Drive) के लिए Vertex AI डेटा स्टोर, Google के मैनेज किए गए Vertex AI Search Model Context Protocol (MCP) सर्वर, Google Chat के मैसेज भेजने के लिए कस्टम टूल फ़ंक्शन (Google Chat API के ज़रिए).
एजेंट बनाने के टूल: एजेंट डेवलपमेंट किट (एडीके).
एजेंट होस्ट: Vertex AI Agent Engine.
यूज़र इंटरफ़ेस (यूआई): Chat और Gmail के लिए Google Workspace ऐड-ऑन. इसे Calendar, Drive, Docs, Sheets, और Slides के लिए आसानी से बढ़ाया जा सकता है.
Google Workspace ऐड-ऑन: Apps Script, Vertex AI Agent Engine API, कॉन्टेक्स्ट के हिसाब से (चुनिंदा Gmail मैसेज).

कॉन्सेप्ट की समीक्षा करना

Google Workspace ऐड-ऑन

Google Workspace ऐड-ऑन, पसंद के मुताबिक बनाया गया एक ऐप्लिकेशन होता है. यह Google Workspace के एक या उससे ज़्यादा ऐप्लिकेशन (Gmail, Chat, Calendar, Docs, Drive, Meet, Sheets, और Slides) की सुविधाओं को बढ़ाता है.

Apps Script

Apps Script, क्लाउड पर आधारित एक JavaScript प्लैटफ़ॉर्म है. यह Google Drive पर काम करता है. इसकी मदद से, Google के सभी प्रॉडक्ट को इंटिग्रेट किया जा सकता है और उनमें किए जाने वाले टास्क को ऑटोमेट किया जा सकता है.

Google Workspace Card framework

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

समाधान के आर्किटेक्चर की समीक्षा करना

सोर्स कोड की समीक्षा करना

Agent

agent.py

पुष्टि करना: यह क्लाइंट की ओर से इंजेक्ट किए गए पुष्टि करने वाले टोकन (CLIENT_AUTH_NAME) को वापस पाने के लिए, हेल्पर फ़ंक्शन _get_access_token_from_context का इस्तेमाल करता है. यह टोकन, Vertex AI Search MCP और Google Chat टूल जैसी डाउनस्ट्रीम सेवाओं को सुरक्षित तरीके से कॉल करने के लिए ज़रूरी है.
टूल सेटअप: यह vertexai_mcp को शुरू करता है. यह टूलसेट, Vertex AI Search के मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) सर्वर और send_direct_message टूल से कनेक्ट होता है. इससे एजेंट को, कनेक्ट किए गए डेटा स्टोर में खोजने और Google Chat पर मैसेज भेजने की सुविधा मिलती है.
एजेंट की परिभाषा: इसमें gemini-2.5-flash मॉडल का इस्तेमाल करके, root_agent के बारे में बताया गया है. इन निर्देशों में एजेंट को बताया जाता है कि जानकारी पाने के लिए, खोज टूल का इस्तेमाल सबसे पहले किया जाए. साथ ही, कार्रवाइयां करने के लिए send_direct_message टूल का इस्तेमाल किया जाए. इससे एजेंट को आपके एंटरप्राइज़ डेटा के बारे में सटीक जानकारी मिलती है.

...
MODEL = "gemini-2.5-flash"

# Client injects a bearer token into the ToolContext state.
# The key pattern is "CLIENT_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
CLIENT_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Helper method to dynamically parse the intercepted bearer token from the context state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    # Handle ADK varying state object types (Raw Dict vs ADK State)
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

def send_direct_message(email: str, message: str, tool_context: ToolContext) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=_get_access_token_from_context(tool_context))
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT
    ),
    tool_filter=['search'],
    # The auth_header_provider dynamically injects the bearer token from the ToolContext
    # into the MCP call for authentication.
    header_provider=auth_header_provider
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

क्लाइंट

appsscript.json

यहां दिए गए कॉन्फ़िगरेशन में, ऐड-ऑन के ट्रिगर और अनुमतियों के बारे में बताया गया है.

ऐड-ऑन के बारे में जानकारी देता है: इससे Workspace को पता चलता है कि यह प्रोजेक्ट, Chat और Gmail, दोनों के लिए एक ऐड-ऑन है.
कॉन्टेक्स्ट के हिसाब से ट्रिगर: Gmail के लिए, यह एक contextualTrigger सेट अप करता है. यह onAddonEvent तब ट्रिगर होता है, जब कोई उपयोगकर्ता ईमेल मैसेज खोलता है. इससे ऐड-ऑन को ईमेल का कॉन्टेंट "देखने" की अनुमति मिलती है.
अनुमतियां: इसमें ऐड-ऑन को चलाने के लिए ज़रूरी oauthScopes की सूची दी गई है. जैसे, मौजूदा ईमेल को पढ़ने, स्क्रिप्ट को चलाने, और बाहरी सेवाओं (जैसे, Vertex AI API) से कनेक्ट करने की अनुमतियां.

...
"addOns": {
    "common": {
      "name": "Vertex AI",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png"
    },
    "chat": {},
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onAddonEvent"
        }
      ]
    }
  },
  "oauthScopes": [
   "https://www.googleapis.com/auth/script.external_request",
   "https://www.googleapis.com/auth/cloud-platform",
   "https://www.googleapis.com/auth/gmail.addons.execute",
   "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
 ]
...

Chat.gs

यहां दिया गया कोड, Google Chat से मिले मैसेज को मैनेज करता है.

मैसेज मिलते हैं: onMessage फ़ंक्शन, मैसेज इंटरैक्शन के लिए एंट्री पॉइंट होता है.
कॉन्टेक्स्ट मैनेज करता है: यह space.name (चैट स्पेस का आईडी) को उपयोगकर्ता की प्रॉपर्टी में सेव करता है. इससे यह पक्का होता है कि जब एजेंट जवाब देने के लिए तैयार हो, तो उसे पता हो कि किस बातचीत में मैसेज पोस्ट करना है.
Delegates to Agent: यह requestAgent को कॉल करता है. साथ ही, उपयोगकर्ता के मैसेज को उस मुख्य लॉजिक को पास करता है जो एपीआई कम्यूनिकेशन को हैंडल करता है.

...
// Service that handles Google Chat operations.

// Handle incoming Google Chat message events, actions will be taken via Google Chat API calls
function onMessage(event) {
  if (isInDebugMode()) {
    console.log(`MESSAGE event received (Chat): ${JSON.stringify(event)}`);
  }
  // Extract data from the event.
  const chatEvent = event.chat;
  setChatConfig(chatEvent.messagePayload.space.name);

  // Request AI agent to answer the message
  requestAgent(chatEvent.messagePayload.message);
  // Respond with an empty response to the Google Chat platform to acknowledge execution
  return null; 
}

// --- Utility functions ---

// The Chat direct message (DM) space associated with the user
const SPACE_NAME_PROPERTY = "DM_SPACE_NAME"

// Sets the Chat DM space name for subsequent operations.
function setChatConfig(spaceName) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(SPACE_NAME_PROPERTY, spaceName);
  console.log(`Space is set to ${spaceName}`);
}

// Retrieved the Chat DM space name to sent messages to.
function getConfiguredChat() {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(SPACE_NAME_PROPERTY);
}

// Finds the Chat DM space name between the Chat app and the given user.
function findChatAppDm(userName) {
  return Chat.Spaces.findDirectMessage(
    { 'name': userName },
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

// Creates a Chat message in the configured space.
function createMessage(message) {
  const spaceName = getConfiguredChat();
  console.log(`Creating message in space ${spaceName}...`);
  return Chat.Spaces.Messages.create(
    message,
    spaceName,
    {},
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

यहां दिया गया कोड, Gmail का साइडबार बनाता है और ईमेल का कॉन्टेक्स्ट कैप्चर करता है.

यूज़र इंटरफ़ेस (यूआई) बनाता है: createSidebarCard, Workspace Card Service का इस्तेमाल करके विज़ुअल इंटरफ़ेस बनाता है. यह एक सामान्य लेआउट बनाता है. इसमें टेक्स्ट डालने की जगह और "मैसेज भेजें" बटन होता है.
ईमेल का कॉन्टेक्स्ट कैप्चर करता है: handleSendMessage में, कोड यह देखता है कि उपयोगकर्ता फ़िलहाल कोई ईमेल (event.gmail.messageId) देख रहा है या नहीं. अगर वह ईमेल देख रहा है, तो यह कोड ईमेल के विषय और मुख्य हिस्से को सुरक्षित तरीके से फ़ेच करता है. इसके बाद, इसे उपयोगकर्ता के प्रॉम्प्ट में जोड़ देता है.
नतीजा दिखाता है: एजेंट के जवाब देने के बाद, कोड साइडबार कार्ड को अपडेट करता है, ताकि जवाब दिखाया जा सके.

...
// Service that handles Gmail operations.

// Triggered when the user opens the Gmail Add-on or selects an email.
function onAddonEvent(event) {
  // If this was triggered by a button click, handle it
  if (event.parameters && event.parameters.action === 'send') {
    return handleSendMessage(event);
  }

  // Otherwise, just render the default initial sidebar
  return createSidebarCard();
}

// Creates the standard Gmail sidebar card consisting of a text input and send button.
// Optionally includes an answer section if a response was generated.
function createSidebarCard(optionalAnswerSection) {
  const card = CardService.newCardBuilder();
  const actionSection = CardService.newCardSection();

  // Create text input for the user's message
  const messageInput = CardService.newTextInput()
    .setFieldName("message")
    .setTitle("Message")
    .setMultiline(true);

  // Create action for sending the message
  const sendAction = CardService.newAction()
    .setFunctionName('onAddonEvent')
    .setParameters({ 'action': 'send' });

  const sendButton = CardService.newTextButton()
    .setText("Send message")
    .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
    .setOnClickAction(sendAction);

  actionSection.addWidget(messageInput);
  actionSection.addWidget(CardService.newButtonSet().addButton(sendButton));

  card.addSection(actionSection);

  // Attach the response at the bottom if we have one
  if (optionalAnswerSection) {
    card.addSection(optionalAnswerSection);
  }

  return card.build();
}

// Handles clicks from the Send message button.
function handleSendMessage(event) {
  const commonEventObject = event.commonEventObject || {};
  const formInputs = commonEventObject.formInputs || {};
  const messageInput = formInputs.message;

  let userMessage = "";
  if (messageInput && messageInput.stringInputs && messageInput.stringInputs.value.length > 0) {
    userMessage = messageInput.stringInputs.value[0];
  }

  if (!userMessage || userMessage.trim().length === 0) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Please enter a message."))
      .build();
  }

  let finalQueryText = `USER MESSAGE TO ANSWER: ${userMessage}`;

  // If we have an email selected in Gmail, append its content as context
  if (event.gmail && event.gmail.messageId) {
    try {
      GmailApp.setCurrentMessageAccessToken(event.gmail.accessToken);
      const message = GmailApp.getMessageById(event.gmail.messageId);

      const subject = message.getSubject();
      const bodyText = message.getPlainBody() || message.getBody();

      finalQueryText += `\n\nEMAIL THE USER HAS OPENED ON SCREEN:\nSubject: ${subject}\nBody:\n---\n${bodyText}\n---`;
    } catch (e) {
      console.error("Could not fetch Gmail context: " + e);
      // Invalidate the token explicitly so the next prompt requests the missing scopes
      ScriptApp.invalidateAuth();

      CardService.newAuthorizationException()
        .setResourceDisplayName("Enterprise AI")
        .setAuthorizationUrl(ScriptApp.getAuthorizationUrl())
        .throwException();
    }
  }

  try {
    const response = queryAgent({ text: finalQueryText });

    // We leverage the 'showdown' library to parse the LLM's Markdown output into HTML
    // We also substitute markdown listings with arrows and adjust newlines for clearer rendering in the sidebar
    let displayedText = substituteListingsFromMarkdown(response.text);
    displayedText = new showdown.Converter().makeHtml(displayedText).replace(/\n/g, '\n\n');

    const textParagraph = CardService.newTextParagraph();
    textParagraph.setText(displayedText);

    const answerSection = CardService.newCardSection()
      .addWidget(textParagraph);

    const updatedCard = createSidebarCard(answerSection);

    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();

  } catch (err) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Error fetching response: " + err.message))
      .build();
  }
}
...

AgentHandler.gs

नीचे दिया गया कोड, Vertex AI को एपीआई कॉल करता है.

एपीआई कॉल को व्यवस्थित करता है: queryAgent, आपके ऐड-ऑन और Vertex AI Agent Engine के बीच का ब्रिज है. यह एक ऐसा अनुरोध बनाता है जिसमें उपयोगकर्ता की क्वेरी और स्थिति में मौजूद ऑथराइज़ेशन टोकन शामिल होता है.
जवाब को स्ट्रीम करता है: एजेंट के जवाबों में कुछ समय लग सकता है. इसलिए, यह सर्वर-सेंट इवेंट (एसएसई) के साथ streamQuery एपीआई का इस्तेमाल करता है. यह कोड, जवाब को छोटे-छोटे हिस्सों में इकट्ठा करता है और फिर पूरे जवाब को फिर से बनाता है.

...
// Service that handles Vertex AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
 let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead." +
   " Do not ask the user follow-up questions or converse with them as history is not kept in this interface." +
   " SYSTEM PROMPT END\n\n";

 const requestPayload = {
   "class_method": "async_stream_query",
   "input": {
     "user_id": "vertex_ai_add_on",
     "message": { "role": "user", "parts": [{ "text": systemPrompt + input.text }] },
     "state_delta": {
       "enterprise-ai_999": `${ScriptApp.getOAuthToken()}`
     }
   }
 };

 const responseContentText = UrlFetchApp.fetch(
   `https://${getLocation()}-aiplatform.googleapis.com/v1/${getReasoningEngine()}:streamQuery?alt=sse`,
   {
     method: 'post',
     headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` },
     contentType: 'application/json',
     payload: JSON.stringify(requestPayload),
     muteHttpExceptions: true
   }
 ).getContentText();
  if (isInDebugMode()) {
   console.log(`Response: ${responseContentText}`);
 }

 const events = responseContentText.split('\n').map(s => s.replace(/^data:\s*/, '')).filter(s => s.trim().length > 0);
 console.log(`Received ${events.length} agent events.`);

 let author = "default";
 let answerText = "";
 for (const eventJson of events) {
   if (isInDebugMode()) {
     console.log("Event: " + eventJson);
   }
   const event = JSON.parse(eventJson);

   // Retrieve the agent responsible for generating the content
   author = event.author;
  
   // Ignore events that are not useful for the end-user
   if (!event.content) {
     console.log(`${author}: internal event`);
     continue;
   }

   // Handle text answers
   const parts = event.content.parts || [];
   const textPart = parts.find(p => p.text);
   if (textPart) {
     answerText += textPart.text;
   }
 }
 return { author: author, text: answerText };
}
...

Vertex AI Agent Engine में एजेंट को डिप्लॉय करना

टर्मिनल में, पिछले चरणों में डाउनलोड किए गए सोर्स से solutions/enterprise-ai-agent डायरेक्ट्री खोलें. इसके बाद, यह कमांड चलाएं:

# 1. Create and activate a new virtual environment
deactivate
python3 -m venv .venv
source .venv/bin/activate

# 2. Install poetry and project dependencies
pip install poetry
poetry install

# 3. Deploy the agent
adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Enterprise AI" \
  enterprise_ai

जब आपको लॉग में Deploying to agent engine... लाइन दिखे, तब एक नया टर्मिनल खोलें. इसके बाद, Vertex AI Reasoning Engine Service Agent में ज़रूरी अनुमतियां जोड़ने के लिए, यह निर्देश चलाएं:

# 1. Get the current Project ID
PROJECT_ID=$(gcloud config get-value project)

# 2. Extract the Project Number for that ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# 3. Construct the Service Account name
SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# 4. Apply the IAM policy binding
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/discoveryengine.viewer"

adk deploy कमांड के पूरा होने का इंतज़ार करें. इसके बाद, हरे रंग में कमांड के आउटपुट से, नए एजेंट का संसाधन नाम कॉपी करें.

सेवा खाता शुरू करना

ऐड-ऑन के सर्वर-साइड ऑपरेशनों को अनुमति देने के लिए, एक सेवा खाता बनाएं.

Google Cloud Console में जाकर, यह तरीका अपनाएं:

मेन्यू ☰ > आईएएम और एडमिन > सेवा खाते > + सेवा खाता बनाएं पर क्लिक करें.

सेवा खाते का नाम को vertexai-add-on पर सेट करें.

हो गया पर क्लिक करें. आपको सेवा खातों वाले पेज पर रीडायरेक्ट कर दिया जाएगा. यहां आपको बनाया गया सेवा खाता दिखेगा.

नए बनाए गए सेवा खाते को चुनें. इसके बाद, कुंजियां टैब को चुनें.
कुंजी जोड़ें पर क्लिक करें. इसके बाद, नई कुंजी बनाएं पर क्लिक करें.
JSON को चुनें. इसके बाद, बनाएं पर क्लिक करें.

डायलॉग बंद हो जाता है और आपकी नई सार्वजनिक/निजी कुंजी की जोड़ी, JSON फ़ाइल के तौर पर आपके लोकल एनवायरमेंट में अपने-आप डाउनलोड हो जाती है.

Apps Script प्रोजेक्ट बनाना और उसे कॉन्फ़िगर करना

ऐड-ऑन कोड को होस्ट करने के लिए, एक नया Apps Script प्रोजेक्ट बनाएं. साथ ही, उसकी कनेक्शन प्रॉपर्टी कॉन्फ़िगर करें.

Enterprise AI add on Apps Script प्रोजेक्ट खोलने के लिए, इस बटन पर क्लिक करें:

खास जानकारी > कॉपी बनाएं पर क्लिक करें.
स्क्रिप्ट प्रॉपर्टी जोड़ने के लिए, अपने Apps Script प्रोजेक्ट में जाकर, प्रोजेक्ट सेटिंग > स्क्रिप्ट की प्रॉपर्टी में बदलाव करें > स्क्रिप्ट की प्रॉपर्टी जोड़ें पर क्लिक करें.
REASONING_ENGINE_RESOURCE_NAME को Vertex AI एजेंट के उस संसाधन के नाम पर सेट करें जिसे आपने पिछले चरणों में कॉपी किया था. इसका फ़ॉर्मैट ऐसा होता है:

projects/<PROJECT_NUMBER>/locations/us-central1/reasoningEngines/<AGENT_ID>

APP_SERVICE_ACCOUNT_KEY को, पिछले चरणों में डाउनलोड की गई सेवा खाते की फ़ाइल से JSON कुंजी पर सेट करें.
स्क्रिप्ट प्रॉपर्टी सेव करें पर क्लिक करें

Gmail और Chat में डिप्लॉय करना

ऐड-ऑन को सीधे Gmail और Google Chat में टेस्ट करने के लिए डिप्लॉय करें.

अपने Apps Script प्रोजेक्ट में, यह तरीका अपनाएं:

तैनात करें > टेस्ट डिप्लॉयमेंट पर क्लिक करें. इसके बाद, इंस्टॉल करें पर क्लिक करें. यह सुविधा अब Gmail में उपलब्ध है.
हेड डिप्लॉयमेंट आईडी में जाकर, कॉपी करें पर क्लिक करें.

Google Cloud Console में जाकर, यह तरीका अपनाएं:

Google Cloud के खोज फ़ील्ड में Google Chat API खोजें. इसके बाद, Google Chat API पर क्लिक करें. इसके बाद, मैनेज करें पर क्लिक करें. इसके बाद, कॉन्फ़िगरेशन पर क्लिक करें.

इंटरैक्टिव सुविधाएं चालू करें को चुनें.
स्पेस और ग्रुप बातचीत में शामिल हों से चुने का निशान हटाएं.
कनेक्शन की सेटिंग में जाकर, Apps Script को चुनें.
डिप्लॉयमेंट आईडी को पिछले चरणों में कॉपी किए गए हेड डिप्लॉयमेंट आईडी पर सेट करें.
दिखने की सेटिंग में जाकर, इस Chat ऐप्लिकेशन को अपने Workspace डोमेन के चुनिंदा लोगों और ग्रुप के लिए उपलब्ध कराएं को चुनें. इसके बाद, अपना ईमेल पता डालें.
सेव करें पर क्लिक करें.

ऐड-ऑन आज़माएं

अपने लाइव ऐड-ऑन के साथ इंटरैक्ट करें, ताकि यह पुष्टि की जा सके कि वह डेटा फ़ेच कर सकता है और कॉन्टेक्स्ट के हिसाब से सवालों के जवाब दे सकता है.

नए टैब में Google Chat खोलें. इसके बाद, यह तरीका अपनाएं:

Chat ऐप्लिकेशन Vertex AI के साथ कोई डायरेक्ट मैसेज स्पेस खोलें.

कॉन्फ़िगर करें पर क्लिक करें और पुष्टि करने की प्रोसेस पूरी करें.
What are my meetings for today? टाइप करें और enter दबाएं. Vertex AI चैट ऐप्लिकेशन को नतीजों के साथ जवाब देना चाहिए.

नए टैब में Gmail खोलें. इसके बाद, यह तरीका अपनाएं:

खुद को एक ईमेल भेजें. इसमें विषय को We need to talk पर और मुख्य हिस्से को Are you available today between 8 and 9 AM? पर सेट करें
हाल ही में मिला ईमेल मैसेज खोलें.
Vertex AI ऐड-ऑन का साइडबार खोलें.
मैसेज को Do I have any meeting conflicts? पर सेट करें
मैसेज भेजें पर क्लिक करें.
जवाब, बटन के बाद दिखता है.

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

Google Cloud प्रोजेक्ट मिटाना

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

चेतावनी: Google Cloud प्रोजेक्ट को मिटाने से ये असर पड़ते हैं::

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

Google Cloud Console में जाकर, यह तरीका अपनाएं:

मेन्यू ☰ > आईएएम और एडमिन > सेटिंग पर क्लिक करें.

शट डाउन करें पर क्लिक करें.
प्रोजेक्ट आईडी डालें.
फिर भी बंद करें पर क्लिक करें.

7. बधाई हो

बधाई हो! आपने ऐसे समाधान बनाए हैं जो कर्मचारियों के लिए, Vertex AI और Google Workspace को एक साथ इस्तेमाल करने की सुविधा देते हैं!

आगे क्या करना है?

इस कोडलैब में, हम सिर्फ़ सबसे सामान्य इस्तेमाल के उदाहरण दिखाते हैं. हालांकि, ऐसे कई अन्य उदाहरण भी हैं जिन पर आपको अपने समाधानों में विचार करना चाहिए. जैसे:

Gemini CLI और Antigravity जैसे एआई की मदद से काम करने वाले डेवलपर टूल इस्तेमाल करें.
कस्टम एमसीपी, कस्टम फ़ंक्शन कॉल, और जनरेटिव यूआई जैसे अन्य एजेंट फ़्रेमवर्क और टूल के साथ इंटिग्रेट करें.
Vertex AI जैसे प्लैटफ़ॉर्म पर होस्ट किए गए कस्टम मॉडल के साथ-साथ अन्य एआई मॉडल के साथ इंटिग्रेट करें.
इन्हें Dialogflow जैसे प्लैटफ़ॉर्म पर होस्ट किए गए अन्य एजेंट के साथ इंटिग्रेट किया जा सकता है. इसके अलावा, इन्हें तीसरे पक्ष के एजेंट के साथ Cloud Marketplace के ज़रिए इंटिग्रेट किया जा सकता है.
टीमों, संगठनों या सार्वजनिक उपयोगकर्ताओं को बेहतर सुविधाएं देने के लिए, Cloud Marketplace पर एजेंट पब्लिश करें.

ज़्यादा जानें

डेवलपर के लिए कई संसाधन उपलब्ध हैं. जैसे, YouTube वीडियो, दस्तावेज़ वाली वेबसाइटें, कोड सैंपल, और ट्यूटोरियल:

Vertex AI Agents को Google Workspace के साथ इंटिग्रेट करना

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

Vertex AI क्या है?

Google Workspace क्या है?

किस तरह के कस्टम इंटिग्रेशन?

ज़रूरी शर्तें

आपको क्या बनाना है

Vertex AI Search ऐप्लिकेशन

कस्टम एजेंट

Google Workspace ऐड-ऑन के तौर पर एजेंट

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

2. सेट अप करें

कॉन्सेप्ट की समीक्षा करें

Vertex AI ऐप्लिकेशन

Vertex AI data store

Vertex AI Applications की सेटिंग शुरू करना

एपीआई चालू करें

डेटा स्टोर बनाना

3. Vertex AI Search ऐप्लिकेशन

कॉन्सेप्ट की समीक्षा करना

Vertex AI Search ऐप्लिकेशन

Vertex AI Search का वेब विजेट

Vertex AI Search की झलक

समाधान के आर्किटेक्चर की समीक्षा करना

ऐप्लिकेशन बनाएं

वेब विजेट कॉन्फ़िगर करना

ऐप्लिकेशन आज़माएँ

4. कस्टम एजेंट

कॉन्सेप्ट की समीक्षा करें

Agent Development Kit (ADK)

मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी)

फ़ंक्शन टूल

ADK Web

समाधान के आर्किटेक्चर की समीक्षा करना

सोर्स कोड की समीक्षा करना

agent.py

सोर्स कोड डाउनलोड करना

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

उस स्क्रीन को कॉन्फ़िगर करना जहां OAuth को सहमति दी जाती है

OAuth क्लाइंट के क्रेडेंशियल बनाना

Vertex AI Search MCP चालू करना

Chat ऐप्लिकेशन को कॉन्फ़िगर करना

ADK वेब में एजेंट को चलाना

एजेंट आज़माएँ

5. Google Workspace ऐड-ऑन के तौर पर एजेंट

कॉन्सेप्ट की समीक्षा करना

Google Workspace ऐड-ऑन

Apps Script

Google Workspace Card framework

समाधान के आर्किटेक्चर की समीक्षा करना

सोर्स कोड की समीक्षा करना

Agent

agent.py

क्लाइंट

appsscript.json

Chat.gs

Sidebar.gs

AgentHandler.gs

Vertex AI Agent Engine में एजेंट को डिप्लॉय करना

सेवा खाता शुरू करना

Apps Script प्रोजेक्ट बनाना और उसे कॉन्फ़िगर करना

Gmail और Chat में डिप्लॉय करना

ऐड-ऑन आज़माएं

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

Google Cloud प्रोजेक्ट मिटाना

7. बधाई हो

आगे क्या करना है?

ज़्यादा जानें