थिंकिंग मोड के साथ ADK, MCP, और Gemini 2.5 Flash का इस्तेमाल करके, QA टेस्ट प्लानर एजेंट बनाना

1. परिचय

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

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

कोडलैब में, आपको सिलसिलेवार तरीके से यह तरीका अपनाना होगा:

1. अपना Google Cloud प्रोजेक्ट तैयार करें और उस पर सभी ज़रूरी एपीआई चालू करें
2. कोडिंग एनवायरमेंट के लिए Workspace सेट अप करना
3. Confluence के लिए लोकल mcp-server को तैयार करना
4. एमसीपी सर्वर से कनेक्ट करने के लिए, ADK एजेंट के सोर्स कोड, प्रॉम्प्ट, और टूल को व्यवस्थित करना
5. आर्टफ़ैक्ट सेवा और टूल कॉन्टेक्स्ट के इस्तेमाल को समझना
6. ADK के लोकल वेब डेवलपमेंट यूज़र इंटरफ़ेस (यूआई) का इस्तेमाल करके एजेंट की जांच करना
7. एनवायरमेंट वैरिएबल मैनेज करना और Cloud Run पर ऐप्लिकेशन को डिप्लॉय करने के लिए ज़रूरी फ़ाइलों को सेट अप करना
8. ऐप्लिकेशन को Cloud Run पर डिप्लॉय करना

आर्किटेक्चर की खास जानकारी

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

• Python के साथ आसानी से काम करना
• एचटीटीपी सेवा का इस्तेमाल करके, बुनियादी फ़ुल-स्टैक आर्किटेक्चर के बारे में जानकारी

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

• ADK एजेंट की कई सुविधाओं का इस्तेमाल करते हुए, उसे बेहतर बनाना
• कस्टम टूल और एमसीपी के साथ टूल का इस्तेमाल
• Artifact Service मैनेजमेंट का इस्तेमाल करके, एजेंट के हिसाब से फ़ाइल आउटपुट सेट अप करना
• Gemini 2.5 Flash की सोचने-समझने की क्षमताओं का इस्तेमाल करके, टास्क को बेहतर तरीके से पूरा करने के लिए BuiltInPlanner का इस्तेमाल करना
• ADK वेब इंटरफ़ेस की मदद से इंटरैक्ट करना और डीबग करना
• Dockerfile का इस्तेमाल करके, Cloud Run पर ऐप्लिकेशन को डिप्लॉय करना और एनवायरमेंट वैरिएबल देना

आपको इन चीज़ों की ज़रूरत होगी

• Chrome वेब ब्राउज़र
• Gmail खाता
• बिलिंग की सुविधा वाला Cloud प्रोजेक्ट
• (ज़रूरी नहीं) प्रॉडक्ट की ज़रूरी शर्तों की जानकारी देने वाले दस्तावेज़ों के पेज वाला Confluence स्पेस

यह कोडलैब, सभी लेवल के डेवलपर (शुरुआती डेवलपर भी) के लिए डिज़ाइन किया गया है. इसमें सैंपल ऐप्लिकेशन के लिए Python का इस्तेमाल किया गया है. हालांकि, यहां दिए गए कॉन्सेप्ट को समझने के लिए, Python के बारे में जानकारी होना ज़रूरी नहीं है. अगर आपके पास Confluence स्पेस नहीं है, तो चिंता न करें. हम आपको इस कोडलैब को आज़माने के लिए क्रेडेंशियल देंगे

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

Cloud Console में चालू प्रोजेक्ट चुनना

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

1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग की सुविधा चालू हो. किसी प्रोजेक्ट के लिए बिलिंग की सुविधा चालू है या नहीं, यह देखने का तरीका जानें.

Cloud Shell टर्मिनल में Cloud प्रोजेक्ट सेटअप करना

1. इसके लिए, आपको Cloud Shell का इस्तेमाल करना होगा. यह Google Cloud में चलने वाला कमांड-लाइन एनवायरमेंट है. Google Cloud कंसोल में सबसे ऊपर, 'Cloud Shell चालू करें' पर क्लिक करें.

2. Cloud Shell से कनेक्ट होने के बाद, यह जांच करें कि आपकी पुष्टि पहले ही हो चुकी है या नहीं. साथ ही, यह भी देखें कि प्रोजेक्ट आपके प्रोजेक्ट आईडी पर सेट है या नहीं. इसके लिए, यह कमांड इस्तेमाल करें:

gcloud auth list

3. Cloud Shell में यह कमांड चलाकर पुष्टि करें कि gcloud कमांड को आपके प्रोजेक्ट के बारे में पता है.

gcloud config list project

4. अगर आपका प्रोजेक्ट सेट नहीं है, तो इसे सेट करने के लिए इस निर्देश का इस्तेमाल करें:

gcloud config set project <YOUR_PROJECT_ID>

