向应用添加 AppFunctions API

本指南介绍了如何将 AppFunctions API 集成到 Android 应用中、实现函数逻辑,以及验证集成是否正常运行。

版本兼容性

此实现要求将项目 compileSdk 设置为 API 级别 37 或更高级别。您的项目必须使用 Android Gradle 插件 9.1.0 或更高版本。

您的应用无需验证是否支持 AppFunctions;AppFunctions Jetpack 库会自动处理此验证。 如果支持该功能,AppFunctionManager 会返回一个实例,否则会返回 null。

依赖项

将所需的库依赖项添加到模块的 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 逻辑

如需为 Android 应用实现 AppFunction,请创建一个实现特定 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 实现在 Android 界面线程中运行。 因此,长时间运行的操作应执行以下操作:
    • 将 AppFunction 声明为挂起函数。
    • 当操作可能会阻塞线程时,切换到合适的协程调度程序。
  • 当 isDescribedByKDoc 设置为 true 时,函数说明或可序列化说明会编码为 AppFunctionMetadata 的一部分,以帮助智能体了解如何使用应用的 AppFunction。从 1.0.0-beta01 版开始,isDescribedByKDoc 没有默认值,因此请明确设置该值。

在清单中声明 AppFunction 服务

在模块清单(例如 src/main/AndroidManifest.xml)中注册 KSP 生成的服务声明和 app_metadata 属性。KSP 编译器会生成扩展抽象入口点类的具体服务类 (TaskAppFunctionService),以及 assets/ 目录中的相应 XML 架构。

<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 可用性

在限制 AppFunctions 时,使用 AppFunctionManager API 明确启用或停用函数。当应用的某些功能并非面向所有用户提供时,门控功能会非常有用。通过动态启用或停用 AppFunctions,智能系统可以确切知道用户在任何给定时间可以使用哪些功能。

如需安全地限制需要特定账号状态的 AppFunctions,请按以下两步流程操作:

第 1 步:默认停用该功能

为防止在功能标志经过验证之前访问函数,请将 @AppFunctionDeclaration 注解的 isEnabled 参数设置为 false。

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

第 2 步:在运行时动态启用该函数

对于每个 @AppFunctionServiceEntryPoint 类,编译器都会生成一个包含函数 ID 常量的对应类(使用 Ids 后缀)。您可以将这些生成的 ID 常量与 AppFunctionManager 中的 setAppFunctionEnabled 方法结合使用,在运行时更改函数的启用状态。

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 提供时,请注意,AI 智能体可能会在服务器上处理用户查询,以使用高级 LLM 功能。

为了提供良好的用户体验,同时避免泄露敏感信息,我们建议您遵循以下准则:

  • 受益于自然语言的功能:提供用户在对话中比通过手动界面导航更容易表达的任务。
  • 限制访问权限:创建 AppFunctions,仅向代理授予访问权限,使其能够访问满足用户特定请求所需的数据和操作。
  • 非敏感信息:仅分享非高度个人化或机密的数据,或用户在操作上下文中明确同意分享的数据。
  • 安全、非破坏性操作:仅提供用户通常会在应用中执行的安全、非破坏性任务,例如创建任务或搜索记事。如需了解详情,请参阅允许的操作和数据共享。

验证 AppFunction 集成

由于 AppFunctions 充当 AI 智能体调用的服务,因此测试分为两个方面:函数的行为方式,以及智能体在调用函数时的行为方式。

测试函数

首先对函数逻辑进行单元测试,并考虑通过 AppFunctions 库进行的智能体调用与直接 Kotlin 调用有何不同:

  • 默认值:Kotlin 默认参数值不适用。省略的可选参数会以 null、0、false 或空列表或数组的形式到达,因此 limit: Int = 10 参数会以 0 的形式到达。使用这些值测试省略的参数,并在函数体中解析默认值。如需了解详情,请参阅可选参数。
  • 主线程:平台调用从主线程开始,直接从单元测试调用 suspend 函数不会捕获主线程阻塞。确保数据库、网络和磁盘 I/O 在后台协程调度程序(例如 Dispatchers.IO)上运行。
  • 异常:当请求无法成功时,抛出特定的 AppFunctionException 子类。其他未捕获的异常会以 AppFunctionAppUnknownException 的形式到达代理,并附带原始异常消息,该消息不会标识故障类型。如需了解详情,请参阅错误处理。
  • 模型输入:由于输入来自模型,而不是受限的界面控件,因此请测试空字符串、同义词(例如“美元”和“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\"}}'"

使用代理进行测试

使用智能体进行测试,验证它是否会根据您的说明选择正确的函数,以及请求是否按预期运行。由于每个代理的行为各不相同,请使用调用 AppFunctions 的代理进行测试:

  • 示例代理:如需在本地测试工具发现和端到端工作流,请在设备上安装并运行开源 AppFunctions 测试代理。
  • Gemini:如需测试 Android 版 Gemini 如何调用您的 AppFunctions,请加入 Connected Apps Platform 开发者预览版,并按照创建和管理关联的应用中的说明操作。
  • 应用内代理:如果您的应用包含自己的代理,该代理会调用 AppFunctionManager 来执行同一软件包中的函数,那么您也应通过该代理测试您的函数。

在开发过程中,您还可以使用基于对话的助理(例如 Android Studio 中的 Gemini)和 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 架构,该架构整合了库依赖项并取代了旧版配置提供程序 (AppFunctionConfiguration.Provider)。1.0.0-alpha12 版移除了旧版提供程序。版本 1.0.0-alpha13 将 @AppFunction 注解重命名为 @AppFunctionDeclaration,版本 1.0.0-beta01 将应用元数据 XML 文件中的 appfn:description 属性重命名为 appfn:instructions。版本 1.0.0-rc01 移除了旧版 appfunctions:aggregateAppFunctions 编译器选项;如果您的 build 将其作为 KSP 参数传递,请将其移除。

如果您的应用使用的是较低版本的 AppFunctions(例如 1.0.0-alpha09 或 1.0.0-alpha10),您可以使用 AI IDE(例如 Android Studio 中的 Gemini)中的 AppFunctions 代理技能自动完成迁移。该技能包含专门的迁移规则,可引导智能体整合 build 依赖项、创建所需的 @AppFunctionServiceEntryPoint 服务封装容器、解耦上下文参数、更新清单声明、应用 1.0.0-beta01 重命名,以及移除已停用的编译器选项。