1. Giới thiệu
Tiềm năng của việc sử dụng AI tạo sinh để tạo kế hoạch kiểm thử xuất phát từ khả năng giải quyết 2 thách thức lớn nhất trong hoạt động đảm bảo chất lượng hiện đại: tốc độ và tính toàn diện. Trong các chu kỳ Agile và DevOps nhanh chóng hiện nay, việc soạn thảo thủ công các kế hoạch kiểm thử chi tiết là một điểm tắc nghẽn đáng kể, làm chậm toàn bộ quy trình kiểm thử. Một tác nhân dựa trên AI tạo sinh có thể tiếp nhận các câu chuyện người dùng và yêu cầu kỹ thuật để tạo ra một kế hoạch kiểm thử kỹ lưỡng trong vài phút thay vì vài ngày, đảm bảo quy trình kiểm thử chất lượng (QA) theo kịp quá trình phát triển. Hơn nữa, AI có khả năng xác định các tình huống phức tạp, trường hợp đặc biệt và đường dẫn tiêu cực mà con người có thể bỏ qua, dẫn đến việc cải thiện đáng kể phạm vi kiểm thử và giảm đáng kể số lượng lỗi phát sinh trong quá trình sản xuất.
Trong lớp học lập trình này, chúng ta sẽ khám phá cách tạo một tác nhân như vậy. Tác nhân này có thể truy xuất tài liệu về yêu cầu đối với sản phẩm từ Confluence, có khả năng đưa ra ý kiến phản hồi mang tính xây dựng và cũng có thể tạo một kế hoạch kiểm thử toàn diện có thể xuất ra tệp CSV.
Trong lớp học lập trình này, bạn sẽ sử dụng phương pháp từng bước như sau:
- Chuẩn bị dự án Google Cloud và Bật tất cả API bắt buộc trên dự án đó
- Thiết lập không gian làm việc cho môi trường lập trình
- Chuẩn bị mcp-server cục bộ cho Confluence
- Cấu trúc mã nguồn, lời nhắc và các công cụ của tác nhân ADK để kết nối với máy chủ MCP
- Tìm hiểu mức sử dụng Dịch vụ cấu phần phần mềm và Ngữ cảnh công cụ
- Kiểm thử tác nhân bằng giao diện người dùng phát triển web cục bộ của ADK
- Quản lý các biến môi trường và thiết lập các tệp bắt buộc cần thiết để triển khai ứng dụng vào Cloud Run
- Triển khai ứng dụng lên Cloud Run
Tổng quan về cấu trúc
Điều kiện tiên quyết
- Thoải mái làm việc với Python
- Hiểu biết về cấu trúc cơ bản của ngăn xếp đầy đủ bằng cách sử dụng dịch vụ HTTP
Kiến thức bạn sẽ học được
- Thiết kế ADK Agent trong khi tận dụng một số chức năng của ADK Agent
- Sử dụng công cụ với Công cụ tuỳ chỉnh và MCP
- Thiết lập đầu ra tệp theo tác nhân bằng cách sử dụng tính năng quản lý Dịch vụ tạo tác
- Sử dụng BuiltInPlanner để cải thiện việc thực thi tác vụ bằng cách lập kế hoạch với khả năng tư duy của Gemini 2.5 Flash
- Tương tác và gỡ lỗi thông qua giao diện web ADK
- Triển khai ứng dụng lên Cloud Run bằng Dockerfile và cung cấp các biến môi trường
Bạn cần có
- Trình duyệt web Chrome
- Tài khoản Gmail
- Một Dự án trên đám mây đã bật tính năng thanh toán
- (Không bắt buộc) Confluence Space có(các) trang Tài liệu về yêu cầu đối với sản phẩm
Lớp học lập trình này được thiết kế cho nhà phát triển ở mọi cấp độ (kể cả người mới bắt đầu), sử dụng Python trong ứng dụng mẫu. Tuy nhiên, bạn không cần có kiến thức về Python để hiểu các khái niệm được trình bày. Đừng lo lắng về không gian Confluence nếu bạn không có, chúng tôi sẽ cung cấp thông tin đăng nhập để bạn thử lớp học lập trình này
2. Trước khi bắt đầu
Chọn dự án đang hoạt động trong Cloud Console
Lớp học lập trình này giả định rằng bạn đã có một dự án trên Google Cloud đã bật tính năng thanh toán. Nếu chưa có, bạn có thể làm theo hướng dẫn bên dưới để bắt đầu.
- Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
- Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.
Thiết lập dự án trên Cloud trong thiết bị đầu cuối Cloud Shell
- Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud. Nhấp vào biểu tượng Kích hoạt Cloud Shell ở đầu bảng điều khiển Google Cloud.
- Sau khi kết nối với Cloud Shell, bạn có thể kiểm tra để đảm bảo rằng bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:
gcloud auth list
- Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.
gcloud config list project
- Nếu bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:
gcloud config set project <YOUR_PROJECT_ID>
Ngoài ra, bạn cũng có thể xem mã PROJECT_ID trong bảng điều khiển
Nhấp vào đó, bạn sẽ thấy tất cả dự án và mã dự án ở bên phải
- Bật các API bắt buộc thông qua lệnh bên dưới. Quá trình này có thể mất vài phút, vì vậy, vui lòng kiên nhẫn chờ đợi.
gcloud services enable aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com
Khi thực thi lệnh thành công, bạn sẽ thấy một thông báo tương tự như thông báo dưới đây:
Operation "operations/..." finished successfully.
Bạn có thể thay thế lệnh gcloud bằng cách tìm kiếm từng sản phẩm trên bảng điều khiển hoặc sử dụng đường liên kết này.
Nếu bỏ lỡ API nào, bạn luôn có thể bật API đó trong quá trình triển khai.
Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.
Chuyển đến Cloud Shell Editor và thiết lập thư mục làm việc của ứng dụng
Bây giờ, chúng ta có thể thiết lập trình chỉnh sửa mã để thực hiện một số việc liên quan đến mã hoá. Chúng ta sẽ sử dụng Trình chỉnh sửa Cloud Shell cho việc này
- Nhấp vào nút Open Editor (Mở trình chỉnh sửa). Thao tác này sẽ mở Cloud Shell Editor. Chúng ta có thể viết mã tại đây
- Đảm bảo dự án Cloud Code được đặt ở góc dưới bên trái (thanh trạng thái) của trình chỉnh sửa Cloud Shell, như được đánh dấu trong hình bên dưới và được đặt thành dự án Google Cloud đang hoạt động mà bạn đã bật tính năng thanh toán. Uỷ quyền nếu được nhắc. Nếu bạn đã làm theo lệnh trước đó, nút này cũng có thể trỏ trực tiếp đến dự án đã kích hoạt của bạn thay vì nút đăng nhập
- Tiếp theo, hãy sao chép thư mục làm việc của mẫu cho lớp học lập trình này từ GitHub bằng cách chạy lệnh sau. Thao tác này sẽ tạo thư mục đang hoạt động trong thư mục qa-test-planner-agent
git clone https://github.com/alphinside/qa-test-planner-agent.git qa-test-planner-agent
- Sau đó, hãy chuyển đến phần trên cùng của Cloud Shell Editor rồi nhấp vào File->Open Folder (Tệp->Mở thư mục), tìm thư mục username (tên người dùng) của bạn, sau đó tìm thư mục qa-test-planner-agent rồi nhấp vào nút OK. Thao tác này sẽ đặt thư mục đã chọn làm thư mục làm việc chính. Trong ví dụ này, tên người dùng là alvinprayuda, do đó, đường dẫn thư mục được hiển thị bên dưới
Giờ đây, Cloud Shell Editor sẽ có dạng như sau
Thiết lập môi trường
Chuẩn bị môi trường ảo Python
Bước tiếp theo là chuẩn bị môi trường phát triển. Thiết bị đầu cuối đang hoạt động hiện tại của bạn phải nằm trong thư mục làm việc qa-test-planner-agent. Chúng ta sẽ sử dụng Python 3.12 trong lớp học lập trình này và sử dụng trình quản lý dự án uv python để đơn giản hoá nhu cầu tạo và quản lý phiên bản Python cũng như môi trường ảo
- Nếu bạn chưa mở cửa sổ dòng lệnh, hãy mở bằng cách nhấp vào Terminal (Cửa sổ dòng lệnh) -> New Terminal (Cửa sổ dòng lệnh mới) hoặc sử dụng tổ hợp phím Ctrl + Shift + C. Thao tác này sẽ mở một cửa sổ dòng lệnh ở phần dưới cùng của trình duyệt
- Tải
uvxuống và cài đặt python 3.12 bằng lệnh sau
curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
- Bây giờ, hãy khởi động môi trường ảo bằng
uv, chạy lệnh này
uv sync --frozen
Thao tác này sẽ tạo thư mục .venv và cài đặt các phần phụ thuộc. Xem nhanh pyproject.toml sẽ cung cấp cho bạn thông tin về các phần phụ thuộc xuất hiện như sau
dependencies = [
"google-adk>=1.5.0",
"mcp-atlassian>=0.11.9",
"pandas>=2.3.0",
"python-dotenv>=1.1.1",
]
- Để kiểm thử môi trường ảo, hãy tạo tệp mới main.py rồi sao chép mã sau
def main():
print("Hello from qa-test-planner-agent")
if __name__ == "__main__":
main()
- Sau đó, hãy chạy lệnh sau
uv run main.py
Bạn sẽ nhận được kết quả đầu ra như bên dưới
Using CPython 3.12 Creating virtual environment at: .venv Hello from qa-test-planner-agent!
Điều này cho thấy dự án Python đang được thiết lập đúng cách.
Giờ đây, chúng ta có thể chuyển sang bước tiếp theo, đó là tạo tác nhân rồi đến các dịch vụ
3. Xây dựng Đặc vụ bằng Google ADK và Gemini 2.5
Giới thiệu về cấu trúc thư mục ADK
Hãy bắt đầu bằng cách khám phá những tính năng mà ADK cung cấp và cách tạo tác nhân. Bạn có thể truy cập vào tài liệu đầy đủ về ADK tại URL này . ADK cung cấp cho chúng ta nhiều tiện ích trong quá trình thực thi lệnh CLI. Sau đây là một số ví dụ :
- Thiết lập cấu trúc thư mục tác nhân
- Nhanh chóng thử tương tác thông qua đầu vào và đầu ra của CLI
- Thiết lập nhanh giao diện web của giao diện người dùng phát triển cục bộ
Bây giờ, hãy tạo cấu trúc thư mục tác nhân bằng lệnh CLI. Chạy lệnh sau
uv run adk create qa_test_planner \
--model gemini-2.5-flash \
--project {your-project-id} \
--region global
Thao tác này sẽ tạo cấu trúc thư mục tác nhân sau đây trong thư mục đang làm việc hiện tại
qa_test_planner/ ├── __init__.py ├── .env ├── agent.py
Nếu kiểm tra init.py và agent.py, bạn sẽ thấy mã này
# __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',
)
Xây dựng tác nhân lập kế hoạch kiểm thử đảm bảo chất lượng
Hãy tạo nhân viên lập kế hoạch kiểm thử đảm bảo chất lượng! Mở tệp qa_test_planner/agent.py rồi sao chép đoạn mã bên dưới. Đoạn mã này sẽ chứa 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,
)
),
)
Thiết lập tệp cấu hình
Bây giờ, chúng ta cần thêm chế độ thiết lập cấu hình bổ sung cho dự án này, vì tác nhân này sẽ cần có quyền truy cập vào Confluence
Mở qa_test_planner/.env và các giá trị biến môi trường sau đây, đảm bảo rằng tệp .env thu được sẽ có dạng như sau
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}
Rất tiếc, không gian Confluence này không thể công khai. Do đó, bạn có thể kiểm tra các tệp này để đọc Tài liệu yêu cầu về sản phẩm hiện có bằng thông tin đăng nhập ở trên.
Giải thích mã
Tập lệnh này chứa phần khởi tạo nhân viên hỗ trợ, trong đó chúng ta khởi tạo những điều sau:
- Đặt mô hình sẽ dùng thành
gemini-2.5-flash - Thiết lập Confluence MCP Tools sẽ giao tiếp thông qua Stdio
- Thiết lập công cụ tuỳ chỉnh
write_test_toolđể viết kế hoạch kiểm thử và kết xuất tệp csv vào cấu phần phần mềm - Thiết lập nội dung mô tả và hướng dẫn về tác nhân
- Cho phép lập kế hoạch trước khi tạo câu trả lời hoặc thực thi cuối cùng bằng cách sử dụng khả năng tư duy của Gemini 2.5 Flash
Bản thân tác nhân, khi được hỗ trợ bởi mô hình Gemini có sẵn các chức năng Tư duy và được định cấu hình bằng các đối số planner, cũng có thể cho thấy các chức năng tư duy và hiển thị trên giao diện web. Mã để định cấu hình việc này được trình bày bên dưới
# 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,
)
),
...
Và trước khi thực hiện hành động, chúng ta có thể thấy quy trình suy nghĩ của nó
Công cụ MCP của Confluence
Để kết nối với MCP Server từ ADK, chúng ta cần sử dụng MCPToolSet có thể được nhập từ mô-đun google.adk.tools.mcp_tool.mcp_toolset. Đoạn mã để khởi chạy tại đây như bên dưới ( được rút gọn để tăng hiệu quả)
# 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],
...
Với cấu hình này, tác nhân sẽ khởi động Confluence MCP Server dưới dạng một quy trình riêng biệt và xử lý giao tiếp với các quy trình đó thông qua Studio I/O. Quy trình này được minh hoạ trong hình ảnh cấu trúc MCP sau đây, được đánh dấu bên trong hộp màu đỏ bên dưới.
Ngoài ra, trong các đối số lệnh của quá trình khởi tạo MCP, chúng tôi cũng giới hạn những công cụ có thể được sử dụng chỉ cho các công cụ sau: confluence_search,confluence_get_page và confluence_get_page_children để hỗ trợ các trường hợp sử dụng của tác nhân kiểm thử QA. Chúng tôi sử dụng Atlassian MCP Server do cộng đồng đóng góp ( xem tài liệu đầy đủ để biết thêm thông tin chi tiết) cho hướng dẫn trong lớp học lập trình này.
Công cụ viết bài kiểm thử
Sau khi nhận được bối cảnh từ Công cụ MCP của Confluence, tác nhân có thể xây dựng kế hoạch kiểm thử cần thiết cho người dùng. Tuy nhiên, chúng ta muốn tạo một tệp chứa kế hoạch kiểm thử này để có thể lưu giữ và chia sẻ với người khác. Để hỗ trợ việc này, chúng tôi cung cấp công cụ tuỳ chỉnh write_test_tool bên dưới
# 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)}",
}
...
Hàm được khai báo ở trên là để hỗ trợ các chức năng sau:
- Kiểm tra kế hoạch kiểm thử đã tạo để đảm bảo kế hoạch đó tuân thủ các quy cách bắt buộc về trường, chúng tôi kiểm tra bằng mô hình Pydantic và nếu xảy ra lỗi, chúng tôi sẽ gửi thông báo lỗi lại cho tác nhân
- Kết xuất kết quả sang CSV bằng chức năng của pandas
- Sau đó, tệp được tạo sẽ được lưu dưới dạng cấu phần phần mềm bằng cách sử dụng các chức năng của Dịch vụ cấu phần phần mềm. Bạn có thể truy cập vào dịch vụ này bằng đối tượng ToolContext mà bạn có thể truy cập trong mọi lệnh gọi công cụ
Nếu chúng ta lưu các tệp đã tạo dưới dạng cấu phần phần mềm, thì tệp đó sẽ được đánh dấu là sự kiện trong thời gian chạy ADK và có thể hiển thị trong hoạt động tương tác của tác nhân sau này trên giao diện Web
Với tính năng này, chúng ta có thể thiết lập phản hồi tệp một cách linh hoạt từ tác nhân để cung cấp cho người dùng.
4. Kiểm thử tác nhân
Bây giờ, hãy thử giao tiếp với tác nhân thông qua CLI bằng cách chạy lệnh sau
uv run adk run qa_test_planner
Công cụ này sẽ cho ra kết quả như thế này, trong đó bạn có thể trò chuyện lần lượt với trợ lý ảo, tuy nhiên, bạn chỉ có thể gửi văn bản thông qua giao diện này
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:
Thật tuyệt khi có thể trò chuyện với nhân viên hỗ trợ thông qua CLI. Nhưng sẽ tốt hơn nữa nếu chúng ta có một cuộc trò chuyện trực tuyến thú vị với nó và chúng ta cũng có thể làm điều đó! ADK cũng cho phép chúng ta có một giao diện người dùng phát triển để tương tác và kiểm tra những gì đang diễn ra trong quá trình tương tác. Chạy lệnh sau để khởi động máy chủ giao diện người dùng phát triển cục bộ
uv run adk web --port 8080
Lệnh này sẽ tạo ra kết quả như ví dụ sau, tức là chúng ta đã có thể truy cập vào giao diện 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)
Bây giờ, để kiểm tra, hãy nhấp vào nút Web Preview (Xem trước trên web) ở khu vực trên cùng của Cloud Shell Editor rồi chọn Preview on port 8080 (Xem trước trên cổng 8080)
Bạn sẽ thấy trang web sau đây, nơi bạn có thể chọn các tác nhân có sẵn trên nút thả xuống ở trên cùng bên trái ( trong trường hợp của chúng tôi, đó phải là qa_test_planner) và tương tác với bot. Bạn sẽ thấy nhiều thông tin về chi tiết nhật ký trong thời gian chạy của tác nhân ở cửa sổ bên trái
Hãy thử một số thao tác! Trò chuyện với các nhân viên hỗ trợ bằng những câu lệnh sau:
- " Vui lòng liệt kê tất cả các PRD hiện có "
- " Viết kế hoạch kiểm thử cho PRD của Snaprecipe "
Khi sử dụng một số công cụ, bạn có thể kiểm tra những gì đang diễn ra trong giao diện người dùng phát triển
Xem cách tác nhân phản hồi bạn, đồng thời kiểm tra thời điểm chúng tôi nhắc bạn về tệp kiểm thử. Tệp này sẽ tạo kế hoạch kiểm thử dưới dạng tệp CSV.
Giờ đây, bạn có thể kiểm tra nội dung của tệp CSV bằng cách nhập tệp đó vào Google Trang tính chẳng hạn
Xin chúc mừng! Giờ đây, bạn đã có một tác nhân Lập kế hoạch kiểm thử QA đang hoạt động trên thiết bị của mình! Bây giờ, hãy xem cách triển khai ứng dụng này lên Cloud Run để những người khác cũng có thể sử dụng!
5. Triển khai lên Cloud Run
Tất nhiên, chúng ta muốn truy cập vào ứng dụng tuyệt vời này ở mọi nơi. Để làm như vậy, chúng ta có thể đóng gói ứng dụng này và triển khai ứng dụng đó vào Cloud Run. Để minh hoạ, dịch vụ này sẽ được cung cấp dưới dạng một dịch vụ công khai mà người khác có thể truy cập. Tuy nhiên, hãy lưu ý rằng đây không phải là phương pháp hay nhất!
Tại thư mục làm việc hiện tại, chúng ta đã có tất cả các tệp cần thiết để triển khai các ứng dụng của mình lên Cloud Run – thư mục tác nhân, Dockerfile và server.py (tập lệnh dịch vụ chính), hãy triển khai ứng dụng này. Chuyển đến Cloud Shell Terminal và đảm bảo dự án hiện tại được định cấu hình cho dự án đang hoạt động của bạn. Nếu không, bạn phải dùng lệnh gcloud configure để đặt mã dự án:
gcloud config set project [PROJECT_ID]
Sau đó, hãy chạy lệnh sau để triển khai ứng dụng này vào 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
Nếu bạn được nhắc xác nhận việc tạo một sổ đăng ký hiện vật cho kho lưu trữ docker, chỉ cần trả lời Y. Xin lưu ý rằng chúng tôi đang cho phép truy cập chưa xác thực tại đây vì đây là một ứng dụng minh hoạ. Bạn nên sử dụng phương thức xác thực phù hợp cho các ứng dụng doanh nghiệp và ứng dụng phát hành công khai.
Sau khi quá trình triển khai hoàn tất, bạn sẽ nhận được một đường liên kết tương tự như đường liên kết bên dưới:
https://qa-test-planner-agent-*******.us-central1.run.app
Khi truy cập vào URL này, bạn sẽ thấy giao diện người dùng dành cho nhà phát triển web tương tự như khi bạn thử nghiệm cục bộ. Hãy tiếp tục sử dụng ứng dụng của bạn trong cửa sổ Ẩn danh hoặc trên thiết bị di động. Nội dung đó đã được xuất bản.
Bây giờ, hãy thử lại các câu lệnh này theo trình tự để xem điều gì sẽ xảy ra:
- " Bạn có thể tìm PRD liên quan đến Công cụ ước tính thế chấp không? "
- " Give me feedback about what can we improve on that"
- "Viết kế hoạch kiểm thử cho nó"
Ngoài ra, khi chạy tác nhân dưới dạng một ứng dụng FastAPI, chúng ta cũng có thể kiểm tra tất cả các tuyến API trong tuyến /docs. Ví dụ: nếu truy cập vào URL như thế này https://qa-test-planner-agent-*******.us-central1.run.app/docs, bạn sẽ thấy trang tài liệu Swagger như minh hoạ bên dưới
Giải thích mã
Giờ đây, hãy kiểm tra xem chúng ta cần tệp nào ở đây để triển khai, bắt đầu bằng 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)
Chúng ta có thể dễ dàng chuyển đổi tác nhân thành một ứng dụng fastapi bằng hàm get_fast_api_app. Trong hàm này, chúng ta có thể thiết lập nhiều chức năng, chẳng hạn như định cấu hình dịch vụ phiên, dịch vụ cấu phần phần mềm hoặc thậm chí là theo dõi dữ liệu lên đám mây.
Nếu muốn, bạn cũng có thể thiết lập vòng đời ứng dụng tại đây. Sau đó, chúng ta có thể dùng uvicorn để chạy ứng dụng Fast API
Sau đó, Dockerfile sẽ cung cấp cho chúng ta các bước cần thiết để chạy ứng dụng
# 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. Thách thức
Giờ là lúc bạn thể hiện và trau dồi kỹ năng khám phá của mình. Bạn cũng có thể tạo một công cụ để ghi phản hồi đánh giá PRD vào một tệp không?
7. Dọn dẹp
Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được dùng trong lớp học lập trình này, hãy làm theo các bước sau:
- Trong Google Cloud Console, hãy chuyển đến trang Quản lý tài nguyên.
- Trong danh sách dự án, hãy chọn dự án mà bạn muốn xoá, rồi nhấp vào Xoá.
- Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Tắt để xoá dự án.
- Ngoài ra, bạn có thể chuyển đến Cloud Run trên bảng điều khiển, chọn dịch vụ bạn vừa triển khai rồi xoá.