इसके अलावा, कंसोल में भी PROJECT_ID आईडी देखा जा सकता है

इस पर क्लिक करने पर, आपको दाईं ओर अपने सभी प्रोजेक्ट और प्रोजेक्ट आईडी दिखेंगे

5. नीचे दिए गए निर्देश का इस्तेमाल करके, ज़रूरी एपीआई चालू करें. इसमें कुछ मिनट लग सकते हैं. इसलिए, कृपया इंतज़ार करें.

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com

निर्देश पूरा होने पर, आपको यहां दिखाए गए मैसेज जैसा मैसेज दिखेगा:

Operation "operations/..." finished successfully.

gcloud कमांड के बजाय, कंसोल में जाकर हर प्रॉडक्ट को खोजें या इस लिंक का इस्तेमाल करें.

अगर कोई एपीआई छूट जाता है, तो उसे लागू करने के दौरान कभी भी चालू किया जा सकता है.

gcloud के निर्देशों और इस्तेमाल के बारे में जानने के लिए, दस्तावेज़ देखें.

Cloud Shell Editor पर जाएं और ऐप्लिकेशन की वर्किंग डायरेक्ट्री सेटअप करें

अब हम कोडिंग से जुड़े कुछ काम करने के लिए, अपना कोड एडिटर सेट अप कर सकते हैं. इसके लिए, हम Cloud Shell एडिटर का इस्तेमाल करेंगे

1. 'एडिटर खोलें' बटन पर क्लिक करें. इससे Cloud Shell एडिटर खुल जाएगा. यहां अपना कोड लिखा जा सकता है
2. पक्का करें कि Cloud Code प्रोजेक्ट, Cloud Shell एडिटर के सबसे नीचे बाईं ओर (स्टेटस बार) में सेट हो, जैसा कि नीचे दी गई इमेज में हाइलाइट किया गया है. साथ ही, यह उस चालू Google Cloud प्रोजेक्ट पर सेट हो जिसमें आपने बिलिंग की सुविधा चालू की है. अगर कहा जाए, तो अनुमति दें. अगर आपने पहले से ही पिछले निर्देश का पालन किया है, तो हो सकता है कि बटन, साइन इन बटन के बजाय सीधे आपके चालू किए गए प्रोजेक्ट पर ले जाए

धैर्य रखें ! Cloud Shell Editor को शुरू करने के बाद, Cloud Code - साइन इन करें बटन दिखने में कुछ समय लग सकता है

3. इसके बाद, GitHub से इस कोडलैब के लिए टेंप्लेट की वर्किंग डायरेक्ट्री को क्लोन करें. इसके लिए, यह कमांड चलाएं. इससे qa-test-planner-agent डायरेक्ट्री में वर्किंग डायरेक्ट्री बन जाएगी

git clone https://github.com/alphinside/qa-test-planner-agent.git qa-test-planner-agent

4. इसके बाद, Cloud Shell Editor के सबसे ऊपर मौजूद सेक्शन में जाएं और फ़ाइल->फ़ोल्डर खोलें पर क्लिक करें. इसके बाद, अपनी उपयोगकर्ता नाम डायरेक्ट्री ढूंढें और qa-test-planner-agent डायरेक्ट्री ढूंढें. इसके बाद, 'ठीक है' बटन पर क्लिक करें. इससे चुनी गई डायरेक्ट्री, मुख्य वर्किंग डायरेक्ट्री बन जाएगी. इस उदाहरण में, उपयोगकर्ता नाम alvinprayuda है. इसलिए, डायरेक्ट्री का पाथ यहां दिखाया गया है

अब, आपका Cloud Shell Editor ऐसा दिखेगा

एनवायरमेंट सेटअप करना

Python वर्चुअल एनवायरमेंट तैयार करना

अगला चरण, डेवलपमेंट एनवायरमेंट तैयार करना है. आपका मौजूदा चालू टर्मिनल, qa-test-planner-agent वर्किंग डायरेक्ट्री में होना चाहिए. इस कोडलैब में, हम Python 3.12 का इस्तेमाल करेंगे. साथ ही, Python वर्शन और वर्चुअल एनवायरमेंट बनाने और मैनेज करने की प्रोसेस को आसान बनाने के लिए, uv python प्रोजेक्ट मैनेजर का इस्तेमाल करेंगे

1. अगर आपने अब तक टर्मिनल नहीं खोला है, तो टर्मिनल -> नया टर्मिनल पर क्लिक करके इसे खोलें. इसके अलावा, Ctrl + Shift + C का इस्तेमाल करके भी टर्मिनल खोला जा सकता है. इससे ब्राउज़र के सबसे नीचे टर्मिनल विंडो खुल जाएगी

2. uv डाउनलोड करें और यहां दिए गए कमांड की मदद से, Python 3.12 इंस्टॉल करें

curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

