টুলস একটি এজেন্ট তৈরি করুন: ADK-এর সাহায্যে জিরো থেকে অ্যাসিস্ট্যান্ট

১. ভূমিকা

এই ল্যাবে, আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে একটি এজেন্ট তৈরি করবেন! আপনি শিখবেন কীভাবে ADK এবং বিভিন্ন ধরণের টুল ব্যবহার করে একটি সফটওয়্যার বাগ অ্যাসিস্ট্যান্ট এজেন্ট তৈরি করতে হয়। আপনি একটি বেসিক এজেন্ট দিয়ে শুরু করবেন এবং পর্যায়ক্রমে এর সক্ষমতা বাড়ানোর জন্য বিভিন্ন টুল যোগ করবেন, যার মধ্যে রয়েছে ফাংশন টুল , বিল্ট-ইন টুল , থার্ড-পার্টি টুল এবং মডেল কনটেক্সট প্রোটোকল (MCP) টুল ।

সরঞ্জাম একজন এজেন্ট তৈরি করে

আপনি যা শিখবেন

  • ADK ডেভেলপমেন্টের জন্য কীভাবে একটি পাইথন প্রজেক্ট সেট আপ করবেন।
  • কীভাবে একটি বেসিক ADK এজেন্ট তৈরি করবেন।
  • ফাংশন টুলস কীভাবে প্রয়োগ ও ব্যবহার করতে হয়।
  • গুগল সার্চের মতো বিল্ট-ইন টুলগুলো কীভাবে ইন্টিগ্রেট করবেন
  • ADK-এর মধ্যে LangChain-এর মতো ফ্রেমওয়ার্কের থার্ড-পার্টি টুলগুলো কীভাবে কাজে লাগানো যায়
  • ডাটাবেস (ক্লাউড এসকিউএল) এবং এপিআই-এর সাথে ইন্টারঅ্যাক্ট করতে কীভাবে এমসিপি টুলস ব্যবহার করবেন।

২. সংক্ষিপ্ত বিবরণ

ধরুন, আপনি কোয়ান্টামরোস্ট নামক একটি বিশ্বব্যাপী কফি মেশিন কোম্পানির একজন প্রজেক্ট ম্যানেজার।

কোয়ান্টাম রোস্ট

আপনি আপনার সতীর্থদের ইঞ্জিনিয়ারিং রোডম্যাপ, হঠাৎ কৌশলগত পরিবর্তন (আমরা এখন মাচা তৈরি করছি!), এবং গ্রাহকদের কাছ থেকে আসা বিভিন্ন টিকেটের বিশাল সাগরে পথ খুঁজে পেতে সাহায্য করেন — যার মধ্যে ত্রুটিপূর্ণ ইনভয়েস সিস্টেম থেকে শুরু করে সারাক্ষণ তীক্ষ্ণ শব্দ করতে থাকা একটি কফি মেশিন পর্যন্ত সবকিছুই অন্তর্ভুক্ত।

সাধারণত দিনে আপনার প্রায় পঞ্চাশটির মতো ব্রাউজার ট্যাব খোলা থাকে: অভ্যন্তরীণ টিকেট সিস্টেম, ইমেল, চ্যাট, গিটহাব, গুগল সার্চ, স্ট্যাকওভারফ্লো এবং আরও অনেক কিছু। আপনি আপনার কাজ এবং সহকর্মীদের পছন্দ করেন — কিন্তু কোনো কোনো দিন আপনি দিশেহারা হয়ে পড়েন।

অভিভূত প্রকল্প ব্যবস্থাপক

কেমন হতো যদি এমন একটি সহায়ক তৈরি করা যেত যা আপনাকে সফটওয়্যার টিকেট তৈরি ও বাছাই করতে এবং সমস্যা ডিবাগ করতে সাহায্য করবে? একটি এআই এজেন্ট এটি সম্ভব করে তোলে।

এআই এজেন্ট

এজেন্ট ডেভেলপমেন্ট কিট (ADK)

এজেন্ট ডেভেলপমেন্ট কিট (ADK) হলো এআই এজেন্ট তৈরি এবং স্থাপন করার জন্য একটি নমনীয় ও মডিউলার ফ্রেমওয়ার্ক। যদিও এটি জেমিনি এবং গুগল ইকোসিস্টেমের জন্য বিশেষভাবে তৈরি, ADK মডেল বা স্থাপনার ক্ষেত্রে কোনো সীমাবদ্ধতা রাখে না এবং এটি অন্যান্য ফ্রেমওয়ার্কের সাথে সামঞ্জস্যপূর্ণ করে তৈরি করা হয়েছে। ADK-কে এমনভাবে ডিজাইন করা হয়েছে যাতে এজেন্ট ডেভেলপমেন্ট প্রক্রিয়াটি সফটওয়্যার ডেভেলপমেন্টের মতোই মনে হয় এবং ডেভেলপাররা সাধারণ কাজ থেকে শুরু করে জটিল ওয়ার্কফ্লো পর্যন্ত বিভিন্ন ধরনের এজেন্টিক আর্কিটেকচার সহজে তৈরি, স্থাপন এবং পরিচালনা করতে পারেন।

ADK হলো সেই ফ্রেমওয়ার্ক যা আমরা আমাদের QuantumRoast সফটওয়্যার বাগ অ্যাসিস্ট্যান্ট তৈরি করার জন্য ব্যবহার করব।

