ADK, MCP ve Gemini 2.5 Flash ile Düşünme Modu'nu kullanarak Kalite Güvencesi Test Planlayıcı Aracı oluşturma

1. Giriş

fd4ad67ab57d9257.png

Test planı oluşturmak için üretken yapay zekayı kullanmanın potansiyeli, modern kalite güvencesindeki en büyük iki zorluğu (hız ve kapsamlılık) çözme yeteneğinden kaynaklanır. Günümüzün hızlı çevik ve DevOps döngülerinde, ayrıntılı test planlarının manuel olarak oluşturulması önemli bir darboğaz oluşturarak tüm test sürecini geciktiriyor. Üretken yapay zeka destekli bir aracı, kullanıcı hikayelerini ve teknik gereksinimleri alarak günlerce değil, dakikalar içinde kapsamlı bir test planı oluşturabilir. Böylece kalite güvencesi süreci, geliştirme sürecine ayak uydurabilir. Ayrıca yapay zeka, insanların gözden kaçırabileceği karmaşık senaryoları, uç durumları ve olumsuz yolları belirleme konusunda üstün bir performans sergiler. Bu da test kapsamının büyük ölçüde iyileşmesine ve üretime sızan hataların önemli ölçüde azalmasına yol açar.

Bu codelab'de, Confluence'ten ürün şartları dokümanlarını alabilen, yapıcı geri bildirimler verebilen ve CSV dosyasına aktarılabilen kapsamlı bir test planı oluşturabilen bir aracı oluşturmayı öğreneceğiz.

Bu codelab'de aşağıdaki gibi adım adım bir yaklaşım kullanacaksınız:

  1. Google Cloud projenizi hazırlayın ve gerekli tüm API'leri etkinleştirin.
  2. Kodlama ortamınız için çalışma alanı oluşturma
  3. Confluence için yerel mcp-server'ı hazırlama
  4. MCP sunucusuna bağlanmak için ADK aracısı kaynak kodunu, istemini ve araçlarını yapılandırma
  5. Artifact Service ve Tool Contexts kullanımını anlama
  6. ADK yerel web geliştirme kullanıcı arayüzünü kullanarak aracıyı test etme
  7. Ortam değişkenlerini yönetme ve uygulamayı Cloud Run'a dağıtmak için gereken dosyaları ayarlama
  8. Uygulamayı Cloud Run'a dağıtma

Mimariye Genel Bakış

819179179d974c07.jpeg

Ön koşullar

  • Python ile rahatça çalışabilme
  • HTTP hizmetini kullanan temel tam yığın mimarisi hakkında bilgi sahibi olma

Neler öğreneceksiniz?

  • ADK aracısını, çeşitli özelliklerinden yararlanarak tasarlama
  • Özel araç ve MCP ile araç kullanımı
  • Artifact Service Management'ı kullanarak aracı tarafından dosya çıkışı ayarlama
  • Gemini 2.5 Flash düşünme özellikleriyle planlama yaparak görev yürütme sürecini iyileştirmek için BuiltInPlanner'ı kullanma
  • ADK web arayüzü üzerinden etkileşim ve hata ayıklama
  • Dockerfile kullanarak uygulamayı Cloud Run'a dağıtma ve ortam değişkenleri sağlama

Gerekenler

  • Chrome web tarayıcısı
  • Gmail hesabı
  • Faturalandırmanın etkin olduğu bir Cloud projesi
  • (İsteğe bağlı) Ürün gereksinimleri belgeleri sayfasını içeren Confluence alanı

Her seviyeden geliştirici (yeni başlayanlar dahil) için tasarlanan bu codelab'de örnek uygulamada Python kullanılmaktadır. Ancak sunulan kavramları anlamak için Python bilgisi gerekmez. Confluence alanınız yoksa endişelenmeyin. Bu codelab'i denemeniz için kimlik bilgileri sağlayacağız.

2. Başlamadan önce

Cloud Console'da Etkin Projeyi Seçme

Bu codelab'de, faturalandırmanın etkin olduğu bir Google Cloud projenizin olduğu varsayılmaktadır. Henüz kullanmıyorsanız başlamak için aşağıdaki talimatları uygulayabilirsiniz.

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmanın bir projede etkin olup olmadığını kontrol etmeyi öğrenin.

3a29a3ec1306e9b4.png

Cloud Shell Terminal'de Cloud projesi oluşturma

  1. Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.

