با استفاده از ADK، MCP، و Gemini 2.5 Flash با حالت تفکر، عامل برنامه ریز آزمون QA بسازید.

1. مقدمه

fd4ad67ab57d9257.png

پتانسیل استفاده از هوش مصنوعی تولیدی برای ایجاد برنامه آزمایشی از توانایی آن در حل دو بزرگترین چالش در تضمین کیفیت مدرن ناشی می شود: سرعت و جامع بودن. در چرخه‌های سریع Agile و DevOps امروزی، نوشتن دستی طرح‌های آزمایشی دقیق یک گلوگاه مهم است که کل فرآیند آزمایش را به تأخیر می‌اندازد. یک عامل مجهز به هوش مصنوعی ژنرال می‌تواند داستان‌های کاربر و الزامات فنی را برای تولید یک طرح آزمایشی کامل در چند دقیقه، نه چند روز، دریافت کند، و اطمینان حاصل کند که فرآیند QA با توسعه همگام است. علاوه بر این، هوش مصنوعی در شناسایی سناریوهای پیچیده، موارد لبه و مسیرهای منفی که ممکن است یک انسان نادیده گرفته شود، برتری دارد، که منجر به بهبود گسترده پوشش آزمایشی و کاهش قابل توجه اشکالاتی می شود که به سمت تولید فرار می کنند.

در این نرم افزار کد، نحوه ساخت چنین عاملی را بررسی خواهیم کرد که بتواند اسناد مورد نیاز محصول را از Confluence بازیابی کند و بتواند بازخورد سازنده بدهد و همچنین یک طرح آزمایشی جامع ایجاد کند که می تواند در یک فایل CSV صادر شود.

از طریق کد لبه، شما یک رویکرد گام به گام را به شرح زیر به کار خواهید گرفت:

  1. پروژه Google Cloud خود را آماده کنید و تمام API مورد نیاز را روی آن فعال کنید
  2. فضای کاری را برای محیط کدنویسی خود تنظیم کنید
  3. آماده سازی mcp-server محلی برای Confluence
  4. ساختار کد منبع عامل ADK، اعلان و ابزار برای اتصال به سرور MCP
  5. درک استفاده از سرویس Artifact و زمینه ابزار
  6. آزمایش عامل با استفاده از رابط کاربری توسعه وب محلی ADK
  7. متغیرهای محیطی را مدیریت کنید و فایل‌های مورد نیاز برای استقرار برنامه در Cloud Run را تنظیم کنید
  8. برنامه را در Cloud Run مستقر کنید

نمای کلی معماری

819179179d974c07.jpeg

پیش نیازها

  • کار راحت با پایتون
  • درک معماری پایه تمام پشته با استفاده از سرویس HTTP

چیزی که یاد خواهید گرفت

  • معماری ADK Agent در حالی که از چندین قابلیت آن استفاده می کند
  • استفاده از ابزار با ابزار سفارشی و MCP
  • تنظیم خروجی فایل توسط نماینده با استفاده از مدیریت Artifact Service
  • استفاده از BuiltInPlanner برای بهبود اجرای وظایف با انجام برنامه ریزی با قابلیت های تفکر فلش Gemini 2.5
  • تعامل و اشکال زدایی از طریق رابط وب ADK
  • برنامه را با استفاده از Dockerfile در Cloud Run اجرا کنید و متغیرهای محیطی را ارائه دهید

آنچه شما نیاز دارید

  • مرورگر وب کروم
  • یک اکانت جیمیل
  • یک پروژه Cloud با فعال کردن صورت‌حساب
  • (اختیاری) تلاقی فضای با صفحه(های) اسناد مورد نیاز محصول

این کد لبه که برای توسعه دهندگان همه سطوح (از جمله مبتدیان) طراحی شده است، از پایتون در برنامه نمونه خود استفاده می کند. با این حال، دانش پایتون برای درک مفاهیم ارائه شده مورد نیاز نیست. اگر فضای Confluence را ندارید نگران نباشید، ما اعتبارنامه‌هایی را برای امتحان این کد لبه ارائه می‌کنیم.

