本指南說明如何將 AppFunctions API 整合至 Android 應用程式、實作函式邏輯,以及驗證整合是否正常運作。
版本相容性
如要採用這項實作,專案 compileSdk 必須設為 API 級別 37 以上。專案必須使用 Android Gradle 外掛程式 9.1.0 以上版本。
應用程式不需要驗證是否支援 AppFunctions,AppFunctions Jetpack 程式庫會自動處理這項作業。如果支援該功能,AppFunctionManager 會傳回例項,否則會傳回空值。
依附元件
將必要的程式庫依附元件新增至模組的 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 邏輯的類別。這包括為參數和回應建立可序列化的資料類別,然後在函式方法中提供核心邏輯。
下列程式碼範例說明如何在 TODO 應用程式中建立工作,包括定義自訂參數和回應類型,以及使用存放區的主要函式邏輯。
@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 UI 執行緒中執行。因此,長時間執行的作業應執行下列動作:
- 將 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,可讓智慧系統確切知道使用者在任何特定時間可使用哪些功能。
如要安全地限制需要特定帳戶狀態的 AppFunction,請按照下列兩步驟程序操作:
步驟 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 功能。
為提供優質的使用者體驗,同時避免洩漏機密資訊,建議您遵循下列規範:
- 適合使用自然語言的功能:提供使用者更容易透過對話表達,而非手動操作 UI 的工作。
- 縮小存取範圍:建立 AppFunction,只授予代理程式執行使用者特定要求所需的資料和動作存取權。
- 非機密資訊:僅分享非高度個人或機密的資料,或使用者在動作情境中明確同意分享的資料。
- 安全、非破壞性的動作:僅提供使用者通常會在應用程式中執行的安全、非破壞性工作,例如建立工作或搜尋記事。詳情請參閱「允許的操作和資料共用」。
驗證 AppFunction 整合
AppFunctions 是 AI 代理呼叫的服務,因此測試分為兩個部分:函式的行為,以及代理呼叫函式時的行為。
測試函式
首先,請針對函式邏輯進行單元測試,考量透過 AppFunctions 程式庫呼叫代理程式與直接呼叫 Kotlin 的差異:
- 預設值:Kotlin 預設參數值不適用。省略的選用參數會以
null、0、false或空白清單或陣列的形式傳送,因此limit: Int = 10參數會以0的形式傳送。使用這些值測試省略的參數,並在函式主體中解析預設值。詳情請參閱「選用參數」。 - 主執行緒:平台呼叫會從主執行緒開始,直接從單元測試呼叫
suspend函式不會擷取主執行緒封鎖。請確認資料庫、網路和磁碟 I/O 是在背景協同程式調度工具 (例如Dispatchers.IO) 上執行。 - 例外狀況:如果要求無法成功,請擲回特定
AppFunctionException子類別。其他未擷取的例外狀況會以AppFunctionAppUnknownException的形式傳送至代理,並附加原始例外狀況訊息,但不會指出失敗類型。詳情請參閱「錯誤處理」。 - 模型輸入:由於輸入內容來自模型,而非受限的 UI 控制項,因此請測試空白字串、同義詞 (例如「dollars」和「USD」),以及超出範圍的值。
在裝置或模擬器上,使用 adb shell cmd app_function 確認平台已為產生的中繼資料建立索引,且可叫用服務。
使用 adb shell cmd app_function list-app-functions --package $myPackageName 查看應用程式提供的 AppFunctions 詳細資料。
您也可以使用明確 ID ("$enclosingClassName#$methodName"),直接從指令列執行 AppFunction:
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 編譯器選項;如果建構作業將其做為 KSP 引數傳遞,請將其移除。
如果應用程式使用較舊版本的 AppFunctions (例如 1.0.0-alpha09 或 1.0.0-alpha10),您可以在 Android Studio 內建 Gemini 等 AI IDE 中,使用 AppFunctions 代理技能自動遷移。這項技能包含專屬遷移規則,可引導代理整合建構依附元件、建立必要的 @AppFunctionServiceEntryPoint 服務包裝函式、分離情境參數、更新資訊清單宣告、套用 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.