В этом руководстве объясняется, как интегрировать AppFunctions API в приложение Android, реализовать логику функции и проверить правильность интеграции.
Совместимость версий
Для этой реализации требуется, чтобы в вашем проекте compileSdk был установлен уровень API 37 или выше. В проекте должен использоваться плагин Android Gradle версии 9.1.0 или более поздней.
Приложению не нужно проверять, поддерживаются ли AppFunctions. Это автоматически выполняется в библиотеке Jetpack для AppFunctions.
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
Чтобы реализовать AppFunction для приложения Android, создайте класс, реализующий логику 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 выполняется в потоке UI Android.
Поэтому продолжительная операция должна выполнять следующие действия:
- Объявите AppFunction как функцию приостановки.
- Переключитесь на подходящий диспетчер сопрограмм, если операция может заблокировать поток.
- Если для
isDescribedByKDocзадано значениеtrue, описание функции или сериализуемое описание кодируется как частьAppFunctionMetadata, чтобы помочь агенту понять, как использовать AppFunction приложения. Начиная с версии 1.0.0-beta01, уisDescribedByKDocнет значения по умолчанию, поэтому его нужно задавать явно.
Объявите сервис AppFunction в манифесте
Зарегистрируйте декларацию сервиса, созданную KSP, и свойство app_metadata в манифесте модуля, например в 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, которым требуется определенное состояние аккаунта, выполните следующие действия:
Шаг 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, помните, что ИИ-агенты могут обрабатывать запросы пользователей на сервере, чтобы использовать расширенные возможности LLM.
Чтобы обеспечить удобство для пользователей и избежать раскрытия конфиденциальной информации, рекомендуем следовать следующим рекомендациям:
- Функции, для которых полезен естественный язык. Сделайте доступными задачи, которые пользователю проще выразить в разговоре, чем вручную перемещаться по интерфейсу.
- Ограничьте доступ. Создайте функции AppFunctions, которые предоставляют агенту доступ только к данным и действиям, необходимым для выполнения конкретного запроса пользователя.
- Неконфиденциальная информация. Передавайте только те данные, которые не являются личными или конфиденциальными, или те, на передачу которых пользователь дал явное согласие в контексте действия.
- Безопасные действия, не приводящие к потере данных. Сделайте доступными только безопасные задачи, которые пользователи обычно выполняют в вашем приложении, например создание задачи или поиск заметок. Подробнее о допустимых действиях и передаче данных…
Проверка интеграции AppFunction
Поскольку AppFunctions действуют как сервисы, вызываемые ИИ-агентами, тестирование состоит из двух частей: проверка поведения функции и проверка поведения агентов при ее вызове.
Протестируйте функцию
Начните с модульных тестов для логики функции, учитывая, чем вызов агента через библиотеку 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. Чтобы проверить, как Gemini на Android вызывает AppFunctions, присоединитесь к предварительной версии Connected Apps Platform для разработчиков и следуйте инструкциям в статье Как создавать подключенные приложения и управлять ими.
- Агент в приложении. Если в вашем приложении есть собственный агент, который вызывает
AppFunctionManagerдля функций в том же пакете, протестируйте функции и через него.
Во время разработки вы также можете проверить интеграцию с помощью чат-помощников, таких как Gemini в Android Studio, используя навык агента 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 атрибут appfn:description в XML-файле метаданных приложения переименован в appfn:instructions. В версии 1.0.0-rc01 удален устаревший параметр компилятора appfunctions:aggregateAppFunctions. Если в вашей сборке он передается как аргумент KSP, удалите его.
Если в вашем приложении используется более ранняя версия AppFunctions (например, 1.0.0-alpha09 или 1.0.0-alpha10), вы можете автоматизировать перенос с помощью навыка агента AppFunctions в ИИ-среде разработки, например Gemini в Android Studio. В навыке есть специальные правила переноса, которые помогают агенту объединить зависимости сборки, создать необходимую оболочку сервиса @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.