เพิ่ม 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 ที่เฉพาะเจาะจง ซึ่งรวมถึงการสร้างคลาสข้อมูลที่สามารถแปลงเป็นอนุกรมได้สำหรับพารามิเตอร์และการตอบกลับ จากนั้นจึงระบุตรรกะหลักภายในเมธอดฟังก์ชัน

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

@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 เพื่อช่วยให้เอเจนต์เข้าใจวิธีใช้ AppFunction ของแอป

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

ลงทะเบียนการประกาศบริการและพร็อพเพอร์ตี้ app_metadata ที่สร้างโดย KSP ภายในไฟล์ 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 เพื่อเปิดหรือปิดใช้ฟังก์ชันอย่างชัดเจนเมื่อ ควบคุมการเข้าถึง AppFunction การจำกัดการเข้าถึงจะเป็นประโยชน์เมื่อฟีเจอร์บางอย่างของแอป ไม่พร้อมให้บริการแก่ผู้ใช้บางราย การเปิดหรือปิดใช้ 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
    }
}

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

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

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

  • ฟังก์ชันการทำงานที่ได้รับประโยชน์จากภาษาธรรมชาติ: ทำให้งานพร้อมใช้งาน ซึ่งผู้ใช้สามารถแสดงออกในการสนทนาได้ง่ายกว่าการไปยังส่วนต่างๆ ของ UI ด้วยตนเอง
  • จำกัดการเข้าถึง: สร้าง AppFunction ที่ให้สิทธิ์เข้าถึงเฉพาะข้อมูลและการดำเนินการที่จำเป็นต่อการตอบสนองคำขอที่เฉพาะเจาะจงของผู้ใช้
  • ข้อมูลที่ไม่ละเอียดอ่อน: แชร์เฉพาะข้อมูลที่ไม่ใช่ข้อมูลส่วนบุคคล หรือข้อมูลลับ หรือข้อมูลที่ผู้ใช้ยินยอมอย่างชัดเจนให้แชร์ใน บริบทของการดำเนินการ
  • การยืนยันที่ชัดเจนสำหรับการดำเนินการที่ทำลายล้าง: โปรดระมัดระวังเป็นอย่างยิ่งกับฟังก์ชันที่ดำเนินการที่ทำลายล้าง (เช่น การลบข้อมูล) แม้ว่าเอเจนต์อาจเรียกใช้ฟังก์ชันเหล่านี้ แต่แอปของคุณควรมี ขั้นตอนการยืนยันของตัวเอง และใช้ภาษาที่ชัดเจนและไม่คลุมเครือเกี่ยวกับเจตนา นอกจากนี้ การเพิ่มขั้นตอนการยืนยันมากกว่า 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\"}}'"

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

หากคุณยืนยันการผสานรวมโดยใช้ผู้ช่วยแบบแชท เช่น 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) คุณสามารถทำให้การย้ายข้อมูลเป็นแบบอัตโนมัติได้โดยใช้เอเจนต์ AppFunctions skill ใน AI IDE เช่น Gemini ใน Android Studio Skill มีกฎการย้ายข้อมูลเฉพาะที่จะแนะนำ Agent ให้รวมการอ้างอิงบิลด์ สร้าง@AppFunctionServiceEntryPoint Service Wrapper ที่จำเป็น ยกเลิกการเชื่อมต่อพารามิเตอร์บริบท และอัปเดตประกาศในไฟล์ Manifest

หากต้องการเริ่มการย้ายข้อมูลอัตโนมัติด้วย AI Agent ให้ใช้พรอมต์ เช่น พรอมต์ต่อไปนี้

Use the AppFunctions migration skill to upgrade my app's AppFunctions implementation from 1.0.0-alpha09 to the 1.0.0-alpha10 @AppFunctionServiceEntryPoint architecture.