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

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

من خلال تحديد هذه الوظائف في 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
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun createTask(
    title: String,
    dueDateTime: LocalDateTime? = null,
    location: String? = null,
): Task = TODO()

  • الإعلام والترفيه

    • طلب المستخدم: "إنشاء قائمة تشغيل جديدة تتضمّن أفضل ألبومات الجاز من هذا العام".
    • إجراء 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.
 */
@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()

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

    • طلب المستخدم: "إضافة حفل عيد ميلاد أمي إلى تقويمي ليوم الاثنين المقبل الساعة 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.
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun createCalendarEvent(
    title: String,
    startDateTime: LocalDateTime,
): Event = TODO()

آلية عمل AppFunctions

يوضّح المخطّط البياني التالي التدفق المعتاد لكيفية مشاركة التطبيقات لوظائف AppFunctions مع وكيل ثم تنفيذها. من المرجّح أن يأخذ الوكلاء في الاعتبار كلاً من أدوات MCP البعيدة من جهة الخادم وAppFunctions المحلية معًا عند معالجة طلبات المستخدمين. في ما يلي التدفق التفصيلي لاستخدام AppFunctions المحلية:

  • إعلان AppFunction: يتم إنشاء تطبيق Android لاستخدام AppFunctions من أجل إتاحة ميزاته، مثل "إنشاء ملاحظة" أو "إرسال رسالة".
  • إنشاء المخطط: تنشئ مكتبة AppFunctions Jetpack ملف مخطط XML يتضمّن جميع وظائف AppFunctions المُعلَنة في التطبيق. ويستخدم نظام التشغيل Android هذا الملف لفهرسة وظائف AppFunctions المتاحة.
  • استرداد البيانات الوصفية: يمكن للوكيل استرداد البيانات الوصفية لوظيفة AppFunction من خلال طلبها. بالإضافة إلى مستندات KDoc الخاصة بالدالة، يمكن للمطوّرين تحديد أنماط التشغيل والقيود على مستوى التطبيق في البيانات الوصفية للتطبيق لتوجيه تنسيق الوكيل على مستوى أدوات متعددة.
  • اختيار AppFunction وتنفيذها: استنادًا إلى طلبات المستخدمين، يختار الوكيل وظيفة AppFunction المناسبة وينفّذها باستخدام المَعلمات المناسبة.
يبدأ مسار AppFunctions النموذجي من عرض التطبيق إلى تنفيذ الوكيل.
الشكل 1: التدفق المعتاد لكيفية عرض الوكيل لوظائف AppFunctions وتنفيذها لاحقًا

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

قبل استدعاء دالة، يجب أن يتأكّد المتصلون من أنّ الجهاز يتيح ميزة AppFunctions من خلال محاولة استرداد مثيل من AppFunctionManager. بعد أن يصبح الجهاز متوافقًا مع الميزة، يمكن للمتصلين التأكّد مما إذا كانت دالة معيّنة مفعّلة ضمن تطبيق مستهدَف باستخدام 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 لتسريع عملية التطوير على مستوى دورة الحياة المكوّنة من أربع خطوات:
    • الاكتشاف: يمكنك تحليل قاعدة الرموز البرمجية لتحديد الميزات القيّمة التي يمكن تنسيقها باستخدام الذكاء الاصطناعي واقتراحها.
    • التنفيذ والإعداد: يمكنك إنشاء عمليات تنفيذ Kotlin وضبط البيانات الوصفية للنظام وإنشاء التبعيات.
    • تحسين مستندات KDoc: يمكنك تحسين مستندات الدوال والسمات للوكلاء المستندين إلى الذكاء الاصطناعي وبروتوكول MCP في Android.
    • الاختبار وتصحيح الأخطاء: يمكنك توفير أوامر Adb للتقييم المحلي وتصحيح الأخطاء على الجهاز فقط.
  • لإجراء الاختبار والتحقّق من سطر الأوامر، يمكنك استخدام أوامر ADB، مثل adb shell cmd app_function ... كطريقة مباشرة وخفيفة الوزن لاختبار تسجيل الدوال وفحص أوصاف البيانات الوصفية وتنفيذ الدوال على الجهاز فقط.
  • لتجربة بروتوكول MCP في Android أثناء العمل واختبار مهام سير العمل الشاملة بدون الحاجة إلى أي طلبات، يمكنك تثبيت تطبيق Android " وكيل اختبار AppFunctions" واستخدامه على جهازك.

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

يتناول القسم التالي الأسئلة الشائعة حول AppFunctions.

أنا مطوّر تطبيقات. هل يمكنني تنفيذ AppFunctions اليوم؟

نعم، من الممكن تنفيذ AppFunctions واختبارها ضمن تطبيقك باتّباع الإرشادات المفصّلة في الأقسام السابقة.

ما الفرق بين AppFunctions وبروتوكول MCP؟

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

باختصار، يتيح لك التطوير باستخدام AppFunctions استخدام حالة التطبيق الحالية مباشرةً على الجهاز فقط ولا يتطلّب منك الحفاظ على الخدمات خارج تطبيق Android.

لقد نفّذت AppFunctions في تطبيقي. لماذا لا يمكن للوكيل على مستوى النظام الوصول إليها؟

AppFunctions هي ميزة تجريبية. لتقييم جودة التجربة العامة بعناية خلال هذه المرحلة التجريبية، يمكن لعدد محدود فقط من التطبيقات والوكلاء على مستوى النظام الوصول إلى مسار البيانات بالكامل.

كيف يمكنني إعداد تطبيقي ليكون متوفرًا للجمهور العام لميزة AppFunctions؟

عليك تحديد ميزات تطبيقك التي تريد عرضها للأتمتة المستندة إلى الوكيل. يمكنك تنفيذ AppFunctions في تطبيقك. ولإجراء ذلك، اتّبِع الخطوات الواردة في الأقسام السابقة من هذه الصفحة، وتأكَّد من تسجيلها على الجهاز من خلال استدعاء adb shell cmd app_function list-app-functions.

هل يمكنني الحصول على وصول مبكر إلى تجربة المطوّر الشاملة المستندة إلى الوكيل؟

نحن نجري برنامج استخدام المنتج قبل إطلاقه (EAP) لإعداد تطبيقات محدّدة لاختبار تجربة المطوّر الشاملة المطلوبة لإطلاق AppFunctions في قناة الإصدار العلني على Android. يمكنك تسجيل اهتمامك بدمج AppFunctions من خلال نموذج تسجيل برنامج الاستخدام التجريبي أعلاه. من خلال تسجيل اهتمامك، لن تحصل تلقائيًا على إمكانية الوصول إلى عملية التكامل الكاملة. سنرسل إليك رسالة إلكترونية إذا تم اختيار تطبيقك لبرنامج الاستخدام التجريبي، أو لإعلامك عندما تصبح AppFunctions متاحة للجميع.

كيف يمكنني تقديم ملاحظات حول AppFunctions؟

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