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

1. Giriş

782957a0266b13f6.png

Test planı oluşturmak için üretken yapay zekayı kullanmanın potansiyeli, modern kalite kontrolündeki en büyük iki zorluğu (hız ve kapsam) çözme yeteneğinden kaynaklanır. Günümüzün hızlı Agile ve DevOps döngülerinde ayrıntılı test planlarının manuel olarak oluşturulması, tüm test sürecini geciktiren önemli bir darboğazdır. Üretken yapay zeka destekli bir ajan, 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 sayede test kapsamı büyük ölçüde iyileşir ve üretime geçişte gözden kaçan hataların sayısı önemli ölçüde azalır.

Bu codelab'de, Confluence'ten ürün gereksinimleri dokümanlarını alabilen, yapıcı geri bildirim verebilen ve CSV dosyasına aktarılabilen kapsamlı bir test planı oluşturabilen bir aracı oluşturmayı ele alacağız.

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. ADK aracısı kaynak kodunu, istemini ve MCP sunucusuna bağlanmak için kullanılan araçları 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 temsilciyi 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ış

af793beb2740233.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 dosya çıkışını aracıya göre ayarlama
  • Gemini 2.5 Flash'in düşünme özellikleriyle planlama yaparak görev yürütmeyi 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'in örnek uygulamasında 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ılı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. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

66ddfbce2eeba53e.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ında Cloud Shell'i etkinleştir'i tıklayın.

26f20e837ff06119.png

  1. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list
  1. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak 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.

bb98435b79995b15.jpeg

Bu seçeneği tıkladığınızda sağ tarafta tüm projeniz ve proje kimliği gösterilir.

ffa73dee57de5307.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 konsol üzerinden de işlem yapabilirsiniz.

Eksik bir API varsa 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. Open Editor (Düzenleyiciyi Aç) düğmesini tıklayın. Bu işlemle Cloud Shell Editor açılır. Kodumuzu buraya yazabiliriz. 168eacea651b086c.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 tıklayın. Önceki komutu zaten uyguladıysanız düğme, oturum açma düğmesi yerine doğrudan etkinleştirilmiş projenize de yönlendirebilir.

613a4889dbcade3d.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.

c87d2b76896d0c59.pngefd32490d592dbb9.png

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

a1a380fb20ce3308.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 ve Python sürümü ile 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 kısayolunu kullanın. Bu kısayol, tarayıcının alt kısmında bir terminal penceresi açar.

8635b60ae2f45bbc.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ıyı, ardından hizmetleri oluşturma

3. Google ADK ve Gemini 2.5'i kullanarak ajan 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 tam dokümanına bu URL'den erişebilirsiniz . ADK, KSA komut yürütme özelliğiyle birçok yardımcı program sunar. Bunlardan bazıları şunlardır :

  • Ajan 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 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 temsilci dizin yapısını oluşturur.

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

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

Kalite Güvencesi Test Planlayıcı Aracımızı Oluşturma

Kalite kontrol test 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 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ı Dokümanlarını okumak için bu dosyaları inceleyebilirsiniz.

Kod Açıklaması

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.
  • Aracı 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

Ajanın kendisi, yerleşik düşünme özelliklerine sahip Gemini modeli tarafından desteklendiğinde ve planlayıcı argümanlarıyla yapılandırıldığında düşünme özelliklerini gösterebilir ve web arayüzünde de görüntülenebilir. 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üşünme sürecini görebiliriz.

7de7004af0fc8c90.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 bu işlemlerle iletişimi Studio I/O üzerinden gerçekleştirir. Bu akış, aşağıdaki kırmızı kutu içinde işaretlenmiş MCP mimarisi resminde gösterilmektedir.

8d8d8fd8e23d3c82.png

Ayrıca, MCP başlatma komut bağımsız değişkenlerinde, kullanılabilen araçları yalnızca confluence_search, confluence_get_page ve confluence_get_page_children araçlarıyla sınırlandırıyoruz. 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 sunucusu ( daha fazla bilgi için tam belgelere bakın) kullanılmaktadır.

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 kullanıcılarla 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 aktarma
  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.

adafec781450c89a.png

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

4. Aracıyı Test Etme

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

uv run adk run qa_test_planner

Bu arayüzde, sırayla ajanla sohbet edebilirsiniz. Ancak bu arayüz üzerinden 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:

Ajanla CLI üzerinden sohbet edebilmek güzel. Ancak, bununla güzel bir web sohbeti yapabilirsek 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 çıkış oluşturur. Bu, web arayüzüne erişebildiğ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 numaralı bağlantı noktasında önizle'yi seçin.

edc73e971b9fc60c.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.

940b1e0391db4871.png

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

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

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

35a3c928bd9dfb87.png

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

183558cb042cb021.png

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

78933239b66eddb2.png

Tebrikler! Artık yerel olarak çalışan bir QA Test Planlayıcı aracınız var. Şimdi de diğer kullanıcıların da kullanabilmesi için bu hizmeti 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, söz konusu 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.

af793beb2740233.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 mevcut. Şimdi dağıtımı yapalım. Cloud Shell Terminali'ne gidin ve mevcut projenin etkin projenize göre yapılandırıldığından emin olun. Yapılandırılmamışsa proje kimliğini ayarlamak için gcloud configure komutunu kullanmanız gerekir:

gcloud config set project [PROJECT_ID]

Ardından, Cloud Run'a dağıtmak için aşağıdaki komutu çalıştırı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ı verin. 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ğunu görelim:

  • "Can you find PRD related to Mortgage Estimator?" (Mortgage Estimator ile ilgili PRD'yi bulabilir misin?) "
  • "Bu konuda neleri iyileştirebileceğimizle ilgili geri bildirim ver"
  • "Bunun için test planı yaz"

Ayrıca, aracı 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.

82d2d91fb3cb2dde.png

Kod Açıklaması

Ş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, yapay nesne 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 misiniz?

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.