3. अब uv का इस्तेमाल करके वर्चुअल एनवायरमेंट को शुरू करते हैं. इसके लिए , यह कमांड चलाएं

uv sync --frozen

इससे .venv डायरेक्ट्री बन जाएगी और डिपेंडेंसी इंस्टॉल हो जाएंगी. pyproject.toml में एक नज़र डालने से, आपको इस तरह दिखाई गई डिपेंडेंसी के बारे में जानकारी मिलेगी

dependencies = [
    "google-adk>=1.5.0",
    "mcp-atlassian>=0.11.9",
    "pandas>=2.3.0",
    "python-dotenv>=1.1.1",
]

ध्यान दें: Python डिपेंडेंसी को pyproject.toml में बताया जाता है और uv.lock फ़ाइल में वर्शन लॉक किया जाता है

4. वर्चुअल एनवायरमेंट की जांच करने के लिए, main.py नाम की नई फ़ाइल बनाएं और नीचे दिया गया कोड कॉपी करें

def main():
   print("Hello from qa-test-planner-agent")

if __name__ == "__main__":
   main()

5. इसके बाद, यह कमांड चलाएं

uv run main.py

आपको नीचे दिखाया गया आउटपुट मिलेगा

Using CPython 3.12
Creating virtual environment at: .venv
Hello from qa-test-planner-agent!

इससे पता चलता है कि Python प्रोजेक्ट सही तरीके से सेट अप किया जा रहा है.

ध्यान दें: हमें मैन्युअल रूप से वर्चुअल एनवायरमेंट बनाने या उसे चालू करने की ज़रूरत नहीं थी, क्योंकि uv पहले से ही इन सभी चीज़ों को मैनेज करता है. इसके बाद, स्टैंडर्ड Python कमांड (उदाहरण के लिए, python main.py ) को uv run (उदाहरण के लिए, uv run main.py ) से बदल दिया जाएगा.

अब हम अगले चरण पर जा सकते हैं. पहले एजेंट और फिर सेवाएं बनाना

3. Google ADK और Gemini 2.5 का इस्तेमाल करके एजेंट बनाना

ADK डायरेक्ट्री स्ट्रक्चर के बारे में जानकारी

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

• एजेंट डायरेक्ट्री का स्ट्रक्चर सेटअप करना
• सीएलआई इनपुट आउटपुट की मदद से, तुरंत इंटरैक्ट करने की कोशिश करें
• लोकल डेवलपमेंट यूज़र इंटरफ़ेस (यूआई) वेब इंटरफ़ेस को तुरंत सेटअप करना

अब, सीएलआई कमांड का इस्तेमाल करके एजेंट डायरेक्ट्री स्ट्रक्चर बनाएं. यह कमांड चलाएं

uv run adk create qa_test_planner \
   --model gemini-2.5-flash \
   --project {your-project-id} \
   --region global

अहम जानकारी: {your-project-id} की वैल्यू को अपने प्रोजेक्ट आईडी से अपडेट करें

इससे आपकी मौजूदा वर्किंग डायरेक्ट्री में, एजेंट डायरेक्ट्री का यह स्ट्रक्चर बन जाएगा

qa_test_planner/
├── __init__.py
├── .env
├── agent.py

init.py और agent.py की जांच करने पर, आपको यह कोड दिखेगा

# __init__.py

from . import agent

# agent.py

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

ध्यान दें: डायरेक्ट्री का स्ट्रक्चर, init.py में एजेंट इंपोर्ट, और agent.py में root_agent ऑब्जेक्ट का एलान, ADK CLI के लिए ज़रूरी स्ट्रक्चर है.

हमारा क्यूए टेस्ट प्लानर एजेंट बनाना

आइए, अपना क्यूए टेस्ट प्लानर एजेंट बनाएं! qa_test_planner/agent.py फ़ाइल खोलें और नीचे दिया गया कोड कॉपी करें. इसमें root_agent शामिल होगा.

# qa_test_planner/agent.py

from google.adk.agents import Agent
from google.adk.tools.mcp_tool.mcp_toolset import (
    MCPToolset,
    StdioConnectionParams,
    StdioServerParameters,
)
from google.adk.planners import BuiltInPlanner
from google.genai import types
from dotenv import load_dotenv
import os
from pathlib import Path
from pydantic import BaseModel
from typing import Literal
import tempfile
import pandas as pd
from google.adk.tools import ToolContext


load_dotenv(dotenv_path=Path(__file__).parent / ".env")

confluence_tool = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="uvx",
            args=[
                "mcp-atlassian",
                f"--confluence-url={os.getenv('CONFLUENCE_URL')}",
                f"--confluence-username={os.getenv('CONFLUENCE_USERNAME')}",
                f"--confluence-token={os.getenv('CONFLUENCE_TOKEN')}",
                "--enabled-tools=confluence_search,confluence_get_page,confluence_get_page_children",
            ],
            env={},
        ),
        timeout=60,
    ),
)


