Trải nghiệm giao diện người dùng với ADK và A2UI

1. Tổng quan

Hầu hết các trợ lý ảo AI đều trả lời bằng văn bản. Trong lớp học lập trình này, bạn sẽ sử dụng A2UI để cho phép tác nhân của bạn trả lời bằng giao diện người dùng. Tác nhân mô tả thẻ, danh sách, nút và biểu mẫu ở định dạng JSON, sử dụng danh mục các thành phần tiêu chuẩn và ứng dụng sẽ hiển thị các thành phần đó bằng các tiện ích gốc của riêng mình, nên bố cục mới không cần mã giao diện người dùng mới.

Bạn sẽ xây dựng tác nhân bằng Bộ công cụ phát triển tác nhân (ADK).

Sản phẩm bạn sẽ tạo ra

Một trang tổng quan mô phỏng về cơ sở hạ tầng đám mây theo 3 giai đoạn:

  1. Một tác nhân tiêu chuẩn trả về dữ liệu tài nguyên dưới dạng văn bản thuần tuý
  2. Một tác nhân A2UI trả về cùng dữ liệu dưới dạng JSON A2UI có cấu trúc
  3. Một tác nhân được kết xuất hiển thị JSON A2UI dưới dạng các thành phần giao diện người dùng tương tác trong giao diện người dùng dành cho nhà phát triển ADK

Tác nhân A2UI ADK

Kiến thức bạn sẽ học được

  • Cách A2UI hoạt động: 18 thành phần cơ bản, các thông báo tạo nên giao diện người dùng và mô hình thành phần phẳng
  • Cách sử dụng A2UI SDK để nhắc một tác nhân ADK tạo JSON A2UI
  • Cách kết xuất các thành phần A2UI trong adk web

Bạn cần có

  • Một dự án trên Google Cloud đã bật tính năng thanh toán
  • Một trình duyệt web như Chrome
  • Python 3.12 trở lên và uv, nếu bạn chạy mã trên máy của mình thay vì Cloud Shell

Lớp học lập trình này dành cho các nhà phát triển có trình độ trung cấp và đã quen thuộc với Python và Google Cloud.

Bạn sẽ chỉ mất khoảng 20 phút để hoàn thành lớp học lập trình này.

Các tài nguyên được tạo trong lớp học lập trình này sẽ có chi phí dưới 5 USD.

2. Thiết lập môi trường

Tạo một dự án trên Google Cloud

  1. 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 đám mây của Google Cloud.
  2. Đả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.

Khởi động Trình chỉnh sửa Cloud Shell

Để chạy một phiên Cloud Shell từ Cloud Console, hãy nhấp vào Kích hoạt Cloud Shell trong Cloud Console.

Thao tác này sẽ khởi chạy một phiên trong ngăn dưới cùng của Cloud Console.

Để khởi chạy trình chỉnh sửa, hãy nhấp vào Open Editor (Mở trình chỉnh sửa) trên thanh công cụ của cửa sổ Cloud Shell.

Bật API

Trong thanh công cụ Cloud Shell Editor, hãy nhấp vào Terminal (Cửa sổ dòng lệnh) và New Terminal (Cửa sổ dòng lệnh mới), sau đó chạy lệnh sau để bật các API bắt buộc:

gcloud services enable aiplatform.googleapis.com

Cài đặt các phần phụ thuộc

Trong cửa sổ dòng lệnh, hãy chạy các lệnh sau để tạo một thư mục cho lớp học lập trình này, với một thư mục a2ui_agent bên trong cho mã tác nhân của bạn, đồng thời cài đặt Bộ công cụ phát triển tác nhân (ADK) và SDK A2UI:

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

uv tạo một môi trường Python riêng biệt cho lớp học lập trình này, vì vậy bạn không cần kích hoạt bất cứ thứ gì. Thêm tiền tố uv run vào các lệnh Python.

3. Tạo tác nhân

Bắt đầu bằng một tác nhân ADK tiêu chuẩn trả về văn bản thuần tuý. Đây là giao diện của hầu hết các ứng dụng đại lý hiện nay.

Định cấu hình chế độ cài đặt dự án

Trong cửa sổ dòng lệnh, hãy chạy lệnh sau để tạo a2ui_agent/.env bằng dự án và vị trí của bạn, đồng thời để ADK gọi Gemini thông qua dự án Google Cloud của bạn. ADK sẽ tự động tải tệp này, vì vậy, các chế độ cài đặt cũng hoạt động trong các thiết bị đầu cuối mới.

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

Xác định công cụ và dữ liệu mô phỏng

Tạo a2ui_agent/resources.py có nội dung sau. Công cụ này trả về danh sách các tài nguyên trên đám mây cùng với trạng thái của chúng.

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

Xác định nhân viên hỗ trợ

Tạo a2ui_agent/agent.py có nội dung sau:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. Kiểm thử tác nhân

