مرور کلی 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 context The execution context provided by the system.
  *   @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(
      context: AppFunctionContext,
      title: String,
      dueDateTime: LocalDateTime? = null,
      location: String? = null
  ) : Task
  

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

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

  /**
  *   Create a new music playlist based on a natural language query.
  *
  *   @param context The execution context provided by the system.
  *   @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(
      context: AppFunctionContext,
      query: String
  ): Playlist
  

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

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

  /**
  *   Search for emails matching a query or sender name to retrieve content like recipes.
  *
  *   @param context The execution context provided by the system.
  *   @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(
      context: AppFunctionContext,
      query: String
  ): List<EmailSummary>
  
  /**
  *   Add a list of items or ingredients to the user's active shopping list.
  *
  *   @param context The execution context provided by the system.
  *   @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(
      context: AppFunctionContext,
      items: List<String>
  ): ShoppingList
  

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

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

  /**
  *   Schedule a new event on the user's primary calendar.
  *
  *   @param context The execution context provided by the system.
  *   @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(
      context: AppFunctionContext,
      title: String,
      startDateTime: LocalDateTime
  ): Event
  

نحوه عملکرد AppFunctions

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

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

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

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

برنامه شما نیازی به تأیید پشتیبانی از ویژگی 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
)

سوالات متداول (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 بازخورد ارائه دهید.