เมื่อใช้ตัวแสดงผล Agent-to-UI (A2UI) ของ Jetpack Compose AI Agent จะส่งข้อความที่อธิบายโครงสร้าง UI, พร็อพเพอร์ตี้ของคอมโพเนนต์ และการอัปเดตข้อมูล หากต้องการแสดงอินเทอร์เฟซเหล่านี้ในแอปโดยตรง คุณต้องโฮสต์และแสดงผล พื้นผิว A2UI ภายในลำดับชั้น Jetpack Compose ของแอป
ตัวแสดงผล A2UI ของ Compose จะประสานงานการแยกวิเคราะห์ข้อความ การจัดการสถานะสแนปชอตแบบรีแอกทีฟ และการเปลี่ยนสถานะของพื้นผิวที่เคลื่อนไหว แม้ว่าเครื่องมือแสดงผลหลักจะ ไม่ขึ้นอยู่กับระบบการออกแบบที่เฉพาะเจาะจง แต่ก็มีการผสานรวมสำเร็จรูป กับ Material Design 3 ผ่านแคตตาล็อกพื้นฐานที่ให้ไว้
เริ่มต้นเลเยอร์ข้อมูลที่ใช้ Compose
ตัวแสดงผล A2UI รองรับสถานะที่รับรู้สแนปชอตในเลเยอร์ข้อมูลของแอป ซึ่ง
ช่วยให้ UI ของแอปตอบสนองต่อการอัปเดตที่เพิ่มขึ้นจากตัวแทนได้ หากต้องการเพิ่มการรองรับนี้ ให้เริ่มต้นตัวแยกวิเคราะห์และตัวประมวลผลโดยใช้ฟังก์ชัน Factory A2uiMessageParser และ A2uiMessageProcessor ใน ViewModel ดังที่แสดงในข้อมูลโค้ดต่อไปนี้
class AgenticUiViewModel : ViewModel() {
// Create a parser that leverages the built-in JSON parser.
private val parser = A2uiMessageParser()
// Create an A2UI message processor with your catalog and optional
// action interceptor (implementing A2uiActionInterceptor).
private val processor = A2uiMessageProcessor(
// You can also use the provided Material catalog instead of
// a custom one.
catalogs = listOf(CustomDesignSystemCatalog)
)
// Expose active surfaces to the UI as a StateFlow.
val a2uiSurfaces: StateFlow<List<A2uiSurfaceModel>> =
processor.activeSurfaces
init {
// Collect messages on a background thread tied to the ViewModel lifecycle.
viewModelScope.launch(Dispatchers.Default) {
processor.collectMessages()
}
// Add support for two-way communication with the agent.
viewModelScope.launch(start = CoroutineStart.UNDISPATCHED) {
processor.outboundEvents.collect(::handleOutboundA2uiEvent)
}
}
// Called by your app's networking layer or business logic whenever
// a new A2UI protocol message arrives from the AI agent.
fun onNetworkMessage(json: String) {
processor.processInput(parser, json)
}
}
แสดงพื้นผิวโดยใช้แคตตาล็อกพื้นฐาน (Material 3)
เมื่อแสดงผลพื้นผิวโดยใช้การติดตั้งใช้งานแคตตาล็อกพื้นฐานที่ระบุ
(androidx.compose.material3:material3-a2ui) คุณจะแสดงผลพื้นผิว Material 3 ที่จัดรูปแบบอย่างเต็มที่
ได้ ซึ่งรวมถึงการรองรับตัวบ่งชี้การโหลด ข้อผิดพลาด
ขอบเขต และการเปลี่ยนภาพเคลื่อนไหวในตัว โดยใช้A2uiSurface
จุดแรกเข้าที่ประกอบได้
@Composable
fun AgenticUiScreen(viewModel: AgenticUiViewModel) {
// Observe active surfaces managed by the data layer.
val surfaces by viewModel.a2uiSurfaces.collectAsStateWithLifecycle()
Column(Modifier.fillMaxSize()) {
surfaces.forEach { surface ->
key(surface.id) {
A2uiSurface(
surfaceModel = surface,
// Add your surface's custom modifiers here.
)
}
}
}
}
จัดการสถานะพื้นผิวและการเปลี่ยนภาพเคลื่อนไหว
A2uiSurface จะประสานงานการแก้ปัญหาสถานะของคอมโพเนนต์รูทและใช้การเปลี่ยน AnimatedContent ในสถานะการโหลด ข้อผิดพลาด และสำเร็จ
@Composable
fun CustomStyledSurface(surface: A2uiSurfaceModel) {
A2uiSurface(
surfaceModel = surface,
modifier = Modifier.fillMaxSize(),
loadingContent = {
Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
CircularProgressIndicator()
}
},
errorContent = { exception ->
Text(
text = "Failed to load: ${exception.message}",
color = MaterialTheme.colorScheme.error,
// Add your custom error styling, such as modifiers, here.
)
},
transitionSpec = {
(fadeIn(animationSpec = tween(600)) togetherWith
fadeOut(animationSpec = tween(600)))
.using(SizeTransform(clip = false))
},
)
}
การแสดงผลพื้นผิวระดับต่ำด้วยเราเตอร์ที่กำหนดเอง
คุณสามารถสังเกตสถานะของคอมโพเนนต์รูทของ Surface ได้โดยตรงด้วย
observeA2uiComponentState และมอบสิทธิ์การแสดงผลให้กับ A2uiComponent
@Composable
fun RawSurfaceCoordinator(surface: A2uiSurfaceModel) {
// Extract the catalog to provide its readiness evaluator to the
// composition. This lets components wait for their dynamic data bindings
// before they're rendered.
val coreSurface = surface as? A2uiCoreSurfaceModel
?: throw IllegalArgumentException(
"Surface must implement A2uiCoreSurfaceModel")
val composeCatalog = coreSurface.catalog as? A2uiCatalog
?: throw IllegalArgumentException("Catalog must implement A2uiCatalog")
val readinessEvaluator = remember(composeCatalog) {
composeCatalog.asReadinessEvaluator() }
CompositionLocalProvider(
LocalA2uiReadinessEvaluator provides readinessEvaluator
) {
val rootState = observeA2uiComponentState(surface = surface)
when (rootState) {
is A2uiComponentState.Loading -> {
LoadingSpinner()
}
is A2uiComponentState.Error -> {
ErrorBanner(rootState.exception)
}
is A2uiComponentState.Success -> {
// Delegate component routing to the Compose A2UI router.
A2uiComponent(
component = rootState.component,
// Add your custom modifiers here.
)
}
}
}
}
รายละเอียดการติดตั้งใช้งาน
ตัวแสดงผลของ Agent ไปยัง UI จะจัดการการแก้ปัญหาเกี่ยวกับสถานะของพื้นผิวและขอบเขตข้อผิดพลาดเชิงรับ
ขอบเขตข้อผิดพลาดเชิงรับและการจัดการการหลอนของเอเจนต์
เนื่องจากแพลตฟอร์ม A2UI ขับเคลื่อนโดยเอเจนต์ LLM แบบ Generative เพย์โหลดขาเข้าจึงอาจมีรูปแบบไม่ถูกต้องหรืออ้างอิงประเภทคอมโพเนนต์ที่ไม่รู้จัก
โปรแกรมแสดงผลจะสร้างขอบเขตการป้องกันต่อไปนี้เพื่อลด โอกาสที่จะเกิดข้อขัดข้อง
- การส่งข้อผิดพลาดสำหรับการแก้ไขตนเองของ Agent: ระบบจะส่งข้อผิดพลาดเป็น ข้อความไคลเอ็นต์ขาออก ซึ่งช่วยให้ Agent แก้ไขตนเองได้ในการโต้ตอบ ครั้งต่อๆ ไป นอกจากนี้ ยังมี API ที่ช่วยให้การติดตั้งใช้งานคอมโพเนนต์ ส่งข้อผิดพลาดไปยังเอเจนต์ในกรณีที่ API ตรวจพบ ข้อผิดพลาดเฉพาะคอมโพเนนต์ในเวลาในการแสดงผล
- คอมโพเนนต์ที่ไม่รู้จัก: เมื่อพบประเภทคอมโพเนนต์ที่ไม่รู้จัก ระบบจะสกัดกั้นก่อนที่จะไปถึงโครงสร้าง UI ทำเครื่องหมายเป็นสถานะข้อผิดพลาด และรายงานกลับไปยังตัวแทนเพื่อแก้ไขด้วยตนเอง
- การตรวจสอบสคีมาไม่สำเร็จ: ระบบจะตรวจสอบเพย์โหลดกับสคีมาของคอมโพเนนต์ (
A2uiSchema) พร็อพเพอร์ตี้ที่มีรูปแบบไม่ถูกต้องไม่ควรไปถึงเลย์เอาต์ UI ของ Compose - การป้องกันอาร์เรย์แบบกระจัดกระจาย: เมื่อได้รับดัชนีรายการขนาดใหญ่มาก โมเดลข้อมูลจะเปลี่ยนจากรายการแบบหนาแน่นเป็นแมปแบบกระจัดกระจายที่ปรับเปลี่ยนได้ เพื่อป้องกันข้อผิดพลาดเกี่ยวกับหน่วยความจำไม่เพียงพอ