1829c3759227c19b.png

  1. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığını kontrol edin:
gcloud auth list
  1. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
  1. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>

Alternatif olarak, PROJECT_ID kimliğini konsolda da görebilirsiniz.

4032c45803813f30.jpeg

Bu seçeneği tıkladığınızda sağ tarafta tüm projenizi ve proje kimliğini görürsünüz.

8dc17eb4271de6b5.jpeg

  1. Aşağıda gösterilen komutu kullanarak gerekli API'leri etkinleştirin. Bu işlem birkaç dakika sürebilir. Lütfen bekleyin.
gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com

Komut başarıyla yürütüldüğünde aşağıda gösterilene benzer bir mesaj görürsünüz:

Operation "operations/..." finished successfully.

Gcloud komutuna alternatif olarak, her ürünü arayarak veya bu bağlantıyı kullanarak konsolu kullanabilirsiniz.

Herhangi bir API atlanırsa uygulama sırasında istediğiniz zaman etkinleştirebilirsiniz.

gcloud komutları ve kullanımı için belgelere bakın.

Cloud Shell Düzenleyici'ye gidin ve uygulama çalışma dizinini ayarlayın

Şimdi kod düzenleyicimizi bazı kodlama işlemleri yapacak şekilde ayarlayabiliriz. Bu işlem için Cloud Shell Düzenleyici'yi kullanacağız.

  1. Düzenleyiciyi aç düğmesini tıklayın. Bu işlemle Cloud Shell Düzenleyici açılır. Kodumuzu buraya yazabiliriz. b16d56e4979ec951.png
  2. Cloud Code projesinin, aşağıdaki resimde vurgulandığı gibi Cloud Shell düzenleyicisinin sol alt köşesinde (durum çubuğu) ayarlandığından ve faturalandırmanın etkin olduğu etkin Google Cloud projesine ayarlandığından emin olun. İstenirse Yetkilendir'i seçin. Önceki komutu zaten uyguladıysanız düğme, oturum açma düğmesi yerine doğrudan etkinleştirilmiş projenize de yönlendirebilir.

f5003b9c38b43262.png

  1. Ardından, bu codelab için şablon çalışma dizinini GitHub'dan klonlayalım. Bunun için aşağıdaki komutu çalıştırın. Çalışma dizini qa-test-planner-agent dizininde oluşturulur.
git clone https://github.com/alphinside/qa-test-planner-agent.git qa-test-planner-agent
  1. Ardından, Cloud Shell Düzenleyici'nin üst bölümüne gidip File->Open Folder'ı (Dosya->Klasörü Aç) tıklayın,username (kullanıcı adı) dizininizi ve qa-test-planner-agent dizinini bulup Tamam düğmesini tıklayın. Bu işlem, seçilen dizini ana çalışma dizini yapar. Bu örnekte, kullanıcı adı alvinprayuda olduğundan dizin yolu aşağıda gösterilmiştir.

2c53696f81d805cc.png

fb321426f3c848b3.png

Cloud Shell Düzenleyiciniz artık aşağıdaki gibi görünmelidir.

9ae344bc522d2a6f.png

Ortam Kurulumu

Python sanal ortamını hazırlama

Bir sonraki adım, geliştirme ortamını hazırlamaktır. Mevcut etkin terminaliniz, qa-test-planner-agent çalışma dizininde olmalıdır. Bu codelab'de Python 3.12'yi kullanacağız. Python sürümü ve sanal ortam oluşturma ve yönetme ihtiyacını basitleştirmek için uv python proje yöneticisini kullanacağız.

  1. Terminali henüz açmadıysanız Terminal -> Yeni Terminal'i tıklayarak açın veya Ctrl + Üst Karakter + C tuşlarını kullanarak açın. Bu tuşlar, tarayıcının alt kısmında bir terminal penceresi açar.

f8457daf0bed059e.jpeg

  1. uv'yı indirin ve aşağıdaki komutla Python 3.12'yi yükleyin.
curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
  1. Şimdi uv kullanarak sanal ortamı başlatalım. Bu komutu çalıştırın.
uv sync --frozen

Bu işlem, .venv dizinini oluşturur ve bağımlılıkları yükler. pyproject.toml dosyasına hızlıca göz atarak, bağımlılıklar hakkında aşağıdaki gibi bilgiler edinebilirsiniz.