class TestPlan(BaseModel):
    test_case_key: str
    test_type: Literal["manual", "automatic"]
    summary: str
    preconditions: str
    test_steps: str
    expected_result: str
    associated_requirements: str


async def write_test_tool(
    prd_id: str, test_cases: list[dict], tool_context: ToolContext
):
    """A tool to write the test plan into file

    Args:
        prd_id: Product requirement document ID
        test_cases: List of test case dictionaries that should conform to these fields:
            - test_case_key: str
            - test_type: Literal["manual","automatic"]
            - summary: str
            - preconditions: str
            - test_steps: str
            - expected_result: str
            - associated_requirements: str

    Returns:
        A message indicating success or failure of the validation and writing process
    """
    validated_test_cases = []
    validation_errors = []

    # Validate each test case
    for i, test_case in enumerate(test_cases):
        try:
            validated_test_case = TestPlan(**test_case)
            validated_test_cases.append(validated_test_case)
        except Exception as e:
            validation_errors.append(f"Error in test case {i + 1}: {str(e)}")

    # If validation errors exist, return error message
    if validation_errors:
        return {
            "status": "error",
            "message": "Validation failed",
            "errors": validation_errors,
        }

    # Write validated test cases to CSV
    try:
        # Convert validated test cases to a pandas DataFrame
        data = []
        for tc in validated_test_cases:
            data.append(
                {
                    "Test Case ID": tc.test_case_key,
                    "Type": tc.test_type,
                    "Summary": tc.summary,
                    "Preconditions": tc.preconditions,
                    "Test Steps": tc.test_steps,
                    "Expected Result": tc.expected_result,
                    "Associated Requirements": tc.associated_requirements,
                }
            )

        # Create DataFrame from the test case data
        df = pd.DataFrame(data)

        if not df.empty:
            # Create a temporary file with .csv extension
            with tempfile.NamedTemporaryFile(suffix=".csv", delete=False) as temp_file:
                # Write DataFrame to the temporary CSV file
                df.to_csv(temp_file.name, index=False)
                temp_file_path = temp_file.name

            # Read the file bytes from the temporary file
            with open(temp_file_path, "rb") as f:
                file_bytes = f.read()

            # Create an artifact with the file bytes
            await tool_context.save_artifact(
                filename=f"{prd_id}_test_plan.csv",
                artifact=types.Part.from_bytes(data=file_bytes, mime_type="text/csv"),
            )

            # Clean up the temporary file
            os.unlink(temp_file_path)

            return {
                "status": "success",
                "message": (
                    f"Successfully wrote {len(validated_test_cases)} test cases to "
                    f"CSV file: {prd_id}_test_plan.csv"
                ),
            }
        else:
            return {"status": "warning", "message": "No test cases to write"}
    except Exception as e:
        return {
            "status": "error",
            "message": f"An error occurred while writing to CSV: {str(e)}",
        }


root_agent = Agent(
    model="gemini-2.5-flash",
    name="qa_test_planner_agent",
    description="You are an expert QA Test Planner and Product Manager assistant",
    instruction=f"""
Help user search any product requirement documents on Confluence. Furthermore you also can provide the following capabilities when asked:
- evaluate product requirement documents and assess it, then give expert input on what can be improved 
- create a comprehensive test plan following Jira Xray mandatory field formatting, result showed as markdown table. Each test plan must also have explicit mapping on 
    which user stories or requirements identifier it's associated to 

Here is the Confluence space ID with it's respective document grouping:

- "{os.getenv("CONFLUENCE_PRD_SPACE_ID")}" : space to store Product Requirements Documents

Do not making things up, Always stick to the fact based on data you retrieve via tools.
""",
    tools=[confluence_tool, write_test_tool],
    planner=BuiltInPlanner(
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=2048,
        )
    ),
)

कॉन्फ़िगरेशन फ़ाइलें सेटअप करना

अब हमें इस प्रोजेक्ट के लिए, अतिरिक्त कॉन्फ़िगरेशन सेटअप जोड़ना होगा, क्योंकि इस एजेंट को Confluence का ऐक्सेस चाहिए

qa_test_planner/.env खोलें और उसमें नीचे दिए गए एनवायरमेंट वैरिएबल की वैल्यू डालें. पक्का करें कि इससे बनी .env फ़ाइल कुछ ऐसी दिखे

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT={YOUR-CLOUD-PROJECT-ID}
GOOGLE_CLOUD_LOCATION=global
CONFLUENCE_URL={YOUR-CONFLUENCE-DOMAIN}
CONFLUENCE_USERNAME={YOUR-CONFLUENCE-USERNAME}
CONFLUENCE_TOKEN={YOUR-CONFLUENCE-API-TOKEN}
CONFLUENCE_PRD_SPACE_ID={YOUR-CONFLUENCE-SPACE-ID}

