Uygulamanızda A2UI yüzeylerini oluşturma

Jetpack Compose agent-to-UI (A2UI) oluşturucuyu kullanırken bir yapay zeka aracısı, kullanıcı arayüzü yapılarını, bileşen özelliklerini ve veri güncellemelerini açıklayan mesajlar gönderir. Bu arayüzleri uygulamanızda yerel olarak göstermek için uygulamanızın Jetpack Compose hiyerarşisinde bir A2UI yüzeyi barındırır ve oluşturursunuz.

Compose A2UI oluşturucusu, mesaj ayrıştırma, reaktif anlık görüntü durumu yönetimi ve animasyonlu yüzey durumu geçişlerini koordine eder. Temel oluşturucu, belirli bir tasarım sisteminden bağımsız olsa da sağlanan Temel Katalog aracılığıyla Material Design 3 ile kullanıma hazır entegrasyon sunar.

Compose destekli veri katmanını başlatma

A2UI oluşturucu, uygulamanızın veri katmanında anlık görüntüye duyarlı durumu destekler. Bu sayede, uygulamanızın kullanıcı arayüzü, temsilciden gelen artımlı güncellemelere tepki verebilir. Bu desteği eklemek için ayrıştırıcıyı ve işlemciyi ViewModel dosyanızda A2uiMessageParser ve A2uiMessageProcessor fabrika işlevlerini kullanarak başlatın. Aşağıdaki kod snippet'inde gösterildiği gibi:

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)
    }
}

Temel Katalog'u (Material 3) kullanarak yüzeyleri oluşturma

Sağlanan Basic Catalog uygulaması (androidx.compose.material3:material3-a2ui) kullanılarak yüzeyler oluşturulurken, yükleme göstergeleri, hata sınırları ve animasyonlu geçişler için yerleşik destek de dahil olmak üzere tamamen stilize edilmiş bir Material 3 yüzeyi oluşturabilirsiniz. Bunu yapmak için A2uiSurface birleştirilebilir giriş noktasını kullanın:

@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.
                )
            }
        }
    }
}

Yüzey durumlarını ve animasyonlu geçişleri işleme

A2uiSurface, kök bileşen durumu çözümlemesini koordine eder ve yükleme, hata ve başarılı durumlar arasında AnimatedContent geçişlerini uygular:

@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))
        },
    )
}

Özel yönlendiricilerle düşük düzeyde yüzey oluşturma

Yüzey kök bileşen durumunu doğrudan observeA2uiComponentState ile gözlemleyebilir ve oluşturma işlemini A2uiComponent'ye devredebilirsiniz:

@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.
                )
            }
        }
    }
}

Uygulama ayrıntıları

Aracıdan kullanıcı arayüzü oluşturucuya, yüzey durumu çözünürlüğünü ve savunma amaçlı hata sınırlarını yönetir.

Savunma amaçlı hata sınırları ve aracı halüsinasyonlarını işleme

A2UI yüzeyleri, üretken LLM aracıları tarafından desteklendiğinden gelen yükler hatalı olabilir veya bilinmeyen bileşen türlerine referans verebilir.

Oluşturucu, kilitlenme olasılığını en aza indirmek için aşağıdaki savunma sınırlarını oluşturur:

  • Aracının kendi kendini düzeltmesi için hata gönderme: Hatalar giden istemci mesajları olarak gönderilir. Böylece aracı, sonraki etkileşim dönüşlerinde kendi kendini düzeltebilir. Ayrıca, API'nin oluşturma sırasında bileşene özgü hatalar tespit ettiği durumlarda bileşen uygulamalarının aracıya hata göndermesine olanak tanıyan bir API de vardır.
  • Bilinmeyen bileşenler: Tanınmayan bir bileşen türüyle karşılaşıldığında, bu bileşen kullanıcı arayüzü ağacına ulaşmadan önce yakalanır, hata durumu olarak işaretlenir ve kendi kendini düzeltmesi için tekrar aracıya bildirilir.
  • Şema doğrulama hataları: Yükler, bileşen şemalarına (A2uiSchema) göre doğrulanır. Hatalı biçimlendirilmiş özellikler hiçbir zaman Compose kullanıcı arayüzü düzenlerine ulaşmamalıdır.
  • Seyrek dizi koruması: Çok büyük liste dizinleri alındığında, veri modeli yoğun bir listeden uyarlanabilir bir seyrek haritaya geçerek bellek yetersizliği hatalarını önler.