เพิ่ม AppFunctions API ลงในแอป

คู่มือนี้อธิบายวิธีผสานรวม AppFunctions API เข้ากับแอป Android, ใช้ตรรกะสำหรับฟังก์ชัน และยืนยันว่าการผสานรวมทำงานอย่างถูกต้อง

ความเข้ากันได้กับเวอร์ชัน

การใช้งานนี้กำหนดให้คุณตั้งค่า compileSdk ของโปรเจ็กต์เป็นระดับ API 36 ขึ้นไป

แอปของคุณไม่จำเป็นต้องตรวจสอบว่ารองรับ AppFunctions หรือไม่ เนื่องจากระบบจะจัดการเรื่องนี้โดยอัตโนมัติภายในไลบรารี AppFunctions Jetpack AppFunctionManager จะแสดงผลอินสแตนซ์หากรองรับฟีเจอร์ และแสดงผล Null หากไม่รองรับ

ความสัมพันธ์

เพิ่มทรัพยากร Dependency ของไลบรารีที่จำเป็นลงในไฟล์ build.gradle.kts (หรือ build.gradle) ของโมดูล และกำหนดค่าปลั๊กอิน KSP ในโมดูลแอประดับบนสุดดังที่แสดงด้านล่าง

dependencies {
  implementation("androidx.appfunctions:appfunctions:1.0.0-alpha10")
  // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
  // See Add the KSP plugin to your project
  ksp("androidx.appfunctions:appfunctions-compiler:1.0.0-alpha10")
}

ใช้ตรรกะ AppFunctions

หากต้องการใช้ AppFunction สำหรับแอป Android ให้สร้างคลาสที่ใช้ตรรกะ AppFunctions ที่เฉพาะเจาะจง ซึ่งเกี่ยวข้องกับการสร้างคลาสข้อมูลที่ทำให้เป็นอนุกรมได้สำหรับพารามิเตอร์และการตอบสนอง แล้วระบุตรรกะหลักภายในเมธอดฟังก์ชัน

โค้ดต่อไปนี้แสดงตัวอย่างการใช้งานสำหรับการสร้างงานในแอป TODO ซึ่งรวมถึงการกำหนดพารามิเตอร์และประเภทการตอบสนองที่กำหนดเอง รวมถึงตรรกะฟังก์ชันหลักโดยใช้ที่เก็บ

@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)
}

ประเด็นสำคัญเกี่ยวกับโค้ด

  • โดยค่าเริ่มต้น การใช้งาน AppFunction จะทำงานในเธรด UI ของ Android ดังนั้น การดำเนินการที่ใช้เวลานานควรทำดังนี้
    • ประกาศ AppFunction เป็นฟังก์ชันระงับ
    • เปลี่ยนไปใช้ตัวส่งสัญญาณโครูทีนที่เหมาะสมเมื่อการดำเนินการอาจบล็อกเธรด
  • เมื่อตั้งค่า isDescribedByKDoc เป็น true ระบบจะเข้ารหัสคำอธิบายฟังก์ชันหรือคำอธิบายที่ทำให้เป็นอนุกรมได้เป็นส่วนหนึ่งของ AppFunctionMetadata เพื่อช่วยให้ Agent เข้าใจวิธีใช้ AppFunction ของแอป

ประกาศบริการ AppFunction ในไฟล์ Manifest

ลงทะเบียนการประกาศบริการที่สร้างโดย KSP และพร็อพเพอร์ตี้ app_metadata ภายในไฟล์ Manifest ของโมดูล เช่น ใน src/main/AndroidManifest.xml คอมไพเลอร์ KSP จะสร้างคลาสบริการที่เป็นรูปธรรม (TaskAppFunctionService) ซึ่งขยายคลาสจุดเริ่มต้นแบบนามธรรม พร้อมกับสคีมา XML ที่เกี่ยวข้องในไดเรกทอรี assets/

<service
    android:name="com.example.snippets.ai.TaskAppFunctionService"
    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
    android:exported="true"
    tools:targetApi="36">
    <property
        android:name="android.app.appfunctions.schema"
        android:value="app_functions_schema.xsd" />
    <property
        android:name="android.app.appfunctions.v2"
        android:value="task_app_function_service.xml" />
    <intent-filter>
        <action android:name="android.app.appfunctions.AppFunctionService" />
    </intent-filter>
</service>
<property
    android:name="android.app.appfunctions.app_metadata"
    android:resource="@xml/app_metadata" />

