Как добавить в приложение API AppFunctions

В этом руководстве объясняется, как интегрировать 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 и удалить устаревшие параметры компилятора.