dependencies = [
    "google-adk>=1.5.0",
    "mcp-atlassian>=0.11.9",
    "pandas>=2.3.0",
    "python-dotenv>=1.1.1",
]
  1. Sanal ortamı test etmek için main.py adlı yeni bir dosya oluşturun ve aşağıdaki kodu kopyalayın.
def main():
   print("Hello from qa-test-planner-agent")

if __name__ == "__main__":
   main()
  1. Ardından aşağıdaki komutu çalıştırın.
uv run main.py

Aşağıdaki gibi bir çıkış alırsınız.

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

Bu, Python projesinin düzgün şekilde ayarlandığını gösterir.

Şimdi bir sonraki adıma geçebiliriz: önce aracı, ardından hizmetleri oluşturma

3. Google ADK ve Gemini 2.5'i kullanarak aracı oluşturma

ADK dizin yapısına giriş

ADK'nın sunduğu özelliklere ve temsilcinin nasıl oluşturulacağına göz atarak başlayalım. ADK'nın tüm belgelerine bu URL'den erişebilirsiniz . ADK, KSA komut yürütme özelliğiyle birçok yardımcı program sunar. Bunlardan bazıları şunlardır :

  • Aracı dizin yapısını ayarlama
  • KSA giriş çıkışı üzerinden etkileşimi hızlıca deneme
  • Yerel geliştirme kullanıcı arayüzü web arayüzünü hızlıca kurma

Şimdi de CLI komutunu kullanarak aracı dizin yapısını oluşturalım. Aşağıdaki komutu çalıştırın

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

Mevcut çalışma dizininizde aşağıdaki aracı dizin yapısını oluşturur.

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

Ayrıca init.py ve agent.py dosyalarını incelerseniz bu kodu görürsünüz.

# __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 Test Planlayıcı Aracımızı Oluşturma

Kalite güvencesi testi planlayıcı aracımızı oluşturalım. qa_test_planner/agent.py dosyasını açın ve root_agent'ı içeren aşağıdaki kodu kopyalayın.

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

Yapılandırma dosyalarını ayarlama

Bu aracı Confluence'e erişebilmesi için bu projeye ek yapılandırma ayarları eklememiz gerekiyor.

qa_test_planner/.env dosyasını açın ve aşağıdaki ortam değişkeni değerlerini bu dosyaya ekleyin. Sonuçta elde edilen .env dosyasının aşağıdaki gibi göründüğünden emin olun.

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}

Maalesef bu Confluence alanı herkese açık hale getirilemiyor. Bu nedenle, yukarıdaki kimlik bilgilerini kullanarak erişebileceğiniz mevcut Ürün Şartları Belgelerini okumak için bu dosyaları inceleyebilirsiniz.

Kod Açıklaması (Code Explanation)

Bu komut dosyası, aşağıdaki öğeleri başlattığımız aracı başlatma kodumuzu içerir:

  • Kullanılacak modeli gemini-2.5-flash olarak ayarlayın.
  • Stdio üzerinden iletişim kuracak Confluence MCP Araçları'nı ayarlayın.
  • Test planı yazmak ve CSV'yi yapay nesneye aktarmak için write_test_tool özel aracı ayarlayın.
  • Temsilci açıklamasını ve talimatını ayarlama
  • Gemini 2.5 Flash'in düşünme özelliklerini kullanarak nihai yanıtı veya yürütmeyi oluşturmadan önce planlamayı etkinleştirme

Düşünme yetenekleri yerleşik olan Gemini modeliyle desteklenen ve planlayıcı bağımsız değişkenleriyle yapılandırılan aracı, düşünme yeteneklerini gösterebilir ve web arayüzünde de görüntüleyebilir. Bunu yapılandırmak için gereken kod aşağıda gösterilmiştir.

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

...

İşlem yapmadan önce düşünce sürecini görebiliriz.

185371e0e7e5995e.png

Confluence MCP Aracı

ADK'dan MCP sunucusuna bağlanmak için MCPToolSet kullanmamız gerekir. Bu, google.adk.tools.mcp_tool.mcp_toolset modülünden içe aktarılabilir. Aşağıda, burada başlatılacak kod gösterilmektedir ( verimlilik için kısaltılmıştır).

# 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],

...

Bu yapılandırmada, aracı Confluence MCP sunucusunu ayrı bir işlem olarak başlatır ve Studio I/O aracılığıyla bu işlemlerle iletişimi yönetir. Bu akış, aşağıdaki kırmızı kutu içinde işaretlenmiş MCP mimarisi resminde gösterilmektedir.

