एजेंट बनाने के टूल: एडीके की मदद से, असिस्टेंट बनाने की शुरुआत करना

1. परिचय

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

टूल की मदद से एजेंट बनाना

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

  • ADK डेवलपमेंट के लिए Python प्रोजेक्ट सेट अप करने का तरीका.
  • बुनियादी ADK एजेंट बनाने का तरीका.
  • फ़ंक्शन टूल को लागू करने और इस्तेमाल करने का तरीका.
  • Google Search जैसे पहले से मौजूद टूल को इंटिग्रेट करने का तरीका.
  • ADK में LangChain जैसे फ़्रेमवर्क से तीसरे पक्ष के टूल का इस्तेमाल कैसे करें.
  • डेटाबेस (Cloud SQL) और एपीआई के साथ इंटरैक्ट करने के लिए, MCP टूल का इस्तेमाल कैसे करें.

2. खास जानकारी

मान लें कि आप दुनिया भर में कॉफ़ी मशीनें बेचने वाली कंपनी QuantumRoast में प्रोजेक्ट मैनेजर हैं.

क्वांटम रोस्ट

आप अपने साथियों की मदद करते हैं, ताकि वे इंजीनियरिंग के रोडमैप, अचानक होने वाले बदलावों (अब हम माचा बना रहे हैं!) और ग्राहकों से मिलने वाली समस्याओं को आसानी से हल कर सकें. इनमें, गड़बड़ी वाले इनवॉइस सिस्टम से लेकर ऐसी कॉफ़ी मशीन तक की समस्याएं शामिल हैं जो 24 घंटे तेज़ आवाज़ करती है.

आपके पास रोज़ाना करीब 50 ब्राउज़र टैब खुले होते हैं: इंटरनल टिकट सिस्टम, ईमेल, चैट, GitHub, Google Search, StackOverflow वगैरह. आपको अपना काम और अपने साथियों के साथ काम करना पसंद है. हालांकि, कुछ दिनों में आपको बहुत ज़्यादा काम करना पड़ता है.

प्रोजेक्ट मैनेजर के पास काम का बहुत ज़्यादा बोझ है

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

एआई एजेंट

Agent Development Kit (ADK)

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

ADK, वह फ़्रेमवर्क है जिसका इस्तेमाल हम QuantumRoast सॉफ़्टवेयर बग असिस्टेंट बनाने के लिए करेंगे.

एजेंट का डायग्राम

टूल 101

एआई एजेंट, किसी समस्या को हल करने के लिए मॉडल का इस्तेमाल करते हैं. वे सिर्फ़ हार्ड कोड किए गए लॉजिक का इस्तेमाल नहीं करते. हालांकि, एआई एजेंट सिर्फ़ एलएलएम पर आधारित तर्क नहीं देते. वे बाहरी डेटा इकट्ठा करने और फिर उपयोगकर्ता की ओर से कार्रवाई करने के लिए खास तौर पर बनाए गए हैं. एआई एजेंट, किसी समस्या को हल करने का तरीका बताने के बजाय, उसे हल करने में आपकी मदद कर सकता है. हम ऐसा कैसे करते हैं? टूल की मदद से!

टूल एक ऐसी सुविधा होती है जिसकी मदद से एआई एजेंट, दुनिया से इंटरैक्ट कर पाता है. कोई टूल कुछ भी हो सकता है: इनलाइन फ़ंक्शन, होस्ट किया गया डेटाबेस, तीसरे पक्ष का एपीआई या कोई अन्य एजेंट. एआई एजेंट फ़्रेमवर्क, जैसे कि एजेंट डेवलपमेंट किट (एडीके) में टूल के लिए पहले से मौजूद सहायता की सुविधा होती है. यह अलग-अलग तरह के टूल के साथ काम करता है. इनके बारे में हम अभी आपको बताएंगे.

हालांकि, एजेंट को यह कैसे पता चलता है कि किसी टूल को कब कॉल करना है और उसे कॉल कैसे करना है? यहां एजेंट का मॉडल कुछ अहम भूमिकाएं निभाता है.

टूल कैसे काम करते हैं

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

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

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

इन सभी को ऐक्शन में देखने के लिए, अब ADK Python का इस्तेमाल करके QuantumRoast की बग असिस्टेंट एजेंट बनाएं.

QuantumRoast Bug Assistant

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

Google Cloud प्रोजेक्ट का सेटअप

  1. अगर आपके पास पहले से कोई Google खाता नहीं है, तो आपको Google खाता बनाना होगा.
    • ऑफ़िस या स्कूल वाले खाते के बजाय, निजी खाते का इस्तेमाल करें. ऑफ़िस और स्कूल वाले खातों पर कुछ पाबंदियां हो सकती हैं. इनकी वजह से, इस लैब के लिए ज़रूरी एपीआई चालू नहीं किए जा सकते.
  2. Google Cloud Console में साइन इन करें.
  3. Cloud Console में बिलिंग चालू करें.
    • इस लैब को पूरा करने में, Cloud संसाधनों पर 1 डॉलर से कम का खर्च आना चाहिए.
    • ज़्यादा शुल्क से बचने के लिए, इस लैब के आखिर में दिए गए निर्देशों का पालन करके संसाधनों को मिटाया जा सकता है.
    • नए उपयोगकर्ता, 300 डॉलर के मुफ़्त क्रेडिट पा सकते हैं.
  4. नया प्रोजेक्ट बनाएं या किसी मौजूदा प्रोजेक्ट का फिर से इस्तेमाल करें.

