عرض مساحات A2UI في تطبيقك

عند استخدام أداة العرض من وكيل الذكاء الاصطناعي إلى واجهة المستخدم (A2UI) في Jetpack Compose، يرسل وكيل الذكاء الاصطناعي رسائل تصف بنى واجهة المستخدم وخصائص المكوّنات وتعديلات البيانات. لعرض هذه الواجهات بشكل أصلي في تطبيقك، عليك استضافة وعرض مساحة A2UI ضمن التسلسل الهرمي لـ Jetpack Compose في تطبيقك.

يُنسّق عارض A2UI في Compose عملية تحليل الرسائل وإدارة حالة اللقطة التفاعلية وانتقالات حالة مساحة العرض المتحرّكة. مع أنّ أداة العرض الأساسية مستقلة عن أي نظام تصميم محدّد، إلا أنّها توفّر إمكانية دمج جاهزة مع التصميم المتعدد الأبعاد 3 من خلال "الكتالوج الأساسي" المتوفّر.

تهيئة طبقة البيانات المستندة إلى 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)
    }
}

عرض الأسطح باستخدام "الفهرس الأساسي" (Material 3)

عند عرض مساحات العرض باستخدام عملية تنفيذ &quot;الكتالوج الأساسي&quot; المتوفّرة (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 تستند إلى وكلاء نماذج لغوية كبيرة توليدية، يمكن أن تكون الحِملات الواردة غير صالحة أو تشير إلى أنواع مكوّنات غير معروفة.

يضع برنامج العرض حدودًا وقائية على النحو التالي للحدّ من احتمالية حدوث أعطال:

  • إرسال الخطأ لتصحيحه ذاتيًا من قِبل المساعد الافتراضي: يتم إرسال الأخطاء كرسائل صادرة من العميل، ما يتيح للمساعد الافتراضي تصحيحها ذاتيًا في جولات التفاعل اللاحقة. تتوفّر أيضًا واجهة برمجة تطبيقات تتيح عمليات تنفيذ المكوّنات إرسال الأخطاء إلى الوكيل في الحالات التي ترصد فيها واجهة برمجة التطبيقات أخطاء خاصة بالمكوّن في الوقت المستغرَق للعرض.
  • المكوّنات غير المعروفة: عند مواجهة نوع مكوّن غير معروف، يتم اعتراض المكوّن قبل وصوله إلى شجرة واجهة المستخدم، ويتم وضع علامة عليه كحالة خطأ، ويتم إرسال تقرير إلى البرنامج الوكيل لتصحيح الخطأ تلقائيًا.
  • أخطاء التحقّق من صحة المخطط: يتم التحقّق من صحة الحِزم استنادًا إلى مخططات المكوّنات (A2uiSchema)، ويجب ألا تصل الخصائص المشوّهة إلى تنسيقات واجهة مستخدم Compose.
  • الحماية من المصفوفات المتفرقة: عند تلقّي فهارس قوائم كبيرة جدًا، ينتقل نموذج البيانات من قائمة كثيفة إلى خريطة متفرقة قابلة للتكيّف، ما يمنع حدوث أخطاء نفاد الذاكرة.