AppFunctions की क्वालिटी के लिए दिशा-निर्देश

AppFunctions, Android पर एमसीपी सर्वर की तरह ही काम करते हैं. इनकी मदद से, अपने ऐप्लिकेशन के लॉजिक के कुछ हिस्सों को एआई एजेंट और असिस्टेंट के साथ शेयर किया जा सकता है.

एजेंट, ब्यौरों का इस्तेमाल करके उस AppFunction को चुनते हैं जो किसी अनुरोध को पूरा करता है. चुनने की यह प्रोसेस, एमसीपी टूल खोजने के पारंपरिक तरीके की तरह काम करती है. इसमें एआई ऐप्लिकेशन, एमसीपी सर्वर और टूल के ब्यौरे का इस्तेमाल करके, अपने विकल्पों को चुनते हैं. आपका ऐप्लिकेशन, Android MCP सर्वर के तौर पर काम करता है. साथ ही, हर AppFunction इसके एक टूल के तौर पर काम करता है. जानकारी वाली ये ऐसेट जोड़ें:

• ऐप्लिकेशन का ब्यौरा (Android एमसीपी सर्वर). आपके ऐप्लिकेशन का ब्यौरा, एजेंट के लिए पहला एंट्री पॉइंट होता है. इससे एजेंट को यह समझने में मदद मिलती है कि आपका ऐप्लिकेशन क्या कर सकता है. एजेंट को आपका ऐप्लिकेशन खोजने में मदद करने के लिए, इसके मुख्य डोमेन के बारे में बताएं. साथ ही, उन टास्क की सूची बनाएं जिन्हें AppFunctions की मदद से पूरा किया जा सकता है.
  • ऐप्लिकेशन के मेटाडेटा की एक्सएमएल फ़ाइल में, ऐप्लिकेशन का ब्यौरा खुद लिखें.
  • ऐप्लिकेशन के ब्यौरे का इस्तेमाल करके, उन चीज़ों के बारे में बताएं जिनके बारे में अलग-अलग फ़ंक्शन के ब्यौरे में नहीं बताया जा सकता. जैसे, फ़ंक्शन को कॉल करने का क्रम.
• AppFunction के ब्यौरे (टूल). हर फ़ंक्शन के ब्यौरे में, एक AppFunction के काम करने के तरीके के बारे में बताया जाता है. फ़ंक्शन के ब्यौरे आम तौर पर, किसी वर्ब और रिसॉर्स के आस-पास स्ट्रक्चर किए जाते हैं. जैसे, अपडेट करें, बनाएं या बुक करें और सेटिंग, चैनल या कमरा.

फ़ंक्शन के ब्यौरे से जुड़े दिशा-निर्देश

एजेंट, फ़ंक्शन के ब्यौरे के आधार पर यह तय करते हैं कि किसी अनुरोध के लिए कौनसा फ़ंक्शन सही है और उसे कैसे कॉल करना है.

AppFunction के बारे में कम शब्दों में और साफ़ तौर पर जानकारी देना

जानकारी जितनी साफ़ होगी, एजेंट किसी अनुरोध के लिए सही फ़ंक्शन को उतनी ही भरोसेमंद तरीके से चुन पाएगा. नीचे दी गई टेबल में बताया गया है कि फ़ंक्शन की जानकारी में क्या करना चाहिए और क्या नहीं:

एनकैप्सुलेशन को ध्यान में रखकर कोड लिखें

हर फ़ंक्शन के ब्यौरे को पूरी तरह से अपने-आप में पूरा रखें, ताकि वह एजेंट को उस फ़ंक्शन का इस्तेमाल करने में मदद करे, न कि किसी दूसरे फ़ंक्शन का. यहां दी गई टेबल में, एनकैप्सुलेशन के दिशा-निर्देशों की सूची दी गई है:

अनुमति वाली कार्रवाइयां और डेटा शेयर करना

जब एजेंट आपके ऐप्लिकेशन के फ़ंक्शन इस्तेमाल करें, तब उपयोगकर्ता की निजता और सुरक्षा को बनाए रखने के लिए इन दिशा-निर्देशों का पालन करें:

पैरामीटर और रिटर्न वैल्यू का डिज़ाइन

पैरामीटर और रिटर्न वैल्यू को ध्यान से डिज़ाइन करने से, भ्रम की स्थिति पैदा नहीं होती. साथ ही, अमान्य कॉल की संभावना कम हो जाती है. इन नियमों का पालन करें:

वैकल्पिक पैरामीटर

सिर्फ़ नलेबल, प्रिमिटिव, लिस्ट, और अरे टाइप को वैकल्पिक बनाया जा सकता है. जब एजेंट किसी वैकल्पिक पैरामीटर को शामिल नहीं करता है, तो लाइब्रेरी आपके तय किए गए डिफ़ॉल्ट वैल्यू के बजाय, टाइप की डिफ़ॉल्ट वैल्यू पास करती है. जैसे, null, शून्य, 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(),
    )
}

मौजूदा संसाधनों से जुड़े अपडेट

यहां दिए गए उदाहरण में, हर उस फ़ील्ड के लिए नलेबल SetField रैपर का इस्तेमाल किया गया है जिसे एजेंट अपडेट कर सकता है. SetField की वैल्यू null होने का मतलब है कि "कोई बदलाव न करें" और SetField(null) का मतलब है कि "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,
    )
}

गड़बड़ी ठीक करना

कॉल न हो पाने पर, एजेंट को आपके फ़ंक्शन से मिलने वाला अपवाद मिलता है. इसमें अपवाद का टाइप और मैसेज शामिल होता है. इन नियमों का पालन करें, ताकि एजेंट गड़बड़ी को ठीक कर सके या उपयोगकर्ता को इसकी जानकारी दे सके: