本指南介绍了如何将 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 重命名,以及移除已停用的编译器选项。
Android skills
在 GitHub 上查看实现 AppFunctions
android skills add appfunctionsUse the AppFunctions skill to upgrade my app's AppFunctions implementation to 1.0.0-rc01.