ประสบการณ์การใช้งานส่วนหน้าด้วย ADK และ A2UI

1. ภาพรวม

ตัวแทน AI ส่วนใหญ่จะตอบกลับด้วยข้อความ ใน Codelab นี้ คุณจะได้ใช้ A2UI เพื่อให้เอเจนต์ตอบกลับด้วยอินเทอร์เฟซผู้ใช้แทน เอเจนต์จะอธิบายการ์ด รายการ ปุ่ม และแบบฟอร์มใน JSON โดยใช้แคตตาล็อกคอมโพเนนต์มาตรฐาน และไคลเอ็นต์จะแสดงผลด้วยวิดเจ็ตดั้งเดิมของตัวเอง จึงไม่จำเป็นต้องมีโค้ดส่วนหน้าใหม่สำหรับเลย์เอาต์ใหม่

คุณจะสร้าง Agent ด้วย Agent Development Kit (ADK)

สิ่งที่คุณจะสร้าง

แดชบอร์ดโครงสร้างพื้นฐานของระบบคลาวด์จำลองใน 3 ขั้นตอน

  1. เอเจนต์มาตรฐานที่แสดงผลข้อมูลทรัพยากรเป็นข้อความธรรมดา
  2. เอเจนต์ A2UI ที่แสดงข้อมูลเดียวกันกับ JSON ของ A2UI ที่มีโครงสร้าง
  3. เอเจนต์ที่แสดงผลซึ่งแสดง JSON ของ A2UI เป็นคอมโพเนนต์ UI แบบอินเทอร์แอกทีฟใน UI สำหรับนักพัฒนา ADK

ADK A2UI Agent

สิ่งที่คุณจะได้เรียนรู้

  • วิธีการทำงานของ A2UI: องค์ประกอบพื้นฐาน 18 รายการ ข้อความที่สร้าง UI และโมเดลคอมโพเนนต์แบบเรียบ
  • วิธีใช้ A2UI SDK เพื่อแจ้งให้ Agent ของ ADK สร้าง JSON ของ A2UI
  • วิธีแสดงผลคอมโพเนนต์ A2UI ใน adk web

สิ่งที่คุณต้องมี

  • โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
  • เว็บเบราว์เซอร์ เช่น Chrome
  • Python 3.12 ขึ้นไปและ uv หากคุณเรียกใช้โค้ดในเครื่องของคุณเองแทน Cloud Shell

Codelab นี้เหมาะสำหรับนักพัฒนาแอประดับกลางที่มีความคุ้นเคยกับ Python และ Google Cloud บ้าง

Codelab นี้จะใช้เวลาประมาณ 20 นาที

ทรัพยากรที่สร้างในโค้ดแล็บนี้ควรมีค่าใช้จ่ายน้อยกว่า $5

2. ตั้งค่าสภาพแวดล้อม

สร้างโปรเจ็กต์ Google Cloud

  1. ในคอนโซล Google Cloud ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud ในหน้าตัวเลือกโปรเจ็กต์
  2. ตรวจสอบว่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์เปิดใช้การเรียกเก็บเงินแล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่

เริ่ม Cloud Shell Editor

หากต้องการเปิดตัวเซสชัน Cloud Shell จากคอนโซล Google Cloud ให้คลิกเปิดใช้งาน Cloud Shell ในคอนโซล Google Cloud

ซึ่งจะเปิดเซสชันในบานหน้าต่างด้านล่างของคอนโซล Google Cloud

หากต้องการเปิดตัวแก้ไข ให้คลิกเปิดตัวแก้ไขในแถบเครื่องมือของหน้าต่าง Cloud Shell

เปิดใช้ API

ในแถบเครื่องมือของ Cloud Shell Editor ให้คลิกเทอร์มินัลและเทอร์มินัลใหม่ จากนั้นเรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ API ที่จำเป็น

gcloud services enable aiplatform.googleapis.com

ติดตั้งการอ้างอิง

ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อสร้างโฟลเดอร์สำหรับ Codelab นี้ โดยมีโฟลเดอร์ a2ui_agent อยู่ภายในสำหรับโค้ดของ Agent และติดตั้ง Agent Development Kit (ADK) และ A2UI SDK

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

uv จะสร้างสภาพแวดล้อม Python ที่แยกต่างหากสำหรับ Codelab นี้ คุณจึงไม่ต้องเปิดใช้งานสิ่งใด นำหน้าคำสั่ง Python ด้วย uv run