এজেন্ট ডায়াগ্রাম

সরঞ্জাম ১০১

এআই এজেন্টরা কোনো সমস্যার সমাধান করতে শুধু পূর্বনির্ধারিত যুক্তিই নয়, বরং মডেলও ব্যবহার করে। কিন্তু শুধু এলএলএম-ভিত্তিক যুক্তির চেয়েও বেশি কিছু; এআই এজেন্টরা বাহ্যিক ডেটা সংগ্রহ করতে এবং তারপর ব্যবহারকারীর পক্ষ থেকে পদক্ষেপ নিতে বিশেষভাবে সক্ষম। কোনো সমস্যার সমাধান কীভাবে করতে হবে তা বলার পরিবর্তে, একটি এআই এজেন্ট আপনাকে সেটি সমাধান করতে সাহায্য করতে পারে। আমরা এটা কীভাবে করি? বিভিন্ন টুলের মাধ্যমে!

টুল হলো এমন একটি সক্ষমতা যা একটি এআই এজেন্টকে পারিপার্শ্বিক জগতের সাথে যোগাযোগ করতে সাহায্য করে। একটি টুল প্রায় যেকোনো কিছুই হতে পারে: একটি ইনলাইন ফাংশন, একটি হোস্টেড ডেটাবেস, একটি থার্ড-পার্টি এপিআই, বা এমনকি অন্য কোনো এজেন্টও। এজেন্ট ডেভেলপমেন্ট কিট (ADK)-এর মতো এআই এজেন্ট ফ্রেমওয়ার্কগুলোতে টুলের জন্য বিল্ট-ইন সাপোর্ট রয়েছে , যা বিভিন্ন ধরনের টুল সমর্থন করে, যেগুলো নিয়ে আমরা একটু পরেই আলোচনা করব।

কিন্তু একজন এজেন্ট কীভাবে জানবে যে কখন একটি নির্দিষ্ট টুলকে কল করতে হবে, শুধু তাই নয়, কীভাবে তাকে কল করতে হবে? এক্ষেত্রে এজেন্টের মডেল কয়েকটি গুরুত্বপূর্ণ ভূমিকা পালন করে।

সরঞ্জামগুলি কীভাবে কাজ করে

প্রথমটি হলো টুল নির্বাচন । আমরা আমাদের এজেন্টকে কিছু টুলের একটি তালিকা এবং সেগুলো ব্যবহারের জন্য কিছু নির্দেশাবলী প্রদান করি। যখন কোনো ব্যবহারকারী এজেন্টকে কোনো কিছু জানতে চায়, তখন এজেন্টের মডেলটি ব্যবহারকারীকে সাহায্য করার জন্য কোন টুলগুলো এবং কেন ব্যবহার করতে হবে, তা নির্ধারণ করতে সাহায্য করে।

দ্বিতীয় গুরুত্বপূর্ণ ধাপটি হলো ফাংশন-কলিং । ফাংশন কলিং নামটি কিছুটা বিভ্রান্তিকর, কারণ মডেলটি আসলে টুলটিকে কল করে না, বরং এটি রিকোয়েস্ট বডি ফরম্যাট করার মাধ্যমে কল করার প্রস্তুতি নেয়, যা ফ্রেমওয়ার্কটি পরে টুলটিকে কল করার জন্য ব্যবহার করে।

সবশেষে, মডেলটি সেই টুল থেকে পাওয়া প্রতিক্রিয়া—যেমন, ডাটাবেস থেকে খোলা বাগগুলির একটি তালিকা—ব্যাখ্যা করতে সাহায্য করে এবং পরবর্তী পদক্ষেপ নেওয়া হবে, নাকি সেই তথ্য দিয়ে ব্যবহারকারীকে উত্তর দেওয়া হবে, সে বিষয়ে সিদ্ধান্ত নেয়।

এই সবকিছু বাস্তবে দেখতে, এখন ADK Python ব্যবহার করে QuantumRoast বাগ অ্যাসিস্ট্যান্ট এজেন্টটি বিল্ড করার সময় এসেছে।

কোয়ান্টামরোস্ট বাগ অ্যাসিস্ট্যান্ট

৩. শুরু করার আগে

গুগল ক্লাউড প্রজেক্ট সেটআপ

  1. যদি আপনার আগে থেকে কোনো গুগল অ্যাকাউন্ট না থাকে, তাহলে আপনাকে অবশ্যই একটি গুগল অ্যাকাউন্ট তৈরি করতে হবে।
    • কর্মক্ষেত্র বা শিক্ষা প্রতিষ্ঠানের অ্যাকাউন্টের পরিবর্তে ব্যক্তিগত অ্যাকাউন্ট ব্যবহার করুন। কর্মক্ষেত্র এবং শিক্ষা প্রতিষ্ঠানে এমন কিছু সীমাবদ্ধতা থাকতে পারে, যার ফলে আপনি এই ল্যাবের জন্য প্রয়োজনীয় এপিআই (API) সক্রিয় করতে পারবেন না।
  2. গুগল ক্লাউড কনসোলে সাইন-ইন করুন।
  3. ক্লাউড কনসোলে বিলিং চালু করুন ।
    • এই ল্যাবটি সম্পন্ন করতে ক্লাউড রিসোর্সে ১ মার্কিন ডলারেরও কম খরচ হওয়া উচিত।
    • পরবর্তী চার্জ এড়াতে, এই ল্যাবের শেষে দেওয়া ধাপগুলো অনুসরণ করে আপনি রিসোর্সগুলো মুছে ফেলতে পারেন।
    • নতুন ব্যবহারকারীরা ৩০০ মার্কিন ডলারের ফ্রি ট্রায়ালের জন্য যোগ্য।
  4. একটি নতুন প্রজেক্ট তৈরি করুন অথবা বিদ্যমান কোনো প্রজেক্ট পুনরায় ব্যবহার করুন।