Cloud Shell Editor खोलें

  1. Cloud Shell Editor पर जाएं
  2. अगर टर्मिनल स्क्रीन पर सबसे नीचे नहीं दिख रहा है, तो इसे खोलें:
    • हैमबर्गर मेन्यू हैमबर्गर मेन्यू का आइकॉन पर क्लिक करें
    • टर्मिनल पर क्लिक करें
    • नया टर्मिनलCloud Shell Editor में नया टर्मिनल खोलें पर क्लिक करें
  3. टर्मिनल में, इस निर्देश का इस्तेमाल करके अपना प्रोजेक्ट सेट करें. इसके लिए, YOUR_PROJECT_ID की जगह पर अपना प्रोजेक्ट आईडी डालें:
    • फ़ॉर्मैट:
      gcloud config set project YOUR_PROJECT_ID
    • उदाहरण:
      gcloud config set project lab-project-id-example
    • अगर आपको अपना प्रोजेक्ट आईडी याद नहीं है, तो:
      • अपने सभी प्रोजेक्ट आईडी की सूची इन तरीकों से देखी जा सकती है:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Cloud Shell Editor के टर्मिनल में प्रोजेक्ट आईडी सेट करना
  4. अगर अनुमति देने के लिए कहा जाए, तो जारी रखने के लिए अनुमति दें पर क्लिक करें. Cloud Shell को अनुमति देने के लिए क्लिक करें
  5. आपको यह मैसेज दिखेगा:
    Updated property [core/project].
    अगर आपको WARNING दिखता है और आपसे Do you want to continue (Y/N)? पूछा जाता है, तो इसका मतलब है कि आपने प्रोजेक्ट आईडी गलत डाला है. N दबाएं, Enter दबाएं, और gcloud config set project कमांड को फिर से चलाने की कोशिश करें.
  6. टर्मिनल में, PROJECT_ID एनवायरमेंट वैरिएबल सेट करें, ताकि इसे बाद के चरणों में इस्तेमाल किया जा सके.
    export PROJECT_ID=$(gcloud config get project)

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

ज़रूरी Google Cloud API चालू करने के लिए, टर्मिनल में यह कमांड चलाएं:

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

Cloud SQL for PostgreSQL इंस्टेंस बनाना

QuantumRoast के पास एक बग टिकट डेटाबेस है, जिसमें सभी इंटरनल टिकट होते हैं. आइए, Cloud SQL for PostgreSQL इंस्टेंस बनाकर इसे सेट अप करें.

gcloud sql instances create software-assistant \
   --database-version=POSTGRES_16 \
   --tier=db-custom-1-3840 \
   --region=us-central1 \
   --edition=ENTERPRISE \
   --enable-google-ml-integration \
   --database-flags cloudsql.enable_google_ml_integration=on \
   --root-password=admin

इंस्टेंस बनने तक इंतज़ार करें. इसमें कुछ मिनट लग सकते हैं.

बन जाने के बाद, Cloud Console में यहां जाकर अपना इंस्टेंस देखा जा सकता है.

Cloud SQL डेटाबेस बनाना

एसक्यूएल डेटाबेस (tickets-db) बनाएं. साथ ही, Cloud SQL सेवा खाते को Vertex AI का ऐक्सेस दें, ताकि हम समानता के आधार पर खोज करने के लिए एम्बेडिंग बना सकें.

gcloud sql databases create tickets-db --instance=software-assistant

SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe software-assistant --format="value(serviceAccountEmailAddress)")
echo $SERVICE_ACCOUNT_EMAIL

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" --role="roles/aiplatform.user"

tickets टेबल सेट अप करना

Cloud Console (Cloud SQL) में जाकर, software-assistant इंस्टेंस के लिए Cloud SQL Studio खोलें.

postgres उपयोगकर्ता नाम और admin पासवर्ड का इस्तेमाल करके, tickets-db डेटाबेस में लॉग इन करें.

Cloud SQL Studio

नया Editor टैब खोलें.

Cloud SQL Studio Editor

इसके बाद, टेबल सेट अप करने और वेक्टर एम्बेडिंग बनाने के लिए, यहां दिया गया SQL कोड चिपकाएं. निर्देश देने के लिए, Run बटन दबाएं.

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector CASCADE;
GRANT EXECUTE ON FUNCTION embedding TO postgres;

CREATE TABLE tickets (
    ticket_id SERIAL PRIMARY KEY,             -- PostgreSQL's auto-incrementing integer type (SERIAL is equivalent to INT AUTO_INCREMENT)
    title VARCHAR(255) NOT NULL,              -- A concise summary or title of the bug/issue.
    description TEXT,                         -- A detailed description of the bug.
    assignee VARCHAR(100),                    -- The name or email of the person/team assigned to the ticket.
    priority VARCHAR(50),                     -- The priority level (e.g., 'P0 - Critical', 'P1 - High').
    status VARCHAR(50) DEFAULT 'Open',        -- The current status of the ticket (e.g., 'Open', 'In Progress', 'Resolved'). Default is 'Open'.
    creation_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, -- Timestamp when the ticket was first created. 'WITH TIME ZONE' is recommended for clarity and compatibility.
    updated_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP  -- Timestamp when the ticket was last updated. Will be managed by a trigger.
);

tickets टेबल बना दी गई है. पुरानी क्वेरी हटाने के लिए, Clear पर क्लिक करें.

अब सैंपल डेटा डालें और Run बटन को फिर से दबाएं.

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Login Page Freezes After Multiple Failed Attempts', 'Users are reporting that after 3 failed login attempts, the login page becomes unresponsive and requires a refresh. No specific error message is displayed.', 'samuel.green@example.com', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Dashboard Sales Widget Intermittent Data Loading Failure', 'The "Sales Overview" widget on the main dashboard intermittently shows a loading spinner but no data. Primarily affects Chrome browser users.', 'maria.rodriguez@example.com', 'P1 - High', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Broken Link in Footer - Privacy Policy', 'The "Privacy Policy" hyperlink located in the website footer leads to a 404 "Page Not Found" error.', 'maria.rodriguez@example.com', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('UI Misalignment on Mobile Landscape View (iOS)', 'On specific iOS devices (e.g., iPhone 14 models), the top navigation bar shifts downwards when the device is viewed in landscape orientation, obscuring content.', 'maria.rodriguez@example.com', 'P2 - Medium', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Critical XZ Utils Backdoor Detected in Core Dependency (CVE-2024-3094)', 'Urgent: A sophisticated supply chain compromise (CVE-2024-3094) has been identified in XZ Utils versions 5.6.0 and 5.6.1. This malicious code potentially allows unauthorized remote SSH access by modifying liblzma. Immediate investigation and action required for affected Linux/Unix systems and services relying on XZ Utils.', 'frank.white@example.com', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Database Connection Timeouts During Peak Usage', 'The application is experiencing frequent database connection timeouts, particularly during peak hours (10 AM - 12 PM EDT), affecting all users and causing service interruptions.', 'frank.white@example.com', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Export to PDF Truncates Long Text Fields in Reports', 'When generating PDF exports of reports containing extensive text fields, the text is abruptly cut off at the end of the page instead of wrapping or continuing to the next page.', 'samuel.green@example.com', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Search Filter "Date Range" Not Applying Correctly', 'The "Date Range" filter on the search results page does not filter records accurately; results outside the specified date range are still displayed.', 'samuel.green@example.com', 'P2 - Medium', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Typo in Error Message: "Unathorized Access"', 'The error message displayed when a user attempts an unauthorized action reads "Unathorized Access" instead of "Unauthorized Access."', 'maria.rodriguez@example.com', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Intermittent File Upload Failures for Large Files', 'Users are intermittently reporting that file uploads fail without a clear error message or explanation, especially for files exceeding 10MB in size.', 'frank.white@example.com', 'P1 - High', 'Open');

