Tổng quan về AppFunction

AppFunctions là một API nền tảng Android có thư viện Jetpack đi kèm để đơn giản hoá việc tích hợp Android MCP. Nền tảng này giúp các ứng dụng của bạn hoạt động như máy chủ MCP trên thiết bị, cung cấp các hàm đóng vai trò là công cụ để các tính năng chủ động sử dụng cùng với các tác nhân và trợ lý, chẳng hạn như Google Gemini. Để thử nghiệm và xuất bản AppFunctions bằng Gemini, hãy đăng ký tham gia chương trình Bản dùng trước cho nhà phát triển của Nền tảng ứng dụng được kết nối. Sau khi tham gia, hãy làm theo các bước trong bài viết Tạo và quản lý ứng dụng có thể kết nối.

Bằng cách xác định các AppFunction này, bạn cho phép ứng dụng cung cấp dịch vụ, dữ liệu và hành động cho sổ đăng ký được tích hợp vào hệ điều hành Android, cho phép người dùng hoàn thành các nhiệm vụ thông qua các tác nhân và hoạt động tương tác ở cấp hệ thống.

AppFunctions đóng vai trò là công cụ tương đương trên thiết bị di động trong Giao thức ngữ cảnh mô hình (MCP). Mặc dù MCP thường chuẩn hoá cách các tác nhân kết nối với các công cụ phía máy chủ, nhưng AppFunctions cung cấp cơ chế tương tự cho các ứng dụng Android. Nhờ vậy, bạn có thể hiển thị các chức năng của ứng dụng dưới dạng "công cụ" có thể điều phối mà các ứng dụng được uỷ quyền (người gọi) có thể khám phá và thực thi để thực hiện ý định của người dùng. Người gọi phải có quyền EXECUTE_APP_FUNCTIONS để khám phá và thực thi AppFunctions, đồng thời có thể bao gồm các tác nhân, ứng dụng và trợ lý AI như Gemini.

AppFunctions có trên các thiết bị chạy Android 16 trở lên.

Trường hợp sử dụng mẫu

AppFunctions cung cấp một cơ chế mạnh mẽ để tự động hoá các tác vụ và đơn giản hoá hoạt động tương tác của người dùng. Bằng cách mở rộng khả năng của ứng dụng, bạn cho phép người dùng hoàn thành các mục tiêu phức tạp bằng ngôn ngữ tự nhiên, thường thay thế nhu cầu điều hướng từng bước, thủ công bằng giao diện người dùng của bạn.

