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

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

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

การติดตั้งใช้งานนี้กำหนดให้โปรเจ็กต์ compileSdk ต้องตั้งค่าเป็นระดับ API 37 ขึ้นไป โปรเจ็กต์ต้องใช้ปลั๊กอิน Android Gradle เวอร์ชัน 9.1.0 ขึ้นไป

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

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

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

dependencies {
  implementation("androidx.appfunctions:appfunctions:1.0.0-rc01")
  // 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-rc01")
}

ใช้ตรรกะ 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 with a title, content, or both.
     *
     * @param createTaskParams The title and content of the task. At least one
     *   of them is required.
     * @return The created task, including its ID.
     */
    @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("A task needs a title, content, or both.")
        }

        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 เป็นฟังก์ชันระงับ
    • เปลี่ยนไปใช้ Coroutine Dispatcher ที่เหมาะสมเมื่อการดำเนินการอาจบล็อกเธรด
  • เมื่อตั้งค่า isDescribedByKDoc เป็น true ระบบจะเข้ารหัสคำอธิบายฟังก์ชันหรือคำอธิบายที่ทำให้เป็นอนุกรมได้เป็นส่วนหนึ่งของ AppFunctionMetadata เพื่อช่วยให้ Agent เข้าใจวิธีใช้ AppFunction ของแอป ตั้งแต่เวอร์ชัน 1.0.0-beta01 เป็นต้นไป isDescribedByKDoc จะไม่มีค่าเริ่มต้น ดังนั้นให้ตั้งค่าอย่างชัดเจน

ประกาศบริการ 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 ของคำอธิบายประกอบ @AppFunctionDeclaration เป็น false

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

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

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

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 โปรดทราบว่า AI Agent อาจประมวลผลคำค้นหาของผู้ใช้ในเซิร์ฟเวอร์เพื่อใช้ความสามารถ LLM ขั้นสูง

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

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

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

เนื่องจาก AppFunction ทำหน้าที่เป็นบริการที่ AI Agent เรียกใช้ การทดสอบจึงมี 2 ด้าน ได้แก่ ลักษณะการทำงานของฟังก์ชัน และลักษณะการทำงานของ Agent เมื่อเรียกใช้ฟังก์ชัน

ทดสอบฟังก์ชัน

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

  • ค่าเริ่มต้น: ค่าพารามิเตอร์เริ่มต้นของ Kotlin จะไม่มีผล พารามิเตอร์ที่ไม่บังคับซึ่งถูกละเว้นจะแสดงเป็น null, 0, false หรือรายการหรืออาร์เรย์ที่ว่างเปล่า ดังนั้นพารามิเตอร์ limit: Int = 10 จะแสดงเป็น 0 ทดสอบพารามิเตอร์ที่ละเว้นด้วยค่าเหล่านั้นและแก้ไขค่าเริ่มต้นในเนื้อหาฟังก์ชัน ดูข้อมูลเพิ่มเติมได้ที่พารามิเตอร์ที่ไม่บังคับ
  • เทรดหลัก: การเรียกใช้แพลตฟอร์มจะเริ่มในเทรดหลัก และการเรียกใช้ฟังก์ชัน suspend โดยตรงจาก Unit Test จะไม่ตรวจจับการบล็อกเทรดหลัก ตรวจสอบว่าฐานข้อมูล เครือข่าย และดิสก์ I/O ทำงานบนโปรแกรมจัดการ Coroutine ในเบื้องหลัง เช่น Dispatchers.IO
  • ข้อยกเว้น: เมื่อคำขอไม่สำเร็จ ให้แสดงคลาสย่อย AppFunctionException ที่เฉพาะเจาะจง ข้อยกเว้นอื่นๆ ที่ไม่ถูกตรวจจับจะเข้าถึง Agent เป็น AppFunctionAppUnknownException โดยมีข้อความข้อยกเว้นดิบแนบมาด้วย ซึ่งไม่ได้ระบุประเภทของความล้มเหลว ดูข้อมูลเพิ่มเติมได้ที่การจัดการข้อผิดพลาด
  • อินพุตของโมเดล: เนื่องจากอินพุตมาจากโมเดลแทนที่จะเป็นตัวควบคุม UI ที่จำกัด ให้ทดสอบสตริงว่าง คำพ้องความหมาย เช่น "ดอลลาร์" สำหรับ "USD" และค่าที่อยู่นอกช่วง

ในอุปกรณ์หรือโปรแกรมจำลอง ให้ใช้ adb shell cmd app_function เพื่อยืนยันว่าแพลตฟอร์มจัดทำดัชนีข้อมูลเมตาที่สร้างขึ้นและเรียกใช้บริการของคุณได้

ใช้ adb shell cmd app_function list-app-functions --package $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\"}}'"

ทดสอบกับตัวแทน

ทดสอบกับ Agent เพื่อยืนยันว่า Agent เลือกฟังก์ชันที่ถูกต้องจากคำอธิบายของคุณ และคำขอทำงานตามที่คุณคาดหวัง เนื่องจาก Agent แต่ละรายการมีลักษณะการทำงานที่แตกต่างกัน ให้ทดสอบกับ Agent ที่เรียกใช้ AppFunctions ของคุณ

  • ตัวแทนตัวอย่าง: หากต้องการทดสอบการค้นพบเครื่องมือและเวิร์กโฟลว์ตั้งแต่ต้นจนจบในเครื่อง ให้ติดตั้งและเรียกใช้ตัวแทนทดสอบ AppFunctions แบบโอเพนซอร์สในอุปกรณ์
  • Gemini: หากต้องการทดสอบวิธีที่ Gemini ใน Android เรียกใช้ AppFunctions ให้เข้าร่วมเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ของแพลตฟอร์มแอปที่เชื่อมต่อ แล้วทำตามหัวข้อสร้างและจัดการแอปที่เชื่อมต่อ
  • ตัวแทนในแอป: หากแอปของคุณมีตัวแทนของตัวเองที่เรียกใช้ AppFunctionManager สำหรับฟังก์ชันในแพ็กเกจเดียวกัน ให้ทดสอบฟังก์ชันผ่านตัวแทนนั้นด้วย

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

Execute `adb shell cmd app_function` to learn how the tool works, then act as a
chat agent aiming to invoke AppFunctions to fulfill user prompts for this app.
Use the AppFunction descriptions to choose functions and parameters.

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

ในเวอร์ชัน 1.0.0-alpha10, AppFunctions ได้เปิดตัวสถาปัตยกรรม @AppFunctionServiceEntryPoint เวลาคอมไพล์ที่รวมทรัพยากร Dependency ของไลบรารีและแทนที่ผู้ให้บริการการกำหนดค่าเดิม (AppFunctionConfiguration.Provider) เวอร์ชัน 1.0.0-alpha12 ได้นำผู้ให้บริการเดิมออก เวอร์ชัน 1.0.0-alpha13 ได้เปลี่ยนชื่อคำอธิบายประกอบ @AppFunction เป็น @AppFunctionDeclaration และเวอร์ชัน 1.0.0-beta01 ได้เปลี่ยนชื่อแอตทริบิวต์ appfn:description ในไฟล์ XML ข้อมูลเมตาของแอปเป็น appfn:instructions เวอร์ชัน 1.0.0-rc01 ได้นำตัวเลือกคอมไพเลอร์ appfunctions:aggregateAppFunctions เดิมออกแล้ว หากบิลด์ของคุณส่งตัวเลือกนี้เป็นอาร์กิวเมนต์ KSP ให้นำออก

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