ไม่บังคับ: สลับความพร้อมใช้งานของ AppFunction ในรันไทม์

ใช้ AppFunctionManager API เพื่อเปิดหรือปิดใช้ฟังก์ชันอย่างชัดเจนเมื่อควบคุมการเข้าถึง AppFunctions การควบคุมการเข้าถึงอาจมีประโยชน์เมื่อฟีเจอร์บางอย่างของแอปไม่พร้อมให้บริการแก่ผู้ใช้บางราย การเปิดหรือปิดใช้ AppFunctions แบบไดนามิกจะช่วยให้ระบบอัจฉริยะทราบได้อย่างชัดเจนว่าฟีเจอร์ใดพร้อมให้บริการแก่ผู้ใช้ในเวลาใดก็ตาม

หากต้องการควบคุมการเข้าถึง AppFunctions ที่ต้องใช้สถานะบัญชีที่เฉพาะเจาะจงอย่างปลอดภัย ให้ทำตามกระบวนการ 2 ขั้นตอนต่อไปนี้

ขั้นตอนที่ 1 ปิดใช้ฟังก์ชันโดยค่าเริ่มต้น

หากต้องการป้องกันไม่ให้เข้าถึงฟังก์ชันได้ก่อนที่จะมีการยืนยันแฟล็กฟีเจอร์ ให้ตั้งค่าพารามิเตอร์ isEnabled ของคำอธิบายประกอบ @AppFunction เป็น false

@AppFunction(isEnabled = false, isDescribedByKDoc = true)
suspend fun createTask(
    createTaskParams: CreateTaskParams,
): Task = TODO()

ขั้นตอนที่ 2 เปิดใช้ฟังก์ชันแบบไดนามิกในรันไทม์

สำหรับคลาส AppFunction แต่ละคลาส คอมไพเลอร์จะสร้างคลาสที่เกี่ยวข้องซึ่งมีค่าคงที่รหัสฟังก์ชัน (โดยใช้คำต่อท้าย Ids) คุณสามารถใช้ค่าคงที่รหัสที่สร้างขึ้นเหล่านี้ร่วมกับเมธอด setAppFunctionEnabled จาก AppFunctionManagerCompat เพื่อเปลี่ยนสถานะเปิดใช้ของฟังก์ชันในรันไทม์

suspend fun onFeatureEnabled(context: Context) {
    try {
        AppFunctionManager.getInstance(context)
            ?.setAppFunctionEnabled(
                BaseTaskAppFunctionServiceIds.CREATE_TASK_ID,
                AppFunctionManager.APP_FUNCTION_STATE_ENABLED,
            )
    } catch (e: Exception) {
        // Handle exception: AppFunctions indexation may not be fully completed
        // upon initial app startup.
    }
}

suspend fun onFeatureDisabled(context: Context) {
    try {
        AppFunctionManager.getInstance(context)
            ?.setAppFunctionEnabled(
                BaseTaskAppFunctionServiceIds.CREATE_TASK_ID,
                AppFunctionManager.APP_FUNCTION_STATE_DISABLED,
            )
    } catch (e: Exception) {
        // Handle exception
    }
}

ข้อควรพิจารณาเกี่ยวกับฟังก์ชันการทำงานประเภทต่างๆ ที่จะทำให้พร้อมใช้งาน

ความปลอดภัยเป็นสิ่งสำคัญที่สุดเสมอ เมื่อเลือกความสามารถของแอปที่จะทำให้พร้อมใช้งานเป็น AppFunctions คุณควรทราบว่า Agent ของระบบอาจประมวลผลคําค้นหาของผู้ใช้ในเซิร์ฟเวอร์เพื่อใช้ประโยชน์จากความสามารถขั้นสูงของ LLM

