1. ภาพรวม
แอปตัวแทนส่วนใหญ่จะแสดงข้อความธรรมดา A2UI ช่วยเปลี่ยนแปลงสิ่งนั้น ซึ่งเป็นโปรโตคอลที่มี UI แบบประกาศสิ่งที่ต้องการ 18 รายการที่ช่วยให้เอเจนต์ของคุณสร้างอินเทอร์เฟซแบบอินเทอร์แอกทีฟที่สมบูรณ์ได้ ไคลเอ็นต์จะแสดงผลแบบเนทีฟ ไม่ต้องใช้โค้ดส่วนหน้าใหม่ต่อเลย์เอาต์
Codelab นี้ใช้ Agent Development Kit (ADK) เพื่อสร้าง Agent และ A2UI เพื่อสร้าง UI
สิ่งที่คุณจะสร้าง
แดชบอร์ดโครงสร้างพื้นฐานของระบบคลาวด์ใน 3 ขั้นตอน
- เอเจนต์มาตรฐานที่แสดงผลข้อมูลทรัพยากรเป็นข้อความธรรมดา
- เอเจนต์ A2UI ที่แสดงข้อมูลเดียวกันกับ JSON ของ A2UI ที่มีโครงสร้าง
- เอเจนต์ที่แสดงผลซึ่งแสดง JSON ของ A2UI เป็นคอมโพเนนต์ UI แบบอินเทอร์แอกทีฟใน UI สำหรับนักพัฒนา ADK
สิ่งที่คุณจะได้เรียนรู้
- วิธีการทำงานของ A2UI: องค์ประกอบพื้นฐาน 18 รายการ, ประเภทข้อความ 3 ประเภท, โมเดลคอมโพเนนต์แบบเรียบ
- วิธีใช้ A2UI SDK เพื่อแจ้งให้ Agent ADK สร้าง JSON ของ A2UI
- วิธีแสดงผลคอมโพเนนต์ A2UI ใน
adk web
สิ่งที่คุณต้องมี
- โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
- เว็บเบราว์เซอร์ เช่น Chrome
- Python 3.12 ขึ้นไป
Codelab นี้เหมาะสำหรับนักพัฒนาแอปที่มีความรู้ระดับกลางซึ่งคุ้นเคยกับ Python และ Google Cloud บ้าง
Codelab นี้จะใช้เวลาประมาณ 15-20 นาที
ทรัพยากรที่สร้างในโค้ดแล็บนี้ควรมีค่าใช้จ่ายน้อยกว่า $5
2. ตั้งค่าสภาพแวดล้อม
สร้างโปรเจ็กต์ Google Cloud
- ในคอนโซล Google Cloud ในหน้าตัวเลือกโปรเจ็กต์ ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud
- ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่
เริ่มต้น Cloud Shell Editor
หากต้องการเปิดเซสชัน Cloud Shell จากคอนโซล Google Cloud ให้คลิกเปิดใช้งาน Cloud Shell ในคอนโซล Google Cloud
ซึ่งจะเปิดเซสชันในบานหน้าต่างด้านล่างของคอนโซล Google Cloud
หากต้องการเปิดตัวแก้ไข ให้คลิกเปิดตัวแก้ไขในแถบเครื่องมือของหน้าต่าง Cloud Shell
ตั้งค่าตัวแปรสภาพแวดล้อม
ในแถบเครื่องมือของ Cloud Shell Editor ให้คลิกเทอร์มินัลและเทอร์มินัลใหม่ จากนั้นเรียกใช้คำสั่งต่อไปนี้เพื่อตั้งค่าโปรเจ็กต์ สถานที่ และกำหนดค่า ADK ให้ใช้ Gemini ใน Vertex AI
export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE> export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
เปิดใช้ API
ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ API ที่จำเป็น
gcloud services enable aiplatform.googleapis.com
ติดตั้งการอ้างอิง
ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อติดตั้ง Agent Development Kit (ADK) เวอร์ชันล่าสุด
pip install -U google-adk a2ui-agent-sdk export PATH="$HOME/.local/bin:$PATH"
3. สร้าง Agent
เริ่มต้นด้วย Agent ADK มาตรฐานที่แสดงข้อความธรรมดา แอปตัวแทนส่วนใหญ่มีลักษณะดังที่เห็นในปัจจุบัน
สร้างโฟลเดอร์ตัวแทน
สร้างโฟลเดอร์ชื่อ a2ui_agent ซึ่งจะมีซอร์สโค้ดสำหรับเอเจนต์และเครื่องมือ
กำหนดเครื่องมือและข้อมูลจำลอง
สร้าง 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 .resources import get_resources
root_agent = Agent(
model="gemini-3-flash-preview",
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
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?
การสนทนาของคุณควรมีลักษณะคล้ายกับตัวอย่างต่อไปนี้
คุณจะเห็นข้อความยาวเป็นพรืด ถูกต้อง แต่ไม่ใช่ประสบการณ์การใช้งานที่ดี
5. สร้าง JSON ของ A2UI
จะเกิดอะไรขึ้นหากตัวแทนอธิบาย UI แทนที่จะทิ้งข้อความ A2UI เป็นโปรโตคอลที่ช่วยให้เอเจนต์สร้างอินเทอร์เฟซแบบอินเทอร์แอกทีฟจากแคตตาล็อกขององค์ประกอบพื้นฐาน 18 รายการ ไคลเอ็นต์จะแสดงผลแบบเนทีฟ
A2UI Python SDK มีเครื่องมือจัดการสคีมาที่จะสร้างพรอมต์ของระบบให้คุณ โดยจะสอน LLM เกี่ยวกับแคตตาล็อกคอมโพเนนต์ A2UI ทั้งหมด ชื่อและประเภทพร็อพเพอร์ตี้ที่ถูกต้อง รวมถึงโครงสร้าง JSON
อัปเดตตัวแทน
แทนที่เนื้อหาของ a2ui_agent/agent.py ด้วยข้อมูลต่อไปนี้
from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources
schema_manager = A2uiSchemaManager(
version="0.8",
catalogs=[BasicCatalog.get_config("0.8")],
)
instruction = schema_manager.generate_system_prompt(
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-3-flash-preview",
name="cloud_dashboard",
description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
instruction=instruction,
tools=[get_resources],
)
generate_system_prompt() วิธีนี้จะรวมคำอธิบายบทบาทของคุณเข้ากับสคีมา JSON ของ A2UI แบบเต็มและตัวอย่างแบบ Few-Shot เพื่อให้ LLM รู้ว่าควรจัดรูปแบบเอาต์พุตอย่างไร คุณไม่จำเป็นต้องเขียนแคตตาล็อกคอมโพเนนต์ด้วยตนเอง
6. ทดสอบเอาต์พุต JSON
หากคุณยังคงใช้ UI สำหรับนักพัฒนาซอฟต์แวร์ ADK จากก่อนหน้านี้อยู่ ระบบควรโหลดการเปลี่ยนแปลงที่คุณทำกับเอเจนต์ซ้ำโดยอัตโนมัติ
เลือก a2ui_agent เริ่มเซสชันใหม่โดยคลิก +เซสชันใหม่ที่ด้านขวาบนของ UI สำหรับนักพัฒนาซอฟต์แวร์ ADK แล้วส่งพรอมต์เดียวกันกับก่อนหน้า
What's running in my project?
คราวนี้เอเจนต์จะตอบกลับด้วย JSON ของ A2UI แทนข้อความธรรมดา คุณจะเห็นข้อความที่มีโครงสร้างซึ่งมี beginRendering, surfaceUpdate และ dataModelUpdate ในเอาต์พุตแชท
JSON อธิบาย UI ที่สมบูรณ์พร้อมการ์ด ไอคอน และปุ่ม แต่ adk web แสดงเป็นข้อความดิบ ในขั้นตอนถัดไป คุณจะทำให้คอมโพเนนต์แสดงผลเป็นคอมโพเนนต์ UI จริง
7. ทำความเข้าใจ A2UI
ดู JSON ที่ Agent เพิ่งสร้าง คุณจะเห็นว่ามีข้อความ 3 ประเภท การตอบกลับ A2UI ทุกครั้งจะมีโครงสร้างเดียวกันนี้
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 |
การดำเนินการ | ปุ่ม |
เอเจนต์จะสร้างเลย์เอาต์ต่างๆ จากแคตตาล็อกเดียวกัน ดูรายละเอียดทั้งหมดเกี่ยวกับแต่ละองค์ประกอบได้ที่ข้อมูลอ้างอิงของคอมโพเนนต์ มุมมองการเรียกดู แดชบอร์ดลำดับความสำคัญ และแบบฟอร์มการกำหนดค่าทั้งหมดใช้ Primitive เดียวกัน 18 รายการนี้ โดยไม่ต้องมีคอมโพเนนต์ส่วนหน้าใหม่
8. แสดงผลคอมโพเนนต์ A2UI
Agent สร้าง JSON ของ A2UI ที่ถูกต้อง แต่ adk web แสดงเป็นข้อความดิบ หากต้องการแสดงผลเป็นคอมโพเนนต์ UI จริง คุณต้องมีเครื่องมือขนาดเล็กที่แปลงเอาต์พุต JSON ของ A2UI ของเอเจนต์เป็นรูปแบบที่ตัวแสดงผลในตัวของ adk web คาดหวัง
สร้างยูทิลิตีการแสดงผล A2UI
สร้าง a2ui_agent/a2ui_utils.py ที่มีเนื้อหาต่อไปนี้
import json
import re
from google.genai import types
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_response import LlmResponse
def _wrap_a2ui_part(a2ui_message: dict) -> types.Part:
"""Wrap a single A2UI message for rendering in adk web."""
datapart_json = json.dumps({
"kind": "data",
"metadata": {"mimeType": "application/json+a2ui"},
"data": a2ui_message,
})
blob_data = (
b"<a2a_datapart_json>"
+ datapart_json.encode("utf-8")
+ b"</a2a_datapart_json>"
)
return types.Part(
inline_data=types.Blob(
data=blob_data,
mime_type="text/plain",
)
)
def a2ui_callback(
callback_context: CallbackContext,
llm_response: LlmResponse,
) -> LlmResponse | None:
"""Convert A2UI JSON in text output to rendered components."""
if not llm_response.content or not llm_response.content.parts:
return None
for part in llm_response.content.parts:
if not part.text:
continue
text = part.text.strip()
if not text:
continue
if not any(k in text for k in ("beginRendering", "surfaceUpdate", "dataModelUpdate")):
continue
# Strip markdown fences
if text.startswith("```"):
text = text.split("\n", 1)[-1]
if text.endswith("```"):
text = text[:-3].strip()
# Find where JSON starts (skip conversational prefix)
json_start = None
for i, ch in enumerate(text):
if ch in ("[", "{"):
json_start = i
break
if json_start is None:
continue
json_text = text[json_start:]
# raw_decode parses JSON and ignores trailing text
try:
parsed, _ = json.JSONDecoder().raw_decode(json_text)
except json.JSONDecodeError:
# Handle concatenated JSON objects: {"a":1} {"b":2}
try:
fixed = "[" + re.sub(r'\}\s*\{', '},{', json_text) + "]"
parsed, _ = json.JSONDecoder().raw_decode(fixed)
except json.JSONDecodeError:
continue
if not isinstance(parsed, list):
parsed = [parsed]
a2ui_keys = {"beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface"}
a2ui_messages = [msg for msg in parsed if isinstance(msg, dict) and any(k in msg for k in a2ui_keys)]
if not a2ui_messages:
continue
new_parts = [_wrap_a2ui_part(msg) for msg in a2ui_messages]
return LlmResponse(
content=types.Content(role="model", parts=new_parts),
custom_metadata={"a2a:response": "true"},
)
return None
ยูทิลิตีนี้ทำ 2 สิ่งต่อไปนี้
- ดึงข้อมูล JSON ของ A2UI จากเอาต์พุตข้อความของเอเจนต์
- ห่อหุ้มข้อความ A2UI แต่ละข้อความในรูปแบบที่ตัวแสดงผล A2UI ในตัวของ
adk webคาดหวัง
อัปเดตตัวแทน
แทนที่เนื้อหาของ a2ui_agent/agent.py ด้วยข้อมูลต่อไปนี้ การเปลี่ยนแปลงจากขั้นตอนก่อนหน้ามีเพียงการนำเข้า a2ui_callback และพารามิเตอร์ after_model_callback ในเอเจนต์ ดังนี้
from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources
from .a2ui_utils import a2ui_callback
schema_manager = A2uiSchemaManager(
version="0.8",
catalogs=[BasicCatalog.get_config("0.8")],
)
instruction = schema_manager.generate_system_prompt(
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-3-flash-preview",
name="cloud_dashboard",
description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
instruction=instruction,
tools=[get_resources],
after_model_callback=a2ui_callback,
)
9. ทดสอบ UI ที่แสดงผล
หากคุณยังคงใช้ UI สำหรับนักพัฒนาซอฟต์แวร์ ADK จากก่อนหน้านี้อยู่ ระบบควรโหลดการเปลี่ยนแปลงที่คุณทำกับเอเจนต์ซ้ำโดยอัตโนมัติ
รีเฟรชแท็บเบราว์เซอร์ เลือก a2ui_agent จากนั้นเริ่มเซสชันใหม่โดยคลิก +เซสชันใหม่ที่ด้านขวาบนของ UI สำหรับนักพัฒนา ADK แล้วส่งพรอมต์เดียวกันกับก่อนหน้า
What's running in my project?
ในครั้งนี้ adk web จะแสดงผลคอมโพเนนต์ A2UI เป็น UI จริง ได้แก่ การ์ดที่มีตัวบ่งชี้สถานะ รายละเอียดทรัพยากร และปุ่มการดำเนินการ
ลองใช้พรอมต์อื่นเพื่อดูว่าเอเจนต์จะสร้าง UI ที่แตกต่างจากชุดองค์ประกอบพื้นฐานเดียวกันได้อย่างไร
Does anything need my attention?
สุดท้าย ให้ลองใช้พรอมต์อื่นเพื่อสร้าง UI ที่แตกต่างกันเพื่อติดตั้งใช้งานบริการใหม่
I need to deploy a new service
โดยแต่ละพรอมต์จะส่งไปยังเอเจนต์ เครื่องมือ และค่าดั้งเดิม 18 รายการเดียวกัน แต่พรอมต์แต่ละรายการจะส่งผลให้ UI แตกต่างกันสำหรับความตั้งใจที่ต่างกัน
10. ล้าง
หากไม่ต้องการให้เซิร์ฟเวอร์ภายในทำงานต่อไป ให้ล้างข้อมูลทรัพยากรโดยทำดังนี้
- ในเทอร์มินัลที่เรียกใช้
adk webให้กด Ctrl+C เพื่อหยุดเซิร์ฟเวอร์ตัวแทน
หากสร้างโปรเจ็กต์สำหรับ Codelab นี้โดยเฉพาะ คุณสามารถลบทั้งโปรเจ็กต์ได้โดยทำดังนี้
gcloud projects delete ${GOOGLE_CLOUD_PROJECT}
11. ขอแสดงความยินดี
คุณสร้าง Agent ของ ADK ที่สร้าง UI แบบอินเทอร์แอกทีฟที่สมบูรณ์โดยใช้ A2UI
สิ่งที่คุณได้เรียนรู้
- A2UI เป็นโปรโตคอลที่มีPrimitive แบบประกาศ 18 รายการและประเภทข้อความ 3 ประเภท
- A2UI SDK จะสร้างพรอมต์ของระบบที่สอนแคตตาล็อกคอมโพเนนต์ให้ LLM
- เอเจนต์ เครื่องมือ และองค์ประกอบพื้นฐานเดียวกันจะประกอบกันเป็น UI ที่แตกต่างกันสำหรับความตั้งใจที่แตกต่างกัน
- คอมโพเนนต์ A2UI แสดงผลได้โดยตรงใน
adk webระหว่างการพัฒนา
สร้างฟรอนท์เอนด์เวอร์ชันที่ใช้งานจริง
ใน Codelab นี้ คุณได้แสดงผล A2UI ภายใน adk web เพื่อการพัฒนาและการทดสอบ
สำหรับการใช้งานจริง คุณจะต้องสร้างส่วนหน้าโดยใช้ตัวแสดงผล A2UI อย่างเป็นทางการรายการใดรายการหนึ่งต่อไปนี้
แพลตฟอร์ม | โปรแกรมร่างภาพ | ติดตั้ง |
เว็บ (React) |
|
|
เว็บ (Lit) |
|
|
เว็บ (Angular) |
|
|
อุปกรณ์เคลื่อนที่/เดสก์ท็อป | Flutter GenUI SDK |