แสดงผลพื้นผิว A2UI ในแอป

เมื่อใช้ตัวแสดงผล Agent-to-UI (A2UI) ของ Jetpack Compose AI Agent จะส่งข้อความที่อธิบายโครงสร้าง UI, พร็อพเพอร์ตี้ของคอมโพเนนต์ และการอัปเดตข้อมูล หากต้องการแสดงอินเทอร์เฟซเหล่านี้ในแอปโดยตรง คุณต้องโฮสต์และแสดงผล พื้นผิว A2UI ภายในลำดับชั้น Jetpack Compose ของแอป

ตัวแสดงผล A2UI ของ Compose จะประสานงานการแยกวิเคราะห์ข้อความ การจัดการสถานะสแนปชอตแบบรีแอกทีฟ และการเปลี่ยนสถานะของพื้นผิวที่เคลื่อนไหว แม้ว่าเครื่องมือแสดงผลหลักจะ ไม่ขึ้นอยู่กับระบบการออกแบบที่เฉพาะเจาะจง แต่ก็มีการผสานรวมสำเร็จรูป กับ Material Design 3 ผ่านแคตตาล็อกพื้นฐานที่ให้ไว้

เริ่มต้นเลเยอร์ข้อมูลที่ใช้ Compose

ตัวแสดงผล A2UI รองรับสถานะที่รับรู้สแนปชอตในเลเยอร์ข้อมูลของแอป ซึ่ง ช่วยให้ UI ของแอปตอบสนองต่อการอัปเดตที่เพิ่มขึ้นจากตัวแทนได้ หากต้องการเพิ่มการรองรับนี้ ให้เริ่มต้นตัวแยกวิเคราะห์และตัวประมวลผลโดยใช้ฟังก์ชัน Factory 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)

เมื่อแสดงผลพื้นผิวโดยใช้การติดตั้งใช้งานแคตตาล็อกพื้นฐานที่ระบุ (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))
        },
    )
}

การแสดงผลพื้นผิวระดับต่ำด้วยเราเตอร์ที่กำหนดเอง

หมายเหตุ: การปรับแต่งนี้มีไว้สำหรับแอปที่ใช้ระบบการออกแบบทางเลือกหรือระบบการออกแบบที่กำหนดเอง รวมถึงแอปที่ต้องมีการควบคุมระดับต่ำด้วย

คุณสามารถสังเกตสถานะของคอมโพเนนต์รูทของ Surface ได้โดยตรงด้วย 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.
                )
            }
        }
    }
}

รายละเอียดการติดตั้งใช้งาน

ตัวแสดงผลของ Agent ไปยัง UI จะจัดการการแก้ปัญหาเกี่ยวกับสถานะของพื้นผิวและขอบเขตข้อผิดพลาดเชิงรับ

ขอบเขตข้อผิดพลาดเชิงรับและการจัดการการหลอนของเอเจนต์

เนื่องจากแพลตฟอร์ม A2UI ขับเคลื่อนโดยเอเจนต์ LLM แบบ Generative เพย์โหลดขาเข้าจึงอาจมีรูปแบบไม่ถูกต้องหรืออ้างอิงประเภทคอมโพเนนต์ที่ไม่รู้จัก

โปรแกรมแสดงผลจะสร้างขอบเขตการป้องกันต่อไปนี้เพื่อลด โอกาสที่จะเกิดข้อขัดข้อง

• การส่งข้อผิดพลาดสำหรับการแก้ไขตนเองของ Agent: ระบบจะส่งข้อผิดพลาดเป็น ข้อความไคลเอ็นต์ขาออก ซึ่งช่วยให้ Agent แก้ไขตนเองได้ในการโต้ตอบ ครั้งต่อๆ ไป นอกจากนี้ ยังมี API ที่ช่วยให้การติดตั้งใช้งานคอมโพเนนต์ ส่งข้อผิดพลาดไปยังเอเจนต์ในกรณีที่ API ตรวจพบ ข้อผิดพลาดเฉพาะคอมโพเนนต์ในเวลาในการแสดงผล
• คอมโพเนนต์ที่ไม่รู้จัก: เมื่อพบประเภทคอมโพเนนต์ที่ไม่รู้จัก ระบบจะสกัดกั้นก่อนที่จะไปถึงโครงสร้าง UI ทำเครื่องหมายเป็นสถานะข้อผิดพลาด และรายงานกลับไปยังตัวแทนเพื่อแก้ไขด้วยตนเอง
• การตรวจสอบสคีมาไม่สำเร็จ: ระบบจะตรวจสอบเพย์โหลดกับสคีมาของคอมโพเนนต์ (A2uiSchema) พร็อพเพอร์ตี้ที่มีรูปแบบไม่ถูกต้องไม่ควรไปถึงเลย์เอาต์ UI ของ Compose
• การป้องกันอาร์เรย์แบบกระจัดกระจาย: เมื่อได้รับดัชนีรายการขนาดใหญ่มาก โมเดลข้อมูลจะเปลี่ยนจากรายการแบบหนาแน่นเป็นแมปแบบกระจัดกระจายที่ปรับเปลี่ยนได้ เพื่อป้องกันข้อผิดพลาดเกี่ยวกับหน่วยความจำไม่เพียงพอ