আপনার অ্যাপে AppFunctions API যোগ করা

এই নির্দেশিকা থেকে জানতে পারবেন যে কীভাবে আপনার Android অ্যাপে AppFunctions API ইন্টিগ্রেট করবেন, কোনও ফাংশনের জন্য লজিক প্রয়োগ করবেন এবং ইন্টিগ্রেশন সঠিকভাবে কাজ করছে কিনা তা যাচাই করবেন।

ভার্সন কম্প্যাটিবিলিটি

এই প্রয়োগের জন্য আপনার প্রোজেক্ট compileSdk API লেভেল ৩৭ বা তার বেশি হতে হবে। আপনার প্রোজেক্টে Android Gradle প্লাগ-ইন 9.1.0 বা তার পরবর্তী যেকোনও ভার্সন ব্যবহার করতে হবে।

AppFunctions কাজ করে কিনা তা যাচাই করার জন্য আপনার অ্যাপের প্রয়োজন নেই; এটি AppFunctions Jetpack লাইব্রেরির মধ্যে অটোমেটিক ম্যানেজ করা হয়। ফিচারটি কাজ করলে AppFunctionManager একটি ইনস্ট্যান্স রিটার্ন করে এবং না করলে নাল রিটার্ন করে।

ডিপেন্ডেন্সি

আপনার মডিউলের build.gradle.kts (বা build.gradle) ফাইলে প্রয়োজনীয় লাইব্রেরি ডিপেন্ডেন্সি যোগ করুন এবং দেখানো পদ্ধতি অনুযায়ী আপনার টপ-লেভেল অ্যাপ মডিউলে KSP প্লাগ-ইন কনফিগার করুন:

dependencies {
  implementation("androidx.appfunctions:appfunctions:1.0.0-beta01")
  // 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-beta01")
}

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 based on [createTaskParams].
     *
     * @param createTaskParams The parameter to describe how to create the task.
     */
    @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("Title or content should be non-null")
        }

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

কোড সম্পর্কে গুরুত্বপূর্ণ পয়েন্ট

  • ডিফল্ট হিসেবে, Android UI থ্রেডে AppFunction ইমপ্লিমেন্টেশন রান করে। তাই, দীর্ঘ সময় ধরে চলা অপারেশনের ক্ষেত্রে নিম্নলিখিত কাজগুলি করা উচিত:
    • AppFunction-কে সাসপেন্ড ফাংশন হিসেবে ঘোষণা করুন।
    • অপারেশন থ্রেড ব্লক করতে পারলে, উপযুক্ত কোরুটিন ডিসপ্যাচারে পাল্টে নিন।
  • isDescribedByKDoc-কে true হিসেবে সেট করা হলে, ফাংশনের বিবরণ বা সিরিয়ালাইজ করা যায় এমন বিবরণ AppFunctionMetadata-এর অংশ হিসেবে এনকোড করা হয় যাতে এজেন্ট বুঝতে পারে যে অ্যাপের AppFunction কীভাবে ব্যবহার করতে হবে। 1.0.0-beta01 ভার্সন থেকে শুরু করে, isDescribedByKDoc-এর কোনও ডিফল্ট ভ্যালু নেই, তাই এটি স্পষ্টভাবে সেট করুন।

আপনার ম্যানিফেস্টে AppFunction পরিষেবা ঘোষণা করুন

আপনার মডিউল ম্যানিফেস্টের মধ্যে KSP-জেনারেটেড পরিষেবা ঘোষণা এবং app_metadata প্রপার্টি রেজিস্টার করুন, যেমন, src/main/AndroidManifest.xml-এ। KSP কম্পাইলার আপনার অ্যাবস্ট্রাক্ট এন্ট্রি পয়েন্ট ক্লাসকে এক্সটেন্ড করে কনক্রিট সার্ভিস ক্লাস (TaskAppFunctionService) তৈরি করে, এর সাথে আপনার assets/ ডিরেক্টরিতে সংশ্লিষ্ট XML স্কিমাও তৈরি করে।

<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 API ব্যবহার করুন। আপনার অ্যাপের নির্দিষ্ট কিছু ফিচার সব ব্যবহারকারীর জন্য উপলভ্য না হলে, গেটিং কার্যকর হতে পারে। 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 হিসেবে উপলভ্য করবেন তা বেছে নেওয়ার সময়, এটি মনে রাখা গুরুত্বপূর্ণ যে উন্নত LLM ক্ষমতার সুবিধা নিতে সিস্টেম এজেন্ট সার্ভারে ব্যবহারকারীর কোয়েরি প্রসেস করতে পারে।

ব্যবহারকারীদের দুর্দান্ত অভিজ্ঞতা প্রদান করতে এবং সংবেদনশীল তথ্য প্রকাশ করা এড়াতে, আমরা এইসব নির্দেশিকা অনুসরণ করার সাজেশন দিই:

  • ন্যাচারাল ল্যাঙ্গুয়েজ থেকে সুবিধা পায় এমন কার্যকারিতা: এমন টাস্ক উপলভ্য করুন যা ব্যবহারকারীর পক্ষে ম্যানুয়াল UI নেভিগেশনের চেয়ে কথোপকথনে প্রকাশ করা সহজ।
  • অ্যাক্সেস সীমিত করা: এমন AppFunctions তৈরি করুন যা এজেন্টকে শুধুমাত্র সেই ডেটা এবং অ্যাকশনের অ্যাক্সেস দেয় যা ব্যবহারকারীর নির্দিষ্ট অনুরোধ পূরণ করার জন্য প্রয়োজন।
  • সংবেদনশীল নয় এমন তথ্য: শুধুমাত্র এমন ডেটা শেয়ার করুন যা অত্যন্ত ব্যক্তিগত বা গোপনীয় নয় অথবা অ্যাকশনের প্রসঙ্গে ব্যবহারকারী স্পষ্টভাবে শেয়ার করার অনুমতি দিয়েছেন।
  • কোনও ধ্বংসাত্মক অ্যাকশনের জন্য দ্ব্যর্থহীন কনফার্মেশন: ধ্বংসাত্মক অ্যাকশন (যেমন ডেটা মুছে ফেলা) করে এমন ফাংশনের ব্যাপারে অত্যন্ত সতর্ক থাকুন। এজেন্ট এগুলি চালু করতে পারলেও, আপনার অ্যাপে নিজস্ব কনফার্মেশন ধাপ অন্তর্ভুক্ত করা উচিত এবং উদ্দেশ্য সম্পর্কে স্পষ্ট, দ্ব্যর্থহীন ভাষা ব্যবহার করা উচিত। এছাড়াও, ব্যবহারকারীকে কী করতে বলা হচ্ছে তা তিনি বুঝতে পেরেছেন কিনা তা নিশ্চিত করতে একাধিক কনফার্মেশন ধাপ যোগ করাও সহায়ক।

AppFunction ইন্টিগ্রেশন যাচাই করুন

আপনি সঠিকভাবে AppFunctions ইন্টিগ্রেট করেছেন কিনা তা যাচাই করতে, আপনি 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\"}}'"

Android MCP-এর অ্যাকশন এবং এন্ড-টু-এন্ড ওয়ার্কফ্লো কোনও প্রম্পট ছাড়াই যাচাই করতে, আপনার ডিভাইসে AppFunctions testing agent Android অ্যাপ ইনস্টল করে রান করুন।

আপনি যদি 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 fulfil user prompts for this app.
Use the AppFunction descriptions to choose functions and parameters.

নিম্নতর API ভার্সন থেকে মাইগ্রেট করুন

1.0.0-alpha10 ভার্সনে, AppFunctions একটি কম্পাইল-টাইম @AppFunctionServiceEntryPoint আর্কিটেকচার চালু করেছে যা লাইব্রেরি নির্ভরতা একত্রিত করে এবং লিগ্যাসি কনফিগারেশন প্রদানকারীদের (AppFunctionConfiguration.Provider) প্রতিস্থাপন করে। 1.0.0-alpha12 ভার্সন লিগ্যাসি প্রদানকারীদের সরিয়ে দিয়েছে। ভার্সন 1.0.0-alpha13-এ @AppFunction অ্যানোটেশনের নাম পরিবর্তন করে @AppFunctionDeclaration করা হয়েছে এবং ভার্সন 1.0.0-beta01-এ আপনার অ্যাপ মেটাডেটা XML ফাইলের appfn:description অ্যাট্রিবিউটের নাম পরিবর্তন করে appfn:instructions করা হয়েছে।

আপনার অ্যাপ যদি AppFunctions-এর কোনও পুরনো ভার্সন (যেমন 1.0.0-alpha09 বা 1.0.0-alpha10) ব্যবহার করে, তাহলে আপনি Android Studio-তে Gemini-র মতো AI IDE-তে AppFunctions এজেন্ট স্কিল ব্যবহার করে আপনার মাইগ্রেশন অটোমেট করতে পারবেন। এই স্কিলে মাইগ্রেশনের নির্দিষ্ট নিয়ম আছে যা আপনার বিল্ড ডিপেন্ডেন্সি একত্রিত করতে, প্রয়োজনীয় @AppFunctionServiceEntryPoint সার্ভিস র‍্যাপার তৈরি করতে, কন্টেক্সট প্যারামিটার ডিকাপল করতে, আপনার ম্যানিফেস্ট ঘোষণা আপডেট করতে এবং 1.0.0-beta01 রিনেম প্রয়োগ করতে এজেন্টকে নির্দেশ দেয়।