1. खास जानकारी
आजकल के यात्री, बातचीत वाली सुविधाओं की उम्मीद करते हैं. वे यूज़र इंटरफ़ेस (यूआई) के मुश्किल फ़िल्टर इस्तेमाल करने के बजाय, यह पूछना चाहते हैं कि "क्या मैं सुबह 9 बजे की बस से बॉस्टन जा सकता/सकती हूँ?" इसके लिए, ऐसे एजेंट की ज़रूरत होती है जो अनस्ट्रक्चर्ड डेटा (पीडीएफ़ नीतियां) और स्ट्रक्चर्ड डेटा (एसक्यूएल शेड्यूल) के आधार पर तर्क दे सके.
इस लैब में, हम Cymbal Transit Agent को इन चीज़ों का इस्तेमाल करके बनाते हैं:
- LangChain4j: यह एआई ऑर्केस्ट्रेशन के लिए, सबसे बेहतरीन Java फ़्रेमवर्क है.
- AlloyDB: यह PostgreSQL के साथ काम करने वाला एक हाई-परफ़ॉर्मेंस डेटाबेस है.
- MCP Toolbox Java SDK: Java एजेंट को बाहरी टूल और डेटा सोर्स से कनेक्ट करने का एक स्टैंडर्ड तरीका.
आपको क्या बनाना है
Cymbal Bus Agent, Java Spring Boot ऐप्लिकेशन है. इसमें ये शामिल हैं:
- एजेंट के साथ टूल ऑर्केस्ट्रेशन के लिए, AlloyDB डेटाबेस और MCP टूलबॉक्स Java SDK.
- Toolbox डिप्लॉयमेंट और ऐप्लिकेशन (एजेंट डिप्लॉयमेंट) के लिए Cloud Run.
- Java 17 के साथ Spring Boot ऐप्लिकेशन में एजेंट और एलएलएम फ़्रेमवर्क के लिए LangChain4J लाइब्रेरी.
आपको क्या सीखने को मिलेगा
- LangChain4J का इस्तेमाल करके, खास एजेंट और सब-एजेंट बनाने का तरीका. इन्हें MCP Toolbox for Databases Java SDK का इस्तेमाल करके व्यवस्थित किया जाता है
- डेटा और एआई के लिए, AlloyDB को सेट अप और इस्तेमाल करने का तरीका.
- एजेंट को AlloyDB के डेटा टूल से कनेक्ट करने के लिए, MCP टूलबॉक्स का इस्तेमाल कैसे करें.
- Cloud Run का इस्तेमाल करके समाधान को डिप्लॉय करने या इसे स्थानीय तौर पर चलाने का तरीका.
आर्किटेक्चर
- AlloyDB for PostgreSQL: यह एक हाई-परफ़ॉर्मेंस वाला ऑपरेशनल डेटाबेस है. इसमें हमारे रूट, नीतियां, और बुकिंग के रिकॉर्ड सेव होते हैं. यह वेक्टर सर्च और जानकारी वापस पाने की सुविधा देता है.
- डेटाबेस के लिए MCP टूलबॉक्स Java SDK: यह "ऑर्केस्ट्रेशन मेस्ट्रो" के तौर पर काम करता है. यह AlloyDB के डेटा को ऐसे टूल के तौर पर दिखाता है जिन्हें एजेंट कॉल कर सकते हैं.
MCP Toolbox Java SDK की मदद से, एंटरप्राइज़-ग्रेड के ऐप्लिकेशन के लिए, एजेंट को अपने डेटाबेस टूल के साथ आसानी से मैनेज किया जा सकता है.
- LangChain4J: यह एक ओपन-सोर्स Java लाइब्रेरी है. इससे Java ऐप्लिकेशन में लार्ज लैंग्वेज मॉडल (एलएलएम) को आसानी से इंटिग्रेट किया जा सकता है. यह एआई की मदद से काम करने वाले ऐप्लिकेशन बनाने के लिए, टूल और ऐब्स्ट्रैक्शन उपलब्ध कराता है. इनमें चैटबॉट, एजेंट, और रिट्रीवल ऑगमेंटेड जनरेशन (आरएजी) सिस्टम शामिल हैं.
- Cloud Run: यह पूरी तरह से मैनेज किया गया SERVERLESS प्लैटफ़ॉर्म है. इसकी मदद से, किसी भी भाषा, लाइब्रेरी या बाइनरी में ऐप्लिकेशन या वेबसाइटों को आसानी से बनाया और तुरंत डिप्लॉय किया जा सकता है. अपनी पसंदीदा भाषा, फ़्रेमवर्क, और लाइब्रेरी का इस्तेमाल करके कोड लिखा जा सकता है. इसे कंटेनर के तौर पर पैकेज किया जा सकता है. इसके बाद, "gcloud run deploy" कमांड चलाएं. इससे आपका ऐप्लिकेशन लाइव हो जाएगा. साथ ही, इसे प्रोडक्शन में चलाने के लिए ज़रूरी सभी चीज़ें मिल जाएंगी. कंटेनर बनाना ज़रूरी नहीं है. अगर Go, Node.js, Python, Java, .NET Core या Ruby का इस्तेमाल किया जा रहा है, तो सोर्स पर आधारित डिप्लॉयमेंट के विकल्प का इस्तेमाल किया जा सकता है. यह विकल्प, इस्तेमाल की जा रही भाषा के सबसे सही तरीकों का इस्तेमाल करके, आपके लिए कंटेनर बनाता है.
ज़रूरी शर्तें
2. शुरू करने से पहले
प्रोजेक्ट बनाना
- Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर जाकर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
- पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.
- आपको Cloud Shell का इस्तेमाल करना होगा. यह Google Cloud में चलने वाला कमांड-लाइन एनवायरमेंट है. Google Cloud Console में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें.
- Cloud Shell से कनेक्ट होने के बाद, यह देखने के लिए कि आपकी पुष्टि हो चुकी है और प्रोजेक्ट को आपके प्रोजेक्ट आईडी पर सेट किया गया है, इस निर्देश का इस्तेमाल करें:
gcloud auth list
- यह पुष्टि करने के लिए कि gcloud कमांड को आपके प्रोजेक्ट के बारे में पता है, Cloud Shell में यह कमांड चलाएं.
gcloud config list project
- अगर आपका प्रोजेक्ट सेट नहीं है, तो इसे सेट करने के लिए इस निर्देश का इस्तेमाल करें:
gcloud config set project <YOUR_PROJECT_ID>
- ज़रूरी एपीआई चालू करें: लिंक पर जाएं और एपीआई चालू करें.
इसके अलावा, इसके लिए gcloud कमांड का इस्तेमाल किया जा सकता है. gcloud कमांड और उनके इस्तेमाल के बारे में जानने के लिए, दस्तावेज़ देखें.
समस्याएं और उन्हें हल करने का तरीका
"घोस्ट प्रोजेक्ट" सिंड्रोम | आपने |
बिलिंग बैरिकेड | आपने प्रोजेक्ट चालू किया है, लेकिन बिलिंग खाते की जानकारी नहीं दी है. AlloyDB एक हाई-परफ़ॉर्मेंस इंजन है. अगर "गैस टैंक" (बिलिंग) खाली है, तो यह शुरू नहीं होगा. |
एपीआई के डेटा को अपडेट होने में लगने वाला समय | आपने "एपीआई चालू करें" पर क्लिक किया है, लेकिन कमांड लाइन में अब भी |
कोटा Quags | अगर आपने नया ट्रायल खाता इस्तेमाल किया है, तो हो सकता है कि आपने AlloyDB इंस्टेंस के लिए क्षेत्र के हिसाब से तय किया गया कोटा पूरा कर लिया हो. अगर |
"छिपा हुआ" सर्विस एजेंट | कभी-कभी, AlloyDB सेवा एजेंट को |
3. डेटाबेस सेटअप करना
हमारे ऐप्लिकेशन के लिए, AlloyDB for PostgreSQL सबसे अहम है. हमने इसकी बेहतरीन वेक्टर क्षमताओं का फ़ायदा उठाया और 50,000 से ज़्यादा एससीएम रिकॉर्ड के लिए एम्बेडिंग जनरेट करने के लिए, कॉलम वाले इंजन को इंटिग्रेट किया. इससे, वेक्टर का विश्लेषण करीब-करीब रीयल-टाइम में किया जा सकता है. इससे हमारे एजेंट, बड़े डेटासेट में इन्वेंट्री की गड़बड़ियों या लॉजिस्टिक्स से जुड़े जोखिमों की पहचान कुछ ही मिलीसेकंड में कर पाते हैं.
इस लैब में, हम टेस्ट डेटा के लिए AlloyDB का इस्तेमाल करेंगे. यह सभी संसाधनों को सेव करने के लिए, क्लस्टर का इस्तेमाल करता है. जैसे, डेटाबेस और लॉग. हर क्लस्टर में एक प्राइमरी इंस्टेंस होता है, जो डेटा का ऐक्सेस पॉइंट उपलब्ध कराता है. टेबल में असल डेटा होगा.
आइए, एक AlloyDB क्लस्टर, इंस्टेंस, और टेबल बनाएं. इसमें टेस्ट डेटासेट लोड किया जाएगा.
- उस ब्राउज़र में नीचे दिए गए बटन पर क्लिक करें या लिंक को कॉपी करें जिसमें आपने Google Cloud Console उपयोगकर्ता के तौर पर लॉग इन किया है.
इसके अलावा, उस प्रोजेक्ट से Cloud Shell टर्मिनल पर जाएं जहां आपने बिलिंग खाता रिडीम किया है. इसके बाद, GitHub repo को क्लोन करें और नीचे दिए गए निर्देशों का इस्तेमाल करके प्रोजेक्ट पर जाएं:
git clone https://github.com/AbiramiSukumaran/easy-alloydb-setup
cd easy-alloydb-setup
- यह चरण पूरा होने के बाद, repo को आपके लोकल Cloud Shell Editor में क्लोन कर दिया जाएगा. इसके बाद, प्रोजेक्ट फ़ोल्डर से नीचे दिए गए कमांड को चलाया जा सकेगा. यह पक्का करना ज़रूरी है कि आप प्रोजेक्ट डायरेक्ट्री में हों:
sh run.sh
- अब यूज़र इंटरफ़ेस (टर्मिनल में लिंक पर क्लिक करके या टर्मिनल में "वेब पर झलक देखें" लिंक पर क्लिक करके) का इस्तेमाल करें.
- शुरू करने के लिए, प्रोजेक्ट आईडी, क्लस्टर, और इंस्टेंस के नाम डालें.
- जब तक लॉग स्क्रोल होते हैं, तब तक जाकर कॉफ़ी ले आएं. यहां यह भी बताया गया है कि पर्दे के पीछे यह कैसे काम करता है.
समस्याएं और उन्हें हल करने का तरीका
"धैर्य" की समस्या | डेटाबेस क्लस्टर, एक बड़ा इन्फ़्रास्ट्रक्चर होता है. अगर आपने पेज को रीफ़्रेश किया या Cloud Shell सेशन को बंद किया, क्योंकि वह "स्टक हो गया था", तो हो सकता है कि आपको एक "घोस्ट" इंस्टेंस मिले. यह इंस्टेंस आंशिक रूप से उपलब्ध कराया गया होता है और इसे मैन्युअल तरीके से बंद किए बिना मिटाया नहीं जा सकता. |
क्षेत्र की जानकारी मेल न खाना | अगर आपने |
ज़ॉम्बी क्लस्टर | अगर आपने किसी क्लस्टर के लिए पहले भी इसी नाम का इस्तेमाल किया था और उसे मिटाया नहीं है, तो स्क्रिप्ट में यह मैसेज दिख सकता है कि क्लस्टर का नाम पहले से मौजूद है. किसी प्रोजेक्ट में क्लस्टर के नाम अलग-अलग होने चाहिए. |
Cloud Shell का टाइम आउट होना | अगर आपका कॉफ़ी ब्रेक 30 मिनट का है, तो Cloud Shell स्लीप मोड में जा सकता है और |
4. स्कीमा प्रोविज़निंग
AlloyDB क्लस्टर और इंस्टेंस चालू होने के बाद, AlloyDB Studio के एसक्यूएल एडिटर पर जाएं. यहां एआई एक्सटेंशन चालू करें और स्कीमा उपलब्ध कराएं.
आपको इंस्टेंस बनने तक इंतज़ार करना पड़ सकता है. इसके बाद, क्लस्टर बनाते समय बनाए गए क्रेडेंशियल का इस्तेमाल करके, AlloyDB में साइन इन करें. PostgreSQL में पुष्टि करने के लिए, इस डेटा का इस्तेमाल करें:
- उपयोगकर्ता नाम : "
postgres" - डेटाबेस : "
postgres" - पासवर्ड : "
alloydb" (या क्रिएशन के समय सेट किया गया कोई भी पासवर्ड)
AlloyDB Studio में पुष्टि हो जाने के बाद, SQL कमांड को एडिटर में डाला जाता है. आखिरी विंडो के दाईं ओर मौजूद प्लस आइकॉन का इस्तेमाल करके, एक से ज़्यादा Editor विंडो जोड़ी जा सकती हैं.
एडिटर विंडो में, AlloyDB के लिए कमांड डाली जाती हैं. इसके लिए, ज़रूरत के हिसाब से 'चलाएं', 'फ़ॉर्मैट करें', और 'मिटाएं' विकल्पों का इस्तेमाल किया जाता है.
एक्सटेंशन चालू करना
इस ऐप्लिकेशन को बनाने के लिए, हम pgvector और google_ml_integration एक्सटेंशन का इस्तेमाल करेंगे. pgvector एक्सटेंशन की मदद से, वेक्टर एम्बेडिंग को सेव किया जा सकता है और उन्हें खोजा जा सकता है. google_ml_integration एक्सटेंशन, ऐसे फ़ंक्शन उपलब्ध कराता है जिनका इस्तेमाल करके, Vertex AI के अनुमान लगाने वाले एंडपॉइंट को ऐक्सेस किया जा सकता है. इससे एसक्यूएल में अनुमान मिलते हैं. इन एक्सटेंशन को चालू करें. इसके लिए, ये DDL चलाएं:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
अनुमति दें
"embedding" फ़ंक्शन पर 'लागू करें' की अनुमति देने के लिए, नीचे दिया गया स्टेटमेंट चलाएं:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
AlloyDB सेवा खाते को Vertex AI उपयोगकर्ता की भूमिका असाइन करना
Google Cloud IAM Console में जाकर, AlloyDB सेवा खाते को "Vertex AI User" की भूमिका का ऐक्सेस दें. यह सेवा खाता इस तरह दिखता है: service-<<PROJECT_NUMBER >>@gcp-sa-alloydb.iam.gserviceaccount.com. PROJECT_NUMBER में आपका प्रोजेक्ट नंबर होगा.
इसके अलावा, Cloud Shell टर्मिनल से नीचे दिया गया कमांड भी चलाया जा सकता है:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
टेबल बनाना
AlloyDB Studio में, नीचे दिए गए डीडीएल स्टेटमेंट का इस्तेमाल करके टेबल बनाई जा सकती है:
DROP TABLE IF EXISTS transit_policies;
DROP TABLE IF EXISTS bus_schedules;
DROP TABLE IF EXISTS bookings;
-- Table 1: Transit Policies (Unstructured Data for RAG)
CREATE TABLE transit_policies (
policy_id SERIAL PRIMARY KEY,
category VARCHAR(50),
policy_text TEXT,
policy_embedding vector(768)
);
-- Table 2: Intercity Bus Schedules (Structured Data)
CREATE TABLE bus_schedules (
trip_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
origin_city VARCHAR(100),
destination_city VARCHAR(100),
departure_time TIMESTAMP,
arrival_time TIMESTAMP,
available_seats INT DEFAULT 50,
ticket_price DECIMAL(6,2)
);
-- Table 3: Booking Ledger (Transactional Action Data)
CREATE TABLE bookings (
booking_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
trip_id UUID REFERENCES bus_schedules(trip_id),
passenger_id VARCHAR(100),
status VARCHAR(20) DEFAULT 'CONFIRMED',
booking_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
policy_embedding कॉलम में, कुछ टेक्स्ट फ़ील्ड की वेक्टर वैल्यू सेव की जा सकेंगी.
डेटा डालना
संबंधित टेबल में एक साथ कई रिकॉर्ड डालने के लिए, एसक्यूएल स्टेटमेंट का यह सेट चलाएं:
- AlloyDB में, बिना किसी स्ट्रक्चर वाली नीतियां डालें और नेटिव तौर पर एम्बेडिंग जनरेट करें
-- 1. Insert Unstructured Policies and GENERATE REAL EMBEDDINGS natively in AlloyDB
INSERT INTO transit_policies (category, policy_text, policy_embedding)
VALUES
('Pets', 'Service animals are always welcome. Small pets (under 25 lbs) are allowed in secure carriers for a $25 fee. Large dogs are not permitted on standard coaches.', embedding('text-embedding-005', 'Service animals are always welcome. Small pets (under 25 lbs) are allowed in secure carriers for a $25 fee. Large dogs are not permitted on standard coaches.')),
('Luggage', 'Each passenger is allowed one carry-on (up to 15 lbs) and two stowed bags (up to 50 lbs each) free of charge. Additional bags cost $15 each.', embedding('text-embedding-005', 'Each passenger is allowed one carry-on (up to 15 lbs) and two stowed bags (up to 50 lbs each) free of charge. Additional bags cost $15 each.')),
('Refunds', 'Tickets are fully refundable up to 24 hours before departure. Within 24 hours, tickets can be exchanged for travel credit only.', embedding('text-embedding-005', 'Tickets are fully refundable up to 24 hours before departure. Within 24 hours, tickets can be exchanged for travel credit only.'));
- generate_series का इस्तेमाल करके, सात दिनों के लिए 200 से ज़्यादा रियलिस्टिक शेड्यूल जनरेट करना
-- 2. Generate 200+ Realistic Schedules for the Next 7 Days using generate_series
INSERT INTO bus_schedules (origin_city, destination_city, departure_time, arrival_time, ticket_price, available_seats)
SELECT
origin,
destination,
-- Generate departures every 4 hours starting from tomorrow
(CURRENT_DATE + 1) + (interval '4 hours' * seq) AS dep_time,
(CURRENT_DATE + 1) + (interval '4 hours' * seq) + interval '4.5 hours' AS arr_time,
ROUND((RANDOM() * 30 + 25)::numeric, 2) AS price, -- Random price between $25 and $55
FLOOR(RANDOM() * 50 + 1) AS seats -- Random seats between 1 and 50
FROM
(VALUES
('New York', 'Boston'), ('Boston', 'New York'),
('Philadelphia', 'Washington DC'), ('Washington DC', 'Philadelphia'),
('Seattle', 'Portland'), ('Portland', 'Seattle')
) AS routes(origin, destination)
CROSS JOIN generate_series(1, 40) AS seq; -- 6 routes * 40 time slots = 240 distinct trips ingested!
डेटा एंबेड करना
"embedding('text-embedding-005', '<<policytext>>')" फ़ंक्शन का इस्तेमाल करके, insert स्टेटमेंट में एम्बेडिंग को transit_policies टेबल में अपने-आप शामिल कर लिया जाता है.
समस्याएं और उन्हें हल करने का तरीका
"पासवर्ड भूल जाना" लूप | अगर आपने "एक क्लिक" सेटअप का इस्तेमाल किया है और आपको अपना पासवर्ड याद नहीं है, तो कंसोल में इंस्टेंस की बुनियादी जानकारी वाले पेज पर जाएं. इसके बाद, |
"एक्सटेंशन नहीं मिला" गड़बड़ी | अगर |
IAM के ऐक्सेस से जुड़ी समस्याएं | आपने
|
वेक्टर डाइमेंशन का मेल न खाना |
|
प्रोजेक्ट आईडी में टाइपिंग की गड़बड़ी |
|
5. टूल और टूलबॉक्स सेटअप
MCP Toolbox for Databases, डेटाबेस के लिए एक ओपन सोर्स एमसीपी सर्वर है. यह आपको टूल को आसानी से, तेज़ी से, और ज़्यादा सुरक्षित तरीके से डेवलप करने की सुविधा देता है. इसके लिए, यह कनेक्शन पूलिंग, पुष्टि करने की प्रोसेस, और अन्य जैसी मुश्किलों को मैनेज करता है. टूलबॉक्स की मदद से, जनरेटिव एआई टूल बनाए जा सकते हैं. इनकी मदद से, आपके एजेंट आपके डेटाबेस में मौजूद डेटा को ऐक्सेस कर सकते हैं.
हम डेटाबेस के लिए मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) टूलबॉक्स का इस्तेमाल "कंडक्टर" के तौर पर करते हैं. यह हमारे एजेंट और AlloyDB के बीच एक स्टैंडर्ड मिडलवेयर के तौर पर काम करता है. tools.yaml कॉन्फ़िगरेशन तय करने पर, टूलबॉक्स अपने-आप डेटाबेस से जुड़ी मुश्किल कार्रवाइयों को साफ़ तौर पर लागू किए जा सकने वाले टूल के तौर पर दिखाता है. जैसे, find-bus-schedules and routes या query-schedules for specific routes. साथ ही, book-ticket जैसी कार्रवाइयां अपने-आप करता है. इससे एजेंट लॉजिक में, मैन्युअल कनेक्शन पूलिंग या बॉयलरप्लेट एसक्यूएल की ज़रूरत नहीं पड़ती.
Toolbox सर्वर इंस्टॉल करना
Cloud Shell टर्मिनल में, अपनी नई टूल की YAML फ़ाइल और टूलबॉक्स बाइनरी को सेव करने के लिए एक फ़ोल्डर बनाएं:
mkdir cymbal-bus-toolbox
cd cymbal-bus-toolbox
उस नए फ़ोल्डर में जाकर, यह कमांड चलाएं:
# see releases page for other versions
export VERSION=0.27.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
इसके बाद, Cloud Shell Editor में जाकर उस नए फ़ोल्डर में tools.yaml फ़ाइल बनाएं. साथ ही, इस repo फ़ाइल के कॉन्टेंट को tools.yaml फ़ाइल में कॉपी करें.
... (Refer to entire file in the repo)
tools:
find-bus-schedules:
kind: postgres-sql
source: alloydb
description: Find all available bus schedules.
statement: |
SELECT CAST(trip_id AS TEXT) trip_id, departure_time, arrival_time, ticket_price, available_seats , origin_city, destination_city
FROM bus_schedules;
query-schedules:
kind: postgres-sql
source: alloydb
description: Find available bus schedules between an origin and destination city.
parameters:
- name: origin
type: string
description: The departure city name.
- name: destination
type: string
description: The arrival city name.
statement: |
SELECT CAST(trip_id AS TEXT) trip_id, departure_time, arrival_time, ticket_price, available_seats
FROM bus_schedules
WHERE lower(origin_city) = lower($1)
AND lower(destination_city) = lower($2)
AND available_seats > 0
ORDER BY departure_time ASC
LIMIT 5;
book-ticket:
kind: postgres-sql
source: alloydb
description: Books a ticket for a specific trip, decrementing available seats and generating a confirmed booking record.
parameters:
- name: trip_id
type: string
description: The UUID of the trip schedule to book.
- name: passenger_name
type: string
description: Name or ID of the passenger (Bound securely via backend or AuthToken).
authServices:
- name: google_auth
field: sub
statement: |
WITH updated_schedule AS (
UPDATE bus_schedules
SET available_seats = available_seats - 1
WHERE trip_id = CAST($1 AS UUID) AND available_seats > 0
RETURNING trip_id
)
INSERT INTO bookings (trip_id, passenger_id)
SELECT trip_id, $2
FROM updated_schedule
RETURNING CAST(booking_id as TEXT) as booking_id, trip_id, passenger_id, status, booking_time;
search-policies:
kind: postgres-sql
source: alloydb
description: Semantic search for transit policies regarding luggage, pets, refunds, and general rules.
parameters:
- name: search_query
type: string
description: The user's question about transit policies to be embedded and searched.
statement: |
SELECT category, policy_text
FROM transit_policies
ORDER BY policy_embedding <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
LIMIT 2;
ध्यान दें:
- tools.yaml सेट अप करते समय, alloydb सोर्स कॉन्फ़िगरेशन में ipType: "private" को शामिल करना न भूलें.
- यह भी याद रखें कि authServices कॉन्फ़िगरेशन के लिए, clientId पैरामीटर में एमसीपी टूलबॉक्स सेवा का यूआरएल शामिल करना ज़रूरी है. आपको लिंक सिर्फ़ शुरुआती डिप्लॉयमेंट के बाद मिल सकता है. इसलिए, आपको डिप्लॉयमेंट के चरणों को दो बार पूरा करना होगा, ताकि यह पक्का किया जा सके कि पुष्टि किए गए टूल का इस्तेमाल किया जा रहा है.
- अगर आपका AlloyDB कनेक्शन प्राइवेट पर सेट है, तो टूलबॉक्स को स्थानीय तौर पर टेस्ट करने के लिए, यहां दिए गए विकल्प काम नहीं करेंगे. इसे स्थानीय तौर पर टेस्ट करने के लिए, आपको इसे सार्वजनिक करना होगा या कनेक्शन के लिए प्रॉक्सी का इस्तेमाल करना होगा. हालांकि, आपको इस बारे में चिंता करने की कोई ज़रूरत नहीं है. हम इसे सीधे Cloud Run पर डिप्लॉय करेंगे और फिर इसकी जांच करेंगे.
लोकल सर्वर में tools.yaml फ़ाइल की जांच करने के लिए:
./toolbox --tools-file "tools.yaml"
इसके अलावा, यूज़र इंटरफ़ेस (यूआई) में भी इसकी जांच की जा सकती है:
./toolbox --ui
आइए, इसे Cloud Run में इस तरह डिप्लॉय करें.
Cloud Run डिप्लॉयमेंट
- PROJECT_ID एनवायरमेंट वैरिएबल सेट करें:
export PROJECT_ID="my-project-id"
- gcloud सीएलआई शुरू करें:
gcloud init
gcloud config set project $PROJECT_ID
- आपके पास ये एपीआई चालू होने चाहिए:
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
- अगर आपके पास पहले से कोई बैकएंड सेवा खाता नहीं है, तो उसे बनाएं:
gcloud iam service-accounts create toolbox-identity
- Secret Manager का इस्तेमाल करने की अनुमतियां दें:
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
- सेवा खाते को अतिरिक्त अनुमतियां दें. ये अनुमतियां, हमारे AlloyDB सोर्स (roles/alloydb.client और roles/serviceusage.serviceUsageConsumer) के लिए खास तौर पर दी जाती हैं
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/alloydb.client
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/serviceusage.serviceUsageConsumer
- tools.yaml को सीक्रेट के तौर पर अपलोड करें:
gcloud secrets create tools-cymbal-transit --data-file=tools.yaml
- अगर आपके पास पहले से कोई सीक्रेट है और आपको सीक्रेट का वर्शन अपडेट करना है, तो यह कमांड चलाएं:
gcloud secrets versions add tools-cymbal-transit --data-file=tools.yaml
- उस कंटेनर इमेज के लिए एनवायरमेंट वैरिएबल सेट करें जिसका इस्तेमाल Cloud Run के लिए करना है:
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
- इस कमांड का इस्तेमाल करके, Toolbox को Cloud Run पर डिप्लॉय करें:
अगर आपने अपने AlloyDB इंस्टेंस में सार्वजनिक ऐक्सेस की सुविधा चालू की है, तो Cloud Run पर डिप्लॉय करने के लिए, यहां दिया गया निर्देश इस्तेमाल करें:
gcloud run deploy toolbox-cymbal-transit \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-cymbal-transit:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
अगर वीपीसी नेटवर्क का इस्तेमाल किया जा रहा है, तो यहां दिए गए निर्देश का इस्तेमाल करें:
gcloud run deploy toolbox-cymbal-transit \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools-cymbal-transit:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--network <<YOUR_NETWORK_NAME>> \
--subnet <<YOUR_SUBNET_NAME>> \
--allow-unauthenticated
ध्यान दें: डिप्लॉय करने के बाद, Cloud Run सेवा की सूची पर जाएं और पक्का करें कि उस सेवा के सुरक्षा टैब में, "सार्वजनिक ऐक्सेस की अनुमति दें" विकल्प चुना गया हो.
6. एजेंट ऐप्लिकेशन सेटअप करना
इस रेपो को अपने प्रोजेक्ट में क्लोन करें और आइए, इसके बारे में जानते हैं.
इसे क्लोन करने के लिए, अपने Cloud Shell टर्मिनल में (रूट डायरेक्ट्री में या जहां भी आपको यह प्रोजेक्ट बनाना है), यह कमांड चलाएं:
git clone https://github.com/googleapis/mcp-toolbox-sdk-java
ऊपर दी गई कमांड, असल में पूरे mcp-toolbox-sdk-java को क्लोन करती है. हमें सिर्फ़ इसका सैंपल प्रोजेक्ट चाहिए. इसलिए, रिपॉज़िटरी में प्रोजेक्ट की रूट डायरेक्ट्री पर जाएं:
cd mcp-toolbox-sdk-java/demo-applications/cymbal-transit
- इससे प्रोजेक्ट बन जाएगा. इसकी पुष्टि Cloud Shell Editor में की जा सकती है.
- CymbalTransitController.java खोलें और एनवायरमेंट वैरिएबल सेट करें:
- GCP_PROJECT_ID
- GCP_REGION
- GEMINI_MODEL_NAME
- MCP_TOOLBOX_URL
इसके अलावा (सिर्फ़ डेवलपमेंट के लिए), फ़ॉलबैक वैल्यू के प्लेसहोल्डर भी बदले जा सकते हैं.
7. कोड के बारे में सिलसिलेवार तरीके से निर्देश
CymbalTransitController, हमारी Cloud Run सेवा के लिए एंट्री पॉइंट के तौर पर काम करता है. यह कुकी, बातचीत के फ़्लो को मैनेज करती है. साथ ही, यह पक्का करती है कि एजेंट के पास उपयोगकर्ता के मौजूदा अनुरोध का ऐक्सेस हो.
इसे लेयर्ड आर्किटेक्चर के हिसाब से लागू किया गया है. इसमें एआई ऑर्केस्ट्रेशन, टूल ब्रिजिंग, और लो-लेवल एमसीपी कम्यूनिकेशन को अलग-अलग किया गया है.
1. एआई एजेंट कॉन्फ़िगरेशन (AgentConfiguration)
यह क्लास, एआई कॉम्पोनेंट को बूटस्ट्रैप करने के लिए Spring के @Configuration का इस्तेमाल करती है. यह VertexAiGeminiChatModel को शुरू करता है और इसे हमारे एजेंट इंटरफ़ेस से बाइंड करता है.
@Bean
ChatLanguageModel geminiChatModel() {
return VertexAiGeminiChatModel.builder()
.project(projectId)
.location(region)
.modelName(modelName)
.build();
}
@Bean
TransitAgent transitAgent(ChatLanguageModel chatLanguageModel, TransitAgentTools tools) {
return AiServices.builder(TransitAgent.class)
.chatLanguageModel(chatLanguageModel)
.chatMemoryProvider(memoryId -> MessageWindowChatMemory.withMaxMessages(20))
.tools(tools)
.build();
}
अहमियत: AiServices इंटरफ़ेस को एलएलएम से जोड़ता है. MessageWindowChatMemory की मदद से, एजेंट यह पक्का करता है कि उसे एक सेशन में 20 मैसेज तक उपयोगकर्ता की प्राथमिकताओं के बारे में याद रहे. जैसे, पहले बताया गया पेट कैरियर.
2. एआई एजेंट का इंटरफ़ेस (TransitAgent)
@SystemMessage एनोटेशन, "Persona" और ऑपरेशनल कंस्ट्रेंट के बारे में बताता है. खास तौर पर, राउटिंग की रणनीति के बारे में.
@SystemMessage({
"You are the Cymbal Transit Concierge.",
"CRITICAL INSTRUCTION: On your very first interaction, you MUST use the 'findAllSchedules' tool to fetch and memorize the broad bus routes.",
"ONLY if the user asks a specifically narrowed-down question... should you route to the specific tools like 'querySchedules', 'bookTicket', 'searchPolicies'.",
"Don't show any asterisks while listing results. Keep it formatted and numbered or bulleted."
})
String chat(@MemoryId String sessionId, @UserMessage String userMessage);
अहमियत: इस रणनीति से, डेटा ट्रांसफ़र में लगने वाला समय कम हो जाता है. सबसे पहले ज़्यादा डेटा फ़ेच करके, एजेंट अपने इंटरनल कॉन्टेक्स्ट का इस्तेमाल करके, सामान्य राउटिंग के सवालों के जवाब दे सकता है. इसके लिए, उसे बैकएंड से बार-बार कॉल करने की ज़रूरत नहीं पड़ती.
3. टूलबॉक्स ब्रिज (TransitAgentTools)
यह सेवा, एजेंट के "हाथों" के तौर पर काम करती है. यह LangChain4j टूल कॉल को एक्ज़ीक्यूशन लॉजिक में बदलती है.
@Tool("Fetches the initial, broad dataset of all available bus schedules and routes.")
public String findAllSchedules() {
return mcpService.findAllSchedules().join();
}
@Tool("Book a ticket for a passenger using a specific trip ID.")
public String bookTicket(String tripId, String passengerName) {
return mcpService.bookTicket(tripId, passengerName).join();
}
सिंक्रोनस तरीके से काम करना: एमसीपी कॉल एसिंक्रोनस (CompletableFuture दिखाता है) होते हैं. हालांकि, एलएलएम को "सोचने" की प्रोसेस जारी रखने से पहले, नतीजे की ज़रूरत होती है. हम .join() का इस्तेमाल करके, एजेंट को सिंक्रोनस नतीजे वापस भेजते हैं.
4. MCP टूलबॉक्स सेवा (McpToolboxService)
यह कम्यूनिकेशन लेयर है. यह MCP टूलबॉक्स Java SDK का इस्तेमाल करके, AlloyDB बैकएंड के साथ इंटरैक्ट करती है.
// Identity Management: Fetching OIDC ID Token for Auth
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
this.idToken = ((IdTokenProvider) credentials)
.idTokenWithAudience(targetUrl, Collections.emptyList())
.getTokenValue();
// Dynamic Invocation: Executing a tool by name
public CompletableFuture<String> findAllSchedules() {
return mcpClient.invokeTool("find-bus-schedules", Collections.emptyMap()).thenApply(result -> {
return result.content().stream()
.map(content -> content.text())
.collect(Collectors.joining(", ", "[", "]"));
});
}
अहमियत: McpToolboxClient, JSON-RPC कम्यूनिकेशन को मैनेज करता है. bookTicket तरीके से, खास तौर पर एसडीके की इस क्षमता के बारे में पता चलता है कि वह डाइनैमिक तौर पर जटिल पैरामीटर को बाइंड कर सकता है.
5. REST कंट्रोलर (TransitAgentController)
LangChain4j, स्थिति और लॉजिक को मैनेज करता है. इसलिए, फ़ाइनल एंडपॉइंट को बहुत आसान बना दिया गया है.
@PostMapping("/chat")
public ResponseEntity<String> handleUserChat(@RequestBody String userMessage, HttpSession session) {
String sessionId = session.getId();
String agentResponse = transitAgent.chat(sessionId, userMessage);
return ResponseEntity.ok(agentResponse);
}
अहमियत: HttpSession आईडी को @MemoryId से मैप करके, हम यह पक्का करते हैं कि अलग-अलग उपयोगकर्ताओं के यात्रा प्लान मिक्स न हों. साथ ही, कंट्रोलर कोड को साफ़-सुथरा और पढ़ने लायक बनाए रखते हैं.
8. MCP टूलबॉक्स: अहमियत और Java SDK
एमसीपी क्या है?
मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) को एआई के लिए यूनिवर्सल ट्रांसलेटर के तौर पर समझें. एमसीपी को इसलिए बनाया गया है, ताकि एआई मॉडल, बाहरी टूल और डेटासेट से एक स्टैंडर्ड तरीके से कनेक्ट हो सकें. एमसीपी, कस्टम और फ़्रैगमेंटेड इंटिग्रेशन स्क्रिप्ट की जगह एक सुरक्षित और यूनिवर्सल प्रोटोकॉल का इस्तेमाल करता है. चाहे आपके एजेंट को लेन-देन वाली एसक्यूएल क्वेरी को पूरा करना हो, नीति से जुड़े हज़ारों दस्तावेज़ों में खोजना हो या REST API को ट्रिगर करना हो, MCP एक ही यूनीफ़ाइड इंटरफ़ेस उपलब्ध कराता है.
डेटाबेस के लिए MCP टूलबॉक्स
इंजीनियरिंग टीमें, अब सामान्य चैटबॉट से आगे बढ़कर एजेंटिक सिस्टम बना रही हैं. ये सिस्टम, मिशन के लिए ज़रूरी डेटाबेस से सीधे इंटरैक्ट करते हैं. हालांकि, इन एंटरप्राइज़ एजेंट को बनाने का मतलब अक्सर कस्टम ग्लू कोड, नाजुक एपीआई, और जटिल डेटाबेस लॉजिक की इंटिग्रेशन वॉल से टकराना होता है.
इन हार्डकोड किए गए बॉटलनेक को सुरक्षित और यूनिफ़ाइड कंट्रोल प्लेन से बदलने के लिए, हमें डेटाबेस के लिए Model Context Protocol (MCP) टूलबॉक्स के Java SDK को लॉन्च करते हुए खुशी हो रही है. इस रिलीज़ के साथ, दुनिया भर में सबसे ज़्यादा इस्तेमाल होने वाले एंटरप्राइज़ इकोसिस्टम के लिए, टाइपसेफ़ एजेंट ऑर्केस्ट्रेशन की सुविधा उपलब्ध कराई गई है. Java का आर्किटेक्चर, इन ज़रूरी शर्तों को पूरा करने के लिए बनाया गया है. यह एक साथ कई अनुरोधों को प्रोसेस करने की सुविधा देता है. साथ ही, लेन-देन की अखंडता और स्टेट मैनेजमेंट को बनाए रखता है. इससे प्रोडक्शन में मिशन-क्रिटिकल एआई एजेंट को सुरक्षित तरीके से स्केल करने में मदद मिलती है.
Java SDK क्यों?
MCP Toolbox Java SDK की मदद से, Java डेवलपर ये काम कर सकते हैं:
- उपयोग किए जाने वाले टूल: किसी एमसीपी सर्वर (जैसे कि AlloyDB के लिए एमसीपी टूलबॉक्स) से कनेक्ट करें. साथ ही, इसकी क्षमताओं को अपने-आप Java के ऐसे तरीकों में बदलें जिन्हें LangChain4j समझता है.
- टाइप सेफ़्टी: टूल पैरामीटर के लिए, Java की टाइपिंग का इस्तेमाल करें. इससे टूल कॉल में रनटाइम "भ्रम" वाली गड़बड़ियां कम होती हैं.
- Enterprise Readiness: Spring Boot, Quarkus, Micronaut वगैरह के साथ आसानी से इंटिग्रेट किया जा सकता है.
- आसानी से कनेक्ट करें: JSON-RPC का बॉयलरप्लेट कोड लिखने से बचें.
- स्टैंडर्डाइज़ ऑथराइज़ेशन: Google Cloud OIDC टोकन के लिए नेटिव सपोर्ट, टूल को सुरक्षित तरीके से चलाने की सुविधा देता है.
और भी बहुत कुछ ज़्यादा.
डिपेंडेंसी: pom.xml कॉन्फ़िगरेशन
MCP Toolbox Java SDK का नया वर्शन शामिल करने के लिए, अपने Maven प्रोजेक्ट में यह डिपेंडेंसी जोड़ें:
<dependency>
<groupId>com.google.cloud.mcp</groupId>
<artifactId>mcp-toolbox-sdk-java</artifactId>
<version>0.2.0</version>
</dependency>
LangChain4j आर्टफ़ैक्ट को शामिल करने के लिए, अपने Maven प्रोजेक्ट में यह डिपेंडेंसी जोड़ें:
<!-- LangChain4j Core & Gemini -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j</artifactId>
<version>0.35.0</version>
</dependency>
बस इतना ही!!! हमने प्रोजेक्ट को क्लोन कर लिया है. साथ ही, एजेंट, MCP Toolbox Java SDK, और कॉन्टेक्स्ट के बारे में जानकारी दे दी है.
9. स्थानीय तौर पर चल रहा है
अपनी मशीन पर एजेंट को टेस्ट करने के लिए, आपको उसे डिप्लॉय किए गए एमसीपी टूलबॉक्स सर्वर पर पॉइंट करना होगा.
- एनवायरमेंट वैरिएबल सेट करें:
export GCP_PROJECT_ID="<<YOUR_PROJECT_ID>>"
export GCP_REGION="us-central1"
export GEMINI_MODEL_NAME="gemini-2.5-flash"
export MCP_TOOLBOX_URL="<<YOUR_TOOLBOX_ENDPOINT_URL>>/mcp"
- Maven के साथ चलाएं:
mvn compile
mvn spring-boot:run
इससे आपका एजेंट स्थानीय तौर पर शुरू हो जाएगा और आपको इसे टेस्ट करने का विकल्प मिलेगा.
10. इसे Cloud Run पर डिप्लॉय करते हैं
इसे Cloud Run पर डिप्लॉय करें. इसके लिए, Cloud Shell टर्मिनल में यह कमांड चलाएं. यह वह टर्मिनल होना चाहिए जहां प्रोजेक्ट को क्लोन किया गया है. साथ ही, पक्का करें कि आप प्रोजेक्ट के रूट फ़ोल्डर में हों.
अगर आप हमारे मौजूदा प्रोजेक्ट के रूट फ़ोल्डर में नहीं हैं, तो इसे अपने Cloud Shell टर्मिनल में चलाएं:
cd cymbal-transit
अगर आप पहले से ही cymbal-transit रूट में हैं, तो ऐप्लिकेशन को सीधे Cloud Run पर डिप्लॉय करने के लिए, यहां दिया गया निर्देश चलाएं:
gcloud run deploy cymbal-transit --source . --set-env-vars GCP_PROJECT_ID=<<YOUR_PROJECT_ID>>,GCP_REGION=us-central1,GEMINI_MODEL_NAME=gemini-2.5-flash,MCP_TOOLBOX_URL=<<YOUR_MCP_TOOLBOX_URL>> --allow-unauthenticated
प्लेसहोल्डर <<YOUR_PROJECT>> and <<YOUR_MCP_TOOLBOX_URL>> की वैल्यू बदलें
कमांड पूरी होने के बाद, यह सेवा का यूआरएल जनरेट करेगा. इसे कॉपी करें.
Cloud Run सेवा खाते को AlloyDB क्लाइंट की भूमिका असाइन करें.इससे आपका सर्वरलेस ऐप्लिकेशन, डेटाबेस में सुरक्षित तरीके से टनल कर पाएगा.
इसे अपने Cloud Shell टर्मिनल में चलाएं:
# 1. Get your Project ID and Project Number
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
# 2. Grant the AlloyDB Client role
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/alloydb.client"
ध्यान दें: डिप्लॉय करने के बाद, Cloud Run सेवा की सूची पर जाएं और पक्का करें कि उस सेवा के सुरक्षा टैब में, "सार्वजनिक ऐक्सेस की अनुमति दें" विकल्प चुना गया हो.
अब सेवा के यूआरएल (Cloud Run एंडपॉइंट, जिसे आपने पहले कॉपी किया था) का इस्तेमाल करें और ऐप्लिकेशन को टेस्ट करें.
ध्यान दें: अगर आपको सेवा से जुड़ी कोई समस्या आती है और इसकी वजह मेमोरी बताई जाती है, तो इसे आज़माने के लिए, मेमोरी की तय सीमा को 1 GiB तक बढ़ाएं.
11. डेमो
एजेंट से पूछें: "मुझे कल सुबह न्यूयॉर्क से बॉस्टन जाना है. क्या मैं अपने गोल्डन रिट्रीवर को ला सकता हूं?" देखें कि एजेंट:
- बड़े कुत्तों से जुड़ी नीतियां खोजता है.
- यह कुकी, खास शेड्यूल ढूंढती है.
- यह कुकी, यात्रा के आईडी के साथ सबसे तेज़ यात्रा की खास जानकारी देती है.
- कार्रवाई के अनुरोध को पूरा करने के लिए, टिकट भी बुक करता है.
12. व्यवस्थित करें
इस लैब को पूरा करने के बाद, alloyDB क्लस्टर और इंस्टेंस को मिटाना न भूलें.
इससे क्लस्टर और उसके इंस्टेंस मिट जाएंगे.
13. बधाई हो
आपने Java पर आधारित एक बेहतर ट्रांज़िट एजेंट बना लिया है. आपने ऑर्केस्ट्रेशन के लिए LangChain4j और डेटा कनेक्टिविटी के लिए MCP Toolbox Java SDK का इस्तेमाल करके, एक ऐसा सिस्टम बनाया है जो एजेंट, टूल, और डेटा सोर्स के बारे में तर्क दे सकता है. अगर आपको कई डेटाबेस और प्लैटफ़ॉर्म पर, डेटाबेस के लिए MCP टूलबॉक्स की मदद से अपने एजेंटिक ऐप्लिकेशन को व्यवस्थित करना है, तो आज ही Java SDK का इस्तेमाल शुरू करें! यहां लॉन्च की सूचना देने वाला ब्लॉग दिया गया है. इसमें लाइब्रेरी के बारे में ज़्यादा जानकारी दी गई है. अगर आपको इस तरह के और ऐप्लिकेशन बनाने हैं, तो https://codevipassana.dev पर जाकर, Code Vipassana के लिए साइन अप करें!!! यहां आपको बिना किसी शुल्क के, अपनी गति के हिसाब से और इंस्ट्रक्टर की मदद से सीखने का मौका मिलेगा.