Ajouter l'API AppFunctions à votre application

Ce guide explique comment intégrer l'API AppFunctions à votre application Android, implémenter la logique d'une fonction et vérifier que l'intégration fonctionne correctement.

Compatibilité des versions

Pour cette implémentation, le compileSdk de votre projet doit être défini sur le niveau d'API 37 ou supérieur. Votre projet doit utiliser le plug-in Android Gradle 9.1.0 ou version ultérieure.

Votre application n'a pas besoin de vérifier si les AppFunctions sont compatibles. Cela est géré automatiquement dans la bibliothèque Jetpack AppFunctions. AppFunctionManager renvoie une instance si la fonctionnalité est compatible, et une valeur nulle si ce n'est pas le cas.

Dépendances

Ajoutez les dépendances de bibliothèque requises au fichier build.gradle.kts (ou build.gradle) de votre module, puis configurez le plug-in KSP dans le module d'application de premier niveau, comme indiqué ci-dessous :

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")
}

Implémenter la logique AppFunctions

Pour implémenter une AppFunction pour votre application Android, créez une classe qui implémente la logique AppFunctions spécifique. Pour ce faire, vous devez créer des classes de données sérialisables pour les paramètres et les réponses, puis fournir la logique de base dans la méthode de la fonction.

Le code suivant montre un exemple d'implémentation pour créer une tâche dans l'application TODO, y compris la définition de paramètres personnalisés et de types de réponses, ainsi que la logique de la fonction principale à l'aide d'un dépôt.

@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)
}

Points clés concernant le code

  • Par défaut, une implémentation AppFunction s'exécute dans le thread UI Android. Par conséquent, une opération de longue durée doit effectuer les opérations suivantes :
    • Déclarez l'AppFunction en tant que fonction de suspension.
    • Passez à un coordinateur de coroutines approprié lorsque l'opération risque de bloquer le thread.
  • Lorsque isDescribedByKDoc est défini sur true, la description de la fonction ou la description sérialisable est encodée dans le AppFunctionMetadata pour aider l'agent à comprendre comment utiliser l'AppFunction de l'application. À partir de la version 1.0.0-beta01, isDescribedByKDoc n'a pas de valeur par défaut. Définissez-la donc explicitement.

Déclarer le service AppFunction dans votre fichier manifeste

Enregistrez la déclaration de service générée par KSP et la propriété app_metadata dans le fichier manifeste de votre module, par exemple dans src/main/AndroidManifest.xml. Le compilateur KSP génère la classe de service concrète (TaskAppFunctionService) qui étend votre classe de point d'entrée abstraite, ainsi que le schéma XML correspondant dans votre répertoire 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" />

Facultatif : Activez ou désactivez la disponibilité d'AppFunction au moment de l'exécution

Utilisez l'API AppFunctionManager pour activer ou désactiver explicitement des fonctions lorsque vous contrôlez vos AppFunctions. Le gating peut être utile lorsque certaines fonctionnalités de votre application ne sont pas disponibles pour tous les utilisateurs. En activant ou en désactivant AppFunctions de manière dynamique, le système d'intelligence sait exactement quelles fonctionnalités sont disponibles pour votre utilisateur à un moment donné.

Pour sécuriser les AppFunctions qui nécessitent un état de compte spécifique, suivez un processus en deux étapes :

Étape 1 : Désactiver la fonction par défaut

Pour empêcher l'accès à la fonction avant que votre flag de fonctionnalité ne soit vérifié, définissez le paramètre isEnabled de votre annotation @AppFunctionDeclaration sur false.

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

Étape 2 : Activer dynamiquement la fonction au moment de l'exécution

Pour chaque classe @AppFunctionServiceEntryPoint, le compilateur génère une classe correspondante contenant des constantes d'ID de fonction (à l'aide d'un suffixe Ids). Vous pouvez utiliser ces constantes d'ID générées avec la méthode setAppFunctionEnabled de AppFunctionManager pour modifier l'état d'activation d'une fonction au moment de l'exécution.

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
    }
}

Considérations sur les types de fonctionnalités à mettre à disposition

La sécurité est toujours primordiale. Lorsque vous choisissez les fonctionnalités de votre application à rendre disponibles en tant qu'AppFunctions, n'oubliez pas que les agents d'IA peuvent traiter les requêtes des utilisateurs sur le serveur pour utiliser des fonctionnalités LLM avancées.

Pour offrir une expérience utilisateur optimale tout en évitant d'exposer des informations sensibles, nous vous recommandons de suivre ces consignes :

  • Fonctionnalités qui bénéficient du langage naturel : rendez disponibles les tâches qu'un utilisateur peut exprimer plus facilement dans une conversation que par une navigation manuelle dans l'interface utilisateur.
  • Accès restreint : créez des AppFunctions qui ne donnent à l'agent accès qu'aux données et aux actions nécessaires pour répondre à la requête spécifique de l'utilisateur.
  • Informations non sensibles : ne partagez que des données qui ne sont pas hautement personnelles ou confidentielles, ou des données que l'utilisateur accepte explicitement de partager dans le contexte de l'action.
  • Actions sûres et non destructives : ne proposez que des tâches sûres et non destructives que les utilisateurs effectuent normalement dans votre application, comme créer une tâche ou rechercher des notes. Pour en savoir plus, consultez Actions autorisées et partage de données.