ADK có một giao diện người dùng dành cho nhà phát triển mà bạn có thể dùng để tương tác và gửi câu lệnh cho tác nhân trong trình duyệt để kiểm thử.

Khởi động giao diện người dùng dành cho nhà phát triển ADK

Trong cửa sổ dòng lệnh của Cloud Shell Editor, hãy chạy lệnh sau để khởi động giao diện người dùng dành cho nhà phát triển ADK:

uv run adk web --port 8080 --allow_origins "*" --reload_agents

Bạn sẽ thấy một thông báo tương tự như sau:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8080.                         |
+-----------------------------------------------------------------------------+

Mở giao diện người dùng dành cho nhà phát triển ADK

Bạn có thể mở giao diện người dùng dành cho nhà phát triển ADK trong trình duyệt bằng cách nhấp vào URL kiểm thử cục bộ bằng tổ hợp phím Ctrl hoặc Cmd, hoặc bằng cách nhấp vào nút Xem trước trên web rồi chọn Xem trước trên cổng 8080.

Sau khi bạn xem giao diện người dùng dành cho nhà phát triển ADK, hãy chọn a2ui_agent trong trình đơn thả xuống.

Gửi câu lệnh mẫu

Gửi một câu lệnh mẫu cho tác nhân:

What's running in my project?

Bây giờ, hãy thử một câu lệnh mẫu khác và bạn sẽ nhận được nhiều văn bản hơn:

Does anything need my attention?

Cuộc trò chuyện của bạn sẽ có dạng như sau:

Nhân viên hỗ trợ bằng tin nhắn ADK

Câu trả lời chính xác nhưng là một khối văn bản khô khan.

5. Tạo JSON A2UI

Tiếp theo, hãy chuyển nhân viên hỗ trợ từ văn bản thuần tuý sang A2UI.

A2UI Python SDK có một trình tạo câu lệnh viết câu lệnh hệ thống cho bạn. Thư viện này dạy cho LLM danh mục thành phần A2UI đầy đủ, tên và loại thuộc tính chính xác cũng như cấu trúc JSON.

Cập nhật tác nhân

Thay thế nội dung của a2ui_agent/agent.py bằng nội dung sau:

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

show_raw_json cho thấy JSON A2UI dưới dạng văn bản để bạn có thể đọc. Sau đó, bạn sẽ xoá nó để xem giao diện người dùng hiển thị.

Phương thức prompt_generator.generate() kết hợp nội dung mô tả vai trò của bạn với giản đồ JSON A2UI đầy đủ và đặt câu lệnh kèm một vài ví dụ, nhờ đó LLM biết chính xác cách định dạng đầu ra. Bạn không cần viết danh mục thành phần theo cách thủ công.

Lớp học lập trình này sử dụng A2UI phiên bản 0.8 (version="0.8"), là phiên bản mà trình kết xuất A2UI adk web hỗ trợ.

6. Kiểm thử đầu ra JSON

Nếu bạn vẫn đang chạy giao diện người dùng dành cho nhà phát triển ADK từ trước đó, thì giao diện này sẽ tự động tải lại những thay đổi mà bạn đã thực hiện đối với tác nhân.

Chọn a2ui_agent, bắt đầu một phiên mới bằng cách nhấp vào +New Session (Phiên mới) ở trên cùng bên phải của giao diện người dùng dành cho nhà phát triển ADK, sau đó gửi cùng một câu lệnh như trước:

What's running in my project?

Lần này, tác nhân sẽ phản hồi bằng JSON A2UI thay vì văn bản thuần tuý. Bạn sẽ thấy các thông báo có cấu trúc như beginRendering và surfaceUpdate (đôi khi là dataModelUpdate) trong đầu ra của cuộc trò chuyện, trong một khối mã JSON.

JSON A2UI ADK

JSON mô tả một giao diện người dùng phong phú với thẻ, biểu tượng và nút, nhưng show_raw_json giữ nguyên nội dung này dưới dạng văn bản để bạn có thể đọc. Tiếp theo, bạn sẽ xem xét cách cấu trúc JSON này, sau đó xoá show_raw_json để hiển thị JSON này dưới dạng các thành phần giao diện người dùng thực tế.

7. Tìm hiểu về A2UI

Xem tệp JSON mà tác nhân vừa tạo. A2UI có 3 loại thông báo để tạo giao diện người dùng. Đầu ra của tác nhân có thể không sử dụng cả 3 thành phần này mỗi lần:

1. beginRendering

Tạo một bề mặt kết xuất và đặt tên cho thành phần gốc:

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

2. surfaceUpdate

Gửi cây thành phần dưới dạng danh sách phẳng có các giá trị tham chiếu mã nhận dạng (không lồng nhau):

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

3. dataModelUpdate

Gửi dữ liệu riêng biệt với cấu trúc:

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

Các thành phần liên kết với dữ liệu bằng {"path": "key"}. Bạn có thể cập nhật dữ liệu mà không cần gửi lại cây thành phần.