ওপেন ক্লাউড শেল এডিটর

  1. ক্লাউড শেল এডিটরে যান
  2. যদি স্ক্রিনের নীচে টার্মিনালটি দেখা না যায়, তাহলে এটি খুলুন:
    • হ্যামবার্গার মেনুতে ক্লিক করুন হ্যামবার্গার মেনু আইকন
    • টার্মিনালে ক্লিক করুন
    • নতুন টার্মিনালে ক্লিক করুন ক্লাউড শেল এডিটরে নতুন টার্মিনাল খুলুন
  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}'
      ক্লাউড শেল এডিটর টার্মিনালে প্রজেক্ট আইডি সেট করুন
  4. অনুমোদন করতে বলা হলে, চালিয়ে যাওয়ার জন্য 'Authorize'-এ ক্লিক করুন। ক্লাউড শেল অনুমোদন করতে ক্লিক করুন
  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)

এপিআই সক্ষম করুন

টার্মিনালে, প্রয়োজনীয় গুগল ক্লাউড এপিআইগুলো সক্রিয় করতে নিম্নলিখিত কমান্ডটি চালান:

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

একটি ক্লাউড এসকিউএল ফর পোস্টগ্রেসকিউএল ইনস্ট্যান্স তৈরি করুন

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

ইনস্ট্যান্সটি তৈরি হওয়ার জন্য অপেক্ষা করুন (এতে কয়েক মিনিট সময় লাগতে পারে)।

একবার তৈরি হয়ে গেলে, আপনি এখানে ক্লাউড কনসোলে আপনার ইনস্ট্যান্সটি দেখতে পারবেন।

একটি ক্লাউড SQL ডেটাবেস তৈরি করুন

একটি SQL ডেটাবেস ( tickets-db ) তৈরি করুন এবং ক্লাউড 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 টেবিলটি সাজান।

ক্লাউড কনসোল (ক্লাউড এসকিউএল) থেকে, software-assistant ইনস্ট্যান্সটির জন্য ক্লাউড এসকিউএল স্টুডিও খুলুন।

postgres ইউজার এবং admin পাসওয়ার্ড ব্যবহার করে tickets-db ডেটাবেসে লগ ইন করুন।

ক্লাউড এসকিউএল স্টুডিও

একটি নতুন 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;

আপনি নিম্নলিখিতের অনুরূপ ১০টি সারি ফেরত পেতে দেখবেন:

ক্লাউড SQL DB যাচাই করুন

এখন আপনি মজার অংশে, অর্থাৎ কোডে যাওয়ার জন্য প্রস্তুত!

৪. পাইথন প্রজেক্ট সেটআপ

আমাদের এজেন্ট তৈরি শুরু করার আগে, আমাদের একটি যথাযথ পাইথন প্রজেক্ট সেটআপ নিশ্চিত করতে হবে। আমরা এই পুরো কাজটি ক্লাউড শেলে করব!

প্রথমে, একটি quantum-roast ফোল্ডার তৈরি করুন এবং তার ভেতরে cd : 

mkdir quantum-roast && cd quantum-roast

এখন যেহেতু আমাদের প্রোজেক্টের জন্য একটি ফোল্ডার তৈরি হয়ে গেছে, তাই প্রোজেক্টটি চালু করার এবং প্রয়োজনীয় ফাইলগুলো তৈরি করার সময় এসেছে।

আমরা আমাদের প্রজেক্ট এবং ডিপেন্ডেন্সিগুলো ম্যানেজ করার জন্য uv (পাইথনের অত্যন্ত দ্রুতগতির প্যাকেজ ও প্রজেক্ট ম্যানেজার) ব্যবহার করব, যা ক্লাউড শেলে আগে থেকেই ইনস্টল করা থাকে। ইউভি আমাদের কিছু ফাইল সেটআপ করার পাশাপাশি ভার্চুয়াল এনভায়রনমেন্ট, ডিপেন্ডেন্সি ইত্যাদি ম্যানেজ করতে সাহায্য করবে, যাতে আমাদের এসব নিয়ে মাথা ঘামাতে না হয়!

uv init দিয়ে একটি নতুন প্রজেক্ট শুরু করুন: 

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