3. สร้าง Agent

เริ่มต้นด้วย Agent ADK มาตรฐานที่แสดงข้อความธรรมดา นี่คือลักษณะของแอปตัวแทนส่วนใหญ่ในปัจจุบัน

กำหนดค่าการตั้งค่าโปรเจ็กต์

ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อสร้าง a2ui_agent/.env ด้วยโปรเจ็กต์และสถานที่ตั้งของคุณ และเพื่อให้ ADK เรียกใช้ Gemini ผ่านโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ADK จะโหลดไฟล์นี้โดยอัตโนมัติ ดังนั้นการตั้งค่าจึงใช้ได้ในเทอร์มินัลใหม่ด้วย

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

กำหนดเครื่องมือและข้อมูลจำลอง

สร้าง a2ui_agent/resources.py โดยใช้เนื้อหาต่อไปนี้ เครื่องมือนี้จะแสดงรายการทรัพยากรระบบคลาวด์พร้อมสถานะ

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

กำหนด Agent

สร้าง a2ui_agent/agent.py โดยมีเนื้อหาต่อไปนี้

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. ทดสอบ Agent

ADK มี UI สำหรับนักพัฒนาแอปที่คุณใช้โต้ตอบและส่งพรอมต์ไปยังเอเจนต์ในเบราว์เซอร์เพื่อทดสอบได้

เริ่ม UI สำหรับนักพัฒนาแอป ADK

ในเทอร์มินัล Cloud Shell Editor ให้เรียกใช้คำสั่งต่อไปนี้เพื่อเริ่ม UI สำหรับนักพัฒนาซอฟต์แวร์ ADK

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

คุณควรเห็นข้อความที่คล้ายกับข้อความต่อไปนี้

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

เปิด UI สำหรับนักพัฒนาแอป ADK

คุณเปิด UI สำหรับนักพัฒนาซอฟต์แวร์ ADK ในเบราว์เซอร์ได้โดยกด Ctrl หรือ Cmd แล้วคลิก URL การทดสอบในเครื่อง หรือคลิกปุ่มตัวอย่างเว็บ แล้วเลือกดูตัวอย่างในพอร์ต 8080

เมื่อดู UI สำหรับนักพัฒนาแอป ADK แล้ว ให้เลือก a2ui_agent จากเมนูแบบเลื่อนลง

ส่งตัวอย่างพรอมต์

ส่งพรอมต์ตัวอย่างไปยัง Agent

What's running in my project?

ตอนนี้ลองใช้พรอมต์ตัวอย่างอื่น แล้วคุณจะได้รับเอาต์พุตข้อความเพิ่มเติม

Does anything need my attention?

การสนทนาควรมีลักษณะคล้ายกับตัวอย่างต่อไปนี้

ADK Text Agent

คำตอบถูกต้อง แต่เป็นข้อความยาวๆ ต่อกัน

5. สร้าง JSON ของ A2UI

จากนั้นเปลี่ยน Agent จากข้อความธรรมดาเป็น A2UI

A2UI Python SDK มีเครื่องมือสร้างพรอมต์ที่จะเขียนพรอมต์ของระบบให้คุณ โดยจะสอน LLM เกี่ยวกับแคตตาล็อกคอมโพเนนต์ A2UI ทั้งหมด ชื่อและประเภทพร็อพเพอร์ตี้ที่ถูกต้อง รวมถึงโครงสร้าง JSON

อัปเดต Agent

แทนที่เนื้อหาของ a2ui_agent/agent.py ด้วยเนื้อหาต่อไปนี้

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 แสดง JSON ของ A2UI เป็นข้อความเพื่อให้คุณอ่านได้ คุณจะนำออกในภายหลังเพื่อดูการแสดงผล UI

prompt_generator.generate() วิธีนี้จะรวมคำอธิบายบทบาทของคุณเข้ากับสคีมา JSON ของ A2UI แบบเต็มและตัวอย่างแบบ Few-Shot เพื่อให้ LLM รู้ว่าควรจัดรูปแบบเอาต์พุตอย่างไร คุณไม่จำเป็นต้องเขียนแคตตาล็อกคอมโพเนนต์ด้วยตนเอง