QuantumRoast में, हमें यह पता करना पड़ सकता है कि किसी बग/टिकट को पिछली बार कब अपडेट किया गया था.

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

ट्रिगर लागू करने के लिए, Clear पर क्लिक करें. इसके बाद, यहां दिया गया SQL चिपकाएं.

इसे लागू करने के लिए, Run बटन दबाएं.

CREATE OR REPLACE FUNCTION update_updated_time_tickets()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_time = NOW();  -- Set the updated_time to the current timestamp
    RETURN NEW;                -- Return the new row
END;
$$ language 'plpgsql';        

CREATE TRIGGER update_tickets_updated_time
BEFORE UPDATE ON tickets
FOR EACH ROW                  -- This means the trigger fires for each row affected by the UPDATE statement
EXECUTE PROCEDURE update_updated_time_tickets();

description फ़ील्ड से वेक्टर एम्बेडिंग बनाएं. इससे हमारे एजेंट को, हमारे डेटाबेस में मिलते-जुलते प्रॉडक्ट खोजने की सुविधा मिलेगी. उदाहरण के लिए, "क्या वेबसाइट के होम पेज से जुड़ी कोई समस्या है?".

ALTER TABLE tickets ADD COLUMN embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005',description)) STORED;

अब डेटाबेस से क्वेरी करके यह पुष्टि की जा सकती है कि वह तैयार है.

SELECT * FROM tickets;

आपको 10 पंक्तियां दिखेंगी, जो इस तरह दिखेंगी:

Cloud SQL डेटाबेस की पुष्टि करना

अब आप इस वर्कशॉप के सबसे मज़ेदार हिस्से की तरफ़ चलते हैं. यानी, कोड!

4. Python प्रोजेक्ट सेटअप करना

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

सबसे पहले, एक quantum-roast फ़ोल्डर बनाएं और उसमें cd करें:

mkdir quantum-roast && cd quantum-roast

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

हम अपने प्रोजेक्ट और डिपेंडेंसी को मैनेज करने के लिए, uv (Python का बहुत तेज़ पैकेज और प्रोजेक्ट मैनेजर) का इस्तेमाल करेंगे. यह Cloud Shell में पहले से इंस्टॉल होता है. Uv की मदद से, हम अपनी कुछ फ़ाइलों को सेट अप कर पाएंगे. साथ ही, वर्चुअल एनवायरमेंट, डिपेंडेंसी वगैरह को मैनेज कर पाएंगे. इसलिए, हमें ऐसा नहीं करना पड़ेगा!

uv init की मदद से नया प्रोजेक्ट शुरू करें:

uv init --description "QuantumRoast Software Bug Assistant with ADK" --bare --python 3.10

कमांड चलाने के बाद, हमारे प्रोजेक्ट के लिए pyproject.toml फ़ाइल होनी चाहिए. पुष्टि करने के लिए, Cloud Shell टर्मिनल में cat pyproject.toml चलाएं:

cat pyproject.toml

आउटपुट में यह दिखना चाहिए:

[project]
name = "quantum-roast"
version = "0.1.0"
description = "QuantumRoast Software Bug Assistant with ADK"
requires-python = ">=3.10"
dependencies = []

अब google-adk का इस्तेमाल करके, अपने प्रोजेक्ट में google-adk (ADK) को डिपेंडेंसी के तौर पर जोड़ने का समय आ गया है.uv add

uv add google-adk==1.11.0

इससे हमारे pyproject.toml में, dependencies की सूची में google-adk जुड़ जाता है.

ADK को सबसे अच्छे नतीजे पाने के लिए, प्रोजेक्ट के स्ट्रक्चर की ज़रूरत होती है.

quantum-roast/
    software_bug_assistant/
        __init__.py
        agent.py
        .env

software_bug_assistant फ़ोल्डर और उसमें मौजूद फ़ाइलें बनाएं:

mkdir software_bug_assistant && touch software_bug_assistant/__init__.py \
software_bug_assistant/agent.py \
software_bug_assistant/tools.py \
software_bug_assistant/.env

ls का इस्तेमाल करके, फ़ाइलों के बनने की पुष्टि करें:

ls -a software_bug_assistant/

आपको यह जानकारी दिखेगी:

__init__.py	 .  ..	 .env	 agent.py    tools.py

अब .env फ़ाइल में, एनवायरमेंट वैरिएबल डालने का समय आ गया है. इनकी ज़रूरत ADK को Gemini के मॉडल को सही तरीके से कॉल करने के लिए होती है. हम Vertex API के ज़रिए Gemini को ऐक्सेस करेंगे.

echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_LOCATION=us-central1" >> software_bug_assistant/.env

.env एट्रिब्यूट की वैल्यू सही तरीके से भरी गई है या नहीं, इसकी पुष्टि करने के लिए यह कमांड चलाएं:

cat software_bug_assistant/.env