Các trường hợp sau đây minh hoạ cách sử dụng AppFunctions để mang lại trải nghiệm trong nhiều danh mục ứng dụng:

  • Quản lý công việc và năng suất

    • Yêu cầu của người dùng: "Nhắc tôi lấy gói hàng tại nơi làm việc vào lúc 5 giờ chiều hôm nay".
    • Hành động AppFunction: Phương thức gọi xác định ứng dụng quản lý việc cần làm có liên quan và gọi một hàm để tạo việc cần làm, tự động điền các trường tiêu đề, thời gian và vị trí dựa trên câu lệnh của người dùng.

    /**
     * Create a new task or reminder with a title, due time, and location.
     *
     * @param title The descriptive title of the task (e.g., "Pick up my package").
     * @param dueDateTime The specific date and time when the task should be completed.
     * @param location The physical location associated with the task (e.g., "Work").
     * @return The created Task
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    suspend fun createTask(
        title: String,
        dueDateTime: LocalDateTime? = null,
        location: String? = null,
    ): Task = TODO()

  • Truyền thông và giải trí

    • Yêu cầu của người dùng: "Tạo một danh sách phát mới gồm các đĩa nhạc jazz hàng đầu trong năm nay".
    • Hành động AppFunction: Phương thức gọi thực thi một hàm tạo danh sách phát trong một ứng dụng nhạc, truyền bối cảnh như "các đĩa nhạc jazz hàng đầu năm 2026" dưới dạng truy vấn để tạo danh sách phát ngay lập tức.

    /**
     * Create a new music playlist based on a natural language query.
     *
     * @param query The description used to generate the playlist (e.g., "top jazz albums from 2026").
     * @return The final created playlist based on songs.
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    suspend fun createPlaylistFromQuery(
        query: String,
    ): Playlist = TODO()

  • Quy trình công việc trên nhiều ứng dụng

    • Yêu cầu của người dùng: "Tìm công thức nấu mì trong email của Lisa và thêm các nguyên liệu vào danh sách mua sắm của tôi".
    • Hành động AppFunction: Yêu cầu này sử dụng các hàm từ nhiều ứng dụng. Trước tiên, phương thức gọi sử dụng chức năng tìm kiếm của ứng dụng email để truy xuất nội dung. Sau đó, ứng dụng này sẽ trích xuất các thành phần liên quan và gọi một hàm của ứng dụng danh sách mua sắm để điền vào danh sách của người dùng.

    /**
     * Search for emails matching a query or sender name to retrieve content like recipes.
     *
     * @param query The search term or contact name (e.g., "Lisa noodle recipe").
     * @return A list of matching email summaries containing the requested information.
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    suspend fun searchEmails(
        query: String,
    ): List<EmailSummary> = TODO()
    
    /**
     * Add a list of items or ingredients to the user's active shopping list.
     *
     * @param items The names of the ingredients or products to add to the list.
     * @return The final shopping list with new items added
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    suspend fun addItemsToShoppingList(
        items: List<String>,
    ): ShoppingList = TODO()

  • Lịch và lên lịch

    • Yêu cầu của người dùng: "Thêm tiệc sinh nhật của mẹ vào lịch của tôi vào 6 giờ chiều thứ Hai tuần sau".
    • Hành động AppFunction: Ứng dụng tác nhân được phê duyệt sẽ gọi hàm "tạo sự kiện" của ứng dụng lịch, phân tích cú pháp bối cảnh có liên quan như "thứ Hai tới" và "6 giờ chiều" để tạo mục nhập mà người dùng không cần phải mở lịch theo cách thủ công.

    /**
     * Schedule a new event on the user's primary calendar.
     *
     * @param title The name of the calendar event (e.g., "Mom's birthday party").
     * @param startDateTime The specific date and time the event is scheduled to begin.
     * @return The created Event object.
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    suspend fun createCalendarEvent(
        title: String,
        startDateTime: LocalDateTime,
    ): Event = TODO()

Cách hoạt động của AppFunctions

Sơ đồ sau đây minh hoạ quy trình thông thường về cách ứng dụng chia sẻ AppFunctions với một tác nhân và sau đó thực thi. Tác nhân có thể sẽ xem xét cả công cụ MCP từ xa phía máy chủ và AppFunctions cục bộ khi xử lý yêu cầu của người dùng. Quy trình chi tiết để sử dụng AppFunction cục bộ như sau:

  • Khai báo AppFunction: Ứng dụng Android được xây dựng để sử dụng AppFunction nhằm cung cấp các tính năng như "Tạo ghi chú" hoặc "Gửi tin nhắn".
  • Tạo giản đồ: Thư viện AppFunctions Jetpack tạo một tệp giản đồ XML liệt kê tất cả AppFunction được khai báo trong ứng dụng. Hệ điều hành Android sử dụng tệp này để lập chỉ mục các AppFunction có sẵn.
  • Truy xuất siêu dữ liệu: Tác nhân có thể truy xuất siêu dữ liệu AppFunction bằng cách truy vấn siêu dữ liệu đó. Ngoài KDoc dành riêng cho hàm, nhà phát triển có thể xác định các mẫu và quy tắc ràng buộc hoạt động ở cấp ứng dụng trong siêu dữ liệu của ứng dụng để hướng dẫn việc điều phối tác nhân trên nhiều công cụ.
  • Lựa chọn và thực thi AppFunction: Dựa trên câu lệnh của người dùng, tác nhân sẽ chọn và thực thi AppFunction phù hợp với các tham số thích hợp.
Luồng AppFunctions thông thường từ khi hiển thị ứng dụng đến khi thực thi tác nhân.
Hình 1: Quy trình thông thường về cách AppFunctions được hiển thị và sau đó được thực thi bởi một tác nhân.

Thư viện AppFunctions Jetpack giúp đơn giản hoá việc hiển thị chức năng của ứng dụng. Với trình xử lý chú thích, bạn chú thích các hàm mà bạn muốn cung cấp cho tác nhân. Sau đó, phương thức gọi có thể khám phá và gọi các hàm được lập chỉ mục này bằng AppFunctionManager.

Trước khi gọi một hàm, phương thức gọi phải xác minh rằng thiết bị hỗ trợ tính năng AppFunctions bằng cách cố gắng truy xuất một thực thể của AppFunctionManager. Sau khi được hỗ trợ, phương thức gọi có thể xác minh xem một chức năng cụ thể có được bật trong ứng dụng mục tiêu hay không bằng cách sử dụng isAppFunctionEnabled(packageName,functionId). Để truy vấn trạng thái của các hàm trong những gói khác, bạn cần có quyền android.permission.EXECUTE_APP_FUNCTIONS.

Ứng dụng của bạn không bắt buộc phải xác minh xem tính năng AppFunction có được hỗ trợ hay không; việc này được xử lý tự động trong thư viện Jetpack. Ví dụ: AppFunctionManager có thể xác minh xem tính năng này có được hỗ trợ hay không.

Dưới đây là ví dụ về AppFunctions cho một ứng dụng ghi chú có khả năng tạo, chỉnh sửa và liệt kê ghi chú:

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

/** The title and content of a new task. */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class CreateTaskParams(
    /** The title of the task. */
    val title: String?,
    /** The content of the task. */
    val content: String?,
)