18 thành phần cơ bản

Danh mục

Thành phần

Bố cục

Thẻ, Cột, Hàng, Danh sách, Thẻ, Đường phân chia, Phương thức

Hiển thị

Văn bản, Hình ảnh, Biểu tượng, Video, AudioPlayer

Thiết bị đầu vào

TextField, DateTimeInput, MultipleChoice, CheckBox, Slider

Hành động

Nút

Tác nhân tạo nhiều bố cục, chẳng hạn như khung hiển thị duyệt qua, trang tổng quan ưu tiên hoặc biểu mẫu cấu hình, từ chính những thành phần này. Hãy xem tài liệu tham khảo về thành phần để biết thông tin chi tiết về từng thành phần.

8. Kết xuất các thành phần A2UI

SDK này bao bọc A2UI trong các thẻ tiêu chuẩn. adk web nhận dạng các thành phần này và kết xuất chúng bằng trình kết xuất A2UI tích hợp sẵn. Để xem nội dung tải xuống, hãy xoá show_raw_json.

Cập nhật tác nhân

Thay thế nội dung của a2ui_agent/agent.py bằng nội dung sau. Những thay đổi duy nhất so với bước trước là hàm show_raw_json, tham số after_model_callback và 2 lần nhập mà hàm này đã dùng đều biến mất:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

9. Kiểm thử giao diện người dùng được kết xuất

Nếu bạn vẫn đang chạy giao diện người dùng dành cho nhà phát triển ADK từ trước đó, thì giao diện này sẽ tự động tải lại những thay đổi mà bạn đã thực hiện đối với tác nhân.

Làm mới thẻ trình duyệt, chọn a2ui_agent, sau đó bắt đầu một phiên mới bằng cách nhấp vào +New Session (Phiên mới) ở trên cùng bên phải của giao diện người dùng dành cho nhà phát triển ADK và gửi cùng một câu lệnh như trước:

What's running in my project?

Lần này, adk web sẽ kết xuất các thành phần A2UI dưới dạng giao diện người dùng thực tế: thẻ có chỉ báo trạng thái, thông tin chi tiết về tài nguyên và nút hành động.

Tác nhân A2UI ADK

Hãy thử một câu lệnh khác để xem cách tác nhân tạo ra một giao diện người dùng khác từ cùng một nhóm thành phần cơ bản:

Does anything need my attention?

Cuối cùng, hãy thử một câu lệnh khác để tạo một giao diện người dùng khác nhằm triển khai dịch vụ mới:

I need to deploy a new service

Cả ba câu lệnh đều sử dụng cùng một tác nhân, công cụ và thành phần, nhưng mỗi câu lệnh tạo ra một giao diện người dùng khác nhau phù hợp với yêu cầu của bạn.

10. Dọn dẹp

Để tránh để máy chủ cục bộ chạy, hãy dọn dẹp các tài nguyên:

  • Trong dòng lệnh đang chạy adk web, hãy nhấn tổ hợp phím Ctrl+C để dừng máy chủ tác nhân.

Nếu đã tạo một dự án dành riêng cho lớp học lập trình này, bạn có thể xoá toàn bộ dự án:

gcloud projects delete <YOUR_PROJECT_ID>

11. Xin chúc mừng

Bạn đã tạo một tác nhân ADK tạo ra giao diện người dùng phong phú, mang tính tương tác bằng A2UI.

Kiến thức bạn học được

  • A2UI là một giao thức có 18 thành phần khai báo cơ bản và một số thông báo đơn giản để tạo giao diện người dùng
  • A2UI SDK tạo ra các câu lệnh hệ thống giúp LLM tìm hiểu danh mục thành phần
  • Cùng một tác nhân, công cụ và các thành phần cơ bản tạo nên nhiều giao diện người dùng cho nhiều ý định
  • Các thành phần A2UI có thể được kết xuất trực tiếp trong adk web trong quá trình phát triển

Tạo giao diện người dùng sản xuất

Trong lớp học lập trình này, bạn đã kết xuất A2UI bên trong adk web để phát triển và kiểm thử.

Đối với bản phát hành công khai, bạn sẽ tạo một giao diện người dùng bằng một trong các trình kết xuất A2UI chính thức:

Nền tảng

Trình kết xuất đồ hoạ

Cài đặt

Web (React)

@a2ui/react

npm install @a2ui/react

Web (Lit)

@a2ui/lit

npm install @a2ui/lit

Web (Angular)

@a2ui/angular

npm install @a2ui/angular

Thiết bị di động/Máy tính

Flutter GenUI SDK

Bắt đầu

Tài liệu tham khảo

Tiếp theo là gì?

Khám phá các tài nguyên học tập để xây dựng và triển khai các tác nhân cấp doanh nghiệp bằng chương trình Gemini Enterprise Agent Ready (GEAR).