2. قبل از شروع

Active Project را در Cloud Console انتخاب کنید

این کد لبه فرض می کند که شما قبلاً یک پروژه Google Cloud با فعال بودن صورتحساب دارید. اگر هنوز آن را ندارید، می توانید دستورالعمل های زیر را برای شروع دنبال کنید.

  1. در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
  2. مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.

3a29a3ec1306e9b4.png

راه اندازی پروژه Cloud در ترمینال Cloud Shell

  1. شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می شود، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

1829c3759227c19b.png

  1. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است: 
gcloud auth list
  1. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد. 
gcloud config list project
  1. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید: 
gcloud config set project <YOUR_PROJECT_ID>

همچنین می‌توانید شناسه PROJECT_ID را در کنسول ببینید

4032c45803813f30.jpeg

روی آن کلیک کنید و تمام پروژه و شناسه پروژه را در سمت راست خواهید دید

8dc17eb4271de6b5.jpeg

  1. API های مورد نیاز را از طریق دستور زیر فعال کنید. این ممکن است چند دقیقه طول بکشد، پس لطفا صبور باشید. 
gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com

در اجرای موفقیت آمیز دستور، باید پیامی مشابه تصویر زیر مشاهده کنید:

Operation "operations/..." finished successfully.

جایگزین دستور gcloud از طریق کنسول با جستجوی هر محصول یا استفاده از این پیوند است.

اگر هر یک از API از دست رفته است، همیشه می توانید آن را در طول پیاده سازی فعال کنید.

برای دستورات و استفاده از gcloud به اسناد مراجعه کنید.

به Cloud Shell Editor and Setup Application Working Directory بروید

اکنون، می‌توانیم ویرایشگر کد خود را برای انجام برخی موارد کدنویسی تنظیم کنیم. برای این کار از Cloud Shell Editor استفاده خواهیم کرد

  1. روی دکمه Open Editor کلیک کنید، با این کار یک Cloud Shell Editor باز می شود، ما می توانیم کد خود را اینجا بنویسیم b16d56e4979ec951.png
  2. مطمئن شوید که پروژه Cloud Code در گوشه سمت چپ پایین (نوار وضعیت) ویرایشگر Cloud Shell تنظیم شده است، همانطور که در تصویر زیر مشخص شده است و روی پروژه فعال Google Cloud که در آن صورت‌حساب را فعال کرده‌اید، تنظیم شده است. در صورت درخواست مجوز دهید . اگر از قبل دستور قبلی را دنبال کرده اید، دکمه ممکن است به جای دکمه ورود مستقیماً به پروژه فعال شده شما اشاره کند

f5003b9c38b43262.png

  1. سپس، بیایید دایرکتوری کار قالب را برای این کد لبه از Github کلون کنیم، دستور زیر را اجرا کنیم. دایرکتوری کاری را در دایرکتوری qa-test-planner-agent ایجاد می کند 
git clone https://github.com/alphinside/qa-test-planner-agent.git qa-test-planner-agent
  1. پس از آن، به بخش بالای ویرایشگر پوسته ابری بروید و روی File->Open Folder کلیک کنید، دایرکتوری نام کاربری خود را پیدا کنید و دایرکتوری qa-test-planner-agent را پیدا کنید و سپس روی دکمه OK کلیک کنید. این دایرکتوری انتخاب شده را به عنوان دایرکتوری اصلی تبدیل می کند. در این مثال، نام کاربری alvinprayuda است، از این رو مسیر دایرکتوری در زیر نشان داده شده است

2c53696f81d805cc.png

fb321426f3c848b3.png

حال، ویرایشگر پوسته ابری شما باید به این شکل باشد

9ae344bc522d2a6f.png

راه اندازی محیط

محیط مجازی پایتون را آماده کنید

