مرور کلی AppFunctions

AppFunctions یک API پلتفرم اندروید با یک کتابخانه Jetpack همراه برای ساده‌سازی ادغام MCP اندروید است. این کتابخانه به برنامه‌های شما این امکان را می‌دهد که مانند سرورهای MCP روی دستگاه رفتار کنند و توابعی را ارائه دهند که به عنوان ابزاری برای استفاده توسط ویژگی‌های پیشگیرانه به همراه عوامل و دستیاران، مانند Google Gemini، عمل می‌کنند. از ماه مه 2026، ادغام AppFunctions با Gemini در یک پیش‌نمایش خصوصی با آزمایش‌کنندگان معتبر قرار دارد. اکنون می‌توانید برنامه‌های خود را برای استفاده از AppFunctions و ابزارهای توسعه آماده کنید.

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

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

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

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

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

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

  • مدیریت وظایف و بهره‌وری

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

    /**
 * Create a new task or reminder with a title, due time, and location.
 *
 * @param title The descriptive title of the task (e.g., "Pick up my package").
 * @param dueDateTime The specific date and time when the task should be completed.
 * @param location The physical location associated with the task (e.g., "Work").
 * @return The created Task
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun createTask(
    title: String,
    dueDateTime: LocalDateTime? = null,
    location: String? = null,
): Task = TODO()

  • رسانه و سرگرمی

    • درخواست کاربر : « ایجاد یک لیست پخش جدید با برترین آلبوم‌های جاز امسال ».
    • اکشن AppFunction : فراخوانی‌کننده یک تابع ایجاد لیست پخش را در یک برنامه موسیقی اجرا می‌کند و متنی مانند "برترین آلبوم‌های جاز برای سال ۲۰۲۶" را به عنوان کوئری برای تولید فوری لیست پخش ارسال می‌کند. 

    /**
 * Create a new music playlist based on a natural language query.
 *
 * @param query The description used to generate the playlist (e.g., "top jazz albums from 2026").
 * @return The final created playlist based on songs.
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun createPlaylistFromQuery(
    query: String,
): Playlist = TODO()

  • گردش‌های کاری بین اپلیکیشنی

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

    /**
 * Search for emails matching a query or sender name to retrieve content like recipes.
 *
 * @param query The search term or contact name (e.g., "Lisa noodle recipe").
 * @return A list of matching email summaries containing the requested information.
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun searchEmails(
    query: String,
): List<EmailSummary> = TODO()

/**
 * Add a list of items or ingredients to the user's active shopping list.
 *
 * @param items The names of the ingredients or products to add to the list.
 * @return The final shopping list with new items added
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun addItemsToShoppingList(
    items: List<String>,
): ShoppingList = TODO()

  • تقویم و برنامه‌ریزی

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

    /**
 * Schedule a new event on the user's primary calendar.
 *
 * @param title The name of the calendar event (e.g., "Mom's birthday party").
 * @param startDateTime The specific date and time the event is scheduled to begin.
 * @return The created Event object.
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun createCalendarEvent(
    title: String,
    startDateTime: LocalDateTime,
): Event = TODO()

نحوه عملکرد AppFunctions

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

  • اعلان AppFunction : برنامه اندروید طوری ساخته شده است که از AppFunctions برای ارائه ویژگی‌هایی مانند «ایجاد یادداشت» یا «ارسال پیام» استفاده کند.
  • تولید طرحواره : کتابخانه AppFunctions Jetpack یک فایل طرحواره XML تولید می‌کند که تمام AppFunctionهای تعریف‌شده در برنامه را فهرست می‌کند. سیستم‌عامل اندروید از این فایل برای فهرست‌بندی AppFunctionهای موجود استفاده می‌کند.
  • بازیابی فراداده : عامل می‌تواند فراداده AppFunction را با پرس‌وجو از آن بازیابی کند. علاوه بر KDocs مختص به هر تابع، توسعه‌دهندگان می‌توانند الگوها و محدودیت‌های عملیاتی در سطح برنامه را در فراداده برنامه تعریف کنند تا هماهنگی عامل را در ابزارهای مختلف هدایت کنند.
  • انتخاب و اجرای AppFunction : بر اساس درخواست‌های کاربر، عامل AppFunction مناسب را با پارامترهای مناسب انتخاب و اجرا می‌کند.
توابع برنامه (AppFunctions) معمول از نمایش برنامه تا اجرای عامل (agent) جریان دارند.
شکل ۱ : جریان معمول نحوه نمایش و اجرای AppFunctionها توسط یک عامل.

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

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

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

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

@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.
     */
    @AppFunction(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)
}

/** The parameter to create the task. */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class CreateTaskParams(
    /** The title of the task. */
    val title: String?,
    /** The content of the task. */
    val content: String?,
)

/** The user-created task. */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class Task(
    /** The ID of the task. */
    val id: String,
    /** The title of the task. */
    val title: String,
    /** The content of the task. */
    val content: String,
)

نمونه‌ها، مهارت‌ها و ابزارهای آزمایش

ما موارد زیر را برای کمک به شما در ارتقای مهارت‌هایتان در AppFunctions در دسترس قرار داده‌ایم:

  • برای تأیید و بررسی نحوه عملکرد همه چیز در دستگاه‌هایتان، نمونه AppFunctions را بررسی کنید.
  • از مهارت عامل AppFunctions برای سرعت بخشیدن به توسعه در طول چرخه حیات چهار مرحله‌ای استفاده کنید:
    • کشف : کدبیس خود را تجزیه و تحلیل کنید تا ویژگی‌های ارزشمند را برای هماهنگ‌سازی هوش مصنوعی شناسایی و پیشنهاد دهید.
    • پیاده‌سازی و پیکربندی : پیاده‌سازی‌های کاتلین را ایجاد کنید و ابرداده‌های سیستم را پیکربندی کنید و وابستگی‌ها را بسازید.
    • اصلاح KDoc : بهینه‌سازی مستندسازی توابع و ویژگی‌ها برای عامل‌های هوش مصنوعی و MCP اندروید.
    • تست و اشکال‌زدایی : دستورات ADB را برای ارزیابی و اشکال‌زدایی محلی روی دستگاه ارائه می‌دهد.
  • برای آزمایش و تأیید خط فرمان، از دستورات ADB مانند adb shell cmd app_function ... به عنوان روشی مستقیم و سبک برای آزمایش ثبت تابع، بررسی توضیحات فراداده و اجرای توابع روی دستگاه استفاده کنید.
  • برای تجربه Android MCP در عمل و آزمایش گردش‌های کاری سرتاسری بدون نیاز به هیچ گونه دستورالعملی، برنامه اندروید AppFunctions testing agent را روی دستگاه خود نصب و استفاده کنید.

سوالات متداول (FAQ)

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

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

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

تفاوت بین AppFunctions و MCP چیست؟

هر دو به عامل‌های هوش مصنوعی اجازه می‌دهند ابزارها را هماهنگ کنند، اما تفاوت‌های قابل توجهی در معماری، تأخیر و تلاش مورد نیاز توسعه‌دهنده دارند. AppFunctionها قلاب‌های داخلی سطح سیستم عامل هستند که منحصر به اندروید هستند و به صورت محلی اجرا می‌شوند. در مقابل، یک سرور استاندارد MCP یک راه‌حل مستقل از پلتفرم است که به اجرای ابری و رفت و برگشت شبکه متکی است.

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

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

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

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

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

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

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

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

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