/** The user-created task. */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class Task(
    /** The ID of the task. */
    val id: String,
    /** The title of the task. */
    val title: String,
    /** The content of the task. */
    val content: String,
)

Đoạn nhạc, kỹ năng và công cụ kiểm thử

Chúng tôi đã cung cấp những nội dung sau để giúp bạn nâng cao kỹ năng về AppFunctions:

  • Khám phá mẫu AppFunctions để xác minh và khám phá cách mọi thứ hoạt động trên thiết bị của bạn.
  • Sử dụng kỹ năng tác nhân AppFunctions để đẩy nhanh quá trình phát triển trong vòng đời gồm 4 bước:
    • Khám phá: Phân tích toàn bộ mã nguồn để xác định và đề xuất các tính năng có giá trị cao cho việc điều phối AI.
    • Triển khai và định cấu hình: Tạo các phương thức triển khai Kotlin, đồng thời định cấu hình siêu dữ liệu hệ thống và các phần phụ thuộc của bản dựng.
    • Tinh chỉnh KDoc: Tối ưu hoá tài liệu về hàm và thuộc tính cho các tác nhân AI và MCP Android.
    • Kiểm thử và gỡ lỗi: Cung cấp các lệnh ADB để đánh giá cục bộ và gỡ lỗi trên thiết bị.
  • Kiểm thử cả cách hoạt động của các hàm (bao gồm cả giá trị mặc định bị bỏ qua, lệnh gọi luồng chính, lỗi AppFunctionException và dữ liệu đầu vào do mô hình tạo) và cách các tác nhân chọn và gọi các hàm đó. Để biết thêm thông tin về kiểm thử đơn vị, ADB và tác nhân, hãy xem bài viết Xác minh việc tích hợp AppFunction.
  • Để kiểm thử cách Gemini sử dụng AppFunctions, hãy làm theo các bước trong phần Tạo và quản lý Ứng dụng được kết nối.