เราขอแนะนำให้ทำตามหลักเกณฑ์ต่อไปนี้เพื่อมอบประสบการณ์การใช้งานที่ยอดเยี่ยมแก่ผู้ใช้และหลีกเลี่ยงการเปิดเผยข้อมูลที่ละเอียดอ่อน

  • ฟังก์ชันการทำงานที่ได้ประโยชน์จากภาษาธรรมชาติ: ทำให้งานพร้อมใช้งาน ซึ่งผู้ใช้สามารถแสดงออกในการสนทนาได้ง่ายกว่าการไปยังส่วนต่างๆ ของ UI ด้วยตนเอง
  • จำกัดการเข้าถึง: สร้าง AppFunctions ที่ให้สิทธิ์เข้าถึง ข้อมูลและการดำเนินการแก่ Agent เฉพาะที่จำเป็นต่อการตอบสนองคำขอที่เฉพาะเจาะจงของผู้ใช้
  • ข้อมูลที่ไม่ละเอียดอ่อน: แชร์เฉพาะข้อมูลที่ไม่ใช่ข้อมูลส่วนบุคคล หรือข้อมูลลับ หรือข้อมูลที่ผู้ใช้ให้ความยินยอมอย่างชัดแจ้งที่จะแชร์ใน บริบทของการดำเนินการ
  • การยืนยันที่ชัดเจนสำหรับการดำเนินการที่ก่อให้เกิดความเสียหาย: ระมัดระวังอย่างยิ่ง กับฟังก์ชันที่ดำเนินการที่ก่อให้เกิดความเสียหาย (เช่น การลบ ข้อมูล) แม้ว่า Agent อาจเรียกใช้ฟังก์ชันดังกล่าว แต่แอปควรมีขั้นตอนการยืนยันของตัวเองและใช้ภาษาที่ชัดเจนและไม่คลุมเครือเกี่ยวกับเจตนา นอกจากนี้ การเพิ่มขั้นตอนการยืนยันมากกว่า 1 ขั้นตอนยังช่วยให้มั่นใจได้ว่าผู้ใช้ทราบถึงสิ่งที่ระบบขอให้ทำ

ยืนยันการผสานรวม AppFunction

หากต้องการยืนยันว่าคุณได้ผสานรวม AppFunctions อย่างถูกต้องหรือไม่ ให้ใช้ adb shell cmd app_function

ใช้ adb shell cmd app_function list-app-functions | grep --after-context 10 $myPackageName เพื่อดูรายละเอียดของ AppFunctions ที่แอปของคุณมี

นอกจากนี้ คุณยังเรียกใช้ AppFunction ได้โดยตรงจากบรรทัดคำสั่งโดยใช้ ตัวระบุที่ชัดเจน ("$enclosingClassName#$methodName") ดังนี้

adb shell "cmd app_function execute-app-function \
  --package com.example.android.appfunctions \
  --function 'com.example.android.appfunctions.BaseTaskAppFunctionService#createTask' \
  --parameters '{\"createTaskParams\": {\"title\": \"Buy milk\", \"content\": \"From grocery store\"}}'"

หากต้องการสัมผัสประสบการณ์การใช้งาน Android MCP และยืนยันเวิร์กโฟลว์แบบครบวงจรโดยไม่ต้อง ใช้พรอมต์ ให้ติดตั้งและเรียกใช้แอป Android ของ Agent สำหรับการทดสอบ AppFunctions ในอุปกรณ์

หากคุณกำลังยืนยันการผสานรวมโดยใช้ผู้ช่วยที่อิงตามการแชท เช่น Gemini ใน Android Studio ให้ใช้ทักษะการพัฒนา AppFunctions หรือระบุพรอมต์ เช่น พรอมต์ต่อไปนี้

Execute `adb shell cmd app_function` to learn how the tool works, then act as a
chat agent aiming to invoke AppFunctions to fulfil user prompts for this app.
Rely on the AppFunction description as instructions.

ย้ายข้อมูลจาก API เวอร์ชันต่ำกว่า

ในเวอร์ชัน 1.0.0-alpha10 AppFunctions ได้เปิดตัวสถาปัตยกรรม @AppFunctionServiceEntryPoint ในเวลาคอมไพล์ ซึ่งรวมทรัพยากร Dependency ของไลบรารีและแทนที่ผู้ให้บริการการกำหนดค่าเดิม (AppFunctionConfiguration.Provider)

หากแอปของคุณใช้ AppFunctions เวอร์ชันก่อนหน้า (เช่น 1.0.0-alpha09) อยู่ในปัจจุบัน คุณสามารถย้ายข้อมูลโดยอัตโนมัติได้โดยใช้ทักษะ Agent ของ AppFunctionsใน AI IDE เช่น Gemini ใน Android Studio ทักษะนี้มีกฎการย้ายข้อมูลเฉพาะที่จะแนะนำ Agent ให้รวมทรัพยากร Dependency ของบิลด์ สร้าง Wrapper บริการ @AppFunctionServiceEntryPoint ที่จำเป็น แยกพารามิเตอร์บริบท และอัปเดตการประกาศไฟล์ Manifest