مرحله بعدی آماده سازی محیط توسعه است. ترمینال فعال فعلی شما باید در دایرکتوری کاری qa-test-planner-agent باشد. ما از Python 3.12 در این کد لبه استفاده خواهیم کرد و از مدیر پروژه uv python برای ساده سازی نیاز به ایجاد و مدیریت نسخه پایتون و محیط مجازی استفاده خواهیم کرد.

  1. اگر هنوز ترمینال را باز نکرده اید، آن را با کلیک بر روی Terminal -> New Terminal باز کنید یا از Ctrl + Shift + C استفاده کنید، یک پنجره ترمینال در قسمت پایین مرورگر باز می شود.

f8457daf0bed059e.jpeg

  1. uv را دانلود و با دستور زیر پایتون 3.12 را نصب کنید 
curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
  1. حال اجازه دهید محیط مجازی را با استفاده از 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",
]
  1. برای تست env مجازی، فایل جدید main.py ایجاد کنید و کد زیر را کپی کنید 
def main():
   print("Hello from qa-test-planner-agent")

if __name__ == "__main__":
   main()
  1. سپس، دستور زیر را اجرا کنید 
uv run main.py

مانند شکل زیر خروجی دریافت خواهید کرد 

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

این نشان می دهد که پروژه پایتون به درستی راه اندازی شده است.

اکنون می‌توانیم به مرحله بعدی برویم، ساخت عامل و سپس خدمات

3. Agent را با استفاده از Google ADK و Gemini 2.5 بسازید

مقدمه ای بر ساختار دایرکتوری ADK

بیایید با بررسی آنچه ADK ارائه می دهد و نحوه ساخت عامل شروع کنیم. اسناد کامل ADK در این URL قابل دسترسی است. ADK ابزارهای بسیاری را در اجرای دستور CLI خود به ما ارائه می دهد. برخی از آنها به شرح زیر است:

  • ساختار دایرکتوری عامل را تنظیم کنید
  • به سرعت تعامل را از طریق خروجی ورودی CLI امتحان کنید
  • به سرعت رابط وب UI توسعه محلی را تنظیم کنید

حال، بیایید ساختار دایرکتوری عامل را با استفاده از دستور CLI ایجاد کنیم. دستور زیر را اجرا کنید 

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

این ساختار دایرکتوری عامل زیر را در فهرست کاری فعلی شما ایجاد می کند 

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',
)

ایجاد عامل برنامه ریز آزمون QA ما

بیایید عامل برنامه ریز آزمون QA خود را بسازیم! فایل 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}

متأسفانه، این فضای Confluence را نمی توان عمومی کرد، بنابراین می توانید این فایل ها را برای خواندن اسناد مورد نیاز محصول موجود که با استفاده از اعتبارنامه های بالا در دسترس خواهند بود، بررسی کنید.

توضیح کد

این اسکریپت شامل شروع عامل ما است که در آن موارد زیر را مقداردهی اولیه می کنیم:

  • مدل مورد استفاده را روی gemini-2.5-flash تنظیم کنید
  • راه اندازی Confluence MCP Tools که از طریق Stdio ارتباط برقرار می کنند
  • ابزار سفارشی write_test_tool برای نوشتن طرح آزمایشی تنظیم کنید و csv را روی آرتیفکت تخلیه کنید
  • توضیحات و دستورالعمل عامل را تنظیم کنید
  • با استفاده از قابلیت‌های تفکر فلش Gemini 2.5 قبل از ایجاد پاسخ یا اجرای نهایی، برنامه‌ریزی را فعال کنید.

خود عامل، هنگامی که توسط مدل 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,
        )
    ),

...

و قبل از انجام اقدامات، می توانیم روند تفکر آن را ببینیم

185371e0e7e5995e.png

ابزار Confluence MCP

برای اتصال به سرور 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],

...

با این پیکربندی، Agent سرور Confluence MCP را به عنوان یک فرآیند جداگانه مقداردهی می‌کند و ارتباط با آن فرآیندها را از طریق Studio I/O انجام می‌دهد. این جریان در تصویر معماری MCP زیر که در کادر قرمز رنگ زیر مشخص شده است، نشان داده شده است.

85d51458405f9217.png