आपको यहां दिया गया टेक्स्ट दिखेगा. इसमें your-project-id आपका प्रोजेक्ट आईडी है:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

अब हम अपना ADK एजेंट बनाने के लिए तैयार हैं.

5. Base ADK Agent

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

Cloud Shell Editor में agent.py खोलें:

cloudshell edit software_bug_assistant/agent.py

यहां दिए गए कोड को agent.py में चिपकाएं और फ़ाइल को Ctrl + s के तौर पर सेव करें:

from google.adk.agents import Agent

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[],
)

ADK के डेवलपर यूज़र इंटरफ़ेस (adk web) को शुरू करके, नए एजेंट को चलाएं. uv run के साथ ऐसा करने पर, ADK इंस्टॉल किया गया वर्चुअल एनवायरमेंट अपने-आप बन जाएगा.

uv run adk web --port 8080 --reload_agents

आपको कंसोल में, ADK वेब सर्वर के चालू होने की सूचना दिखेगी.

INFO:     Started server process [1557]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

यूज़र इंटरफ़ेस (यूआई) देखने के लिए, Cloud Shell की वेब प्रीव्यू सुविधा खोलें.

Cloud Shell में वेब प्रीव्यू

आपको ADK का वेब यूज़र इंटरफ़ेस (यूआई) दिखेगा.

ADK का वेब यूज़र इंटरफ़ेस (यूआई)

आगे बढ़ें और ADK एजेंट से चैट करें.

एजेंट से What day is it today? के बारे में पूछें.

ADK वेब का उदाहरण

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

ADK के पहले टूल टाइप, फ़ंक्शन टूल को लागू करने का समय.

6. फ़ंक्शन टूल

ADK टूल का पहला और सबसे आसान टाइप, फ़ंक्शन टूल है. यह Python का एक ऐसा फ़ंक्शन है जिसे एजेंट कॉल करता है!

फ़ंक्शन टूल

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

QuantumRoast में, हमें आज की तारीख पाने के लिए एक बुनियादी फ़ंक्शन तय करना है, ताकि बाद में इस लैब में, "मुझे पिछले हफ़्ते के बग दिखाओ" या "आज कौन सा दिन है?" जैसी क्वेरी को हैंडल किया जा सके. (ऐसा हम सभी के साथ होता है).

/software_bug_assistant फ़ोल्डर में मौजूद tools.py फ़ाइल में, हम इस लैब के दौरान बनाए गए सभी टूल को व्यवस्थित करेंगे.

+ आइकॉन पर क्लिक करके, नया टर्मिनल खोलें.

नया टर्मिनल

अब नए टर्मिनल में, PROJECT_ID सेट करें और tools.py खोलें:

cd quantum-roast
export PROJECT_ID=$(gcloud config get project)
cloudshell edit software_bug_assistant/tools.py

अब get_current_date फ़ंक्शन को परिभाषित करें. इसका इस्तेमाल फ़ंक्शन टूल के तौर पर किया जाएगा.

from datetime import datetime

# ----- Example of a Function tool -----
def get_current_date() -> dict:
    """
    Get the current date in the format YYYY-MM-DD
    """
    return {"current_date": datetime.now().strftime("%Y-%m-%d")}

अब फ़ंक्शन के बारे में जानकारी दी गई है! अब इसे एजेंट को टूल के तौर पर पास करने का समय है.

Cloud Shell Editor में agent.py खोलें:

cloudshell edit software_bug_assistant/agent.py

हमें tools.py से get_current_date फ़ंक्शन इंपोर्ट करना है और फ़ंक्शन को एजेंट के tools आर्ग्युमेंट में पास करना है.

अपडेट किया गया agent.py इस तरह दिखता है:

from google.adk.agents import Agent

from .tools import get_current_date

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date],
)

अब अगर आपको ADK Web UI चलाने वाले वेब प्रीव्यू टैब पर वापस जाना है और What day is it today? फिर से पूछना है...

ADK वेब फ़ंक्शन टूल

एजेंट, get_current_date फ़ंक्शन टूल को कॉल करके तारीख के बारे में सही जानकारी दे सकता है! 🎉

अब ADK टूल के अगले टाइप के बारे में जानें.

7. पहले से मौजूद टूल

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

पहले से मौजूद टूल

Google Search में मौजूद टूल का इस्तेमाल करने के लिए, tools.py फ़ाइल खोलें.

cloudshell edit software_bug_assistant/tools.py

tools.py के सबसे नीचे यह जोड़ें:

# ----- Built-in Tool Imports -----
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

# ----- Example of a Built-in Tool -----
search_agent = Agent(
    model="gemini-2.5-flash",
    name="search_agent",
    description="A specialist in Google Search.",
    instruction="""
    You're a specialist in Google Search.
    """,
    tools=[google_search],
)

search_tool = AgentTool(search_agent)

यहां, हम Google Search टूल को उसके अपने एजेंट में रैप कर रहे हैं. साथ ही, उसे सिस्टम के अपने निर्देश दे रहे हैं. इससे एजेंट को टूल के तौर पर इस्तेमाल किया जा रहा है.

अब हम search_tool को इंपोर्ट करके, agent.py में रूट एजेंट को पास कर सकते हैं:

cloudshell edit software_bug_assistant/agent.py

agent.py को शामिल करने के लिए, agent.py की जगह यह कोड इस्तेमाल करें:search_tool

from google.adk.agents import Agent

from .tools import get_current_date, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool],
)

फ़ाइल सेव करें और उस टैब पर वापस जाएं जिसमें ADK का वेब यूज़र इंटरफ़ेस (यूआई) चल रहा है.

QuantumRoast में, हम यह पक्का करना चाहते हैं कि हमारी वेबसाइट और सॉफ़्टवेयर, सामान्य जोखिमों और एक्सपोज़र (सीवीई) से सुरक्षित रहें. ये सार्वजनिक सायबर सुरक्षा से जुड़ी कमज़ोरियां होती हैं. हम अपने एजेंट के नए Google Search टूल का इस्तेमाल करके, वेब पर हाल ही में पता चले CVE के बारे में खोज कर सकते हैं.

