Membangun Agen Perencana Pengujian QA menggunakan ADK, MCP, dan Gemini 2.5 Flash dengan Mode Penalaran

1. Pengantar

fd4ad67ab57d9257.png

Potensi penggunaan AI Generatif untuk pembuatan rencana pengujian berasal dari kemampuannya untuk memecahkan dua tantangan terbesar dalam penjaminan kualitas modern: kecepatan dan kelengkapan. Dalam siklus Agile dan DevOps yang serba cepat saat ini, penulisan rencana pengujian mendetail secara manual menjadi hambatan yang signifikan, sehingga menunda seluruh proses pengujian. Agen yang didukung AI Generatif dapat memproses cerita pengguna dan persyaratan teknis untuk menghasilkan rencana pengujian yang menyeluruh dalam hitungan menit, bukan hari, sehingga memastikan proses QA sejalan dengan pengembangan. Selain itu, AI unggul dalam mengidentifikasi skenario kompleks, kasus ekstrem, dan jalur negatif yang mungkin terlewatkan oleh manusia, sehingga menghasilkan cakupan pengujian yang jauh lebih baik dan pengurangan signifikan pada bug yang lolos ke produksi.

Dalam codelab ini, kita akan mempelajari cara membangun agen yang dapat mengambil dokumen persyaratan produk dari Confluence, memberikan masukan yang konstruktif, dan membuat rencana pengujian komprehensif yang dapat diekspor ke file CSV.

Selama mengikuti codelab, Anda akan menggunakan pendekatan langkah demi langkah sebagai berikut:

  1. Siapkan project Google Cloud Anda dan Aktifkan semua API yang diperlukan di project tersebut
  2. Menyiapkan ruang kerja untuk lingkungan coding Anda
  3. Menyiapkan mcp-server lokal untuk Confluence
  4. Menyusun kode sumber, perintah, dan alat agen ADK untuk terhubung ke server MCP
  5. Memahami penggunaan Konteks Alat dan Layanan Artefak
  6. Menguji agen menggunakan UI Pengembangan Web lokal ADK
  7. Mengelola variabel lingkungan dan menyiapkan file yang diperlukan untuk men-deploy aplikasi ke Cloud Run
  8. Men-deploy aplikasi ke Cloud Run

Ringkasan Arsitektur

819179179d974c07.jpeg

Prasyarat

  • Nyaman bekerja dengan Python
  • Pemahaman tentang arsitektur full-stack dasar menggunakan layanan HTTP

Yang akan Anda pelajari

  • Merancang ADK Agent sekaligus memanfaatkan berbagai kemampuannya
  • Penggunaan alat dengan Alat kustom dan MCP
  • Menyiapkan output file menurut agen menggunakan pengelolaan Layanan Artefak
  • Memanfaatkan BuiltInPlanner untuk meningkatkan eksekusi tugas dengan melakukan perencanaan menggunakan kemampuan berpikir Gemini 2.5 Flash
  • Interaksi dan proses debug melalui antarmuka web ADK
  • Men-deploy aplikasi ke Cloud Run menggunakan Dockerfile dan menyediakan variabel lingkungan

Yang Anda butuhkan

  • Browser web Chrome
  • Akun Gmail
  • Project Cloud dengan penagihan diaktifkan
  • (Opsional) Ruang Confluence dengan halaman Dokumen Persyaratan Produk

Codelab ini, yang dirancang untuk developer dari semua level (termasuk pemula), menggunakan Python dalam aplikasi contohnya. Namun, pengetahuan Python tidak diperlukan untuk memahami konsep yang disajikan. Jangan khawatir jika Anda tidak memiliki ruang Confluence, kami akan memberikan kredensial untuk mencoba codelab ini

2. Sebelum memulai

Pilih Project Aktif di Konsol Cloud

Codelab ini mengasumsikan bahwa Anda sudah memiliki project Google Cloud dengan penagihan yang diaktifkan. Jika belum memilikinya, Anda dapat mengikuti petunjuk di bawah untuk memulai.

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

3a29a3ec1306e9b4.png