কমান্ডটি চালানোর পর, আমাদের প্রোজেক্টের জন্য একটি pyproject.toml ফাইল তৈরি হবে। এটি যাচাই করার জন্য, ক্লাউড শেল টার্মিনালে ` 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 = []

এখন uv add . ব্যবহার করে আমাদের প্রজেক্টে google-adk (ADK)-কে একটি ডিপেন্ডেন্সি হিসেবে যুক্ত করার পালা। 

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

ADK যাতে সঠিকভাবে জেমিনি মডেল কল করতে পারে, তার জন্য প্রয়োজনীয় এনভায়রনমেন্ট ভেরিয়েবল দিয়ে .env ফাইলটি পূরণ করার সময় এসেছে। আমরা ভার্টেক্স এপিআই (Vertex API)-এর মাধ্যমে জেমিনি অ্যাক্সেস করব। 

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 এজেন্ট তৈরি করার কাজ শুরু করতে প্রস্তুত।

৫. বেস এডিকে এজেন্ট

চলুন একটি বেস ADK এজেন্ট সেটআপ করে নিই, যাতে আমরা এই ওয়ার্কশপ চলাকালীন এক এক করে টুল যোগ করে একটি শক্তিশালী বাগ অ্যাসিস্ট্যান্ট তৈরি করতে পারব!

ক্লাউড শেল এডিটর-এ 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-এর ডেভ UI ( 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)

UI দেখতে ক্লাউড শেলের ওয়েব প্রিভিউ খুলুন।

ক্লাউড শেল ওয়েব প্রিভিউ

আপনার ADK ওয়েব UI দেখা উচিত।

ADK ওয়েব UI

এগিয়ে যান এবং ADK এজেন্টের সাথে চ্যাট করার চেষ্টা করুন।

এজেন্টকে জিজ্ঞাসা করুন What day is it today?

ADK ওয়েব উদাহরণ

প্রতিক্রিয়াটি দেখলেই আপনি বুঝতে পারবেন যে এজেন্টটি এই সাধারণ প্রশ্নটির উত্তর দিতে পারছে না! মনে রাখবেন যে এলএলএম (LLM) হলো বিচ্ছিন্ন সিস্টেম, যা অতীতের তথ্যের ওপর ভিত্তি করে প্রশিক্ষিত। সাম্প্রতিক ঘটনা বা এমনকি বর্তমান তারিখ সম্পর্কেও তাদের কাছে রিয়েল-টাইম তথ্য থাকে না... যদি না আপনি তাদের প্রয়োজনীয় টুলস দেন!

এখন ADK-এর প্রথম টুল টাইপ, একটি ফাংশন টুল , প্রয়োগ করার সময় এসেছে।

৬. ফাংশন টুল

প্রথম এবং সবচেয়ে সহজ ADK টুল টাইপটি হলো ফাংশন টুল । এর নাম শুনেই বোঝা যায়, এটি একটি পাইথন ফাংশন যাকে এজেন্ট কল করে!

ফাংশন টুল

ফাংশন টুলগুলো বেশ শক্তিশালী, কারণ এগুলো আপনাকে এজেন্টের জন্য কাস্টম কোড লেখার সুযোগ দেয়, যা এজেন্ট একটি টুল হিসেবে ব্যবহার করতে পারে; যেমন—গণনা করা, এপিআই (API) কল করা বা ডাটাবেস কোয়েরি করা। এই ফাংশনগুলো সহজ বা জটিল হতে পারে, বিষয়টি সম্পূর্ণ আপনার উপর নির্ভর করে।

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")}

ফাংশনটি এখন সংজ্ঞায়িত করা হয়েছে! এবার এটিকে এজেন্টের কাছে একটি টুল হিসেবে পাঠানোর পালা।

ক্লাউড শেল এডিটর-এ 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 ওয়েব UI চালিত ওয়েব প্রিভিউ ট্যাবে ফিরে যান এবং আবার জিজ্ঞাসা করেন What day is it today? ’...

ADK ওয়েব ফাংশন টুল

এজেন্ট get_current_date ফাংশন টুলটি কল করে সফলভাবে তারিখ জানতে পারবে! 🎉

এবার পরবর্তী ADK টুলের ধরনটি অন্বেষণ করার পালা।

৭. অন্তর্নির্মিত সরঞ্জাম

আরেক ধরনের ADK টুল হলো বিল্ট-ইন টুল । এই টুলগুলো গুগলের ফ্ল্যাগশিপ মডেলের ফিচারগুলোর সাথে কাজ করে, যেমন মডেলের ভেতরেই কোড এক্সিকিউশন । আমরা আমাদের বাগ অ্যাসিস্ট্যান্ট এজেন্টের সাথে গুগল সার্চ বিল্ট-ইন টুলটি সংযুক্ত করতে পারি, যাতে এজেন্টটি ওয়েব সার্চ করার অ্যাক্সেস পেয়ে প্রাসঙ্গিক প্রেক্ষাপটে নিজেকে প্রতিষ্ঠিত করতে পারে। এর ফলে এজেন্টটি কোনো বাগ বা সুপরিচিত দুর্বলতা সম্পর্কে আরও সাম্প্রতিক তথ্য সংগ্রহ করতে পারবে।

অন্তর্নির্মিত সরঞ্জাম

গুগল সার্চের বিল্ট-ইন টুলের জন্য সাপোর্ট যোগ করতে 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)

এখানে, আমরা আসলে সেই গুগল সার্চ টুলটিকে তার নিজস্ব সিস্টেম নির্দেশাবলী সহ একটি এজেন্টের মধ্যে আবদ্ধ করছি, কার্যকরভাবে একটি এজেন্টকে টুল হিসেবে ব্যবহার করছি।

এখন আমরা agent.py তে search_tool ইম্পোর্ট করে রুট এজেন্টের কাছে পাঠাতে পারি: 

cloudshell edit software_bug_assistant/agent.py

search_tool অন্তর্ভুক্ত করতে আপনি agent.py নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করতে পারেন: 

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 ওয়েব UI চালু আছে।

কোয়ান্টামরোস্টে আমরা নিশ্চিত করতে চাই যে আমাদের ওয়েবসাইট এবং সফটওয়্যার কমন ভালনারেবিলিটিজ অ্যান্ড এক্সপোজারস (CVEs) থেকে সুরক্ষিত আছে, যা হলো সর্বজনীন সাইবার নিরাপত্তা দুর্বলতা। আমরা আমাদের এজেন্টের নতুন গুগল সার্চ টুল ব্যবহার করে ওয়েবে সবচেয়ে সম্প্রতি আবিষ্কৃত CVE-গুলো অনুসন্ধান করতে পারি।

নিম্নলিখিত কোয়েরিটি চালান: Do a web search for 5 of the most recent CVEs?

আমাদের এজেন্টের উচিত ওয়েব অনুসন্ধান করার জন্য search_agent কে কল করা।

ADK ওয়েব বিল্ট-ইন টুলের উদাহরণ

আমাদের এজেন্ট এখন ADK-এর বিল্ট-ইন গুগল সার্চ টুলের মাধ্যমে ওয়েব অনুসন্ধান করার ক্ষমতা সফলভাবে আনলক করেছে! 🎉

এবার পরবর্তী ADK টুলের ধরনে আসা যাক।

৮. তৃতীয় পক্ষের টুল

ADK-কে অত্যন্ত সম্প্রসারণযোগ্য করে ডিজাইন করা হয়েছে, যা আপনাকে CrewAI এবং LangChain-এর মতো অন্যান্য থার্ড-পার্টি এআই এজেন্ট ফ্রেমওয়ার্কের টুলগুলিকে নির্বিঘ্নে একীভূত করার সুযোগ দেয়। এই আন্তঃকার্যক্ষমতা অত্যন্ত গুরুত্বপূর্ণ, কারণ এটি দ্রুততর ডেভেলপমেন্ট সময় এবং বিদ্যমান টুলগুলির পুনঃব্যবহারের সুযোগ করে দেয়।

তৃতীয় পক্ষের টুল

আমাদের বাগ এজেন্টকে StackOverflow-এর শক্তিশালী প্রশ্নোত্তর ডেটার সাথে সংযুক্ত করতে, আমরা 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)

এখন আমরা agent.py তে langchain_tool ইম্পোর্ট করে রুট এজেন্টে পাস করতে পারি: 

cloudshell edit software_bug_assistant/agent.py

langchain_tool অন্তর্ভুক্ত করতে আপনি agent.py নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করতে পারেন: 

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 ওয়েব 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 ওয়েব তৃতীয়-পক্ষ টুলের উদাহরণ

আমাদের এজেন্ট এখন সফলভাবে ADK-এর একটি LangChain টুল ব্যবহার করে StackOverflow-তে কোয়েরি করতে পেরেছে। 🥳

এবার পরবর্তী ADK টুলের ধরন... MCP টুলস!

৯. এমসিপি টুল (ডাটাবেস)

MCP-এর পূর্ণরূপ হলো মডেল কনটেক্সট প্রোটোকল । এটি একটি উন্মুক্ত প্রোটোকল যা অ্যানথ্রোপিক ২০২৪ সালে চালু করে । MCP আপনার এআই এজেন্ট এবং টুল 'ব্যাকএন্ড' (এপিআই, ডেটাবেস)-এর মধ্যে একটি অ্যাবস্ট্রাকশন লেয়ার প্রদান করে।

এমসিপি কীভাবে কাজ করে

MCP-এর কিছু স্বতন্ত্র বৈশিষ্ট্য রয়েছে। সাধারণ HTTP-এর মতো নয়, MCP ক্লায়েন্ট এবং সার্ভারের মধ্যে একটি স্টেটফুল, দ্বিমুখী সংযোগ প্রদান করে। টুল এবং টুল-নির্দিষ্ট ত্রুটির বার্তা সংজ্ঞায়িত করার নিজস্ব পদ্ধতি রয়েছে। এরপর একজন টুল প্রোভাইডার তাদের API-এর উপর ভিত্তি করে MCP সার্ভার তৈরি করতে পারে, যা ডেভেলপার এবং ব্যবহারকারীদের জন্য এক বা একাধিক পূর্ব-নির্মিত টুল উন্মুক্ত করে। তারপর, এজেন্ট ফ্রেমওয়ার্কগুলো একটি এজেন্ট অ্যাপ্লিকেশনের ভিতরে MCP ক্লায়েন্ট চালু করতে পারে, যাতে সেই টুলগুলো খুঁজে বের করে কল করা যায়।

QuantumRoast-এ আমাদের অভ্যন্তরীণ সফটওয়্যার বাগের জন্য একটি Cloud SQL for PostgreSQL ডেটাবেস আছে। আমরা ADK টুলস তৈরি করতে চাই যাতে আমাদের এজেন্ট ডেটাবেসে নির্দিষ্ট কিছু কোয়েরি চালাতে পারে।

এমসিপি টুল ডেটাবেস

এটি করার সবচেয়ে সহজ উপায় হলো MCP Toolbox for Databases ব্যবহার করা, যা ডেটাবেসের জন্য একটি ওপেন-সোর্স MCP সার্ভার! টুলবক্সটি ১৫টিরও বেশি ডেটাবেস সমর্থন করে, যার মধ্যে একটি হলো ক্লাউড এসকিউএল (Cloud SQL)!

টুলবক্সে রয়েছে:

  • সরলীকৃত উন্নয়ন : ১০ লাইনেরও কম কোডে আপনার এজেন্টের সাথে টুলস ইন্টিগ্রেট করুন, একাধিক এজেন্ট বা ফ্রেমওয়ার্কের মধ্যে টুলস পুনঃব্যবহার করুন এবং টুলসের নতুন সংস্করণ আরও সহজে ডেপ্লয় করুন।
  • উন্নততর পারফরম্যান্স : কানেকশন পুলিং, অথেন্টিকেশন এবং আরও অনেক সেরা অনুশীলন।
  • উন্নত নিরাপত্তা : আপনার ডেটাতে আরও সুরক্ষিত অ্যাক্সেসের জন্য সমন্বিত প্রমাণীকরণ।
  • এন্ড-টু-এন্ড পর্যবেক্ষণযোগ্যতা : ওপেনটেলিমেট্রির অন্তর্নির্মিত সমর্থন সহ রেডিমেড মেট্রিক্স এবং ট্রেসিং।

ADK-তে ডাটাবেস টুলের জন্য MCP টুলবক্সের সমর্থন রয়েছে, যা ইন্টিগ্রেশনকে দ্রুত করে তোলে।

ডেটাবেসের জন্য এমসিপি টুলবক্স

ক্লাউড রানে MCP টুলবক্স ফর ডেটাবেস সার্ভার স্থাপন করুন

প্রথমে, আমরা ক্লাউড রান-এ এমসিপি টুলবক্স ফর ডেটাবেস সার্ভারটি ডেপ্লয় করব এবং এটিকে আমাদের ক্লাউড এসকিউএল ইনস্ট্যান্সের সাথে সংযুক্ত করব।

টুলবক্স কনফিগারেশনের জন্য একটি 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 টিকেট ডেটাবেস সম্পর্কিত ৯টি টুল সংজ্ঞায়িত করে।

এখন টুলবক্স ক্লাউড রান সার্ভিসের জন্য একটি সার্ভিস অ্যাকাউন্ট কনফিগার করতে হবে, এটিকে ক্লাউড এসকিউএল ও সিক্রেট ম্যানেজার অ্যাক্সেস করার অনুমতি দিতে হবে এবং আমাদের tools.yaml ফাইলের জন্য একটি সিক্রেট ম্যানেজার সিক্রেট তৈরি করতে হবে।

আমরা আমাদের tools.yaml ফাইলটি সিক্রেট ম্যানেজারে সংরক্ষণ করব, কারণ এতে সংবেদনশীল ক্লাউড এসকিউএল ক্রেডেনশিয়াল রয়েছে। 

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

এখন ক্লাউড রানে MCP টুলবক্স ফর ডেটাবেস ডেপ্লয় করার সময়। আমরা MCP টুলবক্স কন্টেইনার ইমেজের সর্বশেষ রিলিজ সংস্করণটি ব্যবহার করব। 

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" \
    --labels=dev-tutorial=codelab-toolbox \
    --no-invoker-iam-check

ডেপ্লয়মেন্ট শেষ হওয়া পর্যন্ত অপেক্ষা করুন...

ক্লাউড রান লগ কোয়েরি করে টুলবক্স চালু আছে কিনা তা যাচাই করুন: 

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!"

টুলবক্স সার্ভিসের ক্লাউড রান ইউআরএলটি একটি এনভায়রনমেন্ট ভেরিয়েবল হিসেবে সংরক্ষণ করুন, যাতে 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

কোয়ান্টামরোস্ট এজেন্ট আপডেট করুন

দ্বিতীয়ত, আমাদের প্রজেক্টে MCP Toolbox for Databases SDK ( toolbox-core )-এর ডিপেন্ডেন্সিটি অবশ্যই যোগ করতে হবে: 

uv add toolbox-core==0.5.0

MCP টুলবক্স টুলগুলোর জন্য সমর্থন যোগ করতে 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")

এখন আমরা agent.py তে toolbox_tools ইম্পোর্ট করে রুট এজেন্টের কাছে পাঠাতে পারি: 

cloudshell edit software_bug_assistant/agent.py

toolbox_tools অন্তর্ভুক্ত করতে আপনি agent.py নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করতে পারেন: 

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 ওয়েব UI সহ আপনার খোলা ট্যাবটিতে ফিরে যান।

এখন আপনি আমাদের ক্লাউড এসকিউএল অভ্যন্তরীণ টিকিট ডেটাবেসে সংরক্ষিত টিকিটগুলো সম্পর্কে প্রশ্ন করতে পারবেন!

নিচের প্রশ্নগুলোর মতো একটি প্রশ্ন করুন:

  • 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 (বাগ তৈরির বিষয়ে এজেন্টকে আপনাকে নির্দেশনা দিতে দিন)

এমসিপি ডেটাবেস টুল উদাহরণ

আমাদের ADK এজেন্ট এখন MCP Toolbox for Databases টুল ব্যবহার করে সফলভাবে আমাদের ডাটাবেস কোয়েরি করেছে! 🚀

১০. ঐচ্ছিক: এমসিপি টুল (এপিআই)

MCP টুলবক্স ফর ডেটাবেস-এর মতো যেসব MCP টুলের নিজস্ব SDK নেই, সেগুলোর সাথে আমাদের ADK এজেন্টকে সংযুক্ত করার ব্যাপারে কী করা যায়?

ADK তার MCPToolset ক্লাসের মাধ্যমে জেনেরিক MCP টুল সমর্থন করে। একটি MCP সার্ভার থেকে টুল একীভূত করার জন্য MCPToolset ক্লাসটি হলো ADK-এর প্রধান পদ্ধতি।

এমসিপি টুল (এপিআই)

MCPToolset ব্যবহার করে লোকাল বা রিমোট MCP সার্ভারের সাথে সংযোগ স্থাপন করা যায়। QuantumRoast-এ আমরা আমাদের এজেন্টকে GitHub-এর রিমোট MCP সার্ভারের সাথে সংযুক্ত করতে চাই—যাতে সহজেই GitHub-এর API-গুলো কল করা যায়। এর ফলে আমাদের এজেন্ট পাবলিক সফটওয়্যার রিপোজিটরি বা এমনকি আমাদের নিজেদের কোডবেস থেকেও ইস্যু সংক্রান্ত তথ্য সংগ্রহ করতে পারবে। GitHub MCP সার্ভারটি ইস্যু ও পুল রিকোয়েস্ট থেকে শুরু করে নোটিফিকেশন এবং কোড সিকিউরিটি পর্যন্ত GitHub-এর বিভিন্ন কার্যকারিতা উন্মুক্ত করে দেয়।

এমসিপি টুল গিটহাব

গিটহাব ব্যক্তিগত অ্যাক্সেস টোকেন (PAT)

গিটহাব এমসিপি সার্ভারে প্রমাণীকরণের জন্য আপনার একটি গিটহাব পার্সোনাল অ্যাক্সেস টোকেন প্রয়োজন।

একটি অর্জন করতে, এই ধাপগুলো অনুসরণ করুন:

  1. আপনার গিটহাব ডেভেলপার সেটিংসে যান।
  2. 'ব্যক্তিগত অ্যাক্সেস টোকেন' -> 'টোকেন (ক্লাসিক)'-এ ক্লিক করুন।
  3. "Generate new token" -> "Generate new token (classic)"-এ ক্লিক করুন।
  4. আপনার টোকেনটির একটি বর্ণনামূলক নাম দিন।
  5. আপনার টোকেনের জন্য একটি মেয়াদ শেষ হওয়ার তারিখ নির্ধারণ করুন।
  6. গুরুত্বপূর্ণ : নিরাপত্তার জন্য, আপনার টোকেনকে শুধুমাত্র প্রয়োজনীয় সীমিত স্কোপগুলোই প্রদান করুন। রিপোজিটরিগুলোতে শুধুমাত্র পঠনযোগ্য (read-only) অ্যাক্সেসের জন্য, repo:status , public_repo , এবং read:user স্কোপগুলোই প্রায়শই যথেষ্ট। একান্ত প্রয়োজন না হলে সম্পূর্ণ রিপোজিটরি বা অ্যাডমিন পারমিশন প্রদান করা থেকে বিরত থাকুন।
  7. Generate token -এ ক্লিক করুন।
  8. তৈরি হওয়া টোকেনটি কপি করুন।

এজেন্ট যাতে আপনার গিটহাব PAT ব্যবহার করতে পারে, তা সেট করার জন্য ক্লাউড শেল টার্মিনালে নিম্নলিখিত কমান্ডটি চালান। YOUR_GITHUB_PAT জায়গায় আপনার তৈরি করা PAT-টি বসান। 

export GITHUB_PAT=YOUR_GITHUB_PAT

কোয়ান্টামরোস্ট এজেন্ট আপডেট করুন

আমাদের বাগ অ্যাসিস্ট্যান্টের জন্য, আমরা শুধুমাত্র কিছু রিড-অনলি গিটহাব টুল উন্মুক্ত রাখব, যাতে কোয়ান্টামরোস্টের কর্মীরা ওপেন-সোর্স ডিপেন্ডেন্সি সম্পর্কিত সমস্যাগুলো খুঁজে বের করতে পারেন এবং দেখতে পারেন যে এটি তাদের অভ্যন্তরীণ টিকেট সিস্টেমে দেখা বাগগুলোর মূল কারণ খুঁজে পেতে সাহায্য করে কিনা। এটি সেট আপ করার জন্য আমরা একটি tool_filter সহ ADK-এর MCPToolset ব্যবহার করব। tool-filter শুধুমাত্র আমাদের প্রয়োজনীয় গিটহাব টুলগুলোই উন্মুক্ত করে, যা কেবল ব্যবহারকারীদের অ্যাক্সেস করতে না চাওয়া টুলগুলোকেই (যেমন: সংবেদনশীল রিপোজিটরি অ্যাকশন) আড়াল করে না, বরং কাজের জন্য সঠিক টুল বেছে নেওয়ার সময় এজেন্টের মডেলকে অতিরিক্ত চাপ থেকেও রক্ষা করে।

গিটহাব টুলস-এর জন্য সাপোর্ট যোগ করতে 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) প্রদান করতে হবে, ঠিক যেমনভাবে আপনি আপনার কোডে একটি স্ট্যান্ডার্ড API ক্লায়েন্ট সেট আপ করার সময় একটি অথ টোকেন প্রদান করেন। এই PAT-টি শুধুমাত্র পাবলিক রিপোজিটরি ডেটা অ্যাক্সেস করার জন্য সীমাবদ্ধ, এবং সংবেদনশীল ব্যবহারকারী বা রিপোজিটরি অ্যাকশনের ক্ষেত্রে এর কোনো সীমাবদ্ধতা নেই।

এখন আমরা agent.py তে mcp_tools ইম্পোর্ট করে রুট এজেন্টে পাস করতে পারি: 

cloudshell edit software_bug_assistant/agent.py

mcp_tools অন্তর্ভুক্ত করতে আপনি agent.py নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করতে পারেন: 

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 ওয়েব UI সহ আপনার খোলা ট্যাবটিতে ফিরে যান।

এখন, আমাদের কাছে কিছু গিটহাব এমসিপি টুল আছে যা আমাদের এজেন্ট কল করতে পারে। কোয়ান্টামরোস্টের পরিষেবাগুলো এক্সজেড ইউটিলস (XZ utils) নামক একটি ডেটা কম্প্রেশন টুলের উপর নির্ভর করে। আমাদের অভ্যন্তরীণ বাগ টিকেট সিস্টেম গত বছরের একটি সিভিই (নিরাপত্তা দুর্বলতা) ট্র্যাক করছে, যা আমরা স্ট্যাকওভারফ্লো এবং গুগল সার্চ টুল ব্যবহার করে এক্সজেড ইউটিলস গিটহাব রিপোজিটরি পর্যন্ত খুঁজে বের করতে পারি। এরপর আমরা গিটহাবের এমসিপি টুলগুলোর মধ্যে একটি, search_issues , ব্যবহার করে নির্ধারণ করতে পারি যে সেই সিভিই-টি কখন এবং কীভাবে প্যাচ করা হয়েছিল।

এজেন্টকে নিম্নলিখিত বিষয়গুলো জিজ্ঞাসা করুন:

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

আপনি দেখবেন যে এজেন্টটি গিটহাব টুলগুলোকে কল করছে।

এমসিপি টুলস গিটহাব উদাহরণ

QuantumRoast ADK এজেন্ট এখন GitHub MCP সার্ভার টুলগুলোর সাথে যোগাযোগ করতে সক্ষম! 🤩

১১. অভিনন্দন

অভিনন্দন! আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে সফলভাবে কোয়ান্টামরোস্ট বাগ অ্যাসিস্ট্যান্ট এজেন্ট তৈরি করেছেন এবং এর কার্যক্ষমতা বাড়ানোর জন্য বিভিন্ন ধরণের টুল সংযুক্ত করেছেন। আপনি একটি বেসিক এজেন্ট দিয়ে শুরু করে পর্যায়ক্রমে ফাংশন টুলস, বিল্ট-ইন টুলস, থার্ড-পার্টি টুলস এবং এমসিপি টুলস যুক্ত করেছেন।

আমরা যা আলোচনা করেছি

  • ADK ডেভেলপমেন্টের জন্য কীভাবে একটি পাইথন প্রজেক্ট সেট আপ করবেন।
  • কীভাবে একটি বেসিক ADK এজেন্ট তৈরি করবেন।
  • ফাংশন টুলস কীভাবে প্রয়োগ ও ব্যবহার করতে হয়।
  • গুগল সার্চের মতো বিল্ট-ইন টুলগুলো কীভাবে ইন্টিগ্রেট করবেন
  • ADK-এর মধ্যে LangChain-এর মতো ফ্রেমওয়ার্কের থার্ড-পার্টি টুলগুলো কীভাবে কাজে লাগানো যায়
  • ডাটাবেস (ক্লাউড এসকিউএল) এবং এপিআই-এর সাথে ইন্টারঅ্যাক্ট করতে কীভাবে এমসিপি টুলস ব্যবহার করবেন।

কোয়ান্টামরোস্ট ফাইনাল

পরিষ্কার-পরিচ্ছন্নতা

অতিরিক্ত চার্জ এড়াতে আপনি আপনার ক্লাউড প্রজেক্টটি মুছে ফেলতে পারেন।

পরিষেবাটি ব্যবহার না করা হলে ক্লাউড রান কোনো চার্জ না করলেও, আর্টিফ্যাক্ট রেজিস্ট্রি-তে কন্টেইনার ইমেজ সংরক্ষণের জন্য আপনাকে চার্জ করা হতে পারে। আপনার ক্লাউড প্রজেক্টটি ডিলিট করে দিলে সেই প্রজেক্টের মধ্যে ব্যবহৃত সমস্ত রিসোর্সের বিলিং বন্ধ হয়ে যায়।

আপনি চাইলে প্রজেক্টটি মুছে ফেলতে পারেন: 

gcloud projects delete $GOOGLE_CLOUD_PROJECT

আপনি আপনার ক্লাউডশেল ডিস্ক থেকে অপ্রয়োজনীয় রিসোর্সগুলো মুছে ফেলতে চাইতে পারেন। আপনি তা করতে পারেন:

  1. কোডল্যাব প্রজেক্ট ডিরেক্টরিটি মুছে ফেলুন: 
    rm -rf ~/quantum-roast
  2. সতর্কীকরণ! এই পরবর্তী কাজটি পূর্বাবস্থায় ফেরানো যাবে না! জায়গা খালি করার জন্য আপনি যদি আপনার ক্লাউড শেলের সবকিছু মুছে ফেলতে চান, তাহলে আপনি আপনার সম্পূর্ণ হোম ডিরেক্টরিটি ডিলিট করে দিতে পারেন। খেয়াল রাখবেন, আপনি যা কিছু রাখতে চান তা যেন অন্য কোথাও সেভ করা থাকে। 
    sudo rm -rf $HOME