مرور کلی AppFunctions

AppFunctions به برنامه اندروید شما اجازه می‌دهد تا بخش‌های خاصی از عملکرد را که سیستم و عوامل و دستیاران مختلف هوش مصنوعی می‌توانند کشف و فراخوانی کنند، به اشتراک بگذارد. با تعریف این توابع، شما برنامه خود را قادر می‌سازید تا خدمات، داده‌ها و اقدامات را به سیستم عامل اندروید ارائه دهد و به کاربران اجازه می‌دهد تا وظایف را از طریق عوامل هوش مصنوعی و تعاملات سطح سیستم انجام دهند.

AppFunctions به عنوان معادل موبایل ابزارهای درون پروتکل Model Context (MCP) عمل می‌کنند. در حالی که MCP به طور سنتی نحوه اتصال عامل‌ها به ابزارهای سمت سرور را استاندارد می‌کند، AppFunctions همان مکانیسم را برای برنامه‌های اندروید ارائه می‌دهد. این به شما امکان می‌دهد قابلیت‌های برنامه خود را به عنوان "ابزارهای" قابل تنظیم که برنامه‌های مجاز (تماس‌گیرندگان) می‌توانند آنها را کشف و اجرا کنند تا اهداف کاربر را برآورده کنند، در معرض نمایش قرار دهید. تماس‌گیرندگان باید مجوز EXECUTE_APP_FUNCTIONS را برای کشف و اجرای AppFunctions داشته باشند و می‌توانند شامل عامل‌ها، برنامه‌ها و دستیاران هوش مصنوعی مانند Gemini باشند.

AppFunctions با دستگاه‌هایی که اندروید ۱۶ یا بالاتر دارند کار می‌کند.

موارد استفاده مثال

AppFunctions مکانیزم قدرتمندی برای خودکارسازی وظایف و ساده‌سازی تعاملات کاربر فراهم می‌کند. با افشای قابلیت‌های برنامه خود، به کاربران این امکان را می‌دهید که با استفاده از زبان طبیعی به اهداف پیچیده دست یابند و اغلب نیاز به پیمایش گام به گام و دستی با رابط کاربری خود را کنار می‌گذارند.

سناریوهای زیر نشان می‌دهند که چگونه می‌توان از AppFunctions برای ایجاد تجربه‌های جدید در دسته‌های مختلف برنامه‌ها استفاده کرد:

• مدیریت وظایف و بهره‌وری
  • درخواست کاربر : « به من یادآوری کن که امروز ساعت ۵ بعد از ظهر بسته‌ام را از محل کارم تحویل بگیرم ».
  • اکشن AppFunction : فراخوانی‌کننده، برنامه مدیریت وظیفه مربوطه را شناسایی کرده و تابعی را برای ایجاد یک وظیفه فراخوانی می‌کند و به طور خودکار فیلدهای عنوان، زمان و مکان را بر اساس درخواست کاربر پر می‌کند.
• رسانه و سرگرمی
  • درخواست کاربر : « ایجاد یک لیست پخش جدید با برترین آلبوم‌های جاز امسال ».
  • اکشن AppFunction : فراخوانی‌کننده یک تابع ایجاد لیست پخش را در یک برنامه موسیقی اجرا می‌کند و متنی مانند «برترین آلبوم‌های جاز برای سال ۲۰۲۶» را به عنوان کوئری برای تولید و اجرای فوری محتوا ارسال می‌کند.
• گردش‌های کاری بین اپلیکیشنی
  • درخواست کاربر : « دستور پخت نودل را از ایمیل لیزا پیدا کن و مواد لازم را به لیست خرید من اضافه کن ».
  • اکشن AppFunction : این درخواست از توابع چندین برنامه استفاده می‌کند. ابتدا، فراخوانی‌کننده از تابع جستجوی برنامه ایمیل برای بازیابی محتوا استفاده می‌کند. سپس، مواد تشکیل‌دهنده مرتبط را استخراج کرده و تابع یک برنامه لیست خرید را برای پر کردن لیست کاربر فراخوانی می‌کند.
