Nguyên tắc về chất lượng của AppFunctions

AppFunctions là phiên bản tương đương của máy chủ MCP trên Android. Các công cụ này cho phép bạn chia sẻ một số phần trong logic của ứng dụng với các tác nhân và trợ lý AI.

Tác nhân sử dụng nội dung mô tả để chọn AppFunction đáp ứng yêu cầu. Quá trình lựa chọn này hoạt động giống như quy trình khám phá công cụ MCP truyền thống, trong đó các ứng dụng AI sử dụng nội dung mô tả về máy chủ và công cụ MCP để đưa ra lựa chọn. Ứng dụng của bạn đóng vai trò là máy chủ MCP Android và mỗi AppFunction đóng vai trò là một trong các công cụ của máy chủ đó. Cung cấp các nội dung mô tả sau:

• Nội dung mô tả về ứng dụng (máy chủ MCP Android). Nội dung mô tả ứng dụng là điểm truy cập đầu tiên để các tác nhân hiểu được chức năng của ứng dụng. Để giúp các tác nhân khám phá ứng dụng của bạn, hãy bắt đầu bằng miền chính của ứng dụng và liệt kê ngắn gọn các nhiệm vụ mà AppFunctions cho phép ứng dụng hoàn thành.
  • Tự viết nội dung mô tả ứng dụng trong tệp XML siêu dữ liệu của ứng dụng.
  • Sử dụng nội dung mô tả ứng dụng để mô tả những điều mà nội dung mô tả hàm riêng lẻ không thể mô tả, chẳng hạn như thứ tự gọi hàm.
• Nội dung mô tả AppFunction (các công cụ). Mỗi nội dung mô tả hàm giải thích hành vi của một AppFunction. Nội dung mô tả chức năng thường được cấu trúc xoay quanh một động từ, chẳng hạn như cập nhật, tạo hoặc đặt trước, và một tài nguyên, chẳng hạn như chế độ cài đặt, kênh hoặc phòng.

Nguyên tắc mô tả hàm

Tác nhân dựa vào nội dung mô tả hàm để quyết định hàm nào phù hợp với yêu cầu và cách gọi hàm đó.

Viết nội dung mô tả ngắn gọn, rõ ràng về AppFunction

Nội dung mô tả càng rõ ràng thì tác nhân càng có thể chọn đúng hàm cho một yêu cầu một cách đáng tin cậy. Bảng sau đây liệt kê những việc nên làm và những việc nên tránh trong phần mô tả hàm:

Viết mã có tính đóng gói

Mỗi nội dung mô tả hàm phải độc lập để hướng dẫn tác nhân sử dụng hàm đó chứ không phải hàm nào khác. Bảng sau đây liệt kê các nguyên tắc đóng gói:

Các hành động được phép và việc chia sẻ dữ liệu

Hãy làm theo các nguyên tắc sau để bảo vệ quyền riêng tư và sự an toàn của người dùng khi tác nhân sử dụng các chức năng của ứng dụng:

Thiết kế tham số và giá trị trả về

Việc thiết kế tham số và giá trị trả về một cách cẩn thận sẽ giúp tránh được sự mơ hồ và giảm khả năng xảy ra các lệnh gọi không hợp lệ. Hãy tuân theo các quy ước sau:

Thông số tùy chọn

Chỉ các loại có thể rỗng, nguyên gốc, danh sách và mảng mới có thể là không bắt buộc. Khi tác nhân bỏ qua một tham số không bắt buộc, thư viện sẽ truyền giá trị mặc định của loại (null, 0, false hoặc trống) thay vì giá trị mặc định mà bạn khai báo. Giải quyết các giá trị mặc định có ý nghĩa trong phần thân hàm, như trong ví dụ sau:

/**
 * Creates a note.
 *
 * @param title The title of the note.
 * @param content The body text of the note.
 * @param attachments The files to attach to the note.
 * @param owner The ID of the user who owns the note.
 * @return The created note.
 */
@AppFunctionDeclaration(isDescribedByKDoc = true)
suspend fun createNote(
    title: String, // Required
    content: String? = null, // Optional
    attachments: List<Attachment> = emptyList(), // Optional
    owner: String? = null, // Optional
): Note = withContext(Dispatchers.IO) {
    noteRepository.createNote(
        title = title,
        // The library ignores declared default values and passes null for
        // omitted nullable parameters, so resolve meaningful defaults here.
        content = content ?: "",
        attachments = attachments,
        owner = owner ?: currentUserId(),
    )
}

Nội dung cập nhật đối với tài nguyên hiện có

Ví dụ sau đây sử dụng một trình bao bọc SetField có thể rỗng cho mỗi trường mà tác nhân có thể cập nhật. SetField rỗng có nghĩa là "không thay đổi" và SetField(null) có nghĩa là "đặt thành rỗng":

/** A new value for a field of an existing item. */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class SetField<T>(
    /** The new value of the field. */
    val value: T,
)

/**
 * Updates an existing note. Omitted fields keep their values.
 *
 * @param noteId The ID of the note to update.
 * @param title The new title of the note.
 * @param content The new body text of the note.
 * @return The updated note.
 */
@AppFunctionDeclaration(isDescribedByKDoc = true)
suspend fun updateNote(
    noteId: String,
    title: SetField<String>? = null,
    content: SetField<String?>? = null,
): Note = withContext(Dispatchers.IO) {
    val note = noteRepository.getNote(noteId)
        ?: throw AppFunctionElementNotFoundException(
            "No note found with ID $noteId"
        )
    noteRepository.updateNote(
        noteId = noteId,
        // A null SetField means "don't change", and SetField(null) means
        // "set to null", so don't use ?: for nullable fields.
        title = title?.value ?: note.title,
        content = if (content != null) content.value else note.content,
    )
}

Xử lý lỗi

Khi một lệnh gọi không thành công, nhân viên hỗ trợ sẽ nhận được ngoại lệ mà hàm của bạn gửi, bao gồm cả loại và thông báo của ngoại lệ đó. Hãy tuân theo các quy ước sau để tác nhân có thể khôi phục sau lỗi hoặc báo cáo lỗi cho người dùng: