আপনার অ্যাপে 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-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)
}

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

  • ডিফল্ট হিসেবে, 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 ক্ষমতা ব্যবহার করার জন্য AI এজেন্ট সার্ভারে ব্যবহারকারীর কোয়েরি প্রসেস করতে পারে।

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

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

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

যেহেতু আপনার AppFunctions, AI এজেন্টের কল করা পরিষেবা হিসেবে কাজ করে, তাই টেস্টিংয়ের দুটি দিক আছে: আপনার ফাংশন কীভাবে আচরণ করে এবং কল করার সময় এজেন্টরা কীভাবে আচরণ করে।

আপনার ফাংশন পরীক্ষা করুন

আপনার ফাংশন লজিকের জন্য ইউনিট টেস্ট দিয়ে শুরু করুন, AppFunctions লাইব্রেরির মাধ্যমে এজেন্ট কল কীভাবে সরাসরি Kotlin কলের থেকে আলাদা তা বিবেচনা করে:

  • ডিফল্ট ভ্যালু: Kotlin ডিফল্ট প্যারামিটার ভ্যালু প্রযোজ্য নয়। বাদ দেওয়া ঐচ্ছিক প্যারামিটার null, 0, false বা খালি তালিকা বা অ্যারে হিসেবে আসে, তাই limit: Int = 10 প্যারামিটার 0 হিসেবে আসে। বাদ দেওয়া প্যারামিটারগুলি এই মানগুলির সাথে পরীক্ষা করুন এবং ফাংশন বডিতে ডিফল্টগুলি সমাধান করুন। আরও তথ্যের জন্য, ঐচ্ছিক প্যারামিটার দেখুন।
  • মেন থ্রেড: প্ল্যাটফর্ম কল মেন থ্রেডে শুরু হয় এবং ইউনিট টেস্ট থেকে সরাসরি আপনার suspend ফাংশন কল করলে মেন-থ্রেড ব্লকিং ধরা পড়ে না। ডেটাবেস, নেটওয়ার্ক ও ডিস্ক I/O ব্যাকগ্রাউন্ডে কোরুটিন ডিসপ্যাচার, যেমন Dispatchers.IO-এ চলছে কিনা তা নিশ্চিত করুন।
  • ব্যতিক্রম: কোনও অনুরোধ সফল না হলে, একটি নির্দিষ্ট AppFunctionException সাবক্লাস থ্রো করুন। অন্যান্য আনক্যাচড এক্সেপশন এজেন্টের কাছে AppFunctionAppUnknownException হিসেবে পৌঁছায়, যার সাথে আপনার র এক্সেপশন মেসেজ অ্যাটাচ করা থাকে, যা ব্যর্থতার ধরন শনাক্ত করে না। আরও তথ্যের জন্য, সমস্যা সমাধান দেখুন।
  • মডেল ইনপুট: যেহেতু ইনপুটগুলি সীমাবদ্ধ UI কন্ট্রোলের পরিবর্তে একটি মডেল থেকে আসে, তাই ফাঁকা স্ট্রিং, সমার্থক শব্দ যেমন "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 কল করে তা পরীক্ষা করতে, কানেক্টেড অ্যাপ প্ল্যাটফর্ম ডেভেলপার প্রিভিউতে যোগ দিন এবং কানেক্টেড অ্যাপ তৈরি ও ম্যানেজ করুন বিকল্প অনুসরণ করুন।
  • ইন-অ্যাপ এজেন্ট: আপনার অ্যাপে যদি নিজস্ব এজেন্ট থাকে যা একই প্যাকেজে ফাংশনের জন্য AppFunctionManager কল করে, তাহলে সেই এজেন্টের মাধ্যমেও আপনার ফাংশন পরীক্ষা করুন।

ডেভেলপমেন্টের সময়, আপনি AppFunctions এজেন্ট স্কিল সহ Android Studio-তে Gemini-র মতো চ্যাট-ভিত্তিক অ্যাসিস্ট্যান্ট ব্যবহার করে আপনার ইন্টিগ্রেশন যাচাই করতে পারেন, অথবা নিম্নলিখিত প্রম্পট দিতে পারেন:

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.

নিম্নতর 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 করা হয়েছে। ভার্সন 1.0.0-rc01 থেকে লিগ্যাসি appfunctions:aggregateAppFunctions কম্পাইলার বিকল্প সরিয়ে দেওয়া হয়েছে; আপনার বিল্ড যদি এটিকে KSP আর্গুমেন্ট হিসেবে পাস করে, তাহলে এটি সরিয়ে দিন।

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