इस गाइड में, AppFunctions API को अपने Android ऐप्लिकेशन में इंटिग्रेट करने, किसी फ़ंक्शन के लिए लॉजिक लागू करने, और यह पुष्टि करने का तरीका बताया गया है कि इंटिग्रेशन सही तरीके से काम कर रहा है या नहीं.
वर्शन के साथ काम करने वाली सुविधाएं
इस सुविधा को लागू करने के लिए, ज़रूरी है कि आपका प्रोजेक्ट compileSdk, एपीआई लेवल 37 या इसके बाद के वर्शन पर सेट हो. आपके प्रोजेक्ट में Android Gradle प्लगिन 9.1.0 या इसके बाद के वर्शन का इस्तेमाल किया जाना चाहिए.
आपके ऐप्लिकेशन को यह पुष्टि करने की ज़रूरत नहीं है कि AppFunctions काम करते हैं या नहीं. यह काम, AppFunctions Jetpack लाइब्रेरी में अपने-आप हो जाता है.
अगर सुविधा काम करती है, तो AppFunctionManager एक इंस्टेंस दिखाता है. अगर सुविधा काम नहीं करती है, तो शून्य दिखाता है.
डिपेंडेंसी
अपने मॉड्यूल की build.gradle.kts (या build.gradle) फ़ाइल में, ज़रूरी लाइब्रेरी डिपेंडेंसी जोड़ें. साथ ही, अपने टॉप-लेवल ऐप्लिकेशन मॉड्यूल में केएसपी प्लगिन को कॉन्फ़िगर करें, जैसा कि यहां दिखाया गया है:
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")
}
AppFunctions का लॉजिक लागू करना
अपने Android ऐप्लिकेशन के लिए AppFunction लागू करने के लिए, एक ऐसी क्लास बनाएं जो AppFunctions के लॉजिक को लागू करती हो. इसके लिए, पैरामीटर और रिस्पॉन्स के लिए सीरियलाइज़ किए जा सकने वाले डेटा क्लास बनाने होंगे. इसके बाद, फ़ंक्शन के तरीके में मुख्य लॉजिक देना होगा.
यहां दिए गए कोड में, TODO ऐप्लिकेशन में टास्क बनाने का उदाहरण दिया गया है. इसमें कस्टम पैरामीटर और रिस्पॉन्स टाइप तय करने के साथ-साथ, रिपॉज़िटरी का इस्तेमाल करके मुख्य फ़ंक्शन लॉजिक को तय करने का तरीका भी बताया गया है.
@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) }
कोड के बारे में अहम बातें
- डिफ़ॉल्ट रूप से, AppFunction को लागू करने की प्रोसेस, Android यूज़र इंटरफ़ेस (यूआई) थ्रेड में चलती है.
इसलिए, ज़्यादा समय तक चलने वाली कार्रवाई को ये काम करने चाहिए:
- AppFunction को suspend फ़ंक्शन के तौर पर एलान करें.
- जब कोई ऑपरेशन थ्रेड को ब्लॉक कर सकता है, तो किसी सही कोरूटीन डिस्पैचर पर स्विच करें.
- जब
isDescribedByKDocकोtrueपर सेट किया जाता है, तो फ़ंक्शन के ब्यौरे या सीरियलाइज़ किए जा सकने वाले ब्यौरे कोAppFunctionMetadataके हिस्से के तौर पर एन्कोड किया जाता है. इससे एजेंट को यह समझने में मदद मिलती है कि ऐप्लिकेशन के AppFunction का इस्तेमाल कैसे करना है. वर्शन 1.0.0-beta01 से,isDescribedByKDocकी कोई डिफ़ॉल्ट वैल्यू नहीं है. इसलिए, इसे साफ़ तौर पर सेट करें.
अपनी मेनिफ़ेस्ट फ़ाइल में AppFunction सेवा के बारे में बताएं
केएसपी से जनरेट की गई सेवा के एलान और app_metadata प्रॉपर्टी को अपने मॉड्यूल मेनिफ़ेस्ट में रजिस्टर करें. उदाहरण के लिए, src/main/AndroidManifest.xml में. केएसपी कंपाइलर, आपकी ऐब्स्ट्रैक्ट एंट्री पॉइंट क्लास को एक्सटेंड करने वाली कॉंक्रीट सर्विस क्लास (TaskAppFunctionService) जनरेट करता है. साथ ही, आपकी 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" />
ज़रूरी नहीं: रनटाइम के दौरान AppFunction की उपलब्धता को टॉगल करना
अपने AppFunctions को गेट करते समय, फ़ंक्शन को साफ़ तौर पर चालू या बंद करने के लिए, AppFunctionManager एपीआई का इस्तेमाल करें. गेटिंग तब काम आ सकती है, जब आपके ऐप्लिकेशन की कुछ सुविधाएं सभी उपयोगकर्ताओं के लिए उपलब्ध न हों. AppFunctions को डाइनैमिक तौर पर चालू या बंद करके, इंटेलिजेंस सिस्टम को यह पता चलता है कि किसी भी समय उपयोगकर्ता के लिए कौनसी सुविधाएं उपलब्ध हैं.
खाते की किसी खास स्थिति की ज़रूरत वाले AppFunctions को सुरक्षित तरीके से गेट करने के लिए, दो चरणों वाली प्रोसेस अपनाएं:
पहला चरण. फ़ंक्शन को डिफ़ॉल्ट रूप से बंद करें
यह पक्का करने के लिए कि फ़ीचर फ़्लैग की पुष्टि होने से पहले फ़ंक्शन को ऐक्सेस न किया जा सके, अपने @AppFunctionDeclaration एनोटेशन के isEnabled पैरामीटर को false पर सेट करें.
@AppFunctionDeclaration(isEnabled = false, isDescribedByKDoc = true) suspend fun createTask( createTaskParams: CreateTaskParams, ): Task = TODO()
दूसरा चरण. रनटाइम के दौरान, फ़ंक्शन को डाइनैमिक तौर पर चालू करना
हर @AppFunctionServiceEntryPoint क्लास के लिए, कंपाइलर एक ऐसी क्लास जनरेट करता है जिसमें फ़ंक्शन आईडी कॉन्स्टेंट (Ids सफ़िक्स का इस्तेमाल करके) शामिल होते हैं.
जनरेट किए गए इन आईडी कॉन्स्टेंट का इस्तेमाल, AppFunctionManager के setAppFunctionEnabled तरीके के साथ किया जा सकता है. इससे रनटाइम के दौरान, किसी फ़ंक्शन के चालू होने की स्थिति को बदला जा सकता है.
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 } }
उपलब्ध कराई जाने वाली सुविधाओं के टाइप के बारे में ज़रूरी बातें
सुरक्षा हमेशा सबसे अहम होती है. अपने ऐप्लिकेशन की कौनसी सुविधाओं को AppFunctions के तौर पर उपलब्ध कराना है, यह चुनते समय ध्यान रखें कि एआई एजेंट, एलएलएम की बेहतर सुविधाओं का इस्तेमाल करने के लिए, सर्वर पर उपयोगकर्ता की क्वेरी प्रोसेस कर सकते हैं.
उपयोगकर्ताओं को बेहतरीन अनुभव देने और संवेदनशील जानकारी को ज़ाहिर होने से बचाने के लिए, हमारा सुझाव है कि आप इन दिशा-निर्देशों का पालन करें:
- नैचुरल लैंग्वेज से फ़ायदा पाने वाली सुविधा: ऐसे टास्क उपलब्ध कराएं जिन्हें उपयोगकर्ता, यूज़र इंटरफ़ेस (यूआई) पर मैन्युअल तरीके से नेविगेट करने के बजाय, बातचीत के ज़रिए आसानी से बता सके.
- ऐक्सेस सीमित करना: ऐसे AppFunctions बनाएं जो एजेंट को सिर्फ़ उस डेटा और कार्रवाइयों का ऐक्सेस दें जो उपयोगकर्ता के अनुरोध को पूरा करने के लिए ज़रूरी हैं.
- संवेदनशील जानकारी: सिर्फ़ ऐसा डेटा शेयर करें जो बहुत ज़्यादा निजी या गोपनीय न हो. इसके अलावा, ऐसा डेटा शेयर करें जिसे शेयर करने के लिए उपयोगकर्ता ने कार्रवाई के संदर्भ में साफ़ तौर पर सहमति दी हो.
- सुरक्षित और नुकसान न पहुंचाने वाली कार्रवाइयां: सिर्फ़ सुरक्षित और नुकसान न पहुंचाने वाले टास्क उपलब्ध कराएं, जिन्हें उपयोगकर्ता आम तौर पर आपके ऐप्लिकेशन में करते हैं. जैसे, कोई टास्क बनाना या नोट खोजना. ज़्यादा जानकारी के लिए, अनुमति वाली कार्रवाइयां और डेटा शेयर करना लेख पढ़ें.
AppFunction इंटिग्रेशन की पुष्टि करना
आपके AppFunctions, एआई एजेंट की ओर से कॉल की जाने वाली सेवाओं के तौर पर काम करते हैं. इसलिए, टेस्टिंग के दो पहलू होते हैं: आपका फ़ंक्शन कैसे काम करता है और उसे कॉल करते समय एजेंट कैसे काम करते हैं.
अपने फ़ंक्शन की जांच करना
अपने फ़ंक्शन लॉजिक के लिए यूनिट टेस्ट से शुरुआत करें. इसमें यह ध्यान रखें कि AppFunctions लाइब्रेरी के ज़रिए एजेंट कॉल, Kotlin कॉल से किस तरह अलग है:
- डिफ़ॉल्ट वैल्यू: Kotlin की डिफ़ॉल्ट पैरामीटर वैल्यू लागू नहीं होती हैं. हटाया गया वैकल्पिक पैरामीटर,
null,0,falseया खाली सूची या अरे के तौर पर आता है. इसलिए,limit: Int = 10पैरामीटर,0के तौर पर आता है. उन वैल्यू के साथ, हटाए गए पैरामीटर की जांच करें और फ़ंक्शन बॉडी में डिफ़ॉल्ट वैल्यू को ठीक करें. ज़्यादा जानकारी के लिए, वैकल्पिक पैरामीटर लेख पढ़ें. - मुख्य थ्रेड: प्लैटफ़ॉर्म कॉल, मुख्य थ्रेड पर शुरू होते हैं. साथ ही, यूनिट टेस्ट से सीधे
suspendफ़ंक्शन को कॉल करने पर, मुख्य थ्रेड को ब्लॉक करने वाली गड़बड़ी का पता नहीं चलता. पक्का करें कि डेटाबेस, नेटवर्क, और डिस्क I/O, बैकग्राउंड कोरूटीन डिस्पैचर पर चलें, जैसे किDispatchers.IO. - Exceptions: जब कोई अनुरोध पूरा न हो पाए, तो एक खास
AppFunctionExceptionसबक्लास थ्रो करें. अन्य अनकैच्ड एक्सेप्शन, एजेंट तकAppFunctionAppUnknownExceptionके तौर पर पहुंचते हैं. इनमें आपके रॉ एक्सेप्शन मैसेज अटैच होते हैं. इनसे यह पता नहीं चलता कि किस तरह की गड़बड़ी हुई है. ज़्यादा जानकारी के लिए, गड़बड़ी ठीक करना लेख पढ़ें. - मॉडल इनपुट: इनपुट, सीमित यूज़र इंटरफ़ेस (यूआई) कंट्रोल के बजाय मॉडल से आते हैं. इसलिए, खाली स्ट्रिंग, "USD" के लिए "डॉलर" जैसे समानार्थी शब्द, और रेंज से बाहर की वैल्यू की जांच करें.
किसी डिवाइस या एम्युलेटर पर, adb shell cmd app_function का इस्तेमाल करके पुष्टि करें कि प्लैटफ़ॉर्म ने आपके जनरेट किए गए मेटाडेटा को इंडेक्स किया है और आपकी सेवा को शुरू किया जा सकता है.
अपने ऐप्लिकेशन में मौजूद AppFunctions की जानकारी देखने के लिए, adb shell cmd app_function list-app-functions --package $myPackageName का इस्तेमाल करें.
किसी AppFunction को सीधे कमांड लाइन से भी चलाया जा सकता है. इसके लिए, उसके आइडेंटिफ़ायर ("$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\"}}'"
एजेंट की मदद से टेस्ट करना
किसी एजेंट के साथ टेस्ट करके पुष्टि करें कि वह आपके ब्यौरे से सही फ़ंक्शन चुनता है और अनुरोध आपकी उम्मीद के मुताबिक काम करता है. हर एजेंट अलग तरीके से काम करता है. इसलिए, उन एजेंट के साथ टेस्ट करें जो आपके AppFunctions को कॉल करते हैं:
- सैंपल एजेंट: टूल डिस्कवरी और एंड-टू-एंड वर्कफ़्लो को स्थानीय तौर पर टेस्ट करने के लिए, अपने डिवाइस पर ओपन-सोर्स AppFunctions टेस्टिंग एजेंट इंस्टॉल करें और चलाएं.
- Gemini: Android पर Gemini आपके AppFunctions को कैसे कॉल करता है, यह टेस्ट करने के लिए, Connected Apps Platform के डेवलपर के लिए झलक वाले प्रोग्राम में शामिल हों. इसके बाद, कनेक्ट किए गए ऐप्लिकेशन बनाएं और मैनेज करें में दिए गए निर्देशों का पालन करें.
- इन-ऐप्लिकेशन एजेंट: अगर आपके ऐप्लिकेशन में उसका अपना एजेंट शामिल है, जो एक ही पैकेज में मौजूद फ़ंक्शन के लिए
AppFunctionManagerको कॉल करता है, तो उस एजेंट के ज़रिए भी अपने फ़ंक्शन की जांच करें.
डेवलपमेंट के दौरान, चैट पर आधारित असिस्टेंट का इस्तेमाल करके भी इंटिग्रेशन की पुष्टि की जा सकती है. जैसे, Android Studio में Gemini के साथ AppFunctions एजेंट स्किल का इस्तेमाल करना या इस तरह का प्रॉम्प्ट देना:
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.
एपीआई के पुराने वर्शन से माइग्रेट करना
वर्शन 1.0.0-alpha10 में, AppFunctions ने कंपाइल के समय @AppFunctionServiceEntryPoint आर्किटेक्चर को पेश किया. यह आर्किटेक्चर, लाइब्रेरी की डिपेंडेंसी को एक साथ लाता है और लेगसी कॉन्फ़िगरेशन प्रोवाइडर (AppFunctionConfiguration.Provider) को बदल देता है. वर्शन 1.0.0-alpha12 में, लेगसी प्रोवाइडर हटा दिए गए हैं. वर्शन 1.0.0-alpha13 में, @AppFunction एनोटेशन का नाम बदलकर @AppFunctionDeclaration कर दिया गया है. साथ ही, वर्शन 1.0.0-beta01 में, ऐप्लिकेशन के मेटाडेटा की एक्सएमएल फ़ाइल में मौजूद appfn:description एट्रिब्यूट का नाम बदलकर appfn:instructions कर दिया गया है. वर्शन 1.0.0-rc01 में, लेगसी appfunctions:aggregateAppFunctions कंपाइलर विकल्प को हटा दिया गया है. अगर आपका बिल्ड इसे केएसपी आर्ग्युमेंट के तौर पर पास करता है, तो इसे हटा दें.
अगर आपका ऐप्लिकेशन, AppFunctions के किसी पुराने वर्शन (जैसे, 1.0.0-alpha09 या 1.0.0-alpha10) का इस्तेमाल करता है, तो Android Studio में Gemini जैसे एआई आईडीई में AppFunctions एजेंट स्किल का इस्तेमाल करके, माइग्रेशन की प्रोसेस को ऑटोमेट किया जा सकता है. इस स्किल में, माइग्रेशन के लिए खास नियम शामिल हैं. ये नियम, एजेंट को आपके बिल्ड की डिपेंडेंसी को एक साथ लाने, ज़रूरी @AppFunctionServiceEntryPoint सर्विस रैपर बनाने, कॉन्टेक्स्ट पैरामीटर को अलग करने, आपके मेनिफ़ेस्ट के एलान अपडेट करने, 1.0.0-beta01 के नाम बदलने, और कंपाइलर के उन विकल्पों को हटाने में मदद करते हैं जो अब काम नहीं करते.
Android स्किल
GitHub पर देखेंAppFunctions लागू करना
android skills add appfunctionsUse the AppFunctions skill to upgrade my app's AppFunctions implementation to 1.0.0-rc01.