علاوه بر این در آرگومان‌های دستور اولیه MCP، ابزارهایی را که می‌توان از آنها استفاده کرد فقط به این ابزارها محدود می‌کنیم: confluence_search، confluence_get_page، و confluence_get_page_children که از موارد استفاده از عامل تست QA ما پشتیبانی می‌کنند. ما از سرور Atlassian MCP (برای جزئیات بیشتر به مستندات کامل مراجعه کنید) برای این آموزش Codelab استفاده می‌کنیم.

ابزار تست نوشتن

پس از اینکه عامل زمینه را از ابزار 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)}",
        }


...

تابع اعلام شده در بالا برای پشتیبانی از عملکردهای زیر است:

  1. طرح تست تولید شده را بررسی کنید تا با مشخصات فیلد اجباری مطابقت داشته باشد، با استفاده از مدل Pydantic بررسی می کنیم و در صورت بروز خطا، پیغام خطا را به نماینده ارائه می دهیم.
  2. با استفاده از قابلیت پاندا، نتیجه را به CSV بریزید
  3. سپس فایل تولید شده به عنوان مصنوع با استفاده از قابلیت های Artifact Service ذخیره می شود که می توان با استفاده از شی ToolContext که در هر تماس ابزار قابل دسترسی است به آن دسترسی پیدا کرد.

اگر فایل‌های تولید شده را به‌عنوان مصنوع ذخیره کنیم، در زمان اجرا ADK به‌عنوان رویداد علامت‌گذاری می‌شود و می‌تواند بعداً در رابط وب در تعامل با عامل نمایش داده شود.

57f5ab95f4ae86e7.png

با این کار، می‌توانیم پاسخ فایل را به صورت پویا تنظیم کنیم تا به کاربر داده شود.

4. تست عامل

حالا بیایید سعی کنیم از طریق CLI با عامل ارتباط برقرار کنیم، دستور زیر را اجرا کنیم 

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:

خوب است که بتوانید از طریق CLI با نماینده چت کنید. اما، حتی بهتر است اگر یک چت وب خوب با آن داشته باشیم و بتوانیم آن را نیز انجام دهیم! ADK همچنین به ما این امکان را می دهد که یک رابط کاربری توسعه برای تعامل و بررسی آنچه در طول تعامل می گذرد داشته باشیم. دستور زیر را برای راه اندازی سرور UI توسعه محلی اجرا کنید 

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)

اکنون برای بررسی آن، روی دکمه Web Preview در قسمت بالای Cloud Shell Editor خود کلیک کرده و Preview در پورت 8080 را انتخاب کنید.

e7c9f56c2463164.png

صفحه وب زیر را مشاهده خواهید کرد که در آن می توانید عوامل موجود را در دکمه کشویی بالا سمت چپ انتخاب کنید (در مورد ما باید qa_test_planner باشد) و با ربات تعامل کنید. در پنجره سمت چپ، اطلاعات زیادی در مورد جزئیات گزارش در طول اجرای Agent مشاهده خواهید کرد

8ed90debb774207f.png

بیایید برخی اقدامات را امتحان کنیم! با این دستورات با نمایندگان چت کنید:

  • "لطفا همه PRD های موجود را فهرست کنید"
  • "نوشتن طرح آزمایشی برای Snaprecipe PRD"

هنگامی که از برخی ابزارها استفاده می کند، می توانید آنچه را که در رابط کاربری توسعه می گذرد بررسی کنید

3469a0785b507be3.png

ببینید که چگونه نماینده به شما پاسخ می دهد و همچنین در صورت درخواست پرونده آزمایش ، بازرسی می کند ، برنامه آزمایش را در پرونده CSV به عنوان مصنوعات تولید می کند

94b73fb4d447ad62.png

اکنون، می‌توانید محتوای CSV را برای مثال با وارد کردن آن به Google Sheet بررسی کنید

89e3fc18d6e92d82.png

تبریک می گویم! اکنون شما یک عامل QA Test Planner دارید که به صورت محلی اجرا می شود! حالا بیایید ببینیم چگونه می توانیم آن را در Cloud Run مستقر کنیم تا افراد دیگر نیز بتوانند از آن استفاده کنند!