Menyiapkan Project Cloud di Terminal Cloud Shell

  1. Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.

1829c3759227c19b.png

  1. Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:
gcloud auth list
  1. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.
gcloud config list project
  1. Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:
gcloud config set project <YOUR_PROJECT_ID>

Atau, Anda juga dapat melihat ID PROJECT_ID di konsol

4032c45803813f30.jpeg

Klik project tersebut dan Anda akan melihat semua project dan project ID di sisi kanan

8dc17eb4271de6b5.jpeg

  1. Aktifkan API yang diperlukan melalui perintah yang ditampilkan di bawah. Proses ini mungkin memerlukan waktu beberapa menit, jadi harap bersabar.
gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com

Jika perintah berhasil dieksekusi, Anda akan melihat pesan yang mirip dengan yang ditampilkan di bawah:

Operation "operations/..." finished successfully.

Alternatif untuk perintah gcloud adalah melalui konsol dengan menelusuri setiap produk atau menggunakan link ini.

Jika ada API yang terlewat, Anda dapat mengaktifkannya kapan saja selama pelaksanaan.

Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.

Buka Cloud Shell Editor dan Siapkan Direktori Kerja Aplikasi

Sekarang, kita dapat menyiapkan editor kode untuk melakukan beberapa hal terkait coding. Kita akan menggunakan Cloud Shell Editor untuk melakukannya

  1. Klik tombol Open Editor, yang akan membuka Cloud Shell Editor, kita dapat menulis kode di sini b16d56e4979ec951.png
  2. Pastikan project Cloud Code ditetapkan di pojok kiri bawah (status bar) editor Cloud Shell, seperti yang ditandai dalam gambar di bawah dan ditetapkan ke project Google Cloud aktif tempat Anda mengaktifkan penagihan. Authorize jika diminta. Jika Anda sudah mengikuti perintah sebelumnya, tombol juga dapat mengarah langsung ke project yang Anda aktifkan, bukan tombol login

f5003b9c38b43262.png

  1. Selanjutnya, clone direktori kerja template untuk codelab ini dari GitHub dengan menjalankan perintah berikut. Tindakan ini akan membuat direktori kerja di direktori qa-test-planner-agent
git clone https://github.com/alphinside/qa-test-planner-agent.git qa-test-planner-agent
  1. Setelah itu, buka bagian atas Editor Cloud Shell, lalu klik File->Open Folder, cari direktori username Anda, lalu cari direktori qa-test-planner-agent, lalu klik tombol OK. Tindakan ini akan menjadikan direktori yang dipilih sebagai direktori kerja utama. Dalam contoh ini, nama penggunanya adalah alvinprayuda, sehingga jalur direktori ditampilkan di bawah

2c53696f81d805cc.png

fb321426f3c848b3.png

Sekarang, Cloud Shell Editor Anda akan terlihat seperti ini

9ae344bc522d2a6f.png

Penyiapan Lingkungan

Siapkan Lingkungan Virtual Python

Langkah berikutnya adalah menyiapkan lingkungan pengembangan. Terminal aktif Anda saat ini harus berada di dalam direktori kerja qa-test-planner-agent. Kita akan menggunakan Python 3.12 dalam codelab ini dan kita akan menggunakan pengelola project python uv untuk menyederhanakan kebutuhan pembuatan dan pengelolaan versi python serta lingkungan virtual

  1. Jika Anda belum membuka terminal, buka dengan mengklik Terminal -> New Terminal , atau gunakan Ctrl + Shift + C , yang akan membuka jendela terminal di bagian bawah browser

f8457daf0bed059e.jpeg

  1. Download uv dan instal python 3.12 dengan perintah berikut
curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
  1. Sekarang kita akan melakukan inisialisasi lingkungan virtual menggunakan uv. Jalankan perintah ini
uv sync --frozen

Tindakan ini akan membuat direktori .venv dan menginstal dependensi. Pratinjau cepat di pyproject.toml akan memberi Anda informasi tentang dependensi yang ditampilkan seperti ini