यह क्वेरी चलाएं: Do a web search for 5 of the most recent CVEs?.

हमारे एजेंट को वेब पर खोजने के लिए, search_agent को कॉल करना चाहिए.

ADK वेब में बिल्ट-इन टूल का उदाहरण

हमारे एजेंट ने अब Google Search के लिए, ADK के बिल्ट-इन टूल की मदद से, वेब पर खोजने की सुविधा को अनलॉक कर दिया है! 🎉

अब हम अगले एडीके टूल टाइप के बारे में बात करेंगे.

8. थर्ड पार्टी टूल

ADK को इस तरह से डिज़ाइन किया गया है कि इसे आसानी से बढ़ाया जा सकता है. इससे, तीसरे पक्ष के अन्य एआई एजेंट फ़्रेमवर्क, जैसे कि CrewAI और LangChain के टूल को आसानी से इंटिग्रेट किया जा सकता है. यह इंटरऑपरेबिलिटी बहुत ज़रूरी है, क्योंकि इससे डेवलपमेंट में कम समय लगता है और मौजूदा टूल का दोबारा इस्तेमाल किया जा सकता है.

थर्ड पार्टी टूल

StackOverflow के Q&A डेटा को अपने बग एजेंट में शामिल करने के लिए, हम LangChain की टूल लाइब्रेरी से डेटा ले सकते हैं. खास तौर पर, StackExchange API Wrapper टूल से. ADK, LangChain जैसे तीसरे पक्ष के टूल के साथ काम करता है. इसलिए, इस टूल को हमारे ADK एजेंट में जोड़ने के लिए, सिर्फ़ कुछ लाइनों के कोड की ज़रूरत होती है!

सबसे पहले, हमें अपने प्रोजेक्ट में LangChain और StackOverflow (langchain-community और stackapi) के लिए नई डिपेंडेंसी जोड़नी होंगी:

uv add langchain-community==0.3.27 stackapi==0.3.1

LangChain StackExchange टूल के लिए सहायता जोड़ने के लिए, tools.py फ़ाइल खोलें.

cloudshell edit software_bug_assistant/tools.py

tools.py के सबसे नीचे यह जोड़ें:

# ----- Example of a Third-Party Tool -----
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import StackExchangeTool
from langchain_community.utilities import StackExchangeAPIWrapper

stack_exchange_tool = StackExchangeTool(api_wrapper=StackExchangeAPIWrapper())
langchain_tool = LangchainTool(stack_exchange_tool)

अब हम langchain_tool को इंपोर्ट करके, agent.py में रूट एजेंट को पास कर सकते हैं:

cloudshell edit software_bug_assistant/agent.py

agent.py को शामिल करने के लिए, agent.py की जगह यह कोड इस्तेमाल करें:langchain_tool

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool],
)

फ़ाइल सेव करें और ADK Web UI वाले खुले टैब पर वापस जाएं.

एजेंट से, पिछले CVE के बारे में कुछ पूछें "Are there similar issues on stack exchange?" या "Our database queries with SQLAlchemy seem to be timing out, is there anything on StackExchange relevant to this?" जैसे किसी नए विषय के बारे में पूछें.

ADK Web के तीसरे पक्ष के टूल का उदाहरण

हमारे एजेंट ने अब StackOverflow से क्वेरी करने के लिए, ADK में LangChain टूल का इस्तेमाल कर लिया है. 🥳

अब बारी है अगले ADK टूल टाइप की... MCP टूल!

9. MCP टूल (डेटाबेस)

एमसीपी का मतलब मॉडल कॉन्टेक्स्ट प्रोटोकॉल होता है. यह Anthropic की ओर से 2024 में लॉन्च किया गया एक ओपन प्रोटोकॉल है. MCP, आपके एआई एजेंट और टूल "बैकएंड" (एपीआई, डेटाबेस) के बीच एक ऐब्स्ट्रैक्शन लेयर उपलब्ध कराता है.

एमसीपी कैसे काम करता है

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

QuantumRoast में, हमारे पास इंटरनल सॉफ़्टवेयर बग के लिए Cloud SQL for PostgreSQL डेटाबेस है. हमें ADK टूल बनाने हैं, ताकि हमारा एजेंट हमारे डेटाबेस पर कुछ क्वेरी कर सके.

MCP टूल डेटाबेस

इसे करने का सबसे आसान तरीका है , MCP Toolbox for Databases का इस्तेमाल करना. यह डेटाबेस के लिए एक ओपन-सोर्स एमसीपी सर्वर है! Toolbox में 15 से ज़्यादा डेटाबेस इस्तेमाल किए जा सकते हैं. इनमें से एक Cloud SQL है!

टूलबॉक्स में ये सुविधाएं मिलती हैं:

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

ADK में डेटाबेस टूल के लिए MCP टूलबॉक्स का इस्तेमाल किया जा सकता है. इससे इंटिग्रेशन तेज़ी से होता है.

डेटाबेस के लिए MCP टूलबॉक्स

डेटाबेस सर्वर के लिए MCP टूलबॉक्स को Cloud Run पर डिप्लॉय करना

सबसे पहले, हम MCP Toolbox for Databases Server को Cloud Run पर डिप्लॉय करेंगे और इसे अपने Cloud SQL इंस्टेंस पर पॉइंट करेंगे.

Toolbox को कॉन्फ़िगर करने के लिए, YAML फ़ाइल की ज़रूरत होती है. इसमें डेटाबेस सोर्स और कॉन्फ़िगर करने के लिए टूल की जानकारी दी जाती है.

डिप्लॉयमेंट के लिए tools.yaml फ़ाइल बनाएं.

cloudshell edit tools.yaml

इस कॉन्टेंट को tools.yaml में चिपकाएं:

sources:
  postgresql:
    kind: cloud-sql-postgres
    project: ${PROJECT_ID}
    region: us-central1
    instance: software-assistant
    database: tickets-db
    user: postgres
    password: admin

