หลักเกณฑ์ด้านคุณภาพของ AppFunctions

AppFunction เป็นฟังก์ชันที่เทียบเท่ากับเซิร์ฟเวอร์ MCP บน Android ในทางปฏิบัติ ซึ่งช่วยให้คุณแชร์ตรรกะบางส่วนของแอปกับ AI Agent และผู้ช่วย AI ได้

Agent จะใช้คำอธิบายเพื่อเลือก AppFunction ที่ตอบสนองคำขอ กระบวนการเลือกนี้ทำงานเหมือนกับการค้นพบเครื่องมือ MCP แบบดั้งเดิม ซึ่งแอปพลิเคชัน AI จะใช้คำอธิบายเซิร์ฟเวอร์และเครื่องมือ MCP เพื่อเป็นแนวทางในการเลือก แอปของคุณจะทำหน้าที่เป็นเซิร์ฟเวอร์ Android MCP และ AppFunction แต่ละรายการจะทำหน้าที่เป็นเครื่องมืออย่างหนึ่งของเซิร์ฟเวอร์ ระบุคำอธิบายต่อไปนี้

• คำอธิบายแอป (เซิร์ฟเวอร์ Android MCP) คำอธิบายแอปเป็นจุดแรกที่ Agent จะเข้าใจว่าแอปของคุณทำอะไรได้บ้าง หากต้องการช่วยให้ Agent ค้นพบแอปของคุณ ให้ระบุโดเมนหลักและระบุงานที่ AppFunctions ช่วยให้แอปทำได้โดยย่อ
  • เขียนคำอธิบายแอปด้วยตนเองในไฟล์ XML ของข้อมูลเมตาของแอป
  • ใช้คำอธิบายแอปเพื่ออธิบายสิ่งที่คำอธิบายฟังก์ชันแต่ละรายการอธิบายไม่ได้ เช่น ลำดับในการเรียกใช้ฟังก์ชัน
• คำอธิบาย AppFunction (เครื่องมือ) คำอธิบายฟังก์ชันแต่ละรายการจะอธิบายลักษณะการทำงานของ AppFunction 1 รายการ โดยทั่วไปแล้ว คำอธิบายฟังก์ชันจะประกอบด้วยคำกริยา เช่น อัปเดต สร้าง หรือจอง และทรัพยากร เช่น การตั้งค่า ช่อง หรือห้อง

หลักเกณฑ์เกี่ยวกับคำอธิบายฟังก์ชัน

Agent จะอาศัยคำอธิบายฟังก์ชันเพื่อตัดสินใจว่าฟังก์ชันใดเหมาะกับคำขอและวิธีเรียกใช้ฟังก์ชันนั้น

เขียนคำอธิบาย AppFunction ที่สั้นกระชับและไม่กำกวม

ยิ่งคำอธิบายมีความกำกวมน้อยเท่าใด ตัวแทนก็จะยิ่งเลือกฟังก์ชันที่เหมาะสมสำหรับคำขอได้อย่างน่าเชื่อถือมากขึ้นเท่านั้น ตารางต่อไปนี้แสดงสิ่งที่ควรทำและสิ่งที่ควรหลีกเลี่ยงในคำอธิบายฟังก์ชัน

เขียนโดยคำนึงถึงการห่อหุ้ม

เขียนคำอธิบายฟังก์ชันแต่ละรายการให้สมบูรณ์ในตัว เพื่อให้คำแนะนำแก่ Agent ในการใช้ฟังก์ชันนั้นๆ โดยไม่ใช้ฟังก์ชันอื่น ตารางต่อไปนี้แสดงหลักเกณฑ์การห่อหุ้ม

การดำเนินการที่อนุญาตและการแชร์ข้อมูล

ปฏิบัติตามหลักเกณฑ์ต่อไปนี้เพื่อปกป้องความเป็นส่วนตัวและความปลอดภัยของผู้ใช้เมื่อ Agent ใช้ฟังก์ชันของแอป

การออกแบบพารามิเตอร์และค่าที่แสดงผล

การออกแบบพารามิเตอร์และค่าที่แสดงผลอย่างรอบคอบจะช่วยป้องกันความกำกวมและลดโอกาสในการเรียกใช้ที่ไม่ถูกต้อง โปรดทำตามรูปแบบต่อไปนี้

พารามิเตอร์ที่ไม่บังคับ

เฉพาะประเภทที่อนุญาตค่า Null, ประเภทพื้นฐาน, ประเภทรายการ และประเภทอาร์เรย์เท่านั้นที่สามารถเป็นตัวเลือกได้ เมื่อ Agent ละเว้นพารามิเตอร์ที่ไม่บังคับ ไลบรารีจะส่งค่าเริ่มต้นของประเภท ซึ่งก็คือ null, 0, false หรือว่างเปล่า แทนค่าเริ่มต้นที่คุณประกาศ แก้ไขค่าเริ่มต้นที่มีความหมายในเนื้อหาฟังก์ชัน ดังตัวอย่างต่อไปนี้

/**
 * 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(),
    )
}

การอัปเดตแหล่งข้อมูลที่มีอยู่

ตัวอย่างต่อไปนี้ใช้ Wrapper SetField ที่เป็นค่า Null ได้สำหรับแต่ละช่องที่ตัวแทนอัปเดตได้ SetField ที่เป็นค่าว่างหมายถึง "ไม่ต้องเปลี่ยนแปลง" และ SetField(null) หมายถึง "ตั้งค่าเป็นค่าว่าง" ดังนี้

/** 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,
    )
}

การจัดการข้อผิดพลาด

เมื่อการเรียกใช้ไม่สำเร็จ Agent จะได้รับข้อยกเว้นที่ฟังก์ชันแสดงขึ้น รวมถึงประเภทและข้อความ ปฏิบัติตามรูปแบบต่อไปนี้เพื่อให้ Agent สามารถกู้คืนจากความล้มเหลวหรือรายงานให้ผู้ใช้ทราบได้