• تقویم و برنامه‌ریزی
  • درخواست کاربر : « جشن تولد مامان را برای دوشنبه آینده ساعت ۶ بعد از ظهر به تقویم من اضافه کن ».
  • اقدام AppFunction : برنامه عامل تأیید شده، تابع «ایجاد رویداد» برنامه تقویم را فراخوانی می‌کند و زمینه مرتبط مانند «دوشنبه آینده» و «6 بعد از ظهر» را تجزیه و تحلیل می‌کند تا ورودی را بدون نیاز به باز کردن دستی تقویم توسط کاربر ایجاد کند.

نحوه عملکرد AppFunctions

AppFunctions یک ویژگی پلتفرم اندروید ۱۶ و یک کتابخانه Jetpack همراه است که به برنامه‌ها اجازه می‌دهد توابع خاصی را برای تماس‌گیرندگان، مانند برنامه‌های عامل، در دسترس قرار دهند تا روی دستگاه اجرا شوند.

نمودار زیر جریان معمول نحوه اشتراک‌گذاری AppFunctionها توسط برنامه‌ها با یک عامل و متعاقباً اجرا شدن آنها را نشان می‌دهد. عامل‌ها احتمالاً هنگام رسیدگی به درخواست‌های کاربر، هم ابزارهای MCP از راه دور سمت سرور و هم AppFunctionهای محلی را با هم در نظر می‌گیرند. جریان دقیق استفاده از AppFunctionهای محلی به شرح زیر است:

• اعلان AppFunction : برنامه اندروید طوری ساخته شده است که AppFunctionهای خود، مانند «ایجاد یادداشت» یا «ارسال پیام» را نمایش دهد.
• تولید طرحواره : کتابخانه AppFunctions Jetpack یک فایل طرحواره XML تولید می‌کند که تمام AppFunctionهای اعلام‌شده در برنامه را فهرست می‌کند. این فایل توسط سیستم عامل اندروید برای فهرست‌بندی AppFunctionهای موجود استفاده می‌شود.
• بازیابی فراداده : عامل می‌تواند فراداده AppFunction را با پرس‌وجو از آن بازیابی کند.
• انتخاب و اجرای AppFunction : بر اساس درخواست‌های کاربر، عامل AppFunction مناسب را با پارامترهای مناسب انتخاب و اجرا می‌کند.

کتابخانه AppFunctions Jetpack نمایش قابلیت‌های برنامه شما را ساده می‌کند. با استفاده از پردازنده حاشیه‌نویسی، توسعه‌دهندگان توابعی را که می‌خواهند نمایش داده شوند، حاشیه‌نویسی می‌کنند. سپس فراخوانی‌کنندگان می‌توانند این توابع اندیس‌گذاری شده را با استفاده از AppFunctionManager کشف و فراخوانی کنند.

قبل از فراخوانی یک تابع، فراخوانی‌کنندگان باید با تلاش برای بازیابی نمونه‌ای از AppFunctionManager ، تأیید کنند که دستگاه از ویژگی AppFunctions پشتیبانی می‌کند. پس از پشتیبانی، فراخوانی‌کنندگان می‌توانند با استفاده از isAppFunctionEnabled(packageName, functionId) تأیید کنند که آیا یک تابع خاص در برنامه هدف فعال است یا خیر. پرس‌وجو از وضعیت توابع در سایر بسته‌ها به android.permission.EXECUTE_APP_FUNCTIONS permission نیاز دارد.

برنامه شما نیازی به تأیید پشتیبانی از ویژگی AppFunction ندارد؛ این کار به طور خودکار در کتابخانه Jetpack انجام می‌شود. برای مثال، AppFunctionManager می‌تواند تأیید کند که آیا از این ویژگی پشتیبانی می‌شود یا خیر.

در اینجا مثالی از AppFunctions برای یک برنامه یادداشت‌برداری با قابلیت‌های ایجاد، ویرایش و فهرست کردن یادداشت‌ها آورده شده است:

/**
 * A note app's [AppFunction]s.
 */
