Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Thêm AppFunctions API vào ứng dụng

Hướng dẫn này giải thích cách tích hợp AppFunctions API vào ứng dụng Android, triển khai logic cho một hàm và xác minh rằng quá trình tích hợp hoạt động đúng cách.

Khả năng tương thích với phiên bản

Việc triển khai này yêu cầu bạn phải đặt dự án compileSdk thành cấp độ API 36 trở lên.

Ứng dụng của bạn không bắt buộc phải xác minh xem AppFunctions có được hỗ trợ hay không; việc này sẽ tự động được xử lý trong thư viện AppFunctions Jetpack. AppFunctionManager trả về một thực thể nếu tính năng được hỗ trợ và trả về giá trị rỗng nếu không.

Phần phụ thuộc

Thêm các phần phụ thuộc của thư viện bắt buộc vào tệp build.gradle.kts (hoặc build.gradle) của mô-đun, rồi định cấu hình trình bổ trợ KSP trong mô-đun ứng dụng cấp cao nhất như minh hoạ:

dependencies {
  implementation("androidx.appfunctions:appfunctions:1.0.0-alpha10")
  // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
  // See Add the KSP plugin to your project
  ksp("androidx.appfunctions:appfunctions-compiler:1.0.0-alpha10")
}

Triển khai logic AppFunctions

Để triển khai AppFunction cho ứng dụng Android, hãy tạo một lớp triển khai logic AppFunctions cụ thể. Điều này liên quan đến việc tạo các lớp dữ liệu có thể chuyển đổi tuần tự cho các tham số và phản hồi, sau đó cung cấp logic cốt lõi trong phương thức hàm.

Đoạn mã sau đây cho thấy một ví dụ về cách triển khai để tạo một việc cần làm trong ứng dụng Việc cần làm, bao gồm cả việc xác định các tham số tuỳ chỉnh và các loại phản hồi cũng như logic hàm chính bằng cách sử dụng một kho lưu trữ.

@RequiresApi(36)
@AndroidEntryPoint
@AppFunctionServiceEntryPoint(
    serviceName = "TaskAppFunctionService",
    appFunctionXmlFileName = "task_app_function_service",
)
abstract class BaseTaskAppFunctionService : AppFunctionService() {
    @Inject internal lateinit var taskRepository: TaskRepository