dependencies = [
    "google-adk>=1.5.0",
    "mcp-atlassian>=0.11.9",
    "pandas>=2.3.0",
    "python-dotenv>=1.1.1",
]
  1. Untuk menguji lingkungan virtual, buat file main.py baru dan salin kode berikut
def main():
   print("Hello from qa-test-planner-agent")

if __name__ == "__main__":
   main()
  1. Kemudian, jalankan perintah berikut
uv run main.py

Anda akan mendapatkan output seperti yang ditunjukkan di bawah

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

Ini menunjukkan bahwa project python sedang disiapkan dengan benar.

Sekarang kita dapat melanjutkan ke langkah berikutnya, yaitu membuat agen dan kemudian layanan

3. Membangun Agen menggunakan ADK Google dan Gemini 2.5

Pengantar Struktur Direktori ADK

Mari kita mulai dengan mempelajari apa yang ditawarkan ADK dan cara membangun agen. Dokumentasi lengkap ADK dapat diakses di URL ini . ADK menawarkan banyak utilitas dalam eksekusi perintah CLI-nya. Beberapa di antaranya adalah sebagai berikut :

  • Menyiapkan struktur direktori agen
  • Mencoba interaksi dengan cepat melalui input output CLI
  • Menyiapkan antarmuka web UI pengembangan lokal dengan cepat

Sekarang, mari buat struktur direktori agen menggunakan perintah CLI. Jalankan perintah berikut

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

Perintah ini akan membuat struktur direktori agen berikut di direktori kerja Anda saat ini

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

Jika Anda memeriksa init.py dan agent.py, Anda akan melihat kode ini

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

Membangun Agen Perencana Pengujian QA Kami

Mari kita bangun agen perencana pengujian QA kita. Buka file qa_test_planner/agent.py dan salin kode di bawah yang akan berisi 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,
        )
    ),
)

Menyiapkan File Konfigurasi

Sekarang kita perlu menambahkan penyiapan konfigurasi tambahan untuk project ini, karena agen ini akan memerlukan akses ke Confluence

Buka qa_test_planner/.env dan tambahkan nilai variabel lingkungan berikut ke dalamnya, pastikan file .env yang dihasilkan terlihat seperti ini

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}

Sayangnya, ruang Confluence ini tidak dapat dibuat publik, sehingga Anda dapat memeriksa file ini untuk membaca Dokumen Persyaratan Produk yang tersedia dan akan tersedia menggunakan kredensial di atas.

Penjelasan Kode

Skrip ini berisi inisiasi agen kami yang menginisialisasi hal-hal berikut:

  • Menetapkan model yang akan digunakan ke gemini-2.5-flash
  • Siapkan Alat MCP Confluence yang akan berkomunikasi melalui Stdio
  • Menyiapkan alat kustom write_test_tool untuk menulis rencana pengujian dan mengekspor CSV ke artefak
  • Menyiapkan deskripsi dan petunjuk agen
  • Mengaktifkan perencanaan sebelum membuat respons atau eksekusi akhir menggunakan kemampuan berpikir Gemini 2.5 Flash

Agen itu sendiri, jika didukung oleh model Gemini dengan kemampuan Berpikir bawaan dan dikonfigurasi dengan argumen planner, dapat menunjukkan kemampuan berpikirnya dan ditampilkan di antarmuka web juga. Kode untuk mengonfigurasi ini ditunjukkan di bawah

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

...

Sebelum mengambil tindakan, kita dapat melihat proses berpikirnya

185371e0e7e5995e.png

Alat MCP Confluence

Untuk terhubung ke Server MCP dari ADK, kita perlu menggunakan MCPToolSet yang dapat diimpor dari modul google.adk.tools.mcp_tool.mcp_toolset. Kode yang diinisialisasi di sini ditunjukkan di bawah ( dipangkas untuk efisiensi)

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

...

Dengan konfigurasi ini, agen akan menginisialisasi Server MCP Confluence sebagai proses terpisah dan akan menangani komunikasi dengan proses tersebut melalui I/O Studio. Alur ini diilustrasikan pada gambar arsitektur MCP berikut yang ditandai di dalam kotak merah di bawah.

