Hiển thị các nền tảng A2UI trong ứng dụng của bạn

Khi sử dụng trình kết xuất tác nhân thành giao diện người dùng (A2UI) Jetpack Compose, một tác nhân AI sẽ gửi các thông báo mô tả cấu trúc giao diện người dùng, thuộc tính thành phần và nội dung cập nhật dữ liệu. Để hiển thị các giao diện này một cách tự nhiên trong ứng dụng, bạn sẽ lưu trữ và kết xuất một bề mặt A2UI trong hệ phân cấp Jetpack Compose của ứng dụng.

Trình kết xuất Compose A2UI điều phối việc phân tích cú pháp thông báo, quản lý trạng thái ảnh chụp nhanh phản ứng và chuyển đổi trạng thái bề mặt động. Mặc dù trình kết xuất cốt lõi không phụ thuộc vào bất kỳ hệ thống thiết kế cụ thể nào, nhưng trình kết xuất này cung cấp khả năng tích hợp sẵn với Material Design 3 thông qua Danh mục cơ bản được cung cấp.

Khởi chạy lớp dữ liệu dựa trên Compose

Trình kết xuất A2UI hỗ trợ trạng thái nhận biết ảnh chụp nhanh trong lớp dữ liệu của ứng dụng, cho phép giao diện người dùng của ứng dụng phản ứng với các bản cập nhật gia tăng từ tác nhân. Để thêm chế độ hỗ trợ này, hãy khởi chạy trình phân tích cú pháp và trình xử lý bằng các hàm tạo A2uiMessageParserA2uiMessageProcessor trong ViewModel, như minh hoạ trong đoạn mã sau:

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

Kết xuất các thành phần hiển thị bằng Danh mục cơ bản (Material 3)

Khi kết xuất các thành phần hiển thị bằng cách triển khai Danh mục cơ bản được cung cấp (androidx.compose.material3:material3-a2ui), bạn có thể kết xuất một thành phần hiển thị Material 3 có đầy đủ kiểu dáng, bao gồm cả tính năng hỗ trợ tích hợp cho chỉ báo tải, ranh giới lỗi và hiệu ứng chuyển đổi có ảnh động. Để làm như vậy, hãy sử dụng điểm truy cập có thể kết hợp 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.
                )
            }
        }
    }
}

Xử lý trạng thái nền tảng và hiệu ứng chuyển đổi có ảnh động

A2uiSurface điều phối quá trình phân giải trạng thái thành phần gốc và áp dụng các hiệu ứng chuyển đổi AnimatedContent trên các trạng thái tải, lỗi và thành công:

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

Kết xuất bề mặt cấp thấp bằng các bộ định tuyến tuỳ chỉnh

Bạn có thể quan sát trực tiếp trạng thái thành phần gốc của nền tảng bằng observeA2uiComponentState và uỷ quyền kết xuất cho 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.
                )
            }
        }
    }
}

Thông tin chi tiết về việc triển khai

Trình kết xuất từ tác nhân đến giao diện người dùng xử lý độ phân giải trạng thái bề mặt và các ranh giới lỗi phòng thủ.

Ranh giới lỗi phòng thủ và xử lý ảo giác của tác nhân

Vì các giao diện A2UI được điều khiển bởi các tác nhân LLM tạo sinh, nên các tải trọng đến có thể bị sai định dạng hoặc tham chiếu đến các loại thành phần không xác định.

Trình kết xuất thiết lập các ranh giới phòng thủ sau đây để giảm thiểu khả năng xảy ra sự cố:

  • Lỗi gửi đi để nhân viên tự sửa: Lỗi được gửi đi dưới dạng thông báo của ứng dụng gửi đi, cho phép nhân viên tự sửa trong các lượt tương tác tiếp theo. Ngoài ra, còn có một API cho phép các hoạt động triển khai thành phần gửi lỗi đến tác nhân trong trường hợp API phát hiện thấy các lỗi dành riêng cho thành phần tại thời gian kết xuất.
  • Các thành phần không xác định: Khi gặp phải một loại thành phần không xác định, thành phần đó sẽ bị chặn trước khi đến cây giao diện người dùng, được đánh dấu là trạng thái lỗi và được báo cáo lại cho tác nhân để tự sửa lỗi.
  • Lỗi xác thực giản đồ: Tải trọng được xác thực dựa trên giản đồ thành phần (A2uiSchema). Các thuộc tính bị lỗi không bao giờ được đưa vào bố cục giao diện người dùng Compose.
  • Bảo vệ mảng thưa: Khi nhận được chỉ mục danh sách rất lớn, mô hình dữ liệu sẽ chuyển từ danh sách dày đặc sang bản đồ thưa thớt thích ứng, ngăn chặn lỗi hết bộ nhớ.