अहम जानकारी: पक्का करें कि GOOGLE_CLOUD_PROJECT की वैल्यू, आपके प्रोजेक्ट आईडी की सही वैल्यू हो. शुरू करने के दौरान, ADK ने इसे पहले ही कॉन्फ़िगर कर लिया होगा

अहम जानकारी: अगर आपके पास ऐसा Confluence स्पेस है जिसमें प्रॉडक्ट की ज़रूरी शर्तों का दस्तावेज़ पहले से मौजूद है, तो **CONFLUENCE_** env वैल्यू को अपनी पसंद के मुताबिक भरें. इसके अलावा, इसे इस मॉक Confluence स्पेस से भी भरा जा सकता है

CONFLUENCE_URL="https://alvinprayuda.atlassian.net"

CONFLUENCE_USERNAME="[e-mail]"

CONFLUENCE_TOKEN="ATATT3xFfGF0b7MMEfXdLik4asfx1MaYBZnlDMtxJkudYO0sOf7HmrK9LlFTEkzv25_iPymHM3f78itZB0Q9EnNKYZ27X_Svi-219vJtCrnXqhDdGqNndC7oKkBRd22LNKj-HI2NCoqAr1Gt-O4SUXFmGGqb4LmQcHUOrPp1yXL9DcTqUnVZx70=E5E9C50D"

CONFLUENCE_PRD_SPACE_ID="PRD"

माफ़ करें, इस Confluence स्पेस को सार्वजनिक नहीं किया जा सकता. इसलिए, प्रॉडक्ट की ज़रूरी शर्तों के दस्तावेज़ पढ़ने के लिए, इन फ़ाइलों की जांच की जा सकती है. ये दस्तावेज़, ऊपर दिए गए क्रेडेंशियल का इस्तेमाल करके उपलब्ध होंगे.

प्रॉडक्ट की जानकारी वाले मॉक डाउनलोड करें

कोड के बारे में जानकारी

इस स्क्रिप्ट में, एजेंट को शुरू करने की प्रोसेस शामिल होती है. इसमें हम ये चीज़ें शुरू करते हैं:

• इस्तेमाल किए जाने वाले मॉडल को gemini-2.5-flash पर सेट करें
• Confluence MCP टूल सेट अप करना, जो Stdio के ज़रिए कम्यूनिकेट करेंगे
• टेस्ट प्लान लिखने और आर्टफ़ैक्ट में सीएसवी को डंप करने के लिए, write_test_tool कस्टम टूल सेटअप करना
• एजेंट की जानकारी और निर्देश सेट अप करना
• Gemini 2.5 Flash की थिंकिंग कैपेसिटी का इस्तेमाल करके, आखिरी जवाब जनरेट करने या उसे लागू करने से पहले प्लानिंग की सुविधा चालू करना

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

# qa-test-planner/agent.py

from google.adk.planners import BuiltInPlanner
from google.genai import types

...

# Provide the confluence tool to agent

root_agent = Agent(
    model="gemini-2.5-flash",
    name="qa_test_planner_agent",
    ...,
    tools=[confluence_tool, write_test_tool],
    planner=BuiltInPlanner(
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=2048,
        )
    ),

...

साथ ही, कोई कार्रवाई करने से पहले, हम यह देख सकते हैं कि मशीन लर्निंग की प्रोसेस क्या सोच रही है

Confluence MCP टूल

ADK से एमसीपी सर्वर से कनेक्ट करने के लिए, हमें MCPToolSet का इस्तेमाल करना होगा. इसे google.adk.tools.mcp_tool.mcp_toolset मॉड्यूल से इंपोर्ट किया जा सकता है. यहां शुरू किया जाने वाला कोड नीचे दिखाया गया है ( बेहतर तरीके से काम करने के लिए छोटा किया गया है)

# qa-test-planner/agent.py

from google.adk.tools.mcp_tool.mcp_toolset import (
    MCPToolset,
    StdioConnectionParams,
    StdioServerParameters,
)

...

# Initialize the Confluence MCP Tool via Stdio Output

confluence_tool = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="uvx",
            args=[
                "mcp-atlassian",
                f"--confluence-url={os.getenv('CONFLUENCE_URL')}",
                f"--confluence-username={os.getenv('CONFLUENCE_USERNAME')}",
                f"--confluence-token={os.getenv('CONFLUENCE_TOKEN')}",
                "--enabled-tools=confluence_search,confluence_get_page,confluence_get_page_children",
            ],
            env={},
        ),
        timeout=60,
    ),
)


...

# Provide the confluence tool to agent