tools:
  search-tickets:
    kind: postgres-sql
    source: postgresql
    description: Search for similar tickets based on their descriptions.
    parameters:
      - name: query
        type: string
        description: The query to perform vector search with.
    statement: |
      SELECT ticket_id, title, description, assignee, priority, status, (embedding <=> embedding('text-embedding-005', $1)::vector) as distance
      FROM tickets
      ORDER BY distance ASC
      LIMIT 3;
  get-ticket-by-id:
    kind: postgres-sql
    source: postgresql
    description: Retrieve a ticket's details using its unique ID.
    parameters:
      - name: ticket_id
        type: string
        description: The unique ID of the ticket.
    statement: SELECT * FROM tickets WHERE ticket_id = $1;
  get-tickets-by-assignee:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on assignee (email).
    parameters:
      - name: assignee
        type: string
        description: The email of the assignee.
    statement: SELECT * FROM tickets WHERE assignee ILIKE '%' || $1 || '%';
  update-ticket-priority:
    kind: postgres-sql
    source: postgresql
    description: Update the priority of a ticket based on its ID.
    parameters:
      - name: priority
        type: string
        description: The priority of the ticket. Can be one of 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'.
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET priority = $1 WHERE ticket_id = $2;
  update-ticket-status:
    kind: postgres-sql
    source: postgresql
    description: Update the status of a ticket based on its ID.
    parameters:
      - name: status
        type: string
        description: The new status of the ticket (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET status = $1 WHERE ticket_id = $2;
  get-tickets-by-status:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their current status.
    parameters:
      - name: status
        type: string
        description: The status of the tickets to retrieve (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
    statement: SELECT * FROM tickets WHERE status ILIKE '%' || $1 || '%';
  get-tickets-by-priority:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their priority.
    parameters:
      - name: priority
        type: string
        description: The priority of the tickets to retrieve (e.g., 'P0 - Critical', 'P1 - High', 'P2 - Medium', 'P3 - Low').
    statement: SELECT * FROM tickets WHERE priority ILIKE '%' || $1 || '%';
  create-new-ticket:
    kind: postgres-sql
    source: postgresql
    description: Create a new software ticket.
    parameters:
      - name: title
        type: string
        description: The title of the new ticket.
      - name: description
        type: string
        description: A detailed description of the bug or issue.
      - name: assignee
        type: string
        description: (Optional) The email of the person to whom the ticket should be assigned.
      - name: priority
        type: string
        description: (Optional) The priority of the ticket. Can be 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'. Default is 'P3 - Low'.
      - name: status
        type: string
        description: (Optional) The initial status of the ticket. Default is 'Open'.
    statement: INSERT INTO tickets (title, description, assignee, priority, status) VALUES ($1, $2, $3, COALESCE($4, 'P3 - Low'), COALESCE($5, 'Open')) RETURNING ticket_id;
  get-tickets-by-date-range:
    kind: postgres-sql
    source: postgresql
    description: Retrieve tickets created or updated within a specific date range.
    parameters:
      - name: start_date
        type: string
        description: The start date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: end_date
        type: string
        description: The end date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: date_field
        type: string
        description: The date field to filter by ('creation_time' or 'updated_time').
    statement: SELECT * FROM tickets WHERE CASE WHEN $3 = 'creation_time' THEN creation_time ELSE updated_time END BETWEEN $1::timestamp AND $2::timestamp;

toolsets:
  tickets_toolset:
    - search-tickets
    - get-ticket-by-id
    - get-tickets-by-assignee
    - get-tickets-by-status
    - get-tickets-by-priority
    - get-tickets-by-date-range
    - update-ticket-priority
    - update-ticket-status
    - create-new-ticket

YAML फ़ाइल, QuantumRoast के टिकट डेटाबेस से जुड़े नौ टूल के बारे में बताती है.

Toolbox Cloud Run सेवा के लिए सेवा खाता कॉन्फ़िगर करने, उसे Cloud SQL और Secret Manager को ऐक्सेस करने की अनुमति देने, और हमारी tools.yaml फ़ाइल के लिए Secret Manager सीक्रेट बनाने में लगने वाला समय.

हम अपनी tools.yaml फ़ाइल को Secret Manager में सेव करेंगे, क्योंकि इसमें Cloud SQL के संवेदनशील क्रेडेंशियल शामिल हैं.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudsql.client

gcloud secrets create tools --data-file=tools.yaml

Cloud Run पर, डेटाबेस के लिए MCP टूलबॉक्स को डिप्लॉय करने में लगने वाला समय. हम MCP Toolbox कंटेनर इमेज के सबसे नए रिलीज़ वर्शन का इस्तेमाल करेंगे.

gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --set-env-vars="PROJECT_ID=$PROJECT_ID" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --allow-unauthenticated

डिप्लॉयमेंट पूरा होने तक इंतज़ार करें...

Cloud Run के लॉग क्वेरी करके, पुष्टि करें कि Toolbox चल रहा है:

gcloud run services logs read toolbox --region us-central1 --limit 10

आपको यह दिखना चाहिए:

2025-08-20 18:03:55 2025-08-20T18:03:55.465847801Z INFO "Initialized 1 sources."
2025-08-20 18:03:55 2025-08-20T18:03:55.466152914Z INFO "Initialized 0 authServices."
2025-08-20 18:03:55 2025-08-20T18:03:55.466374245Z INFO "Initialized 9 tools."
2025-08-20 18:03:55 2025-08-20T18:03:55.466477938Z INFO "Initialized 2 toolsets."
2025-08-20 18:03:55 2025-08-20T18:03:55.467492303Z INFO "Server ready to serve!"

Toolbox सेवा के लिए Cloud Run यूआरएल को एनवायरमेंट वैरिएबल के तौर पर सेव करें, ताकि ADK एजेंट को पता चल सके कि इसे कहां ढूंढना है.

export MCP_TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format "value(status.url)")
echo MCP_TOOLBOX_URL=$MCP_TOOLBOX_URL >> software_bug_assistant/.env

QuantumRoast एजेंट को अपडेट करना

दूसरा, हमें अपने प्रोजेक्ट में MCP Toolbox for Databases SDK (toolbox-core) के लिए डिपेंडेंसी जोड़नी होगी:

uv add toolbox-core==0.5.0

MCP Toolbox टूल के लिए सहायता जोड़ने के लिए, tools.py फ़ाइल खोलें.

cloudshell edit software_bug_assistant/tools.py

tools.py के सबसे नीचे यह जोड़ें:

# ----- Example MCP Toolbox for Databases tools -----
import os
from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = os.getenv("MCP_TOOLBOX_URL", "http://127.0.0.1:5000")

# Initialize Toolbox client
toolbox = ToolboxSyncClient(TOOLBOX_URL)
# Load all the tools from toolset
toolbox_tools = toolbox.load_toolset("tickets_toolset")

अब हम toolbox_tools को इंपोर्ट करके, agent.py में रूट एजेंट को पास कर सकते हैं:

cloudshell edit software_bug_assistant/agent.py

agent.py को शामिल करने के लिए, agent.py की जगह यह कोड इस्तेमाल करें:toolbox_tools

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools],
)