Vérifier l'intégration d'AppFunction

Étant donné que vos AppFunctions agissent comme des services appelés par les agents IA, les tests comportent deux aspects : le comportement de votre fonction et le comportement des agents lorsqu'ils l'appellent.

Tester votre fonction

Commencez par des tests unitaires pour la logique de votre fonction, en tenant compte de la différence entre un appel d'agent via la bibliothèque AppFunctions et un appel Kotlin direct :

  • Valeurs par défaut : les valeurs de paramètre par défaut de Kotlin ne s'appliquent pas. Un paramètre facultatif omis arrive sous la forme null, 0, false, ou d'une liste ou d'un tableau vide. Un paramètre limit: Int = 10 arrive donc sous la forme 0. Testez les paramètres omis avec ces valeurs et résolvez les valeurs par défaut dans le corps de la fonction. Pour en savoir plus, consultez Paramètres facultatifs.
  • Thread principal : les appels de plate-forme démarrent sur le thread principal. Appeler votre fonction suspend directement à partir d'un test unitaire ne permet pas de détecter le blocage du thread principal. Assurez-vous que les opérations de base de données, de réseau et d'E/S disque s'exécutent sur un coordinateur de coroutines en arrière-plan, tel que Dispatchers.IO.
  • Exceptions : lorsqu'une requête ne peut pas aboutir, générez une sous-classe AppFunctionException spécifique. Les autres exceptions non interceptées atteignent l'agent en tant que AppFunctionAppUnknownException avec votre message d'exception brut joint, qui n'identifie pas le type d'échec. Pour en savoir plus, consultez Gestion des exceptions.
  • Entrées du modèle : étant donné que les entrées proviennent d'un modèle plutôt que de commandes d'interface utilisateur limitées, testez les chaînes vides, les synonymes tels que "dollars" pour "USD" et les valeurs hors plage.

Sur un appareil ou un émulateur, utilisez adb shell cmd app_function pour vérifier que la plate-forme a indexé vos métadonnées générées et peut appeler votre service.

Utilisez adb shell cmd app_function list-app-functions --package $myPackageName pour afficher les détails des AppFunctions fournies par votre application.

Vous pouvez également exécuter une AppFunction directement à partir de la ligne de commande à l'aide de son identifiant explicite ("$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\"}}'"

Tester avec des agents

Testez avec un agent pour vérifier qu'il sélectionne la bonne fonction à partir de vos descriptions et que la requête fonctionne comme prévu. Chaque agent se comportant différemment, effectuez des tests avec les agents qui appellent vos AppFunctions :

  • Exemple d'agent : pour tester la découverte d'outils et les workflows de bout en bout localement, installez et exécutez l'agent de test AppFunctions Open Source sur votre appareil.
  • Gemini : pour tester la façon dont Gemini sur Android appelle vos AppFunctions, rejoignez la preview développeur de la plate-forme Connected Apps Platform et suivez les instructions de la section Créer et gérer des applications connectées.
  • Agent intégré à l'application : si votre application inclut son propre agent qui appelle AppFunctionManager pour les fonctions du même package, testez également vos fonctions via cet agent.

Pendant le développement, vous pouvez également vérifier votre intégration à l'aide d'assistants basés sur le chat, comme Gemini dans Android Studio, avec la compétence d'agent AppFunctions, ou fournir un prompt comme celui-ci :

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.

Migrer depuis des versions d'API antérieures

Dans la version 1.0.0-alpha10, AppFunctions a introduit une architecture @AppFunctionServiceEntryPoint au moment de la compilation qui consolide les dépendances de bibliothèque et remplace les anciens fournisseurs de configuration (AppFunctionConfiguration.Provider). La version 1.0.0-alpha12 a supprimé les anciens fournisseurs. La version 1.0.0-alpha13 a renommé l'annotation @AppFunction en @AppFunctionDeclaration, et la version 1.0.0-beta01 a renommé l'attribut appfn:description dans le fichier XML de métadonnées de votre application en appfn:instructions. La version 1.0.0-rc01 a supprimé l'ancienne option de compilateur appfunctions:aggregateAppFunctions. Si votre build la transmet en tant qu'argument KSP, supprimez-la.

Si votre application utilise une version antérieure d'AppFunctions (comme 1.0.0-alpha09 ou 1.0.0-alpha10), vous pouvez automatiser votre migration à l'aide de la compétence d'agent AppFunctions dans un IDE d'IA comme Gemini dans Android Studio. La compétence contient des règles de migration dédiées qui guident un agent pour consolider vos dépendances de compilation, créer le wrapper de service @AppFunctionServiceEntryPoint requis, dissocier les paramètres de contexte, mettre à jour vos déclarations de fichier manifeste, appliquer les renommages de la version 1.0.0-beta01 et supprimer les options de compilateur obsolètes.