class NoteFunctions(
    private val noteRepository: NoteRepository
) {
    /**
     * Lists all available notes.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun listNotes(appFunctionContext: AppFunctionContext): List<Note>? {
        return noteRepository.appNotes.ifEmpty { null }?.toList()
    }

    /**
     * Adds a new note to the app.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     * @param title The title of the note.
     * @param content The note's content.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun createNote(
        appFunctionContext: AppFunctionContext,
        title: String,
        content: String
    ): Note {
        return noteRepository.createNote(title, content)
    }

    /**
     * Edits a single note.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     * @param noteId The target note's ID.
     * @param title The note's title if it should be updated.
     * @param content The new content if it should be updated.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun editNote(
        appFunctionContext: AppFunctionContext,
        noteId: Int,
        title: String?,
        content: String?,
    ): Note? {
        return noteRepository.updateNote(noteId, title, content)
    }
}

/**
 * A note.
 */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class Note(
    /** The note's identifier */
    val id: Int,
    /** The note's title */
    val title: String,
    /** The note's content */
    val content: String
)
AppFunctionsApiSnippets.kt

سوالات متداول

بخش زیر به سوالات متداول در مورد AppFunctions می‌پردازد.

س: من یک توسعه‌دهنده اپلیکیشن هستم. آیا می‌توانم AppFunctions را امروز پیاده‌سازی کنم؟

بله ، با پیروی از راهنمایی‌های شرح داده شده در بخش‌های قبلی، می‌توان AppFunctions را درون برنامه خود پیاده‌سازی و آزمایش کرد.

س: من AppFunctions را در برنامه‌ام پیاده‌سازی کرده‌ام. چرا عامل سیستم من نمی‌تواند به آنها دسترسی داشته باشد؟

الف ) AppFunctions یک ویژگی آزمایشی است. برای ارزیابی دقیق کیفیت تجربه کلی در طول این مرحله آزمایشی، فقط تعداد محدودی از برنامه‌ها و عوامل سیستم می‌توانند به کل خط لوله دسترسی داشته باشند.

س: من در حال توسعه یک عامل هستم. آیا می‌توانم به AppFunctions ارائه شده توسط برنامه‌ها دسترسی داشته باشم؟

الف ) عامل آزمایشی شما می‌تواند در محیط توسعه به AppFunctions دسترسی داشته باشد. در طول این مرحله آزمایشی، فقط تعداد محدودی از عامل‌های سیستم می‌توانند در محیط عملیاتی به AppFunctions دسترسی داشته و آنها را اجرا کنند.

س: کدام عامل‌های سیستم به AppFunctions دسترسی دارند؟

الف ) فقط تعداد محدودی از عامل‌های سیستم می‌توانند به کل خط لوله دسترسی داشته باشند در حالی که AppFunctions آزمایشی هستند.

س: چگونه می‌توانم برنامه‌ام را برای دسترسی عمومی به AppFunctions آماده کنم؟

الف ) در نظر بگیرید که می‌خواهید کدام ویژگی‌های برنامه خود را در معرض اتوماسیون عامل قرار دهید. می‌توانید AppFunctions را در برنامه خود پیاده‌سازی کنید. برای انجام این کار، مراحل بخش‌های قبلی این صفحه را دنبال کنید و با فراخوانی adb shell cmd app_function list-app-functions ، تأیید کنید که آنها در دستگاه ثبت شده‌اند.

س: آیا می‌توانم به تجربه توسعه‌دهنده عامل‌گرا از ابتدا تا انتها دسترسی پیدا کنم؟

الف ) ما در حال اجرای یک برنامه دسترسی زودهنگام (EAP) هستیم تا برنامه‌های منتخب را برای آزمایش تجربه توسعه‌دهنده سرتاسری مورد نیاز برای راه‌اندازی AppFunctions در محیط تولید اندروید، به صورت آن‌بورد ارائه دهیم. می‌توانید علاقه خود را برای ادغام AppFunctions خود از طریق این فرم ثبت‌نام EAP ثبت کنید. با ثبت علاقه، شما به طور خودکار به ادغام کامل دسترسی پیدا نمی‌کنید. در صورت انتخاب برنامه شما برای EAP یا اطلاع‌رسانی عمومی AppFunctions، به شما ایمیل خواهیم زد.

س: چگونه می‌توانم در مورد AppFunctions بازخورد ارائه دهم؟

الف ) شما می‌توانید با ثبت مشکل و ثبت علاقه خود در فرم برنامه دسترسی زودهنگام، در مورد API بازخورد ارائه دهید.