نظرة عامة على AppFunctions

‫AppFunctions هي واجهة برمجة تطبيقات لنظام Android الأساسي مع مكتبة Jetpack مصاحبة لتبسيط عملية دمج بروتوكول MCP على Android. فهي تتيح لتطبيقاتك العمل كخوادم MCP على الجهاز، ما يوفّر وظائف تعمل كأدوات تستخدمها الميزات الاستباقية إلى جانب الوكلاء والمساعدين، مثل Google Gemini. اعتبارًا من مايو 2026، أصبح دمج AppFunctions مع Gemini متاحًا في نسخة حصرية مع مختبِرين موثوق بهم. يمكنك البدء في إعداد تطبيقاتك الآن لاستخدام AppFunctions وأدوات المطوّرين.

من خلال تحديد هذه الدوال، يمكنك تمكين تطبيقك من تقديم الخدمات والبيانات والإجراءات إلى السجلّ المضمّن في نظام التشغيل Android، ما يتيح للمستخدمين إكمال المهام من خلال الوكلاء والتفاعلات على مستوى النظام.

تُعدّ AppFunctions المكافئ للأجهزة الجوّالة للأدوات ضمن بروتوكول سياق النموذج (MCP). في حين أنّ بروتوكول MCP يوحّد عادةً طريقة اتصال الوكلاء بالأدوات من جهة الخادم، توفّر واجهات AppFunctions الآلية نفسها لتطبيقات Android. يتيح لك ذلك عرض إمكانات تطبيقك كـ "أدوات" قابلة للتنسيق يمكن للتطبيقات المصرَّح لها (المتصلين) اكتشافها وتنفيذها لتلبية طلبات المستخدمين. يجب أن يحصل المتصلون على إذن EXECUTE_APP_FUNCTIONS لاكتشاف واجهات AppFunctions وتنفيذها، ويمكن أن يشمل ذلك الوكلاء والتطبيقات والمساعدين المستندين إلى الذكاء الاصطناعي مثل Gemini.

تتوفّر AppFunctions على الأجهزة التي تعمل بنظام التشغيل Android 16 أو إصدار أحدث.

أمثلة على حالات الاستخدام

توفّر AppFunctions آلية فعّالة لتنفيذ المهام آليًا وتبسيط تفاعلات المستخدمين. من خلال إتاحة إمكانات تطبيقك، يمكنك تمكين المستخدمين من تحقيق أهداف معقدة باستخدام اللغة الطبيعية، وغالبًا ما يحل ذلك محل الحاجة إلى التنقل اليدوي خطوة بخطوة في واجهة المستخدم.

توضّح السيناريوهات التالية كيفية استخدام AppFunctions لتقديم تجارب ضمن مجموعة متنوعة من فئات التطبيقات:

• إدارة المهام والإنتاجية

  • طلب المستخدم: "ذكّرني باستلام الطرد من العمل اليوم في الساعة 5 مساءً".
  • إجراء 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: ينفّذ المتصل دالة إنشاء قائمة تشغيل ضمن تطبيق موسيقى، ويمرّر سياقًا مثل "أفضل ألبومات الجاز لعام 2026" كطلب لإنشاء قائمة التشغيل على الفور.

  /**
   * 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

• التقويم والجداول الزمنية

  • طلب المستخدم: "أريد إضافة حفلة عيد ميلاد أمي إلى تقويمي يوم الاثنين القادم في الساعة 6 مساءً".
  • إجراء 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.
   */
  @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 من خلال إرسال طلب بحث عنها. بالإضافة إلى مستندات KDocs الخاصة بالوظائف، يمكن للمطوّرين تحديد الأنماط والقيود التشغيلية على مستوى التطبيق في البيانات الوصفية للتطبيق لتوجيه تنسيق الوكلاء عبر أدوات متعددة.
• اختيار AppFunction وتنفيذها: استنادًا إلى طلبات المستخدم، يختار الوكيل AppFunction المناسبة وينفّذها باستخدام المَعلمات المناسبة.

تسهّل مكتبة AppFunctions Jetpack عرض وظائف تطبيقك. باستخدام معالج التعليقات التوضيحية، يمكنك إضافة تعليقات توضيحية إلى الدوال التي تريد إتاحتها للوكلاء. ويمكن للمتصلين بعد ذلك العثور على هذه الدوال المفهرَسة واستدعاؤها باستخدام AppFunctionManager.

قبل استدعاء دالة، يجب أن يتحقّق المتصلون من أنّ الجهاز يتيح ميزة AppFunctions من خلال محاولة استرداد مثيل من AppFunctionManager. Once supported, callers can verify whether a specific function is enabled within a target app using 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: يمكنك تحسين مستندات الدوال والسمات لوكلاء الذكاء الاصطناعي وAndroid MCP.
  • الاختبار وتصحيح الأخطاء: توفير أوامر ADB للتقييم المحلي وتصحيح الأخطاء على الجهاز فقط.
• لإجراء الاختبار والتحقّق من خلال سطر الأوامر، استخدِم أوامر ADB، مثل adb shell cmd app_function ...، كطريقة مباشرة وبسيطة لاختبار تسجيل الدوال وفحص أوصاف البيانات الوصفية وتنفيذ الدوال على الجهاز فقط.

الأسئلة الشائعة

يتناول القسم التالي الأسئلة الشائعة حول 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؟

يمكنك تقديم ملاحظاتك بشأن واجهة برمجة التطبيقات من خلال الإبلاغ عن مشكلة وتسجيل اهتمامك في نموذج "برنامج استخدام المنتج قبل إطلاقه".