फ़ाइल सेव करें और ADK Web UI वाले खुले टैब पर वापस जाएं.

अब हमारे Cloud SQL इंटरनल टिकट डेटाबेस में सेव किए गए टिकट के बारे में सवाल पूछे जा सकते हैं!

इनमें से किसी एक तरह का सवाल पूछें:

  • I am seeing an issue with database timeouts, has anyone else seen a similar issue?
  • How many bugs are assigned to samuel.green@example.com? Show a table.
  • Can you bump the priority of ticket with ID 6 to to P0 - Critical priority
  • Create a new ticket (एजेंट को बग बनाने की प्रोसेस के बारे में बताने दें)

MCP डेटाबेस टूल का उदाहरण

हमारे एडीके एजेंट ने अब डेटाबेस के लिए एमसीपी टूलबॉक्स टूल की मदद से, हमारे डेटाबेस से क्वेरी कर ली है!🚀

10. ज़रूरी नहीं: एमसीपी टूल (एपीआई)

हमारा ADK एजेंट, MCP टूल से कैसे कनेक्ट होगा? ऐसे टूल जिनका अपना एसडीके नहीं है, जैसे कि डेटाबेस के लिए MCP टूलबॉक्स.

ADK, MCPToolset क्लास के ज़रिए सामान्य एमसीपी टूल के साथ काम करता है. MCPToolset क्लास, ADK का मुख्य तरीका है. इसकी मदद से, MCP सर्वर से टूल इंटिग्रेट किए जाते हैं.

MCP टूल (एपीआई)

MCPToolset का इस्तेमाल, लोकल या रिमोट MCP सर्वर से कनेक्ट करने के लिए किया जा सकता है. QuantumRoast में, हम अपने एजेंट को GitHub के रिमोट MCP सर्वर से कनेक्ट करना चाहते हैं, ताकि GitHub के एपीआई को आसानी से कॉल किया जा सके. इससे हमारा एजेंट, सार्वजनिक सॉफ़्टवेयर रिपॉज़िटरी या हमारे अपने कोडबेस से समस्याओं के बारे में जानकारी हासिल कर पाएगा. GitHub MCP सर्वर, GitHub की अलग-अलग सुविधाओं को दिखाता है. जैसे, समस्या और पुल अनुरोधों से लेकर सूचनाओं और कोड की सुरक्षा तक.

MCP टूल GitHub

GitHub का निजी ऐक्सेस टोकन (पीएटी)

GitHub MCP सर्वर से पुष्टि करने के लिए, आपके पास GitHub का निजी ऐक्सेस टोकन होना चाहिए.

इसे पाने के लिए, यह तरीका अपनाएं:

  1. GitHub की डेवलपर सेटिंग पर जाएं.
  2. "निजी ऐक्सेस टोकन" -> "टोकन (क्लासिक)" पर क्लिक करें.
  3. "नया टोकन जनरेट करें" -> "नया टोकन जनरेट करें (क्लासिक)" पर क्लिक करें.
  4. अपने टोकन को ऐसा नाम दें जिससे उसके बारे में जानकारी मिलती हो.
  5. अपने टोकन के लिए समयसीमा खत्म होने की तारीख सेट करें.
  6. अहम जानकारी: सुरक्षा के लिए, अपने टोकन को सिर्फ़ ज़रूरी स्कोप दें. डेटाबेस को सिर्फ़ पढ़ने के लिए ऐक्सेस करने के लिए, repo:status, public_repo, और read:user स्कोप काफ़ी होते हैं. जब तक बहुत ज़रूरी न हो, तब तक पूरी रिपॉज़िटरी या एडमिन की अनुमतियां न दें.
  7. Generate token पर क्लिक करें.
  8. जनरेट किए गए टोकन को कॉपी करें.

Cloud Shell टर्मिनल में, एजेंट के लिए GitHub PAT सेट करने के लिए, यह कमांड चलाएं. YOUR_GITHUB_PAT को जनरेट किए गए PAT से बदलें.

export GITHUB_PAT=YOUR_GITHUB_PAT

QuantumRoast एजेंट को अपडेट करना

हम गड़बड़ी का पता लगाने वाले अपने असिस्टेंट के लिए, GitHub के सिर्फ़ कुछ रीड-ओनली टूल उपलब्ध कराएंगे. इससे QuantumRoast के कर्मचारी, ओपन-सोर्स डिपेंडेंसी से जुड़ी समस्याओं का पता लगा पाएंगे. साथ ही, यह देख पाएंगे कि क्या इससे उन्हें इंटरनल टिकट सिस्टम में दिख रही गड़बड़ियों की मुख्य वजह का पता लगाने में मदद मिल सकती है. इसे सेट अप करने के लिए, हम ADK के MCPToolset का इस्तेमाल tool_filter के साथ करेंगे. tool-filter सिर्फ़ उन GitHub टूल को दिखाता है जिनकी हमें ज़रूरत होती है. इससे न सिर्फ़ उन टूल को छिपाया जाता है जिन्हें हम उपयोगकर्ताओं को ऐक्सेस नहीं करने देना चाहते (जैसे: संवेदनशील रिपॉज़िटरी ऐक्शन), बल्कि एजेंट के मॉडल को भी सुरक्षित रखा जाता है. ऐसा तब होता है, जब एजेंट सही टूल चुनने की कोशिश कर रहा होता है.

