1. บทนำ
A2UI ช่วยให้ AI Agent สร้างอินเทอร์เฟซผู้ใช้แบบอินเทอร์แอกทีฟที่สมบูรณ์ ซึ่งแสดงผลแบบเนทีฟในเว็บ อุปกรณ์เคลื่อนที่ และเดสก์ท็อปได้โดยไม่ต้องเรียกใช้โค้ดที่กำหนดเอง A2UI ช่วยให้ Agent ส่งคำอธิบายคอมโพเนนต์แบบประกาศได้ ซึ่งไคลเอ็นต์จะแสดงผลโดยใช้วิดเจ็ตเนทีฟของตนเอง แทนที่จะตอบกลับเป็นข้อความเท่านั้นหรือการเรียกใช้โค้ดที่มีความเสี่ยง ซึ่งก็เหมือนกับให้ Agent พูดภาษา UI สากล
ในแล็บภาคปฏิบัติในครั้งนี้ คุณจะสร้าง Agent สร้างรูปภาพโดยใช้ Agent Development Kit (ADK) และ Gemini 3.1 Flash Image (หรือที่เรียกว่า Nano Banana 2) ก่อน จากนั้นคุณจะใช้ A2UI เพื่อสร้างอินเทอร์เฟซที่กำหนดเองซึ่งมีความสามารถมากกว่าแชทบ็อตทั่วไป โดยจะแสดงให้เห็นว่าคุณสามารถสร้างอินเทอร์เฟซแบบไดนามิกเพื่อเปิดใช้การโต้ตอบระหว่าง Agent กับผู้ใช้ที่สมบูรณ์ยิ่งขึ้นได้อย่างไร
สิ่งที่คุณจะได้เรียนรู้
- สร้าง Agent โดยใช้ ADK Python
- กำหนดค่า Agent ให้สตรีมคอมโพเนนต์ A2UI ไปยังฟรอนท์เอนด์
- สร้างฟรอนท์เอนด์ที่กำหนดเองเพื่อแสดงผลองค์ประกอบ A2UI
ข้อกำหนดเบื้องต้น
- ความรู้พื้นฐานเกี่ยวกับ AI Agent
- ความเข้าใจพื้นฐานเกี่ยวกับไวยากรณ์ Python
- ความเข้าใจพื้นฐานเกี่ยวกับแนวคิดฟรอนท์เอนด์
2. ตั้งค่า
ทำตามวิธีการด้านล่างเพื่อเริ่มต้น Google Cloud Project ที่จำเป็นสำหรับ Codelab นี้ หลังจากเริ่มต้นโปรเจ็กต์แล้ว เราขอแนะนำให้คุณดำเนินการ Codelab นี้ใน Cloud Shell เนื่องจากมีเครื่องมือทั้งหมดที่จำเป็นสำหรับการดำเนินการได้ทันที
หากต้องการเรียกใช้ Codelab นี้ในสภาพแวดล้อมในเครื่อง คุณจะต้องติดตั้ง Python, UV และโปรแกรมแก้ไขโค้ดก่อนดำเนินการต่อ วิธีการทั้งหมดใน Codelab นี้จะถือว่าคุณเรียกใช้ใน Cloud Shell เว้นแต่จะระบุไว้เป็นอย่างอื่น
การตั้งค่าสภาพแวดล้อมแบบเรียนรู้ด้วยตนเอง
- ลงชื่อเข้าใช้ คอนโซล Google Cloud แล้วสร้างโปรเจ็กต์ใหม่หรือใช้โปรเจ็กต์ที่มีอยู่ หากยังไม่มีบัญชี Gmail หรือ Google Workspace คุณต้อง สร้างบัญชี
- ชื่อโปรเจ็กต์ คือชื่อที่แสดงสำหรับผู้เข้าร่วมโปรเจ็กต์นี้ ซึ่งเป็นสตริงอักขระที่ Google APIs ไม่ได้ใช้ คุณอัปเดตชื่อนี้ได้ทุกเมื่อ
- รหัสโปรเจ็กต์ ไม่ซ้ำกันในโปรเจ็กต์ Google Cloud ทั้งหมดและเปลี่ยนแปลงไม่ได้ (เปลี่ยนไม่ได้หลังจากตั้งค่าแล้ว) Cloud Console จะสร้างสตริงที่ไม่ซ้ำกันโดยอัตโนมัติ ซึ่งโดยปกติแล้วคุณไม่จำเป็นต้องสนใจว่าสตริงนั้นคืออะไร ใน Codelab ส่วนใหญ่ คุณจะต้องอ้างอิงรหัสโปรเจ็กต์ (โดยทั่วไปจะระบุเป็น
PROJECT_ID) หากไม่ชอบรหัสที่สร้างขึ้น คุณอาจสร้างรหัสแบบสุ่มอีกรหัสหนึ่ง หรือจะลองใช้รหัสของคุณเองและดูว่ารหัสนั้นพร้อมใช้งานหรือไม่ก็ได้ คุณจะเปลี่ยนรหัสไม่ได้หลังจากขั้นตอนนี้ และรหัสจะคงอยู่ตลอดระยะเวลาของโปรเจ็กต์ - โปรดทราบว่ามีค่าที่ 3 คือหมายเลขโปรเจ็กต์ ซึ่ง API บางรายการใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับค่าทั้ง 3 นี้ได้ใน เอกสารประกอบ
- จากนั้นคุณจะต้อง เปิดใช้การเรียกเก็บเงิน ใน Cloud Console เพื่อใช้ทรัพยากร/API ของ Cloud การทำตาม Codelab นี้จะไม่เสียค่าใช้จ่ายมากนัก หรืออาจไม่เสียค่าใช้จ่ายเลย หากต้องการปิดทรัพยากรเพื่อหลีกเลี่ยงการเรียกเก็บเงินนอกเหนือจากบทแนะนำนี้ คุณสามารถลบทรัพยากรที่สร้างขึ้นหรือลบโปรเจ็กต์ ผู้ใช้ Google Cloud รายใหม่มีสิทธิ์รับโปรแกรมช่วงทดลองใช้ฟรีมูลค่า$300 USD
เริ่มต้น Cloud Shell
แม้ว่าคุณจะใช้งาน Google Cloud จากระยะไกลจากแล็ปท็อปได้ แต่ใน Codelab นี้คุณจะใช้ Google Cloud Shell ซึ่งเป็นสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานในระบบคลาวด์
จาก คอนโซล Google Cloud ให้คลิกไอคอน Cloud Shell ในแถบเครื่องมือด้านขวาบน
การจัดสรรและเชื่อมต่อกับสภาพแวดล้อมควรใช้เวลาไม่นาน เมื่อเสร็จแล้ว คุณควรเห็นข้อความลักษณะนี้
เครื่องเสมือนนี้โหลดเครื่องมือพัฒนาทั้งหมดที่คุณต้องการ โดยมีไดเรกทอรีหลักแบบถาวรขนาด 5 GB และทำงานบน Google Cloud ซึ่งช่วยเพิ่มประสิทธิภาพเครือข่ายและการตรวจสอบสิทธิ์ได้อย่างมาก คุณสามารถทำงานทั้งหมดใน Codelab นี้ได้ภายในเบราว์เซอร์ โดยไม่จำเป็นต้องติดตั้งสิ่งใด
3. สร้าง Agent ADK ใหม่
- สร้างโฟลเดอร์สำหรับเวิร์กช็อปนี้ชื่อ
a2ui_lab
mkdir -p ~/a2ui_lab && cd ~/a2ui_lab
- กำหนดค่าตัวจัดการแพ็กเกจ UV ในโฟลเดอร์นี้และติดตั้งทรัพยากร Dependency
uv init && uv add google-adk fastapi uvicorn a2ui-agent-sdk
- เปิดใช้ AI Platform API (เพื่อเรียกใช้โมเดล Gemini)
gcloud services enable aiplatform.googleapis.com
- เริ่มต้น Agent ADK ในโฟลเดอร์นี้
export GOOGLE_CLOUD_PROJECT=`gcloud config get project`
uv run adk create --model gemini-3.5-flash --project $GOOGLE_CLOUD_PROJECT --region global art_creator
คุณควรเห็นเอาต์พุตลักษณะนี้
$ uv run adk create --model gemini-3.5-flash --project $GOOGLE_CLOUD_PROJECT --region global art_creator Agent created in ~/a2ui_lab/art_creator: - .env - __init__.py - agent.py ⚠️ WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env. Please ensure .env is added to your .gitignore to avoid committing secrets to version control.
โปรดทราบว่า uv run เป็นคำสั่งที่เรียกใช้คำสั่งภายในบริบทของที่เก็บ uv ปัจจุบัน ซึ่งเราสร้างขึ้นเมื่อเรียกใช้ uv init คำสั่ง adk ได้รับการติดตั้งลงในที่เก็บนี้เมื่อเราเพิ่มทรัพยากร Dependency ของแพ็กเกจ google-adk
ในเอกสารประกอบของ ADK คุณมักจะเห็นคำสั่ง adk โดยไม่มีคำนำหน้า uv run แต่เมื่อใดก็ตามที่เรียกใช้คำสั่งในเวิร์กช็อปนี้ ให้ใส่คำนำหน้า adk ด้วย uv run เสมอ เพื่อให้เรียกใช้ยูทิลิตีบรรทัดคำสั่งที่ถูกต้อง
ตอนนี้เราได้สร้างโครงสร้าง Agent พื้นฐานแล้ว เราจึงกำหนด Agent สร้างรูปภาพใน agent.py ได้
- เปิดโปรแกรมแก้ไข Cloud Shell ด้วยคำสั่งต่อไปนี้
cloudshell workspace ~/a2ui_lab
- แทนที่เนื้อหาของ
art_creator/agent.pyด้วยโค้ดด้านล่าง
art_creator/agent.py
import os
import time
from google.adk.agents.llm_agent import Agent
from google.adk.tools.tool_context import ToolContext
from google.genai import types
# Load env variables
from dotenv import load_dotenv
load_dotenv(os.path.join(os.path.dirname(__file__), ".env"))
async def generate_image(prompt: str, tool_context: ToolContext) -> dict:
"""Generates a high-quality image based on the user's detailed description prompt.
Args:
prompt: A descriptive text prompt describing the image to generate.
tool_context: Context for the tool execution.
"""
from google.genai import Client
client = Client(
vertexai=True,
project=os.environ.get("GOOGLE_CLOUD_PROJECT"),
location=os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
)
try:
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=prompt,
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
)
)
image_bytes = None
for part in response.parts or []:
if part.inline_data is not None:
image_bytes = part.inline_data.data
break
if not image_bytes:
return {"status": "failed", "detail": "No image data returned"}
filename = f"image_{int(time.time())}.png"
await tool_context.save_artifact(
filename,
types.Part.from_bytes(data=image_bytes, mime_type='image/png'),
)
return {
"status": "success",
"filename": filename,
"url": f"/api/artifacts/{tool_context.session.id}/{filename}"
}
except Exception as e:
return {"status": "failed", "detail": str(e)}
root_agent = Agent(
name="art_agent",
model="gemini-3.5-flash",
description="A basic art generation agent.",
instruction=(
"You are an art assistant. When the user describes an image they want to generate, "
"use the generate_image tool to create it, then return a text message containing the image's URL."
),
tools=[generate_image],
)
- ตอนนี้คุณสามารถทดสอบ Agent ใน UI การพัฒนาของ ADK โดยใช้คำสั่ง
uv run adk webได้แล้ว
uv run adk web --port 8080 --allow_origins "*" --reload_agents
จากนั้นคลิกปุ่มตัวอย่างเว็บ แล้วเลือกแสดงตัวอย่างบนพอร์ต 8080 ซึ่งจะเปิด UI การพัฒนาในเบราว์เซอร์
ใช้ UI การพัฒนาของ ADK เพื่อทดสอบความสามารถของ Agent โดยป้อนคำสั่ง 2-3 รายการ เช่น
- เด็กผู้หญิงสไตล์อนิเมะนอนหลับใต้ต้นไม้ สีพาสเทล 16:9
- รูปภาพกระท่อมที่สะท้อนบนทะเลสาบ ช่วงบ่ายแก่ๆ ให้ความรู้สึกโหยหา
คุณควรเห็น Agent ตอบกลับด้วยข้อความและรูปภาพที่สร้างขึ้น
4. สร้างฟรอนท์เอนด์อย่างง่าย
ตอนนี้เราจะสร้างเว็บแอปเฉพาะสำหรับ Agent ของเรา เราจะใช้ FastAPI เพื่อเรียกใช้ ADK Runner และแสดงอินเทอร์เฟซแชทแบบหน้าเดียวอย่างง่าย
ขั้นแรก ให้หยุดเซิร์ฟเวอร์การพัฒนา ADK โดยพิมพ์ Ctrl+C ในเทอร์มินัล จากนั้นสร้างไฟล์ชื่อ main.py ในรูทของพื้นที่ทำงาน (~/a2ui_lab/main.py) ด้วยเนื้อหาต่อไปนี้
main.py
import os
import logging
from fastapi import FastAPI, HTTPException
from fastapi.staticfiles import StaticFiles
from pydantic import BaseModel
from google.adk.runners import InMemoryRunner
from google.adk.agents.run_config import RunConfig
from google.genai import types
from art_creator.agent import root_agent
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
app = FastAPI(title="Art Agent - Simple Chat")
class ChatRequest(BaseModel):
prompt: str
session_id: str = "default_session"
static_dir = os.path.join(os.path.dirname(__file__), "static")
os.makedirs(static_dir, exist_ok=True)
runner = InMemoryRunner(agent=root_agent)
runner.auto_create_session = True
@app.get("/api/artifacts/{session_id}/{filename}")
async def get_artifact(session_id: str, filename: str):
user_id = "default_user"
part = await runner.artifact_service.load_artifact(
app_name=runner.app_name,
user_id=user_id,
filename=filename,
session_id=session_id
)
if not part:
raise HTTPException(status_code=404, detail="Artifact not found")
if part.inline_data:
from fastapi.responses import Response
return Response(content=part.inline_data.data, media_type=part.inline_data.mime_type)
raise HTTPException(status_code=400, detail="Unsupported artifact format")
@app.post("/api/chat")
async def chat_endpoint(request: ChatRequest):
if not request.prompt.strip():
raise HTTPException(status_code=400, detail="Prompt cannot be empty")
user_id = "default_user"
content = types.Content(
role="user",
parts=[types.Part.from_text(text=request.prompt)]
)
full_response_text = ""
try:
async for event in runner.run_async(
user_id=user_id,
session_id=request.session_id,
new_message=content,
run_config=RunConfig(save_input_blobs_as_artifacts=True),
):
if event.content and event.content.parts:
if event.author != "user":
for part in event.content.parts:
if part.text:
full_response_text += part.text
elif part.inline_data:
try:
# Process raw binary/custom text parts (A2UI callback packages)
text_data = part.inline_data.data.decode("utf-8")
full_response_text += text_data
except Exception:
pass
except Exception as e:
logger.exception("Error running ADK agent:")
raise HTTPException(status_code=500, detail=str(e))
image_url = None
try:
artifact_keys = await runner.artifact_service.list_artifact_keys(
app_name=runner.app_name,
user_id=user_id,
session_id=request.session_id
)
image_keys = [k for k in artifact_keys if k.startswith("image_") and k.endswith(".png")]
if image_keys:
sorted_keys = sorted(image_keys, reverse=True)
image_url = f"/api/artifacts/{request.session_id}/{sorted_keys[0]}"
except Exception:
pass
return {
"text": full_response_text.strip(),
"image_url": image_url
}
app.mount("/static", StaticFiles(directory=static_dir), name="static")
@app.get("/")
async def read_index():
from fastapi.responses import FileResponse
return FileResponse(os.path.join(static_dir, "index.html"))
จากนั้นสร้างไดเรกทอรี static เพื่อจัดเก็บไฟล์ฟรอนท์เอนด์
mkdir -p static
ตอนนี้ให้เพิ่ม HTML ของหน้าแรก (static/index.html)
static/index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Art Agent - Simple Chat</title>
<link rel="stylesheet" href="/static/style.css">
</head>
<body>
<div class="container">
<div id="chat-messages" class="messages">
<div class="message system">
<strong>System:</strong> Welcome to the Art Agent! Describe the image you want to generate.
</div>
</div>
<form id="chat-form" class="input-form">
<input type="text" id="user-input" placeholder="Type image description..." autocomplete="off" required>
<button type="submit">Generate</button>
</form>
</div>
<script src="/static/app.js"></script>
</body>
</html>
และ CSS การจัดรูปแบบ (static/style.css)
static/style.css
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
background-color: #f7f9fa;
margin: 0;
padding: 20px;
display: flex;
justify-content: center;
}
.container {
width: 100%;
max-width: 600px;
background: #ffffff;
border: 1px solid #e1e8ed;
border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.05);
display: flex;
flex-direction: column;
height: 80vh;
}
.messages {
flex: 1;
overflow-y: auto;
padding: 20px;
display: flex;
flex-direction: column;
gap: 12px;
}
.message {
padding: 10px 14px;
border-radius: 6px;
max-width: 85%;
line-height: 1.4;
word-wrap: break-word;
}
.message.user {
background-color: #e8f5fe;
align-self: flex-end;
}
.message.agent {
background-color: #f1f3f4;
align-self: flex-start;
}
.message.system {
background-color: #fff;
border: 1px solid #e1e8ed;
color: #657786;
align-self: center;
font-size: 13px;
text-align: center;
}
.input-form {
display: flex;
border-top: 1px solid #e1e8ed;
padding: 12px;
}
.input-form input {
flex: 1;
border: 1px solid #ccc;
border-radius: 4px;
padding: 10px;
font-size: 14px;
outline: none;
}
.input-form button {
background-color: #1da1f2;
color: white;
border: none;
border-radius: 4px;
padding: 10px 16px;
margin-left: 8px;
font-size: 14px;
font-weight: bold;
cursor: pointer;
}
.input-form button:hover {
background-color: #1a91da;
}
.generated-img {
max-width: 100%;
border-radius: 4px;
margin-top: 8px;
display: block;
}
.image-card {
border: 1px solid #ddd;
border-radius: 6px;
padding: 12px;
background-color: #fff;
margin-top: 8px;
}
.btn-download {
background-color: #1da1f2;
color: white;
border: none;
border-radius: 4px;
padding: 8px 12px;
font-size: 13px;
font-weight: bold;
cursor: pointer;
margin-top: 8px;
width: 100%;
}
สุดท้าย ให้เพิ่มตัวควบคุม JavaScript (static/app.js)
static/app.js
document.addEventListener('DOMContentLoaded', () => {
const chatForm = document.getElementById('chat-form');
const userInput = document.getElementById('user-input');
const chatMessages = document.getElementById('chat-messages');
const sessionId = "session_" + Math.random().toString(36).substring(2, 9);
chatForm.addEventListener('submit', async (e) => {
e.preventDefault();
const prompt = userInput.value.trim();
if (!prompt) return;
userInput.value = '';
appendMessage('user', prompt);
const tempBubble = appendMessage('agent', '...');
try {
const response = await fetch('/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ prompt, session_id: sessionId })
});
const data = await response.json();
tempBubble.remove();
const textValue = (data && typeof data === 'object' && data.text) ? data.text : "";
const imageUrl = (data && typeof data === 'object' && data.image_url) ? data.image_url : null;
appendMessage('agent', textValue, imageUrl);
} catch (error) {
tempBubble.remove();
appendMessage('agent', `Error: ${error.message}`);
}
});
function appendMessage(sender, text, imageUrl = null) {
const bubble = document.createElement('div');
bubble.className = `message ${sender}`;
const content = document.createElement('span');
content.innerHTML = `<strong>${sender === 'user' ? 'You' : 'Agent'}:</strong> `;
const textNode = document.createTextNode(text);
content.appendChild(textNode);
bubble.appendChild(content);
// Always format multi-line JSON blocks nicely if the message is from the agent and looks like JSON
if (sender === 'agent' && text && (text.startsWith('{') || text.startsWith('['))) {
bubble.style.fontFamily = 'monospace';
bubble.style.whiteSpace = 'pre-wrap';
bubble.style.fontSize = '12px';
}
if (imageUrl) {
const card = document.createElement('div');
card.className = 'image-card';
const img = document.createElement('img');
img.src = imageUrl;
img.className = 'generated-img';
card.appendChild(img);
const dlBtn = document.createElement('button');
dlBtn.className = 'btn-download';
dlBtn.textContent = 'Download PNG';
dlBtn.onclick = () => {
const link = document.createElement('a');
link.href = imageUrl;
link.download = `generation-${Date.now()}.png`;
link.click();
};
card.appendChild(dlBtn);
bubble.appendChild(card);
}
chatMessages.appendChild(bubble);
chatMessages.scrollTop = chatMessages.scrollHeight;
return bubble;
}
});
ทดสอบเว็บแอปโดยเริ่มเซิร์ฟเวอร์ FastAPI
uv run python -m uvicorn main:app --port 8080 --host 0.0.0.0
ใช้ตัวอย่างเว็บ บนพอร์ต 8080 เพื่อเข้าถึงแชทที่กำหนดเอง ตอนนี้คุณสามารถพูดคุยกับ Agent ได้โดยตรง
5. กำหนดค่า Agent ให้ส่งข้อความ A2UI
ตอนนี้มาอัปเดต Agent ให้แสดงผล UI ที่มีโครงสร้างแทนที่จะเป็นข้อความเท่านั้น เราจะใช้ a2ui-agent-sdk อย่างเป็นทางการเพื่อสร้างข้อความแจ้งระบบที่รับรู้ A2UI สำหรับ Agent
เมื่อใช้ A2UI SDK เราจะใช้คลาส A2uiSchemaManager ซึ่งจะจัดโครงสร้างข้อความแจ้งระบบของ Agent เพื่อให้เข้าใจความสามารถในการสร้างอินเทอร์เฟซของ A2UI รวมถึงการให้สิทธิ์เข้าถึงแคตตาล็อกคอมโพเนนต์ สคีมาคอมโพเนนต์แบบเต็ม และตัวอย่างการใช้งาน (หากมี) แทนที่จะกำหนดคำแนะนำของ Agent โดยตรง
- ขั้นแรก ให้หยุดเซิร์ฟเวอร์ FastAPI ด้วย Ctrl+C
- แก้ไข
art_creator/agent.pyเพื่อผสานรวมA2uiSchemaManagerและฮุกa2ui_callbackใหม่
art_creator/agent.py
import os
import time
from google.adk.agents.llm_agent import Agent
from google.adk.tools.tool_context import ToolContext
from google.genai import types
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
# Load env variables
from dotenv import load_dotenv
load_dotenv(os.path.join(os.path.dirname(__file__), ".env"))
async def generate_image(prompt: str, tool_context: ToolContext) -> dict:
"""Generates a high-quality image based on the user's detailed description prompt."""
from google.genai import Client
client = Client(
vertexai=True,
project=os.environ.get("GOOGLE_CLOUD_PROJECT"),
location=os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
)
try:
response = client.models.generate_content(
model="gemini-3.1-flash-image",
contents=prompt,
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
)
)
image_bytes = None
for part in response.parts or []:
if part.inline_data is not None:
image_bytes = part.inline_data.data
break
if not image_bytes:
return {"status": "failed", "detail": "No image data returned"}
filename = f"image_{int(time.time())}.png"
await tool_context.save_artifact(
filename,
types.Part.from_bytes(data=image_bytes, mime_type='image/png'),
)
return {
"status": "success",
"filename": filename,
"url": f"/api/artifacts/{tool_context.session.id}/{filename}"
}
except Exception as e:
return {"status": "failed", "detail": str(e)}
schema_manager = A2uiSchemaManager(
version="0.8",
catalogs=[BasicCatalog.get_config("0.8")],
)
instruction = schema_manager.generate_system_prompt(
role_description=(
"You are a specialized Image Creator agent. "
"When given an image description, analyze the prompt and ask the user for any missing details. "
"The image generation prompt should include: "
"Subject, environment, style, lighting, color and mood. "
),
workflow_description=(
"1. if the user greets you, greet the user back explaining your purpose. "
"2. if the user describes an image, DO NOT GENERATE IT IMMEDIATELY: compare with "
" the ideal generation prompt and ask the user for any missing details using "
" rich A2UI UI elements only. NOTE: only run this step once per image, if the user "
" decides to not detail one or more elements it is ok. "
"3. combine the original prompt with the responses in the UI elements and call `generate_image` "
" with the generated prompt. "
" DO NOT INCLUDE EXAMPLES IN THE GENERATED PROMPT, ONLY THE ELEMENTS THE USER ASKED FOR. "
"4. display the resulting image to the user in a card including the image, the prompt and a "
" download button"
),
ui_description=(
"Use Card, Text, Image, Multichoice and Button components to present the options. "
"Always include a single choice selection box for image resolution (1K, 2K or 4K) and one for "
"aspect ratio (1:1, 16:9 or 9:16). "
"When rendering the final output (generated image) always render the generated image using an "
"Image component with the url bound to the image's URL/path returned by the tool. "
"Add a Text component with the prompt that generated the image. "
"Include a Button component labeled 'Download PNG' to allow downloading the image. "
"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,
)
root_agent = Agent(
model="gemini-3.5-flash",
name="art_agent_a2ui",
instruction=instruction,
tools=[generate_image],
)
โปรดสังเกตว่าตอนนี้คำแนะนำของ Agent จะสร้างขึ้นโดยการเรียก schema_manager.generate_system_prompt แทนที่จะฮาร์ดโค้ดไว้ในการกำหนด Agent
ทดสอบเว็บแอปโดยเริ่มเซิร์ฟเวอร์ FastAPI
uv run python -m uvicorn main:app --port 8080 --host 0.0.0.0
ใช้ตัวอย่างเว็บ บนพอร์ต 8080 เพื่อเข้าถึงแชทที่กำหนดเอง คุณจะสังเกตเห็นว่าตอนนี้ Agent กำลังส่งข้อความ JSON แทนที่จะเป็นข้อความปกติ ซึ่งเป็นการแสดงภายในขององค์ประกอบ A2UI ที่เราจะแสดงผลในส่วนถัดไป
6. สร้างฟรอนท์เอนด์ที่กำหนดเองสำหรับ Agent
ในขั้นตอนนี้ ไคลเอ็นต์จะได้รับรายการข้อความ A2UI ที่ชัดเจน (beginRendering, surfaceUpdate และ dataModelUpdate) ตอนนี้เราจะสร้างเครื่องมือแสดงผลฝั่งไคลเอ็นต์ที่กำหนดเองใน JavaScript ธรรมดาเพื่อดูคอมโพเนนต์เหล่านี้ในการทำงาน
นี่คือ static/app.js ที่สมบูรณ์พร้อมตรรกะการแยกวิเคราะห์และการแสดงผล A2UI
static/app.js
document.addEventListener('DOMContentLoaded', () => {
const chatForm = document.getElementById('chat-form');
const userInput = document.getElementById('user-input');
const chatMessages = document.getElementById('chat-messages');
const sessionId = "session_" + Math.random().toString(36).substring(2, 9);
async function sendChat(prompt, showInUi = true) {
if (!prompt) return;
if (showInUi) {
appendMessage('user', prompt);
}
const tempBubble = appendMessage('agent', '...');
try {
const response = await fetch('/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ prompt, session_id: sessionId })
});
const data = await response.json();
tempBubble.remove();
let text = data.text || "";
let a2uiMessages = [];
// 1. Extract <a2ui-json> blocks
const a2uiRegex = /<a2ui-json>(.*?)<\/a2ui-json>/gs;
let match;
while ((match = a2uiRegex.exec(text)) !== null) {
try {
const jsonStr = match[1].trim();
const parsed = JSON.parse(jsonStr);
const parsedList = Array.isArray(parsed) ? parsed : [parsed];
for (const msg of parsedList) {
if (msg && typeof msg === 'object') {
a2uiMessages.push(msg);
}
}
} catch (e) {
console.error("Error parsing <a2ui-json> block:", e);
}
}
// 2. Extract <a2a_datapart_json> blocks (for robust history/callback parsing)
const a2aRegex = /<a2a_datapart_json>(.*?)<\/a2a_datapart_json>/gs;
while ((match = a2aRegex.exec(text)) !== null) {
try {
const jsonStr = match[1].trim();
const parsed = JSON.parse(jsonStr);
const dataMsg = (parsed && parsed.kind === 'data') ? parsed.data : parsed;
if (dataMsg && typeof dataMsg === 'object') {
a2uiMessages.push(dataMsg);
}
} catch (e) {
console.error("Error parsing <a2a_datapart_json> block:", e);
}
}
// 3. Clean XML and A2UI JSON tags from displayed conversational text
const cleanText = text.replace(/<(a2ui-json|a2a_datapart_json)>.*?<\/\1>/gs, '').trim();
const imageUrl = (data && typeof data === 'object' && data.image_url) ? data.image_url : null;
appendMessage('agent', cleanText, imageUrl, a2uiMessages);
} catch (error) {
tempBubble.remove();
appendMessage('agent', `Error: ${error.message}`);
}
}
chatForm.addEventListener('submit', async (e) => {
e.preventDefault();
const prompt = userInput.value.trim();
if (!prompt) return;
userInput.value = '';
await sendChat(prompt, true);
});
function renderA2UI(a2uiMessages) {
try {
let rootId = null;
const components = {};
const dataModel = {};
for (const msg of a2uiMessages) {
if (msg.beginRendering) {
rootId = msg.beginRendering.root;
} else if (msg.surfaceUpdate) {
for (const item of msg.surfaceUpdate.components) {
components[item.id] = item.component;
}
} else if (msg.dataModelUpdate) {
for (const item of msg.dataModelUpdate.contents) {
const val = item.valueString !== undefined ? item.valueString :
item.valueBool !== undefined ? item.valueBool :
item.valueInt !== undefined ? item.valueInt :
item.valueDouble !== undefined ? item.valueDouble : item.valueString;
dataModel[item.key] = val;
}
}
}
if (!rootId || Object.keys(components).length === 0) {
return null;
}
function resolveValue(valObj) {
if (!valObj) return '';
let val = '';
if (typeof valObj === 'string') val = valObj;
else if (valObj.literalString !== undefined) val = valObj.literalString;
else if (valObj.path !== undefined) val = dataModel[valObj.path] || '';
else val = JSON.stringify(valObj);
// Dynamically replace any wrong session IDs in artifact URLs with the active sessionId
if (typeof val === 'string' && val.includes('/api/artifacts/')) {
val = val.replace(/\/api\/artifacts\/session_[a-z0-9]+/g, `/api/artifacts/${sessionId}`);
}
return val;
}
function buildElement(id) {
try {
const compDesc = components[id];
if (!compDesc) return null;
const type = Object.keys(compDesc)[0];
const props = compDesc[type];
const el = document.createElement('div');
el.className = `a2ui-component a2ui-${type.toLowerCase()}`;
el.style.margin = '4px 0';
if (type === 'Column') {
el.style.display = 'flex';
el.style.flexDirection = 'column';
el.style.gap = '8px';
const children = props.children?.explicitList || [];
for (const childId of children) {
const childEl = buildElement(childId);
if (childEl) el.appendChild(childEl);
}
} else if (type === 'Row') {
el.style.display = 'flex';
el.style.flexDirection = 'row';
el.style.gap = '8px';
el.style.alignItems = 'center';
const children = props.children?.explicitList || [];
for (const childId of children) {
const childEl = buildElement(childId);
if (childEl) el.appendChild(childEl);
}
} else if (type === 'Card') {
el.style.border = '1px solid #ddd';
el.style.borderRadius = '6px';
el.style.padding = '12px';
el.style.backgroundColor = '#fdfdfd';
el.style.marginTop = '8px';
if (props.child) {
const childEl = buildElement(props.child);
if (childEl) el.appendChild(childEl);
}
} else if (type === 'Text') {
const textVal = resolveValue(props.text);
const tag = props.usageHint === 'h1' ? 'h3' :
props.usageHint === 'h2' ? 'h4' : 'p';
const textEl = document.createElement(tag);
textEl.textContent = textVal;
textEl.style.margin = '0 0 4px 0';
el.appendChild(textEl);
} else if (type === 'Image') {
const srcVal = resolveValue(props.url) || resolveValue(props.src);
const imgEl = document.createElement('img');
imgEl.src = srcVal;
imgEl.style.maxWidth = '100%';
imgEl.style.borderRadius = '4px';
imgEl.style.display = 'block';
imgEl.style.marginTop = '6px';
imgEl.className = 'generated-img';
el.appendChild(imgEl);
} else if (type === 'Divider') {
const hrEl = document.createElement('hr');
hrEl.style.border = '0';
hrEl.style.borderTop = '1px solid #eee';
hrEl.style.margin = '12px 0';
el.appendChild(hrEl);
} else if (type === 'MultipleChoice') {
const labelVal = resolveValue(props.label);
const options = props.options?.explicitList || (Array.isArray(props.options) ? props.options : []);
const container = document.createElement('div');
container.style.display = 'flex';
container.style.flexDirection = 'column';
container.style.gap = '4px';
container.style.margin = '8px 0';
if (labelVal) {
const labelEl = document.createElement('label');
labelEl.textContent = labelVal;
labelEl.style.fontSize = '12px';
labelEl.style.fontWeight = 'bold';
container.appendChild(labelEl);
}
const selectEl = document.createElement('select');
selectEl.className = 'a2ui-select';
selectEl.name = id;
for (const option of options) {
const optEl = document.createElement('option');
optEl.value = option.value !== undefined ? option.value : (option.id !== undefined ? option.id : '');
optEl.textContent = resolveValue(option.label);
selectEl.appendChild(optEl);
}
container.appendChild(selectEl);
el.appendChild(container);
} else if (type === 'Button') {
let labelVal = props.label ? resolveValue(props.label) : '';
if (!labelVal && props.child) {
const childComp = components[props.child];
if (childComp && childComp.Text) {
labelVal = resolveValue(childComp.Text.text);
}
}
const btnEl = document.createElement('button');
btnEl.className = 'btn-download';
btnEl.textContent = labelVal || 'Submit';
btnEl.addEventListener('click', (e) => {
e.preventDefault();
const action = props.action;
let downloadUrl = null;
if (action && (action.name === 'download_file' || action.name === 'download') && action.context) {
const urlContext = action.context.find(ctx => ctx.key === 'url');
if (urlContext) {
downloadUrl = resolveValue(urlContext.value);
}
}
const isDownload = downloadUrl || (labelVal && labelVal.toLowerCase().includes('download'));
if (isDownload) {
const finalUrl = downloadUrl || (el.closest('.message')?.querySelector('img')?.src);
if (finalUrl) {
const link = document.createElement('a');
link.href = finalUrl;
link.download = `generation-${Date.now()}.png`;
link.click();
}
} else {
const bubbleEl = el.closest('.message');
const selects = bubbleEl.querySelectorAll('.a2ui-select');
let answers = [];
selects.forEach(sel => {
let labelText = sel.previousSibling ? sel.previousSibling.textContent : sel.name;
const selectedText = sel.options[sel.selectedIndex]?.textContent || sel.value;
answers.push(`- ${labelText}: ${selectedText}`);
});
if (answers.length > 0) {
const responseText = `Selected options:\n` + answers.join('\n');
sendChat(responseText, false);
} else {
sendChat(labelVal || 'Submit', false);
}
}
});
el.appendChild(btnEl);
}
return el;
} catch (err) {
console.error('Error building component:', id, err);
return null;
}
}
return buildElement(rootId);
} catch (err) {
console.error('Error in renderA2UI:', err);
return null;
}
}
function appendMessage(sender, text, imageUrl = null, a2ui = null) {
const bubble = document.createElement('div');
bubble.className = `message ${sender}`;
const textSpan = document.createElement('span');
textSpan.innerHTML = `<strong>${sender === 'user' ? 'You' : 'Agent'}:</strong> `;
bubble.appendChild(textSpan);
if (text) {
const textContent = document.createTextNode(text);
textSpan.appendChild(textContent);
}
if (sender === 'agent' && a2ui && a2ui.length > 0) {
const a2uiEl = renderA2UI(a2ui);
if (a2uiEl) {
bubble.appendChild(a2uiEl);
}
}
if (imageUrl) {
const imgContainer = document.createElement('div');
imgContainer.style.marginTop = '8px';
const img = document.createElement('img');
img.src = imageUrl;
img.style.maxWidth = '100%';
img.style.borderRadius = '4px';
img.className = 'generated-img';
imgContainer.appendChild(img);
bubble.appendChild(imgContainer);
}
chatMessages.appendChild(bubble);
chatMessages.scrollTop = chatMessages.scrollHeight;
return bubble;
}
});
เริ่มเซิร์ฟเวอร์แอป FastAPI อีกครั้ง
uv run python -m uvicorn main:app --port 8080 --host 0.0.0.0
และพูดคุยกับ Agent สร้างงานศิลปะ A2UI แบบไดนามิกอย่างเต็มรูปแบบ
7. ยินดีด้วย
คุณได้สร้าง Agent ADK ที่สร้างองค์ประกอบ UI แบบไดนามิกโดยใช้ A2UI คุณสามารถเดินทางเพื่อการเรียนรู้ต่อไปได้โดยสำรวจการผสานรวมเฟรมเวิร์กที่หลากหลาย หรือสำรวจเอกสารประกอบในข้อมูลอ้างอิงด้านล่าง
สร้างฟรอนท์เอนด์ที่ใช้งานจริง
ในเวิร์กช็อปนี้ เราใช้ฟรอนท์เอนด์ JS ธรรมดาที่สร้างขึ้นเองเพื่อวัตถุประสงค์ด้านการสอน แต่สำหรับการใช้งานจริง คุณจะต้องสร้างฟรอนท์เอนด์โดยใช้เครื่องมือแสดงผล 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 |