Codelab นี้ใช้ A2UI เวอร์ชัน 0.8 (version="0.8") ซึ่งเป็นเวอร์ชันที่ตัวแสดงผล A2UI ของ adk web รองรับ

6. ทดสอบเอาต์พุต JSON

หากคุณยังคงใช้ UI สำหรับนักพัฒนาซอฟต์แวร์ ADK จากก่อนหน้านี้อยู่ UI ควรจะโหลดการเปลี่ยนแปลงที่คุณทำกับเอเจนต์ซ้ำโดยอัตโนมัติ

เลือก a2ui_agent แล้วเริ่มเซสชันใหม่โดยคลิก +เซสชันใหม่ที่ด้านขวาบนของ UI สำหรับนักพัฒนาซอฟต์แวร์ ADK จากนั้นส่งพรอมต์เดียวกันกับก่อนหน้า

What's running in my project?

คราวนี้เอเจนต์จะตอบกลับด้วย JSON ของ A2UI แทนข้อความธรรมดา คุณจะเห็นข้อความที่มีโครงสร้าง เช่น beginRendering และ surfaceUpdate (และบางครั้ง dataModelUpdate) ในเอาต์พุตแชทในบล็อกโค้ด JSON

ADK A2UI JSON

JSON อธิบาย UI ที่สมบูรณ์พร้อมการ์ด ไอคอน และปุ่ม แต่ show_raw_json จะเก็บไว้เป็นข้อความเพื่อให้คุณอ่านได้ จากนั้นคุณจะดูโครงสร้างของ JSON นี้ แล้วนำ show_raw_json ออกเพื่อแสดงเป็นคอมโพเนนต์ UI จริง

7. ทำความเข้าใจ A2UI

ดู JSON ที่ Agent เพิ่งสร้างขึ้น A2UI มีข้อความ 3 ประเภทสําหรับสร้าง UI เอาต์พุตของเอเจนต์อาจไม่ได้ใช้ทั้ง 3 อย่างทุกครั้ง

1. beginRendering

สร้างพื้นผิวการแสดงผลและตั้งชื่อคอมโพเนนต์รูท

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

2. surfaceUpdate

ส่งโครงสร้างคอมโพเนนต์เป็นรายการแบบแบนที่มีการอ้างอิงรหัส (ไม่ใช่แบบซ้อนกัน)

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

ส่งข้อมูลแยกจากโครงสร้าง

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

คอมโพเนนต์จะเชื่อมโยงกับข้อมูลโดยใช้ {"path": "key"} คุณอัปเดตข้อมูลได้โดยไม่ต้องส่งแผนผังคอมโพเนนต์อีกครั้ง

องค์ประกอบพื้นฐาน 18 รายการ

หมวดหมู่

คอมโพเนนต์

เลย์เอาต์

การ์ด คอลัมน์ แถว รายการ แท็บ ตัวคั่น โมดัล

Display

ข้อความ รูปภาพ ไอคอน วิดีโอ AudioPlayer

อินพุต

TextField, DateTimeInput, MultipleChoice, CheckBox, Slider

การดำเนินการ

ปุ่ม

เอเจนต์จะสร้างเลย์เอาต์ต่างๆ เช่น มุมมองการเรียกดู แดชบอร์ดที่มีลำดับความสำคัญ หรือแบบฟอร์มการกำหนดค่า จากคอมโพเนนต์เดียวกันเหล่านี้ ดูรายละเอียดของแต่ละรายการได้ที่ข้อมูลอ้างอิงเกี่ยวกับคอมโพเนนต์

8. แสดงคอมโพเนนต์ A2UI

SDK จะรวม A2UI ไว้ในแท็ก มาตรฐาน adk web จะจดจำและแสดงผลคอมโพเนนต์ด้วยโปรแกรมแสดงผล A2UI ในตัว หากต้องการดู ให้นำ show_raw_json ออก

อัปเดต Agent

แทนที่เนื้อหาของ a2ui_agent/agent.py ด้วยเนื้อหาต่อไปนี้ การเปลี่ยนแปลงจากขั้นตอนก่อนหน้ามีเพียงฟังก์ชัน show_raw_json พารามิเตอร์ after_model_callback และการนำเข้า 2 รายการที่ใช้ได้หายไปแล้ว ดังนี้

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. ทดสอบ UI ที่แสดงผล

