Pengalaman Frontend dengan ADK dan A2UI

1. Ringkasan

Sebagian besar agen AI merespons dengan teks. Dalam codelab ini, Anda akan menggunakan A2UI agar agen Anda membalas dengan antarmuka pengguna. Agen menjelaskan kartu, daftar, tombol, dan formulir dalam JSON, menggunakan katalog komponen standar, dan klien merendernya dengan widget native-nya sendiri, sehingga tata letak baru tidak memerlukan kode frontend baru.

Anda akan membangun agen dengan Agent Development Kit (ADK).

Yang akan Anda build

Dasbor infrastruktur cloud tiruan dalam tiga tahap:

  1. Agen standar yang menampilkan data resource sebagai teks biasa
  2. Agen A2UI yang menampilkan data yang sama dengan JSON A2UI terstruktur
  3. Agen yang dirender yang menampilkan JSON A2UI sebagai komponen UI interaktif di UI dev ADK

Agen A2UI ADK

Yang akan Anda pelajari

  • Cara kerja A2UI: 18 elemen dasar, pesan yang membangun UI, dan model komponen datar
  • Cara menggunakan A2UI SDK untuk meminta agen ADK membuat JSON A2UI
  • Cara merender komponen A2UI di adk web

Yang Anda butuhkan

  • Project Google Cloud yang mengaktifkan penagihan
  • Browser web seperti Chrome
  • Python 3.12+ dan uv, jika Anda menjalankan kode di komputer Anda sendiri, bukan di Cloud Shell

Codelab ini ditujukan bagi developer tingkat menengah yang sudah memahami Python dan Google Cloud.

Codelab ini membutuhkan waktu sekitar 20 menit untuk diselesaikan.

Resource yang dibuat dalam codelab ini seharusnya berbiaya kurang dari $5.

2. Menyiapkan lingkungan Anda

Buat Project Google Cloud

  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.

Mulai Cloud Shell Editor

Untuk meluncurkan sesi Cloud Shell dari konsol Google Cloud, klik Activate Cloud Shell di konsol Google Cloud Anda.

Tindakan ini akan meluncurkan sesi di panel bawah konsol Google Cloud.

Untuk meluncurkan editor, klik Open Editor di toolbar jendela Cloud Shell.

Mengaktifkan API

Di toolbar Cloud Shell Editor, klik Terminal dan New Terminal, lalu jalankan perintah berikut untuk mengaktifkan API yang diperlukan:

gcloud services enable aiplatform.googleapis.com

Menginstal dependensi

Di terminal, jalankan perintah berikut untuk membuat folder untuk codelab ini, dengan folder a2ui_agent di dalamnya untuk kode agen Anda, dan instal Agent Development Kit (ADK) serta A2UI SDK:

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

uv membuat lingkungan Python yang terisolasi untuk codelab ini, jadi Anda tidak perlu mengaktifkan apa pun. Awali perintah Python dengan uv run.

3. Membangun agen

Mulai dengan agen ADK standar yang menampilkan teks biasa. Seperti inilah tampilan sebagian besar aplikasi agen saat ini.

Mengonfigurasi setelan project

Di terminal, jalankan perintah berikut untuk membuat a2ui_agent/.env dengan project dan lokasi Anda, serta agar ADK memanggil Gemini melalui project Google Cloud Anda. ADK memuat file ini secara otomatis, sehingga setelan juga berfungsi di terminal baru.

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

Menentukan alat dan data tiruan

Buat a2ui_agent/resources.py dengan konten berikut. Alat ini menampilkan daftar resource cloud beserta statusnya.

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

Menentukan agen

Buat a2ui_agent/agent.py dengan konten berikut:

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. Menguji agen

ADK menyertakan UI dev yang dapat Anda gunakan untuk berinteraksi dengan dan mengirim perintah ke agen Anda di browser untuk pengujian.

Mulai UI dev ADK

Di terminal Cloud Shell Editor, jalankan perintah berikut untuk memulai UI dev ADK:

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

Anda akan melihat pesan yang mirip dengan yang berikut ini:

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

Membuka UI dev ADK

Anda dapat membuka UI dev ADK di browser dengan mengklik Ctrl atau Cmd pada URL pengujian lokal, atau dengan mengklik tombol Web Preview dan memilih Preview on Port 8080.

Setelah Anda melihat UI dev ADK, pilih a2ui_agent dari menu drop-down.

Mengirim contoh perintah

Kirim perintah contoh ke agen:

What's running in my project?

Sekarang coba perintah contoh lain dan Anda akan mendapatkan lebih banyak output teks:

Does anything need my attention?

Percakapan Anda akan terlihat seperti berikut:

Agen Teks ADK

Jawabannya akurat, tetapi berupa teks panjang.

5. Membuat JSON A2UI

Selanjutnya, alihkan agen dari teks biasa ke A2UI.

A2UI Python SDK menyertakan generator perintah yang menulis perintah sistem untuk Anda. Hal ini mengajarkan LLM katalog komponen A2UI lengkap, nama dan jenis properti yang benar, serta struktur JSON.

Memperbarui agen

Ganti konten a2ui_agent/agent.py dengan konten berikut:

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 menampilkan JSON A2UI sebagai teks sehingga Anda dapat membacanya. Anda akan menghapusnya nanti untuk melihat rendering UI.

Metode prompt_generator.generate() menggabungkan deskripsi peran Anda dengan contoh few-shot dan skema JSON A2UI lengkap, sehingga LLM mengetahui persis cara memformat outputnya. Anda tidak perlu menulis katalog komponen secara manual.

