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

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

پردازنده Compose A2UI تجزیه پیام، مدیریت حالت عکس آنی واکنشی، و انتقال حالت سطح پویانمایی‌شده را هماهنگ می‌کند. درحالی‌که موتور پردازش اصلی مستقل از هر سیستم طراحی خاصی است، ازطریق «کاتالوگ پایه» ارائه‌شده، ادغام آماده استفاده با «طراحی مواد ۳» را ارائه می‌دهد.

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

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

Render surfaces using the Basic Catalog (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))
        },
    )
}

پرداخت سطح پایین با مسیریاب‌های سفارشی

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

می‌توانید وضعیت مؤلفه ریشه سطح را مستقیماً با 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 خطاهای خاص مؤلفه را در زمان پرداز زدن تشخیص می‌دهد.
• قطعات ناشناخته: وقتی نوع قطعه ناشناخته‌ای شناسایی می‌شود، قبل‌از رسیدن به درخت واسط کاربر رهگیری می‌شود، به‌عنوان حالت خطا علامت‌گذاری می‌شود، و برای اصلاح خودکار به عامل گزارش می‌شود.
• ناموفق بودن اعتبارسنجی طرح‌واره: بار داده‌ها دربرابر طرح‌واره‌های مؤلفه (A2uiSchema) اعتبارسنجی می‌شوند. ویژگی‌های بدشکل هرگز نباید به چیدمان‌های میانای کاربر Compose برسند.
• محافظت از آرایه پراکنده: وقتی نمایه‌های فهرست بسیار بزرگ دریافت می‌شود، مدل داده از فهرست متراکم به نقشه پراکنده تطبیقی منتقل می‌شود، که از خطاهای کمبود حافظه جلوگیری می‌کند.