رندر سطوح A2UI در برنامه شما

هنگام استفاده از رندرکننده Jetpack Compose agent-to-UI (A2UI)، یک عامل هوش مصنوعی پیام‌هایی را ارسال می‌کند که ساختارهای رابط کاربری، ویژگی‌های کامپوننت و به‌روزرسانی‌های داده‌ها را توصیف می‌کنند. برای نمایش این رابط‌ها به صورت بومی در برنامه خود، شما یک سطح A2UI را در سلسله مراتب Jetpack Compose برنامه خود میزبانی و رندر می‌کنید.

رندرکننده Compose A2UI، تجزیه پیام، مدیریت وضعیت snapshot واکنشی و انتقال وضعیت سطوح متحرک را هماهنگ می‌کند. در حالی که رندرکننده اصلی مستقل از هر سیستم طراحی خاصی است، از طریق کاتالوگ پایه ارائه شده، ادغام آماده با Material Design 3 را ارائه می‌دهد.

لایه داده پشتیبانی شده توسط Compose را مقداردهی اولیه کنید

رندرکننده A2UI از حالت snapshot-aware در لایه داده برنامه شما پشتیبانی می‌کند، که به رابط کاربری برنامه شما اجازه می‌دهد تا به به‌روزرسانی‌های افزایشی از عامل واکنش نشان دهد. برای افزودن این پشتیبانی، تجزیه‌کننده و پردازنده را با استفاده از توابع کارخانه‌ای 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)
    }
}

رندر سطوح با استفاده از کاتالوگ پایه (متریال ۳)

هنگام رندر کردن سطوح با استفاده از پیاده‌سازی کاتالوگ پایه ارائه شده ( 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))
        },
    )
}

رندرینگ سطح پایین با روترهای سفارشی

توجه: این سفارشی‌سازی برای برنامه‌هایی است که از سیستم‌های طراحی جایگزین یا سفارشی استفاده می‌کنند، و همچنین برنامه‌هایی که به کنترل سطح پایین نیاز دارند.

شما می‌توانید وضعیت کامپوننت ریشه سطحی را مستقیماً با 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.
                )
            }
        }
    }
}

جزئیات پیاده‌سازی

رندرکننده‌ی عامل به رابط کاربری، تفکیک وضعیت سطح و مرزهای خطای دفاعی را مدیریت می‌کند.

مرزهای خطای دفاعی و مدیریت توهم عامل

از آنجا که سطوح A2UI توسط عامل‌های مولد LLM هدایت می‌شوند، بارهای ورودی می‌توانند ناقص باشند یا به انواع اجزای ناشناخته ارجاع دهند.

رندرکننده مرزهای دفاعی زیر را برای به حداقل رساندن احتمال خرابی‌ها تعیین می‌کند:

• ارسال خطا برای خود-تصحیح‌گری عامل : خطاها به عنوان پیام‌های کلاینت خروجی ارسال می‌شوند و به عامل اجازه می‌دهند تا در نوبت‌های تعامل بعدی خود-تصحیح‌گری کند. همچنین یک API وجود دارد که به پیاده‌سازی‌های کامپوننت اجازه می‌دهد در مواردی که API خطاهای خاص کامپوننت را در زمان رندر تشخیص می‌دهد، خطاها را به عامل ارسال کند.
• اجزای ناشناخته : وقتی با یک نوع جزء ناشناخته مواجه می‌شویم، قبل از رسیدن به درخت رابط کاربری، آن را رهگیری می‌کنیم، به عنوان یک حالت خطا علامت‌گذاری می‌کنیم و برای اصلاح خودکار به عامل گزارش می‌دهیم.
• خطاهای اعتبارسنجی طرحواره : بارهای داده (Payloads) در برابر طرحواره‌های کامپوننت ( A2uiSchema ) اعتبارسنجی می‌شوند. ویژگی‌های ناقص هرگز نباید به طرح‌بندی‌های رابط کاربری Compose برسند.
• محافظت در برابر آرایه‌های پراکنده : وقتی فهرست‌های بسیار بزرگی دریافت می‌شوند، مدل داده از یک فهرست متراکم به یک نگاشت پراکنده تطبیقی ​​منتقل می‌شود و از خطاهای کمبود حافظه جلوگیری می‌کند.