Codelab ini menggunakan A2UI versi 0.8 (version="0.8"), yang merupakan versi yang didukung oleh perender A2UI adk web.

6. Menguji output JSON

Jika Anda masih menjalankan UI dev ADK dari sebelumnya, UI tersebut akan otomatis memuat ulang perubahan yang Anda buat pada agen.

Pilih a2ui_agent, mulai sesi baru dengan mengklik +New Session di kanan atas UI dev ADK, lalu kirim perintah yang sama seperti sebelumnya:

What's running in my project?

Kali ini, agen merespons dengan JSON A2UI, bukan teks biasa. Anda akan melihat pesan terstruktur seperti beginRendering dan surfaceUpdate (dan terkadang dataModelUpdate) dalam output chat, di blok kode JSON.

JSON A2UI ADK

JSON menjelaskan UI yang kaya dengan kartu, ikon, dan tombol, tetapi show_raw_json menyimpannya sebagai teks sehingga Anda dapat membacanya. Selanjutnya, Anda akan melihat struktur JSON ini, lalu menghapus show_raw_json untuk merendernya sebagai komponen UI yang sebenarnya.

7. Memahami A2UI

Lihat JSON yang baru saja dihasilkan agen Anda. A2UI memiliki tiga jenis pesan untuk membangun UI. Output agen Anda mungkin tidak menggunakan ketiganya setiap saat:

1. beginRendering

Membuat platform rendering dan memberi nama komponen root:

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

2. surfaceUpdate

Mengirimkan hierarki komponen sebagai daftar datar dengan referensi ID (tidak bertingkat):

{"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

Mengirim data secara terpisah dari struktur:

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

Komponen terikat ke data menggunakan {"path": "key"}. Anda dapat memperbarui data tanpa mengirim ulang hierarki komponen.

18 primitif

Kategori

Komponen

Tata letak

Kartu, Kolom, Baris, Daftar, Tab, Pemisah, Modal

Display

Teks, Gambar, Ikon, Video, AudioPlayer

Input

TextField, DateTimeInput, MultipleChoice, CheckBox, Slider

Tindakan

Tombol

Agen membuat tata letak yang berbeda, seperti tampilan penjelajahan, dasbor prioritas, atau formulir konfigurasi, dari komponen yang sama ini. Lihat referensi komponen untuk mengetahui detail masing-masing komponen.

8. Merender komponen A2UI

SDK membungkus A2UI dalam tag standar. adk web mengenalinya dan merender komponen dengan perender A2UI bawaannya. Untuk melihatnya, hapus show_raw_json.

Memperbarui agen

Ganti konten a2ui_agent/agent.py dengan konten berikut. Satu-satunya perubahan dari langkah sebelumnya adalah fungsi show_raw_json, parameter after_model_callback, dan dua impor yang digunakannya telah dihapus:

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. Menguji UI yang dirender

Jika Anda masih menjalankan UI dev ADK dari sebelumnya, UI tersebut akan otomatis memuat ulang perubahan yang Anda buat pada agen.

Muat ulang tab browser, pilih a2ui_agent, lalu mulai sesi baru dengan mengklik +New Session di kanan atas UI dev ADK dan kirim perintah yang sama seperti sebelumnya:

What's running in my project?

Kali ini, adk web merender komponen A2UI sebagai UI sebenarnya: kartu dengan indikator status, detail resource, dan tombol tindakan.

Agen A2UI ADK

Coba perintah yang berbeda untuk melihat cara agen menyusun UI yang berbeda dari kumpulan primitif yang sama:

Does anything need my attention?

Terakhir, coba perintah lain untuk membuat UI yang berbeda guna men-deploy layanan baru:

I need to deploy a new service

Ketiga perintah menggunakan agen, alat, dan komponen yang sama, tetapi masing-masing menghasilkan UI yang berbeda yang sesuai dengan permintaan Anda.

10. Pembersihan

Untuk menghindari server lokal tetap berjalan, bersihkan resource:

  • Di terminal yang menjalankan adk web, tekan Ctrl+C untuk menghentikan server agen.

Jika Anda membuat project khusus untuk codelab ini, Anda dapat menghapus seluruh project tersebut:

gcloud projects delete <YOUR_PROJECT_ID>

11. Selamat

Anda telah membangun agen ADK yang menghasilkan UI interaktif yang kaya menggunakan A2UI.

Yang telah Anda pelajari

  • A2UI adalah protokol dengan 18 primitif deklaratif dan beberapa pesan sederhana yang membangun UI
  • A2UI SDK menghasilkan perintah sistem yang mengajarkan katalog komponen kepada LLM
  • Agen, alat, dan elemen dasar yang sama menyusun UI yang berbeda untuk maksud yang berbeda
  • Komponen A2UI dapat dirender langsung di adk web selama pengembangan

Membangun frontend produksi

Dalam codelab ini, Anda merender A2UI di dalam adk web untuk pengembangan dan pengujian.

Untuk produksi, Anda akan membangun frontend menggunakan salah satu perender A2UI resmi:

Platform

Perender

Instal

Web (React)

@a2ui/react

npm install @a2ui/react

Web (Lit)

@a2ui/lit

npm install @a2ui/lit

Web (Angular)

@a2ui/angular

npm install @a2ui/angular

Seluler/Desktop

Flutter GenUI SDK

Memulai

Dokumen referensi

Langkah Berikutnya

Pelajari sumber daya pembelajaran untuk membangun dan men-deploy agen tingkat perusahaan dengan Gemini Enterprise Agent Ready (GEAR).