85d51458405f9217.png

Ayrıca, MCP başlatma komut argümanlarında, kullanılabilen araçları yalnızca confluence_search, confluence_get_page ve confluence_get_page_children araçlarıyla sınırlarız. Bu araçlar, kalite kontrol test aracımızın kullanım alanlarını destekler. Bu codelab eğitiminde, topluluk tarafından katkıda bulunulan Atlassian MCP Server'ı ( daha fazla bilgi için tam belgeleri inceleyin) kullanıyoruz.

Yazma Testi Aracı

Aracı, Confluence MCP Aracı'ndan bağlam aldıktan sonra kullanıcı için gerekli test planını oluşturabilir. Ancak bu test planını içeren bir dosya oluşturmak istiyoruz. Böylece bu dosya saklanabilir ve diğer kişiyle paylaşılabilir. Bunu desteklemek için aşağıda özel aracı write_test_tool sunuyoruz.

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


...

Yukarıda belirtilen işlev, aşağıdaki işlevleri desteklemek için kullanılır:

  1. Üretilen test planının zorunlu alan spesifikasyonlarına uygun olup olmadığını kontrol edin. Pydantic modeli kullanılarak kontrol edilir ve hata oluşursa hata mesajı aracıya geri gönderilir.
  2. Pandas işlevini kullanarak sonucu CSV'ye aktarın.
  3. Oluşturulan dosya, her araç çağrısında erişilebilen ToolContext nesnesi kullanılarak erişilebilen Artifact Service özellikleri kullanılarak yapıt olarak kaydedilir.

Oluşturulan dosyaları yapıt olarak kaydedersek bu dosyalar ADK çalışma zamanında etkinlik olarak işaretlenir ve daha sonra web arayüzünde aracı etkileşiminde gösterilebilir.

57f5ab95f4ae86e7.png

Bu sayede, kullanıcıya verilecek dosya yanıtını aracıdan dinamik olarak ayarlayabiliriz.

4. Aracıyı Test Etme

Şimdi de KSA üzerinden aracıyla iletişim kurmayı deneyelim. Aşağıdaki komutu çalıştırın:

uv run adk run qa_test_planner

Bu arayüzde, temsilciyle sırayla sohbet edebilirsiniz ancak yalnızca metin gönderebilirsiniz.

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:

Temsilciyle CLI üzerinden sohbet edebilmek güzel. Ancak, bununla güzel bir web sohbeti yaparsak daha da iyi olur ve bunu da yapabiliriz. ADK, etkileşim sırasında neler olduğunu incelemek ve etkileşim kurmak için bir geliştirme kullanıcı arayüzü kullanmamıza da olanak tanır. Yerel geliştirme kullanıcı arayüzü sunucusunu başlatmak için aşağıdaki komutu çalıştırın.

uv run adk web --port 8080

Aşağıdaki örneğe benzer bir çıktı oluşturulur. Bu, web arayüzüne erişebileceğimiz anlamına gelir.

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)

Şimdi bunu kontrol etmek için Cloud Shell Düzenleyicinizin üst kısmındaki Web Önizlemesi düğmesini tıklayın ve 8080 bağlantı noktasında önizle'yi seçin.

e7c9f56c2463164.png

Sol üstteki açılır düğmeden ( bizim durumumuzda qa_test_planner olmalıdır) kullanılabilir aracıları seçebileceğiniz ve bot ile etkileşim kurabileceğiniz aşağıdaki web sayfasını görürsünüz. Sol pencerede, temsilci çalışma zamanı sırasında günlük ayrıntılarıyla ilgili birçok bilgi görürsünüz.

8ed90debb774207f.png

Bazı işlemleri deneyelim. Aşağıdaki istemleri kullanarak temsilcilerle sohbet edin:

  • "Lütfen mevcut tüm PRD'leri listeleyin."
  • "Snaprecipe PRD için test planı yaz "

Bazı araçları kullanırken geliştirme kullanıcı arayüzünde neler olduğunu inceleyebilirsiniz.

3469a0785b507be3.png

Aracının size nasıl yanıt verdiğini görün ve test dosyası istemi yaptığımızda test planını CSV dosyası olarak oluşturup oluşturmadığını inceleyin.

94b73fb4d447ad62.png