    /**
     * Creates a task based on [createTaskParams].
     *
     * @param createTaskParams The parameter to describe how to create the task.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun createTask(
        createTaskParams: CreateTaskParams,
    ): Task = withContext(Dispatchers.IO) {
        // Developers can use predefined exceptions to let the agent know
        // why it failed.
        if (createTaskParams.title == null && createTaskParams.content == null) {
            throw AppFunctionInvalidArgumentException("Title or content should be non-null")
        }

        val id = taskRepository.createTask(
            createTaskParams.title,
            createTaskParams.content
        )

        return@withContext taskRepository
            .getTask(id)
            ?.toTask()
            ?: throw AppFunctionElementNotFoundException("Task not found for ID = $id")
    }

    // Maps internal TaskEntity
    private fun TaskEntity.toTask() = Task(id = id, title = title, content = description)
}AppFunctionApiSnippets.kt

Các điểm chính về mã

Theo mặc định, một phương thức triển khai AppFunction sẽ chạy trong luồng giao diện người dùng Android. Do đó, một thao tác diễn ra trong thời gian dài phải thực hiện những việc sau:
- Khai báo AppFunction dưới dạng hàm tạm ngưng.
- Chuyển sang trình điều phối coroutine phù hợp khi thao tác có thể chặn luồng.
Khi isDescribedByKDoc được đặt thành true, nội dung mô tả hàm hoặc nội dung mô tả có thể chuyển đổi tuần tự sẽ được mã hoá trong AppFunctionMetadata để giúp tác nhân hiểu cách sử dụng AppFunction của ứng dụng.

Khai báo dịch vụ AppFunction trong tệp kê khai

Đăng ký khai báo dịch vụ do KSP tạo và thuộc tính app_metadata bên trong tệp kê khai mô-đun, chẳng hạn như trong src/main/AndroidManifest.xml. Trình biên dịch KSP sẽ tạo lớp dịch vụ cụ thể (TaskAppFunctionService) mở rộng lớp điểm truy cập trừu tượng, cùng với giản đồ XML tương ứng trong thư mục assets/.

<service
    android:name="com.example.snippets.ai.TaskAppFunctionService"
    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
    android:exported="true"
    tools:targetApi="36">
    <property
        android:name="android.app.appfunctions.schema"
        android:value="app_functions_schema.xsd" />
    <property
        android:name="android.app.appfunctions.v2"
        android:value="task_app_function_service.xml" />
    <intent-filter>
        <action android:name="android.app.appfunctions.AppFunctionService" />
    </intent-filter>
</service>
<property
    android:name="android.app.appfunctions.app_metadata"
    android:resource="@xml/app_metadata" />AndroidManifest.xml

Không bắt buộc: Bật/tắt trạng thái cung cấp AppFunction trong thời gian chạy

Sử dụng API AppFunctionManager để bật hoặc tắt rõ ràng các chức năng khi kiểm soát AppFunctions. Việc hạn chế có thể hữu ích khi một số tính năng của ứng dụng không được cung cấp cho tất cả người dùng. Bằng cách bật hoặc tắt AppFunctions một cách linh hoạt, hệ thống thông minh sẽ biết chính xác những tính năng mà người dùng có thể sử dụng tại một thời điểm bất kỳ.

Để kiểm soát an toàn AppFunctions yêu cầu một trạng thái tài khoản cụ thể, hãy làm theo quy trình gồm 2 bước:

Bước 1. Tắt chức năng theo mặc định

Để ngăn người dùng truy cập vào hàm trước khi cờ tính năng của bạn được xác minh, hãy đặt tham số isEnabled của chú giải @AppFunction thành false.

@AppFunction(isEnabled = false, isDescribedByKDoc = true)
suspend fun createTask(
    createTaskParams: CreateTaskParams,
): Task = TODO()AppFunctionApiSnippets.kt

Bước 2. Bật hàm một cách linh động trong thời gian chạy

Đối với mỗi lớp AppFunction, trình biên dịch sẽ tạo một lớp tương ứng chứa các hằng số mã nhận dạng hàm (sử dụng hậu tố Ids). Bạn có thể sử dụng các hằng số mã nhận dạng đã tạo này cùng với phương thức setAppFunctionEnabled từ AppFunctionManagerCompat để thay đổi trạng thái đã bật của một hàm trong thời gian chạy.

suspend fun onFeatureEnabled(context: Context) {
    try {
        AppFunctionManager.getInstance(context)
            ?.setAppFunctionEnabled(
                BaseTaskAppFunctionServiceIds.CREATE_TASK_ID,
                AppFunctionManager.APP_FUNCTION_STATE_ENABLED,
            )
    } catch (e: Exception) {
        // Handle exception: AppFunctions indexation may not be fully completed
        // upon initial app startup.
    }
}

suspend fun onFeatureDisabled(context: Context) {
    try {
        AppFunctionManager.getInstance(context)
            ?.setAppFunctionEnabled(
                BaseTaskAppFunctionServiceIds.CREATE_TASK_ID,
                AppFunctionManager.APP_FUNCTION_STATE_DISABLED,
            )
    } catch (e: Exception) {
        // Handle exception
    }
}AppFunctionApiSnippets.kt

Những điểm cần cân nhắc về các loại chức năng cần cung cấp

Bảo mật luôn là yếu tố quan trọng nhất. Khi chọn những chức năng của ứng dụng mà bạn muốn cung cấp dưới dạng AppFunction, bạn cần nhớ rằng các tác nhân hệ thống có thể xử lý các truy vấn của người dùng trên máy chủ để tận dụng các chức năng LLM nâng cao.

Để mang lại trải nghiệm tuyệt vời cho người dùng mà vẫn tránh để lộ thông tin nhạy cảm, bạn nên làm theo các nguyên tắc sau:

Chức năng tận dụng ngôn ngữ tự nhiên: Cung cấp những tác vụ mà người dùng dễ dàng thể hiện trong cuộc trò chuyện hơn là thông qua thao tác điều hướng giao diện người dùng theo cách thủ công.
Hạn chế quyền truy cập: Tạo AppFunction chỉ cấp cho tác nhân quyền truy cập vào dữ liệu và hành động cần thiết để thực hiện yêu cầu cụ thể của người dùng.
Thông tin không nhạy cảm: Chỉ chia sẻ dữ liệu không mang tính cá nhân hoặc mật cao, hoặc dữ liệu mà người dùng đồng ý chia sẻ một cách rõ ràng trong bối cảnh của hành động.
Xác nhận rõ ràng cho mọi hành động phá huỷ: Cực kỳ thận trọng với các hàm thực hiện hành động phá huỷ (chẳng hạn như xoá dữ liệu). Mặc dù tác nhân có thể gọi các thao tác này, nhưng ứng dụng của bạn phải có bước xác nhận riêng và sử dụng ngôn ngữ rõ ràng, không mơ hồ về ý định. Việc thêm nhiều bước xác nhận cũng rất hữu ích để thực sự đảm bảo rằng người dùng biết họ được yêu cầu làm gì.

Xác minh việc tích hợp AppFunction

Để xác minh xem bạn đã tích hợp AppFunctions đúng cách hay chưa, bạn có thể sử dụng adb shell cmd app_function.

Sử dụng adb shell cmd app_function list-app-functions | grep --after-context 10 $myPackageName để xem thông tin chi tiết về AppFunctions mà ứng dụng của bạn cung cấp.

Bạn cũng có thể thực thi AppFunction trực tiếp từ dòng lệnh bằng cách dùng giá trị nhận dạng rõ ràng ("$enclosingClassName#$methodName"):

adb shell "cmd app_function execute-app-function \
  --package com.example.android.appfunctions \
  --function 'com.example.android.appfunctions.BaseTaskAppFunctionService#createTask' \
  --parameters '{\"createTaskParams\": {\"title\": \"Buy milk\", \"content\": \"From grocery store\"}}'"

Để trải nghiệm MCP Android đang hoạt động và xác minh quy trình làm việc từ đầu đến cuối mà không cần bất kỳ lời nhắc nào, hãy cài đặt và chạy ứng dụng Android tác nhân kiểm thử AppFunctions trên thiết bị của bạn.

Nếu bạn đang xác minh quá trình tích hợp bằng các trợ lý dựa trên cuộc trò chuyện như Gemini trong Android Studio, hãy sử dụng kỹ năng phát triển AppFunctions hoặc đưa ra một câu lệnh như sau:

Execute `adb shell cmd app_function` to learn how the tool works, then act as a
chat agent aiming to invoke AppFunctions to fulfil user prompts for this app.
Rely on the AppFunction description as instructions.

Di chuyển từ các phiên bản API thấp hơn

Trong phiên bản 1.0.0-alpha10, AppFunctions đã giới thiệu một cấu trúc @AppFunctionServiceEntryPoint trong thời gian biên dịch, giúp hợp nhất các phần phụ thuộc của thư viện và thay thế các trình cung cấp cấu hình cũ (AppFunctionConfiguration.Provider).

Nếu ứng dụng của bạn hiện đang dùng một phiên bản AppFunctions cũ hơn (chẳng hạn như 1.0.0-alpha09), bạn có thể tự động hoá quá trình di chuyển bằng cách sử dụng kỹ năng tác nhân AppFunctions trong một IDE AI như Gemini trong Android Studio. Kỹ năng này chứa các quy tắc di chuyển chuyên dụng giúp một tác nhân hợp nhất các phần phụ thuộc bản dựng, tạo trình bao bọc dịch vụ @AppFunctionServiceEntryPoint bắt buộc, tách các tham số ngữ cảnh và cập nhật các khai báo tệp kê khai.

Để bắt đầu quá trình di chuyển tự động bằng tác nhân AI, hãy sử dụng một câu lệnh như sau:

Use the AppFunctions migration skill to upgrade my app's AppFunctions implementation from 1.0.0-alpha09 to the 1.0.0-alpha10 @AppFunctionServiceEntryPoint architecture.

Thêm AppFunctions API vào ứng dụng Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.