Hướng dẫn này giải thích cách tích hợp API AppFunctions 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 của phiên bản
Cách triển khai này yêu cầu compileSdk của dự án phải được đặt thành cấp độ API 37 trở lên. Dự án của bạn phải sử dụng Trình bổ trợ Android cho Gradle phiên bản 9.1.0 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 được xử lý tự động trong thư viện Jetpack AppFunctions.
AppFunctionManager trả về một thực thể nếu tính năng này được hỗ trợ và trả về giá trị rỗng nếu không được hỗ trợ.
Phần phụ thuộc
Thêm các phần phụ thuộc bắt buộc của thư viện 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-rc01")
// 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-rc01")
}
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ể. Việc này bao gồm 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 việc cần làm trong ứng dụng TODO, bao gồm cả việc xác định các tham số tuỳ chỉnh và loại phản hồi cũng như logic hàm chính bằng cách sử dụng 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 with a title, content, or both. * * @param createTaskParams The title and content of the task. At least one * of them is required. * @return The created task, including its ID. */ @AppFunctionDeclaration(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("A task needs a title, content, or both.") } 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) }
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 chạy trong thời gian dài nên làm như sau:
- Khai báo AppFunction dưới dạng hàm tạm ngưng.
- Chuyển sang một 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ànhtrue, 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á dưới dạng một phần củaAppFunctionMetadatađể giúp tác nhân hiểu cách sử dụng AppFunction của ứng dụng. Kể từ phiên bản 1.0.0-beta01,isDescribedByKDockhông có giá trị mặc định, vì vậy, hãy đặt giá trị này một cách rõ ràng.
Khai báo dịch vụ AppFunction trong tệp kê khai
Đăng ký nội dung 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, ví dụ: trong src/main/AndroidManifest.xml. Trình biên dịch KSP 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" />
Không bắt buộc: Bật/tắt phạm vi cung cấp AppFunction trong thời gian chạy
Sử dụng API AppFunctionManager để bật hoặc tắt các hàm một cách rõ ràng khi
kiểm soát AppFunctions. Tính năng kiểm soát 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 động, hệ thống thông minh sẽ biết chính xác những tính năng nào có sẵn cho người dùng tại bất kỳ thời điểm nào.
Để kiểm soát một cách an toàn các AppFunction 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 hai bước sau:
Bước 1. Tắt chức năng này theo mặc định
Để ngăn hàm này truy cập được 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ú thích @AppFunctionDeclaration thành false.
@AppFunctionDeclaration(isEnabled = false, isDescribedByKDoc = true) suspend fun createTask( createTaskParams: CreateTaskParams, ): Task = TODO()
Bước 2. Bật chức năng này một cách linh hoạt trong thời gian chạy
Đối với mỗi lớp @AppFunctionServiceEntryPoint, trình biên dịch sẽ tạo một lớp tương ứng chứa 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 được tạo này cùng với phương thức setAppFunctionEnabled từ AppFunctionManager để 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 } }
Những điểm cần lưu ý 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 để cung cấp dưới dạng AppFunctions, hãy lưu ý rằng các tác nhân AI có thể xử lý truy vấn của người dùng trên máy chủ để sử dụng các chức năng nâng cao của LLM.
Để mang lại trải nghiệm người dùng tuyệt vời, đồng thời tránh làm 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 hưởng lợi từ ngôn ngữ tự nhiên: Cung cấp các nhiệm 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.
- Thu hẹp quyền truy cập: Tạo AppFunctions 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 bí 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.
- Hành động an toàn, không gây hại: Chỉ cung cấp những nhiệm vụ an toàn, không gây hại mà người dùng thường làm trong ứng dụng của bạn, chẳng hạn như tạo nhiệm vụ hoặc tìm kiếm ghi chú. Để biết thêm thông tin, hãy xem phần Các hành động và hoạt động chia sẻ dữ liệu được cho phép.
Xác minh việc tích hợp AppFunction
Vì AppFunction hoạt động như các dịch vụ mà tác nhân AI gọi, nên việc kiểm thử có hai mặt: cách hàm của bạn hoạt động và cách tác nhân hoạt động khi gọi hàm đó.
Kiểm thử hàm
Bắt đầu bằng các kiểm thử đơn vị cho logic hàm, tính đến sự khác biệt giữa lệnh gọi tác nhân thông qua thư viện AppFunctions và lệnh gọi Kotlin trực tiếp:
- Giá trị mặc định: Giá trị tham số mặc định của Kotlin không áp dụng. Tham số không bắt buộc bị bỏ qua sẽ được coi là
null,0,falsehoặc một danh sách/mảng trống, vì vậy, tham sốlimit: Int = 10sẽ được coi là0. Kiểm thử các tham số bị bỏ qua bằng các giá trị đó và phân giải giá trị mặc định trong phần thân hàm. Để biết thêm thông tin, hãy xem phần Tham số tuỳ chọn. - Luồng chính: Các lệnh gọi nền tảng bắt đầu trên luồng chính và việc gọi trực tiếp hàm
suspendtừ một kiểm thử đơn vị sẽ không phát hiện được tình trạng chặn luồng chính. Đảm bảo cơ sở dữ liệu, mạng và I/O ổ đĩa chạy trên một trình điều phối coroutine trong nền, chẳng hạn nhưDispatchers.IO. - Ngoại lệ: Khi một yêu cầu không thành công, hãy gửi một lớp con
AppFunctionExceptioncụ thể. Các ngoại lệ khác không được phát hiện sẽ đến tác nhân dưới dạngAppFunctionAppUnknownExceptionkèm theo thông báo ngoại lệ thô, không xác định được loại lỗi. Để biết thêm thông tin, hãy xem phần Xử lý lỗi. - Dữ liệu đầu vào của mô hình: Vì dữ liệu đầu vào đến từ một mô hình chứ không phải các thành phần điều khiển trên giao diện người dùng bị ràng buộc, nên hãy kiểm thử các chuỗi trống, từ đồng nghĩa như "đô la" cho "USD" và các giá trị nằm ngoài phạm vi.
Trên thiết bị hoặc trình mô phỏng, hãy dùng adb shell cmd app_function để xác minh rằng nền tảng đã lập chỉ mục siêu dữ liệu bạn tạo và có thể gọi dịch vụ của bạn.
Sử dụng adb shell cmd app_function list-app-functions --package $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 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\"}}'"
Kiểm thử bằng tác nhân
Thử nghiệm với một tác nhân để xác minh rằng tác nhân đó chọn đúng hàm trong nội dung mô tả của bạn và yêu cầu hoạt động như mong đợi. Vì mỗi tác nhân hoạt động theo cách khác nhau, hãy thử nghiệm với các tác nhân gọi AppFunctions của bạn:
- Tác nhân mẫu: Để kiểm thử quy trình khám phá công cụ và quy trình công việc toàn diện trên thiết bị, hãy cài đặt và chạy tác nhân kiểm thử AppFunctions nguồn mở trên thiết bị của bạn.
- Gemini: Để kiểm thử cách Gemini trên Android gọi AppFunctions, hãy tham gia chương trình Bản dùng trước cho nhà phát triển của Connected Apps Platform và làm theo hướng dẫn trong bài viết Tạo và quản lý Ứng dụng đã kết nối.
- Tác nhân trong ứng dụng: Nếu ứng dụng của bạn có tác nhân riêng gọi
AppFunctionManagercho các chức năng trong cùng một gói, hãy thử nghiệm các chức năng của bạn thông qua tác nhân đó.
Trong quá trình phát triển, bạn cũng có thể xác minh quá trình tích hợp bằng cách sử dụng các trợ lý dựa trên cuộc trò chuyện như Gemini trong Android Studio với kỹ năng tác nhân AppFunctions hoặc đưa ra 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 fulfill user prompts for this app.
Use the AppFunction descriptions to choose functions and parameters.
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 đã ra mắt một cấu trúc @AppFunctionServiceEntryPoint 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). Phiên bản 1.0.0-alpha12 đã xoá các trình cung cấp cũ. Phiên bản 1.0.0-alpha13 đã đổi tên chú thích @AppFunction thành @AppFunctionDeclaration và phiên bản 1.0.0-beta01 đã đổi tên thuộc tính appfn:description trong tệp XML siêu dữ liệu của ứng dụng thành appfn:instructions. Phiên bản 1.0.0-rc01 đã xoá tuỳ chọn trình biên dịch appfunctions:aggregateAppFunctions cũ; nếu bản dựng của bạn truyền tuỳ chọn này dưới dạng đối số KSP, hãy xoá tuỳ chọn này.
Nếu ứng dụng của bạn sử dụng phiên bản AppFunctions thấp hơn (chẳng hạn như 1.0.0-alpha09 hoặc 1.0.0-alpha10), bạn có thể tự động di chuyển bằ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 biệt hướng dẫn 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 riêng các tham số ngữ cảnh, cập nhật nội dung khai báo tệp kê khai, áp dụng
các tên mới trong phiên bản 1.0.0-beta01 và xoá các tuỳ chọn trình biên dịch đã ngừng hoạt động.
Kỹ năng Android
Xem trên GitHubTriển khai AppFunctions
android skills add appfunctionsUse the AppFunctions skill to upgrade my app's AppFunctions implementation to 1.0.0-rc01.