Câu hỏi thường gặp

Phần sau đây giải đáp các câu hỏi thường gặp về AppFunctions.

Tôi là nhà phát triển ứng dụng. Tôi có thể triển khai AppFunction ngay hôm nay không?

Có, bạn có thể triển khai và kiểm thử AppFunctions trong ứng dụng bằng cách làm theo hướng dẫn chi tiết trong các phần trước.

Sự khác biệt giữa AppFunctions và MCP là gì?

Cả hai đều cho phép tác nhân AI điều phối các công cụ, nhưng có sự khác biệt đáng kể về cấu trúc, độ trễ và nỗ lực cần thiết của nhà phát triển. AppFunctions là các hook tích hợp sẵn ở cấp hệ điều hành dành riêng cho Android và thực thi cục bộ. Ngược lại, máy chủ MCP tiêu chuẩn là một giải pháp không phụ thuộc vào nền tảng, dựa vào việc thực thi trên đám mây và các chuyến khứ hồi mạng.

Nói tóm lại, việc phát triển bằng AppFunctions cho phép bạn sử dụng trạng thái ứng dụng hiện có ngay trên thiết bị mà không cần duy trì các dịch vụ bên ngoài ứng dụng Android.

Tôi đã triển khai AppFunctions trong ứng dụng của mình. Tại sao Gemini hoặc các tác nhân AI khác không thể truy cập vào các hàm đó?

  • Cách sử dụng AppFunctions với Gemini trên Android: Đăng ký và gửi ứng dụng của bạn trong Google Connected Console thông qua bản dùng trước cho nhà phát triển của Connected Apps Platform. Cho đến khi ứng dụng có thể kết nối của bạn được xuất bản, chỉ những người thử nghiệm trong danh sách người thử nghiệm của ứng dụng có thể kết nối mới có thể sử dụng ứng dụng đó và chỉ trên phiên bản gói ứng dụng mà bạn đã gửi. Để biết các bước thiết lập, hãy xem hướng dẫn về Ứng dụng được kết nối và Android MCP trên Google Connected Console.
  • Cách gọi AppFunctions từ tác nhân của riêng bạn: Ứng dụng có thể gọi AppFunctions được khai báo bên trong gói của chính ứng dụng đó. Để khám phá và gọi AppFunctions của các ứng dụng khác, bạn cần có quyền đặc quyền EXECUTE_APP_FUNCTIONS. Android chỉ cấp quyền này cho các trợ lý hệ thống được uỷ quyền.

Làm cách nào để chuẩn bị ứng dụng cho giai đoạn phát hành rộng rãi của AppFunctions?

Cân nhắc những tính năng của ứng dụng mà bạn muốn hiển thị cho tính năng tự động hoá dựa trên tác nhân. Bạn có thể triển khai AppFunctions trong ứng dụng của mình. Để làm việc này, hãy làm theo các bước trong các phần trước trên trang này và xác minh rằng các hàm đó đã được đăng ký trên thiết bị bằng cách gọi adb shell cmd app_function list-app-functions --package kèm theo tên gói của ứng dụng.

Làm cách nào để thử nghiệm và phát hành AppFunctions bằng Gemini?

Tham gia bản dùng trước cho nhà phát triển của Connected Apps Platform. Để yêu cầu quyền truy cập, hãy đăng ký tham gia chương trình xem trước. Sau khi tham gia, trong Google Connected Console, hãy tạo một ứng dụng Android MCP được kết nối, tải gói ứng dụng lên kênh thử nghiệm, và thêm cùng một người kiểm thử vào cả hai. Để biết thông tin chi tiết, hãy xem bài viết Tạo và quản lý Ứng dụng đã kết nối.

Làm cách nào để đưa ra ý kiến phản hồi về AppFunctions?

Bạn có thể đưa ra ý kiến phản hồi về API bằng cách gửi vấn đề.