85d51458405f9217.png

Selain itu, dalam argumen perintah inisialisasi MCP, kami juga membatasi alat yang dapat digunakan hanya untuk alat berikut: confluence_search, confluence_get_page, dan confluence_get_page_children yang mendukung kasus penggunaan agen pengujian QA kami. Kita akan menggunakan Server MCP Atlassian yang dikontribusikan oleh komunitas ( lihat dokumentasi lengkap untuk mengetahui detail selengkapnya) untuk tutorial codelab ini.

Alat Pengujian Penulisan

Setelah menerima konteks dari Alat MCP Confluence, agen dapat membuat rencana pengujian yang diperlukan untuk pengguna. Namun, kita ingin membuat file yang berisi rencana pengujian ini sehingga dapat dipertahankan dan dibagikan kepada orang lain. Untuk mendukung hal ini, kami menyediakan alat kustom write_test_tool di bawah

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


...

Fungsi yang dideklarasikan di atas adalah untuk mendukung fungsi berikut:

  1. Periksa rencana pengujian yang dihasilkan agar sesuai dengan spesifikasi kolom wajib diisi, kami memeriksa menggunakan model Pydantic, dan jika terjadi error, kami akan memberikan pesan error kembali kepada agen
  2. Buang hasil ke CSV menggunakan fungsi pandas
  3. File yang dihasilkan kemudian disimpan sebagai artefak menggunakan kemampuan Layanan Artefak yang dapat diakses menggunakan objek ToolContext yang dapat diakses di setiap panggilan alat

Jika kita menyimpan file yang dihasilkan sebagai artefak, file tersebut akan ditandai sebagai peristiwa di runtime ADK dan dapat ditampilkan dalam interaksi agen nanti di antarmuka Web

57f5ab95f4ae86e7.png

Dengan demikian, kita dapat menyiapkan respons file secara dinamis dari agen, untuk diberikan kepada pengguna.

4. Menguji Agen

Sekarang, coba berkomunikasi dengan agen melalui CLI, jalankan perintah berikut

uv run adk run qa_test_planner

Output akan ditampilkan seperti ini, tempat Anda dapat melakukan percakapan secara bergiliran dengan agen, tetapi Anda hanya dapat mengirim teks melalui antarmuka ini

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:

Anda dapat melakukan chat dengan agen melalui CLI. Namun, akan lebih baik jika kita melakukan chat web yang menyenangkan dengannya dan kita juga bisa melakukannya. ADK juga memungkinkan kita memiliki UI pengembangan untuk berinteraksi dan memeriksa apa yang terjadi selama interaksi. Jalankan perintah berikut untuk memulai server UI pengembangan lokal

uv run adk web --port 8080

Perintah ini akan menghasilkan output seperti contoh berikut, yang berarti kita sudah dapat mengakses antarmuka web

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)

Sekarang, untuk memeriksanya, klik tombol Web Preview di area atas Cloud Shell Editor Anda, lalu pilih Preview on port 8080

e7c9f56c2463164.png

Anda akan melihat halaman web berikut tempat Anda dapat memilih agen yang tersedia di tombol drop-down kiri atas ( dalam kasus ini, agennya adalah qa_test_planner) dan berinteraksi dengan bot. Anda akan melihat banyak informasi tentang detail log selama runtime agen di jendela kiri

8ed90debb774207f.png

Mari kita coba beberapa tindakan. Lakukan chat dengan agen menggunakan perintah berikut:

  • " Please list all available PRDs " (Cantumkan semua PRD yang tersedia)
  • "Tulis rencana pengujian untuk PRD Snaprecipe "

Saat menggunakan beberapa alat, Anda dapat memeriksa apa yang terjadi di UI pengembangan

3469a0785b507be3.png

Lihat cara agen merespons Anda dan juga periksa saat kami meminta file pengujian, agen akan membuat rencana pengujian dalam file CSV sebagai artefak

94b73fb4d447ad62.png

