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

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

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

تعمل AppFunctions كأدوات مكافئة للأدوات على الأجهزة الجوّالة ضمن بروتوكول Model Context Protocol (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 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: ينفّذ المتصل دالة إنشاء قائمة تشغيل ضمن تطبيق موسيقى، مع تمرير سياق مثل "أفضل ألبومات الجاز لعام 2026" كـ طلب بحث لإنشاء قائمة التشغيل على الفور.

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

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

  • طلب المستخدم: "إضافة حفل عيد ميلاد أمي إلى تقويمي ليوم الاثنين المقبل الساعة 6 مساءً".
  • إجراء 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

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

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

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

قبل استدعاء دالة، يجب أن يتأكّد المتصلون من أنّ الجهاز يتيح ميزة AppFunctions من خلال محاولة استرداد مثيل من AppFunctionManager. بعد أن يصبح الجهاز متوافقًا مع الميزة، يمكن للمتصلين التحقّق مما إذا كانت دالة معيّنة مفعّلة ضمن تطبيق مستهدَف باستخدام 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
)

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

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

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