หากคุณยังคงใช้ UI สำหรับนักพัฒนาซอฟต์แวร์ ADK จากก่อนหน้านี้อยู่ UI ควรจะโหลดการเปลี่ยนแปลงที่คุณทำกับเอเจนต์ซ้ำโดยอัตโนมัติ

รีเฟรชแท็บเบราว์เซอร์ เลือก a2ui_agent จากนั้นเริ่มเซสชันใหม่โดยคลิก +เซสชันใหม่ที่ด้านขวาบนของ UI สำหรับนักพัฒนา ADK แล้วส่งพรอมต์เดียวกันกับก่อนหน้า

What's running in my project?

ในครั้งนี้ adk web จะแสดงผลคอมโพเนนต์ A2UI เป็น UI จริง ได้แก่ การ์ดที่มีตัวบ่งชี้สถานะ รายละเอียดทรัพยากร และปุ่มการดำเนินการ

ADK A2UI Agent

ลองใช้พรอมต์อื่นเพื่อดูว่าเอเจนต์จะสร้าง UI ที่แตกต่างจากชุดองค์ประกอบพื้นฐานเดียวกันได้อย่างไร

Does anything need my attention?

สุดท้าย ลองใช้พรอมต์อื่นเพื่อสร้าง UI อื่นเพื่อติดตั้งใช้งานบริการใหม่

I need to deploy a new service

พรอมต์ทั้ง 3 รายการใช้เอเจนต์ เครื่องมือ และคอมโพเนนต์เดียวกัน แต่แต่ละรายการจะสร้าง UI ที่แตกต่างกันซึ่งเหมาะกับสิ่งที่คุณขอ

10. ล้าง

หากต้องการหลีกเลี่ยงการปล่อยให้เซิร์ฟเวอร์ในเครื่องทำงานต่อไป ให้ล้างข้อมูลทรัพยากรโดยทำดังนี้

  • ในเทอร์มินัลที่เรียกใช้ adk web ให้กด Ctrl+C เพื่อหยุดเซิร์ฟเวอร์ตัวแทน

หากสร้างโปรเจ็กต์สำหรับ Codelab นี้โดยเฉพาะ คุณสามารถลบทั้งโปรเจ็กต์ได้โดยทำดังนี้

gcloud projects delete <YOUR_PROJECT_ID>

11. ขอแสดงความยินดี

คุณสร้าง Agent ของ ADK ที่สร้าง UI แบบอินเทอร์แอกทีฟที่สมบูรณ์โดยใช้ A2UI

สิ่งที่คุณได้เรียนรู้

  • A2UI เป็นโปรโตคอลที่มีPrimitive แบบประกาศ 18 รายการและข้อความง่ายๆ ไม่กี่รายการที่สร้าง UI
  • A2UI SDK จะสร้างพรอมต์ของระบบที่สอน LLM เกี่ยวกับแคตตาล็อกคอมโพเนนต์
  • เอเจนต์ เครื่องมือ และองค์ประกอบพื้นฐานเดียวกันจะประกอบกันเป็น UI ที่แตกต่างกันสำหรับความตั้งใจที่แตกต่างกัน
  • คอมโพเนนต์ A2UI สามารถแสดงผลได้โดยตรงใน adk web ระหว่างการพัฒนา

สร้างส่วนหน้าของเวอร์ชันที่ใช้งานจริง

ใน Codelab นี้ คุณได้แสดงผล A2UI ภายใน adk web เพื่อการพัฒนาและการทดสอบ

สําหรับการใช้งานจริง คุณจะต้องสร้างส่วนหน้าโดยใช้เครื่องมือแสดงผล A2UI อย่างเป็นทางการอย่างใดอย่างหนึ่งต่อไปนี้

แพลตฟอร์ม

โปรแกรมร่างภาพ

ติดตั้ง

เว็บ (React)

@a2ui/react

npm install @a2ui/react

เว็บ (Lit)

@a2ui/lit

npm install @a2ui/lit

เว็บ (Angular)

@a2ui/angular

npm install @a2ui/angular

อุปกรณ์เคลื่อนที่/เดสก์ท็อป

Flutter GenUI SDK

เริ่มต้นใช้งาน

เอกสารอ้างอิง

ขั้นตอนถัดไป

สำรวจแหล่งข้อมูลการเรียนรู้เพื่อสร้างและติดตั้งใช้งานเอเจนต์ระดับองค์กรด้วย Gemini Enterprise Agent Ready (GEAR)