คู่มือนี้อธิบายวิธีผสานรวม 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 และนำตัวเลือกคอมไพเลอร์ที่เลิกใช้งานแล้วออก
ทักษะ Android
ดูใน GitHubใช้ AppFunctions
android skills add appfunctionsUse the AppFunctions skill to upgrade my app's AppFunctions implementation to 1.0.0-rc01.