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

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

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

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

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

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

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

# Add this to your app module at the top level. For multi module applications,
# you only need to specify this once.
ksp {
  arg("appfunctions:aggregateAppFunctions", "true")
}

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

ใช้ตรรกะ AppFunctions

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

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

package com.example.android.appfunctions


import androidx.appfunctions.AppFunctionSerializable
import androidx.appfunctions.AppFunctionContext
import androidx.appfunctions.AppFunctionElementNotFoundException
import androidx.appfunctions.AppFunctionInvalidArgumentException
import androidx.appfunctions.service.AppFunction
import javax.inject.Inject
...

// Developers can provide additional parameters in the constructor if needed.
// This requires a custom factory setup in the next step.
class TaskFunctions @Inject constructor(
  private val taskRepository: TaskRepository
) {
  /** The parameter to create the task. */
  @AppFunctionSerializable(isDescribedByKDoc = true)
  data class CreateTaskParams(
    /** The title of the task. */
    val title: String,
    /** The content of the task. */
     val content: String
  )

  /** The user-created task. */
  @AppFunctionSerializable(isDescribedByKDoc = true)
  data class Task(
    /** The ID of the task. */
    val id: String,
    /** The title of the task. */
    val title: String,
    /** The content of the task. */
    val content: String
  )

  /**
   * Creates a task based on [createTaskParams].
   *
   * @param createTaskParams The parameter to describe how to create the task.
   */
  @AppFunction(isDescribedByKDoc = true)
  suspend fun createTask(
    appFunctionContext: AppFunctionContext,
    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 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 ของแอป

ไม่บังคับ: ใช้ Hilt เพื่อระบุโรงงาน AppFunction ที่กำหนดเอง

หากคลาสการติดตั้งใช้งาน AppFunction ต้องมี Dependency ใน Constructor (เช่น ใน TaskRepository ในตัวอย่างก่อนหน้า) คุณจะต้อง ระบุ Factory ที่กำหนดเองเพื่อให้ระบบทราบวิธีสร้างอินสแตนซ์ ขั้นตอนนี้เป็นขั้นตอนที่ไม่บังคับและจำเป็นเฉพาะในกรณีที่คลาสฟังก์ชันมีพารามิเตอร์ของตัวสร้าง ตัวอย่างนี้แสดงวิธีสร้าง AppFunctionFactory ที่กำหนดเองและกำหนดค่าภายในคลาส Application โดยใช้ Hilt สำหรับการแทรกทรัพยากร Dependency

import android.app.Application
import androidx.appfunctions.service.AppFunctionConfiguration
import com.example.android.appfunctions.TaskFunctions
import dagger.hilt.android.HiltAndroidApp
import javax.inject.Inject

@HiltAndroidApp
class TodoApplication : Application(), AppFunctionConfiguration.Provider {
  @Inject lateinit var taskFunctions: TaskFunctions
  override fun onCreate() {
    super.onCreate()
  }
  // This shows how AppFunctions works with Hilt.
  override val appFunctionConfiguration: AppFunctionConfiguration
    get() =
      AppFunctionConfiguration.Builder()
        .addEnclosingClassFactory(TaskFunctions::class.java) { taskFunctions }
        .build()
}

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

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

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

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

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

@AppFunction(isEnabled = false, isDescribedByKDoc = true)
suspend fun createTask(...) { ... }

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

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

import androidx.appfunctions.AppFunctionManager
// Assuming there is a hook API to observe user state or feature flags
suspend fun onFeatureEnabled() {
    try {
        AppFunctionManager.getInstance(context)
            .setAppFunctionEnabled(
                // Function ID is generated for developer to get
                TaskFunctionsIds.CREATE_TASK_ID,
                AppFunctionManagerCompat.APP_FUNCTION_STATE_ENABLED,
            )
    } catch (e: Exception) {
        // Handle exception: AppFunctions indexation may not be fully completed
        // upon initial app startup.
    }
}

suspend fun onFeatureDisabled() {
    AppFunctionManagerCompat.getInstance(context)
        .setAppFunctionEnabled(
            TaskFunctionsIds.CREATE_TASK_ID,
            AppFunctionManagerCompat.APP_FUNCTION_STATE_DISABLED,
        )
}

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

ความปลอดภัยเป็นสิ่งสำคัญสูงสุดเสมอ เมื่อเลือกความสามารถของแอปที่จะทำให้พร้อมใช้งานเป็น 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 ที่แอปของคุณมี

ใน Gemini ใน Android Studio หรือเอเจนต์อื่นๆ ที่คุณเลือก ให้ระบุพรอมต์ เช่น พรอมต์ต่อไปนี้

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.