root_agent = Agent(
    model="gemini-2.5-flash",
    name="qa_test_planner_agent",
    ...,
    tools=[confluence_tool, write_test_tool],

...

इस कॉन्फ़िगरेशन की मदद से, एजेंट Confluence MCP सर्वर को एक अलग प्रोसेस के तौर पर शुरू करेगा. साथ ही, यह Studio I/O के ज़रिए उन प्रोसेस के साथ कम्यूनिकेशन मैनेज करेगा. इस फ़्लो को एमसीपी के आर्किटेक्चर की इस इमेज में दिखाया गया है. इमेज में लाल बॉक्स में इसे मार्क किया गया है.

इसके अलावा, एमसीपी को शुरू करने के लिए दिए गए निर्देशों के आर्ग्युमेंट में, हम सिर्फ़ इन टूल का इस्तेमाल करने की अनुमति देते हैं: confluence_search, confluence_get_page, और confluence_get_page_children. ये टूल, हमारे क्यूए टेस्ट एजेंट के इस्तेमाल के उदाहरणों के साथ काम करते हैं. इस कोडलैब ट्यूटोरियल के लिए, हम समुदाय के योगदान से बनाए गए Atlassian MCP सर्वर का इस्तेमाल करते हैं. ज़्यादा जानकारी के लिए, पूरे दस्तावेज़ देखें.

Write टेस्ट टूल

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

# qa-test-planner/agent.py

...

async def write_test_tool(
    prd_id: str, test_cases: list[dict], tool_context: ToolContext
):
    """A tool to write the test plan into file

    Args:
        prd_id: Product requirement document ID
        test_cases: List of test case dictionaries that should conform to these fields:
            - test_case_key: str
            - test_type: Literal["manual","automatic"]
            - summary: str
            - preconditions: str
            - test_steps: str
            - expected_result: str
            - associated_requirements: str

    Returns:
        A message indicating success or failure of the validation and writing process
    """
    validated_test_cases = []
    validation_errors = []

    # Validate each test case
    for i, test_case in enumerate(test_cases):
        try:
            validated_test_case = TestPlan(**test_case)
            validated_test_cases.append(validated_test_case)
        except Exception as e:
            validation_errors.append(f"Error in test case {i + 1}: {str(e)}")

    # If validation errors exist, return error message
    if validation_errors:
        return {
            "status": "error",
            "message": "Validation failed",
            "errors": validation_errors,
        }

    # Write validated test cases to CSV
    try:
        # Convert validated test cases to a pandas DataFrame
        data = []
        for tc in validated_test_cases:
            data.append(
                {
                    "Test Case ID": tc.test_case_key,
                    "Type": tc.test_type,
                    "Summary": tc.summary,
                    "Preconditions": tc.preconditions,
                    "Test Steps": tc.test_steps,
                    "Expected Result": tc.expected_result,
                    "Associated Requirements": tc.associated_requirements,
                }
            )

        # Create DataFrame from the test case data
        df = pd.DataFrame(data)

        if not df.empty:
            # Create a temporary file with .csv extension
            with tempfile.NamedTemporaryFile(suffix=".csv", delete=False) as temp_file:
                # Write DataFrame to the temporary CSV file
                df.to_csv(temp_file.name, index=False)
                temp_file_path = temp_file.name

            # Read the file bytes from the temporary file
            with open(temp_file_path, "rb") as f:
                file_bytes = f.read()

            # Create an artifact with the file bytes
            await tool_context.save_artifact(
                filename=f"{prd_id}_test_plan.csv",
                artifact=types.Part.from_bytes(data=file_bytes, mime_type="text/csv"),
            )

            # Clean up the temporary file
            os.unlink(temp_file_path)

            return {
                "status": "success",
                "message": (
                    f"Successfully wrote {len(validated_test_cases)} test cases to "
                    f"CSV file: {prd_id}_test_plan.csv"
                ),
            }
        else:
            return {"status": "warning", "message": "No test cases to write"}
    except Exception as e:
        return {
            "status": "error",
            "message": f"An error occurred while writing to CSV: {str(e)}",
        }


...

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

ऊपर बताए गए फ़ंक्शन का इस्तेमाल, इन सुविधाओं के लिए किया जाता है:

1. जनरेट किए गए टेस्ट प्लान की जांच करें, ताकि यह ज़रूरी फ़ील्ड की खास बातों के मुताबिक हो. हम Pydantic मॉडल का इस्तेमाल करके जांच करते हैं. अगर कोई गड़बड़ी होती है, तो हम एजेंट को गड़बड़ी का मैसेज वापस भेजते हैं
2. pandas फ़ंक्शन का इस्तेमाल करके, नतीजे को CSV में डालना
3. जनरेट की गई फ़ाइल को आर्टफ़ैक्ट के तौर पर सेव किया जाता है. इसके लिए, आर्टफ़ैक्ट सेवा की सुविधाओं का इस्तेमाल किया जाता है. इन्हें ToolContext ऑब्जेक्ट का इस्तेमाल करके ऐक्सेस किया जा सकता है. इसे हर टूल कॉल पर ऐक्सेस किया जा सकता है

अगर जनरेट की गई फ़ाइलों को आर्टफ़ैक्ट के तौर पर सेव किया जाता है, तो उन्हें ADK रनटाइम में इवेंट के तौर पर मार्क किया जाएगा. साथ ही, वे वेब इंटरफ़ेस पर एजेंट इंटरैक्शन में बाद में दिख सकती हैं

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

4. एजेंट की जांच करना

अब सीएलआई के ज़रिए एजेंट से बातचीत करने की कोशिश करते हैं. इसके लिए, यह निर्देश चलाएं

uv run adk run qa_test_planner

यह इस तरह का आउटपुट दिखाएगा. यहां एजेंट के साथ बारी-बारी से चैट की जा सकती है. हालांकि, इस इंटरफ़ेस से सिर्फ़ टेक्स्ट भेजा जा सकता है

Log setup complete: /tmp/agents_log/agent.xxxx_xxx.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent qa_test_planner_agent, type exit to exit.
user: hello
[qa_test_planner_agent]: Hello there! How can I help you today?
user: 

🤖इससे पूछें कि यह क्या-क्या कर सकता है: "मुझे किस काम में मदद मिल सकती है?"

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

uv run adk web --port 8080

इससे, नीचे दिए गए उदाहरण की तरह आउटपुट जनरेट होगा. इसका मतलब है कि हम वेब इंटरफ़ेस को पहले से ही ऐक्सेस कर सकते हैं

INFO:     Started server process [xxxx]
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://0.0.0.0:8080 (Press CTRL+C to quit)

अब इसे देखने के लिए, Cloud Shell Editor के सबसे ऊपर मौजूद वेब की झलक बटन पर क्लिक करें. इसके बाद, पोर्ट 8080 पर झलक देखें को चुनें

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

आइए, कुछ कार्रवाइयां आज़माते हैं! इन प्रॉम्प्ट की मदद से एजेंट से चैट करें:

• " कृपया सभी उपलब्ध पीआरडी की सूची दें "
• " Snaprecipe के पीआरडी के लिए टेस्ट प्लान लिखना "

जब यह कुछ टूल इस्तेमाल करता है, तो डेवलपमेंट यूज़र इंटरफ़ेस (यूआई) में जाकर देखा जा सकता है कि क्या हो रहा है

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

अब, CSV फ़ाइल को Google शीट में इंपोर्ट करके, उसका कॉन्टेंट देखा जा सकता है. उदाहरण के लिए

बधाई हो! अब आपके पास स्थानीय तौर पर काम करने वाला क्यूए टेस्ट प्लानर एजेंट है! अब देखते हैं कि इसे Cloud Run में कैसे डिप्लॉय किया जा सकता है, ताकि दूसरे लोग भी इसका इस्तेमाल कर सकें!

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

अब, हम इस बेहतरीन ऐप्लिकेशन को कहीं से भी ऐक्सेस करना चाहते हैं. ऐसा करने के लिए, हम इस ऐप्लिकेशन को पैकेज कर सकते हैं और उसे Cloud Run पर डिप्लॉय कर सकते हैं. इस डेमो के लिए, इस सेवा को सार्वजनिक सेवा के तौर पर दिखाया जाएगा. इसे दूसरे लोग ऐक्सेस कर सकते हैं. हालांकि, ध्यान रखें कि यह सबसे सही तरीका नहीं है!

आपकी मौजूदा वर्किंग डायरेक्ट्री में, हमारे ऐप्लिकेशन को Cloud Run पर डिप्लॉय करने के लिए ज़रूरी सभी फ़ाइलें पहले से मौजूद हैं - एजेंट डायरेक्ट्री, Dockerfile, और server.py (मुख्य सेवा स्क्रिप्ट). आइए, इसे डिप्लॉय करें. Cloud Shell टर्मिनल पर जाएं और पक्का करें कि मौजूदा प्रोजेक्ट, आपके चालू प्रोजेक्ट के तौर पर कॉन्फ़िगर किया गया हो. अगर ऐसा नहीं है, तो प्रोजेक्ट आईडी सेट करने के लिए gcloud configure कमांड का इस्तेमाल करें:

gcloud config set project [PROJECT_ID]

इसके बाद, इसे Cloud Run पर डिप्लॉय करने के लिए, यह कमांड चलाएं.

gcloud run deploy qa-test-planner-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --update-env-vars GOOGLE_GENAI_USE_VERTEXAI=1 \
                  --update-env-vars GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --update-env-vars GOOGLE_CLOUD_LOCATION=global \
                  --update-env-vars CONFLUENCE_URL={YOUR_CONFLUENCE_URL} \
                  --update-env-vars CONFLUENCE_USERNAME={YOUR_CONFLUENCE_USERNAME} \
                  --update-env-vars CONFLUENCE_TOKEN={YOUR_CONFLUENCE_TOKEN} \
                  --update-env-vars CONFLUENCE_PRD_SPACE_ID={YOUR_PRD_SPACE_ID} \
                  --memory 1G

अहम जानकारी: अगर आपके पास ऐसा Confluence स्पेस है जिसमें प्रॉडक्ट की ज़रूरी शर्तों का दस्तावेज़ पहले से मौजूद है, तो **CONFLUENCE_** env वैल्यू को अपनी पसंद के मुताबिक भरें. इसके अलावा, इसे इस मॉक Confluence स्पेस से भी भरा जा सकता है

CONFLUENCE_URL="https://alvinprayuda.atlassian.net"

CONFLUENCE_USERNAME="[e-mail]"

CONFLUENCE_TOKEN="ATATT3xFfGF0b7MMEfXdLik4asfx1MaYBZnlDMtxJkudYO0sOf7HmrK9LlFTEkzv25_iPymHM3f78itZB0Q9EnNKYZ27X_Svi-219vJtCrnXqhDdGqNndC7oKkBRd22LNKj-HI2NCoqAr1Gt-O4SUXFmGGqb4LmQcHUOrPp1yXL9DcTqUnVZx70=E5E9C50D"

CONFLUENCE_PRD_SPACE_ID="PRD"

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

डिप्लॉयमेंट पूरा होने के बाद, आपको नीचे दिए गए लिंक जैसा एक लिंक मिलेगा:

https://qa-test-planner-agent-*******.us-central1.run.app

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

अब इन अलग-अलग प्रॉम्प्ट को फिर से आज़माते हैं - क्रम से, देखें कि क्या होता है:

• " क्या आपको मॉर्टगेज एस्टिमेटर से जुड़ा पीआरडी मिल सकता है? "
• " इस बारे में सुझाव दें कि हम इसमें क्या सुधार कर सकते हैं"
• " इसके लिए टेस्ट प्लान लिखें"

इसके अलावा, हम एजेंट को FastAPI ऐप्लिकेशन के तौर पर चलाते हैं. इसलिए, हम /docs रूट में मौजूद सभी एपीआई रूट की जांच भी कर सकते हैं. उदाहरण के लिए, अगर https://qa-test-planner-agent-*******.us-central1.run.app/docs जैसा यूआरएल ऐक्सेस किया जाता है, तो आपको Swagger दस्तावेज़ पेज दिखेगा, जैसा कि यहां दिखाया गया है

कोड के बारे में जानकारी

अब, server.py से शुरू करके, यह देखें कि डिप्लॉयमेंट के लिए हमें यहां किस फ़ाइल की ज़रूरत है

# server.py

import os

from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

app_args = {"agents_dir": AGENT_DIR, "web": True}

app: FastAPI = get_fast_api_app(**app_args)

app.title = "qa-test-planner-agent"
app.description = "API for interacting with the Agent qa-test-planner-agent"


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

get_fast_api_app फ़ंक्शन का इस्तेमाल करके, अपने एजेंट को आसानी से FastAPI ऐप्लिकेशन में बदला जा सकता है. इस फ़ंक्शन में, हम अलग-अलग सुविधाएं सेट अप कर सकते हैं. उदाहरण के लिए, सेशन सेवा, आर्टफ़ैक्ट सेवा को कॉन्फ़िगर करना या क्लाउड में डेटा को ट्रैक करना.

अगर आप चाहें, तो यहां ऐप्लिकेशन लाइफ़साइकल भी सेट किया जा सकता है. इसके बाद, Fast API ऐप्लिकेशन को चलाने के लिए, uvicorn का इस्तेमाल किया जा सकता है

इसके बाद, Dockerfile से हमें ऐप्लिकेशन को चलाने के लिए ज़रूरी निर्देश मिलेंगे

# Dockerfile

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

6. चुनौती

अब समय आ गया है कि आप अपनी खोज की स्किल को बेहतर बनाएं. क्या आपके पास ऐसा टूल बनाने का विकल्प है जिससे पीआरडी की समीक्षा का फ़ीडबैक भी फ़ाइल में लिखा जा सके?

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

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

1. Google Cloud Console में, संसाधन मैनेज करें पेज पर जाएं.
2. प्रोजेक्ट की सूची में, वह प्रोजेक्ट चुनें जिसे मिटाना है. इसके बाद, मिटाएं पर क्लिक करें.
3. डायलॉग बॉक्स में, प्रोजेक्ट आईडी टाइप करें. इसके बाद, प्रोजेक्ट मिटाने के लिए बंद करें पर क्लिक करें.
4. इसके अलावा, आपके पास Console पर Cloud Run पर जाकर, वह सेवा चुनने और मिटाने का विकल्प है जिसे आपने अभी डिप्लॉय किया है.