نمای کلی AppFunctions

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

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

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

AppFunctions در دستگاه‌های دارای Android 16 یا بالاتر دردسترس است.

نمونه موارد استفاده

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
   */
  @AppFunctionDeclaration(isDescribedByKDoc = true)
  suspend fun createTask(
      title: String,
      dueDateTime: LocalDateTime? = null,
      location: String? = null,
  ): Task = TODO()
  AppFunctionApiSnippets.kt

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

  • درخواست کاربر: «فهرست پخش جدیدی با برترین آلبوم‌های جاز امسال ایجاد کن».
  • کنش 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.
   */
  @AppFunctionDeclaration(isDescribedByKDoc = true)
  suspend fun createPlaylistFromQuery(
      query: String,
  ): Playlist = TODO()
  AppFunctionApiSnippets.kt

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

  • درخواست کاربر: «دستور پخت نودل را در ایمیل لیزا پیدا کن و مواد لازم را به فهرست خریدم اضافه کن».
  • کنش 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.
   */
  @AppFunctionDeclaration(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
   */
  @AppFunctionDeclaration(isDescribedByKDoc = true)
  suspend fun addItemsToShoppingList(
      items: List<String>,
  ): ShoppingList = TODO()
  AppFunctionApiSnippets.kt

• تقویم و زمان‌بندی

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

  /**
   * 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.
   */
  @AppFunctionDeclaration(isDescribedByKDoc = true)
  suspend fun createCalendarEvent(
      title: String,
      startDateTime: LocalDateTime,
  ): Event = TODO()
  AppFunctionApiSnippets.kt

نحوه عملکرد AppFunctions

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

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

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

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

برنامه شما ملزم به درستی‌سنجی پشتیبانی شدن ویژگی 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.
     */
    @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)
}
AppFunctionApiSnippets.kt

/** 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,
)
AppFunctionApiSnippets.kt

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

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

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

پرسشگان (FAQ)

بخش زیر به پرسشگان درباره AppFunctions می‌پردازد.

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

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

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

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

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

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

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

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

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

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

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

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

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