Artık CSV'nin içeriğini, örneğin Google E-Tablolar'a aktararak kontrol edebilirsiniz.

89e3fc18d6e92d82.png

Tebrikler! Artık yerel olarak çalışan bir Kalite Güvencesi Test Planlayıcı aracınız var. Şimdi de diğer kullanıcıların da kullanabilmesi için bu uygulamayı Cloud Run'a nasıl dağıtabileceğimize bakalım.

5. Cloud Run'a dağıtma

Elbette bu harika uygulamaya her yerden erişmek istiyoruz. Bunu yapmak için bu uygulamayı paketleyip Cloud Run'a dağıtabiliriz. Bu demoda, bu hizmet başkalarının erişebileceği herkese açık bir hizmet olarak sunulacaktır. Ancak bunun en iyi uygulama olmadığını unutmayın.

819179179d974c07.jpeg

Mevcut çalışma dizininizde, uygulamalarımızı Cloud Run'a dağıtmak için gereken tüm dosyalar (agent dizini, Dockerfile ve server.py (ana hizmet komut dosyası)) zaten var. Şimdi dağıtımı yapalım. Cloud Shell terminaline gidin ve mevcut projenin etkin projeniz olarak yapılandırıldığından emin olun. Aksi takdirde, proje kimliğini ayarlamak için gcloud configure komutunu kullanmanız gerekir:

gcloud config set project [PROJECT_ID]

Ardından, aşağıdaki komutu çalıştırarak görüntüyü Cloud Run'a dağıtın.

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 deposu için bir Artifact Registry oluşturmayı onaylamanız istenirse Y yanıtını vermeniz yeterlidir. Bunun bir demo uygulaması olması nedeniyle burada kimliği doğrulanmamış erişime izin verildiğini unutmayın. Kurumsal ve üretim uygulamalarınız için uygun kimlik doğrulama yöntemini kullanmanız önerilir.

Dağıtım tamamlandığında aşağıdakine benzer bir bağlantı alırsınız:

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

URL'ye eriştiğinizde, yerel olarak denediğinizde olduğu gibi web geliştirme kullanıcı arayüzüne girersiniz. Uygulamanızı gizli pencereden veya mobil cihazınızdan kullanmaya devam edebilirsiniz. Bu özellik şu anda kullanılabilir.

Şimdi bu farklı istemleri tekrar deneyelim. Sırayla deneyerek neler olduğuna bakalım:

  • "Can you find PRD related to Mortgage Estimator?" (Mortgage Estimator ile ilgili PRD'yi bulabilir misin?) "
  • "Give me feedback about what can we improve on that" (Bu konuda neleri iyileştirebileceğimizle ilgili geri bildirim ver)
  • "Bunun için test planı yaz"

Ayrıca, aracıyı FastAPI uygulaması olarak çalıştırdığımız için /docs rotasındaki tüm API rotalarını da inceleyebiliriz. Örneğin, URL'ye https://qa-test-planner-agent-*******.us-central1.run.app/docs şeklinde erişirseniz aşağıdaki gibi bir Swagger dokümanı sayfası görürsünüz.

c6f613b7bdc91ef3.png

Kod Açıklaması (Code Explanation)

Şimdi de server.py ile başlayarak dağıtım için hangi dosyaya ihtiyacımız olduğunu inceleyelim.

# 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 işlevini kullanarak aracımızı kolayca bir FastAPI uygulamasına dönüştürebiliriz. Bu işlevde çeşitli işlevler ayarlayabiliriz. Örneğin, oturum hizmetini, yapıt hizmetini veya hatta izleme verilerini buluta yapılandırabiliriz.

İsterseniz uygulama yaşam döngüsünü de buradan ayarlayabilirsiniz. Ardından, Fast API uygulamasını çalıştırmak için uvicorn'u kullanabiliriz.

Ardından, Dockerfile uygulamayı çalıştırmak için gerekli adımları sağlar.

# 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. Zorluk

Şimdi keşif becerilerinizi geliştirme ve parlatma zamanı. PRD inceleme geri bildirimlerinin de bir dosyaya yazılmasını sağlayacak bir araç oluşturabilir misin?

7. Temizleme

Bu codelab'de kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
  2. Proje listesinde silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
  3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.
  4. Alternatif olarak, konsolda Cloud Run'a gidebilir, yeni dağıttığınız hizmeti seçip silebilirsiniz.