Saat menggunakan perender agent-ke-UI (A2UI) Jetpack Compose, agen AI mengirim pesan yang menjelaskan struktur UI, properti komponen, dan update data. Untuk menampilkan antarmuka ini secara native di aplikasi, Anda menghosting dan merender permukaan A2UI dalam hierarki Jetpack Compose aplikasi Anda.
Renderer A2UI Compose mengoordinasikan penguraian pesan, pengelolaan status snapshot reaktif, dan transisi status permukaan animasi. Meskipun perender intinya independen dari sistem desain tertentu, perender ini menawarkan integrasi siap pakai dengan Desain Material 3 melalui Katalog Dasar yang disediakan.
Melakukan inisialisasi lapisan data yang didukung Compose
Renderer A2UI mendukung status yang kompatibel dengan snapshot di lapisan data aplikasi Anda, yang memungkinkan UI aplikasi Anda bereaksi terhadap update inkremental dari agen. Untuk menambahkan dukungan ini, lakukan inisialisasi parser dan pemroses menggunakan fungsi factory A2uiMessageParser dan A2uiMessageProcessor di ViewModel Anda, seperti yang ditunjukkan dalam cuplikan kode berikut:
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)
}
}
Merender platform menggunakan Katalog Dasar (Material 3)
Saat merender permukaan menggunakan implementasi Katalog Dasar yang disediakan
(androidx.compose.material3:material3-a2ui), Anda dapat merender permukaan Material 3 yang sepenuhnya bergaya, termasuk dukungan bawaan untuk indikator pemuatan, batas error, dan transisi animasi. Untuk melakukannya, gunakan titik entri composable 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.
)
}
}
}
}
Menangani status platform dan transisi animasi
Koordinat A2uiSurface menyelesaikan status komponen root dan menerapkan transisi
AnimatedContent di seluruh status pemuatan, error, dan berhasil:
@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))
},
)
}
Rendering permukaan tingkat rendah dengan router kustom
Anda dapat mengamati status komponen root permukaan secara langsung dengan
observeA2uiComponentState dan mendelegasikan rendering ke 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.
)
}
}
}
}
Detail implementasi
Perender agent-ke-UI menangani penyelesaian status permukaan dan batas kesalahan defensif.
Batas error defensif dan penanganan halusinasi agen
Karena platform A2UI didukung oleh agen LLM generatif, payload yang masuk dapat salah bentuk atau merujuk ke jenis komponen yang tidak diketahui.
Perender menetapkan batas pertahanan berikut untuk meminimalkan kemungkinan terjadinya error:
- Pengiriman error untuk koreksi mandiri agen: Error dikirim sebagai pesan klien keluar, sehingga agen dapat melakukan koreksi mandiri pada giliran interaksi berikutnya. Ada juga API yang memungkinkan penerapan komponen mengirim error ke agen jika API mendeteksi error khusus komponen pada waktu rendering.
- Komponen tidak dikenal: Saat jenis komponen yang tidak dikenal ditemukan, komponen tersebut dicegat sebelum mencapai hierarki UI, ditandai sebagai status error, dan dilaporkan kembali ke agen untuk mengoreksi diri sendiri.
- Kegagalan validasi skema: Payload divalidasi terhadap skema
komponen (
A2uiSchema). Properti yang salah format tidak boleh mencapai tata letak Compose UI. - Perlindungan array jarang: Saat indeks daftar yang sangat besar diterima, model data bertransisi dari daftar padat ke peta jarang adaptif, sehingga mencegah error kehabisan memori.