5. استقرار در Cloud Run

اکنون، البته ما می خواهیم از هر کجا به این برنامه شگفت انگیز دسترسی داشته باشیم. برای انجام این کار، می توانیم این برنامه را بسته بندی کنیم و آن را در Cloud Run مستقر کنیم. به خاطر این نسخه ی نمایشی، این سرویس به عنوان یک سرویس عمومی که برای دیگران قابل دسترسی است در معرض دید قرار می گیرد. با این حال، به خاطر داشته باشید که این بهترین تمرین نیست!

819179179d974c07.jpeg

در فهرست کاری فعلی شما، ما از قبل همه فایل‌های مورد نیاز برای استقرار برنامه‌های خود را در 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

اگر از شما خواسته شد که ایجاد یک رجیستری مصنوع را برای مخزن docker تأیید کنید، فقط به Y پاسخ دهید. توجه داشته باشید که ما در اینجا اجازه دسترسی غیرقانونی را می دهیم زیرا این یک برنامه آزمایشی است. توصیه این است که از احراز هویت مناسب برای برنامه های تجاری و تولیدی خود استفاده کنید.

پس از تکمیل استقرار، باید پیوندی شبیه به زیر دریافت کنید:

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

هنگامی که به URL دسترسی پیدا می کنید، رابط کاربری وب توسعه دهنده را مشابه زمانی که آن را به صورت محلی امتحان می کنید، وارد خواهید کرد. ادامه دهید و از برنامه خود از پنجره ناشناس یا دستگاه تلفن همراه خود استفاده کنید. از قبل باید زنده باشد.

حالا بیایید دوباره این دستورهای مختلف را امتحان کنیم - به طور متوالی، ببینید در آنجا چه اتفاقی می افتد:

  • "آیا می توانید PRD مربوط به برآوردگر وام مسکن را پیدا کنید؟"
  • "درباره اینکه چه چیزی را می توانیم در آن بهبود دهیم به من بازخورد بدهید"
  • "برنامه آزمایشی آن را بنویسید"

علاوه بر این، همانطور که عامل را به عنوان یک برنامه FastAPI اجرا می کنیم، همچنین می توانیم تمام مسیرهای API را در مسیر /docs بازرسی کنیم. به عنوان مثال، اگر به URL مانند این https://qa-test-planner-agent-********.us-central1.run.app/docs دسترسی داشته باشید، صفحه اسناد Swagger را مانند نشان داده شده در زیر مشاهده خواهید کرد.

c6f613b7bdc91ef3.png

توضیح کد

حالا، بیایید بررسی کنیم که چه فایلی برای استقرار در اینجا نیاز داریم، که با 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 تبدیل کنیم. در این تابع، ما می توانیم عملکردهای مختلفی را تنظیم کنیم، به عنوان مثال پیکربندی سرویس جلسه، سرویس مصنوع یا حتی ردیابی داده ها در ابر.

در صورت تمایل، می توانید چرخه عمر برنامه را نیز در اینجا تنظیم کنید. پس از آن می توانیم از uvicorn برای اجرای برنامه Fast API استفاده کنیم

پس از آن، 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. چالش

اکنون زمان آن است که مهارت های اکتشافی خود را بدرخشید و صیقل دهید. آیا می توانید ابزاری ایجاد کنید تا بازخورد بررسی PRD نیز در یک فایل نوشته شود؟

7. پاکسازی کنید

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع مورد استفاده در این Codelab، این مراحل را دنبال کنید:

  1. در کنسول Google Cloud، به صفحه مدیریت منابع بروید.
  2. در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی Delete کلیک کنید.
  3. در محاوره، شناسه پروژه را تایپ کنید و سپس روی Shut down کلیک کنید تا پروژه حذف شود.
  4. یا می‌توانید به Cloud Run در کنسول بروید، سرویسی را که به تازگی مستقر کرده‌اید انتخاب کرده و حذف کنید.