GitHub टूल के लिए सहायता जोड़ने के लिए, tools.py फ़ाइल खोलें.

cloudshell edit software_bug_assistant/tools.py

tools.py के सबसे नीचे यह जोड़ें:

# ----- Example MCP Tools with MCPToolset (GitHub) -----
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://api.githubcopilot.com/mcp/",
        headers={
            "Authorization": "Bearer " + os.getenv("GITHUB_PAT"),
        },
    ),
    # Read only tools
    tool_filter=[
        "search_repositories",
        "search_issues",
        "list_issues",
        "get_issue",
        "list_pull_requests",
        "get_pull_request",
    ],
)

ध्यान दें कि हमें अपने MCPToolset डेफ़िनिशन में GitHub का निजी ऐक्सेस टोकन (पीएटी) भी देना होगा. ठीक उसी तरह जैसे आपको अपने कोड में स्टैंडर्ड एपीआई क्लाइंट सेट अप करते समय, पुष्टि करने वाला टोकन देना होता है. इस PAT का दायरा सिर्फ़ सार्वजनिक रिपॉज़िटरी के डेटा को ऐक्सेस करने तक सीमित है. इसमें उपयोगकर्ता की संवेदनशील जानकारी या रिपॉज़िटरी से जुड़ी कार्रवाइयों के लिए कोई स्कोप नहीं है.

अब हम mcp_tools को इंपोर्ट करके, agent.py में रूट एजेंट को पास कर सकते हैं:

cloudshell edit software_bug_assistant/agent.py

agent.py को शामिल करने के लिए, agent.py की जगह यह कोड इस्तेमाल करें:mcp_tools

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, mcp_tools, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools, mcp_tools],
)

फ़ाइल सेव करें और ADK Web UI वाले खुले टैब पर वापस जाएं.

अब हमारे पास GitHub MCP टूल का एक सेट है, जिसे हमारा एजेंट कॉल कर सकता है. QuantumRoast की सेवाएं, XZ utils, a data compression tool पर निर्भर करती हैं. हमारे इंटरनल बग टिकट सिस्टम में, पिछले साल के CVE (सुरक्षा से जुड़ी कमज़ोरी) को ट्रैक किया जा रहा है. StackOverflow और Google Search टूल का इस्तेमाल करके, हम इसका पता XZ Utils GitHub रिपॉज़िटरी से लगा सकते हैं. इसके बाद, हम GitHub के एमसीपी टूल, search_issues में से किसी एक का इस्तेमाल करके यह पता लगा सकते हैं कि उस सीवीई को कब और कैसे ठीक किया गया था:

एजेंट से ये सवाल पूछें:

  • Find the official XZ Utils GitHub repository
  • Search the repository for issues related to CVE-2024-3094

आपको एजेंट की ओर से GitHub टूल कॉल किए जाते हुए दिखेंगे.

MCP टूल का GitHub उदाहरण

QuantumRoast ADK एजेंट अब GitHub MCP सर्वर टूल के साथ इंटरैक्ट कर सकता है! 🤩

11. बधाई हो

बधाई हो! आपने Agent Development Kit (ADK) का इस्तेमाल करके, QuantumRoast की गड़बड़ी ठीक करने वाले एजेंट को बना लिया है. साथ ही, इसकी क्षमताओं को बेहतर बनाने के लिए, अलग-अलग तरह के टूल इंटिग्रेट किए हैं. आपने एक बुनियादी एजेंट से शुरुआत की और धीरे-धीरे फ़ंक्शन टूल, बिल्ट-इन टूल, तीसरे पक्ष के टूल, और एमसीपी टूल जोड़े.

हमने क्या-क्या कवर किया है

  • ADK डेवलपमेंट के लिए Python प्रोजेक्ट सेट अप करने का तरीका.
  • बुनियादी ADK एजेंट बनाने का तरीका.
  • फ़ंक्शन टूल को लागू करने और इस्तेमाल करने का तरीका.
  • Google Search जैसे पहले से मौजूद टूल को इंटिग्रेट करने का तरीका.
  • ADK में LangChain जैसे फ़्रेमवर्क से तीसरे पक्ष के टूल का इस्तेमाल कैसे करें.
  • डेटाबेस (Cloud SQL) और एपीआई के साथ इंटरैक्ट करने के लिए, MCP टूल का इस्तेमाल कैसे करें.

QuantumRoast Final

साफ़-सफ़ाई सेवा

अतिरिक्त शुल्क से बचने के लिए, अपना Cloud प्रोजेक्ट मिटाया जा सकता है.

Cloud Run, सेवा का इस्तेमाल न किए जाने पर कोई शुल्क नहीं लेता. हालांकि, Artifact Registry में कंटेनर इमेज सेव करने के लिए, आपसे शुल्क लिया जा सकता है. Cloud प्रोजेक्ट मिटाने पर, उस प्रोजेक्ट में इस्तेमाल किए गए सभी संसाधनों के लिए बिलिंग बंद हो जाती है.

अगर आपको प्रोजेक्ट मिटाना है, तो यह तरीका अपनाएं:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

ऐसा भी हो सकता है कि आपको अपने Cloud Shell डिस्क से ग़ैर-ज़रूरी संसाधन मिटाने हों. इसमें ये काम किए जा सकते हैं:

  1. कोड लैब प्रोजेक्ट की डायरेक्ट्री मिटाएं: 
    rm -rf ~/quantum-roast
  2. चेतावनी! इस कार्रवाई को पहले जैसा नहीं किया जा सकता! अगर आपको Cloud Shell पर मौजूद सभी फ़ाइलें मिटाकर जगह खाली करनी है, तो अपनी पूरी होम डायरेक्ट्री मिटाएं. ध्यान रखें कि आपको जो भी डेटा रखना है उसे किसी दूसरी जगह पर सेव कर लिया गया हो. 
    sudo rm -rf $HOME