Sekarang, Anda dapat memeriksa konten CSV dengan mengimpornya ke Google Spreadsheet, misalnya

89e3fc18d6e92d82.png

Selamat! Sekarang Anda memiliki agen QA Test Planner yang berfungsi dan berjalan secara lokal. Sekarang, mari kita lihat cara men-deploy-nya ke Cloud Run agar orang lain juga dapat menggunakannya.

5. Men-deploy ke Cloud Run

Sekarang, tentu saja kita ingin mengakses aplikasi luar biasa ini dari mana saja. Untuk melakukannya, kita dapat mengemas aplikasi ini dan men-deploy-nya ke Cloud Run. Untuk tujuan demo ini, layanan ini akan diekspos sebagai layanan publik yang dapat diakses oleh orang lain. Namun, perlu diingat bahwa ini bukan praktik terbaik.

819179179d974c07.jpeg

Di direktori kerja Anda saat ini, kita sudah memiliki semua file yang diperlukan untuk men-deploy aplikasi ke Cloud Run - direktori agen, Dockerfile, dan server.py (skrip layanan utama), mari kita deploy. Buka Terminal Cloud Shell dan pastikan project saat ini dikonfigurasi ke project aktif Anda. Jika tidak, Anda harus menggunakan perintah gcloud configure untuk menyetel project ID:

gcloud config set project [PROJECT_ID]

Kemudian, jalankan perintah berikut untuk men-deploy-nya ke 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

Jika Anda diminta untuk mengonfirmasi pembuatan repositori Docker Artifact Registry, cukup jawab Y. Perhatikan bahwa kami mengizinkan akses tanpa autentikasi di sini karena ini adalah aplikasi demo. Sebaiknya gunakan autentikasi yang sesuai untuk aplikasi produksi dan perusahaan Anda.

Setelah deployment selesai, Anda akan mendapatkan link yang mirip dengan di bawah ini:

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

Saat mengakses URL, Anda akan masuk ke UI pengembangan web yang serupa dengan saat Anda mencobanya secara lokal. Lanjutkan penggunaan aplikasi Anda dari jendela Samaran atau perangkat seluler Anda. Fitur ini seharusnya sudah aktif.

Sekarang, coba lagi perintah yang berbeda ini - secara berurutan, lihat apa yang terjadi:

  • " Bisakah Anda menemukan PRD terkait Estimator Hipotek? "
  • " Beri saya masukan tentang apa yang dapat kami tingkatkan"
  • "Tulis rencana pengujiannya"

Selain itu, saat menjalankan agen sebagai aplikasi FastAPI, kita juga dapat memeriksa semua rute API di rute /docs. Misalnya, jika Anda mengakses URL seperti ini https://qa-test-planner-agent-*******.us-central1.run.app/docs, Anda akan melihat halaman dokumentasi Swagger seperti yang ditunjukkan di bawah

c6f613b7bdc91ef3.png

Penjelasan Kode

Sekarang, mari kita periksa file apa yang kita butuhkan di sini untuk deployment, dimulai dengan 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)

Kita dapat dengan mudah mengonversi agen menjadi aplikasi fastapi menggunakan fungsi get_fast_api_app. Dalam fungsi ini, kita dapat menyiapkan berbagai fungsi, misalnya mengonfigurasi layanan sesi, layanan artefak, atau bahkan melacak data ke cloud.

Jika mau, Anda juga dapat menyetel siklus proses aplikasi di sini. Setelah itu, kita dapat menggunakan uvicorn untuk menjalankan aplikasi Fast API

Setelah itu, Dockerfile akan memberi kita langkah-langkah yang diperlukan untuk menjalankan aplikasi

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

Sekarang saatnya Anda bersinar dan mengasah keterampilan eksplorasi. Dapatkah Anda juga membuat alat agar masukan ulasan PRD juga ditulis ke file?

7. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud, buka halaman Manage resources.
  2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
  3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.
  4. Atau, Anda dapat membuka Cloud Run di konsol, memilih layanan yang baru saja Anda deploy, lalu menghapusnya.