En esta guía, se explica cómo integrar la API de AppFunctions en tu app para Android, implementar la lógica de una función y verificar que la integración funcione correctamente.
Compatibilidad de versiones
Esta implementación requiere que tu proyecto compileSdk esté configurado en el nivel de API 37 o uno superior. Tu proyecto debe usar el complemento de Android para Gradle 9.1.0 o una versión posterior.
No es necesario que tu app verifique si se admiten las funciones de AppFunctions, ya que esto se controla automáticamente en la biblioteca de Jetpack de AppFunctions.
AppFunctionManager devuelve una instancia si se admite la función y, de lo contrario, devuelve un valor nulo.
Dependencias
Agrega las dependencias de biblioteca requeridas al archivo build.gradle.kts (o
build.gradle) de tu módulo y configura el complemento de KSP en el módulo de nivel superior de la app, como se muestra a continuación:
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")
}
Implementa la lógica de AppFunctions
Para implementar una AppFunction en tu app para Android, crea una clase que implemente la lógica específica de AppFunctions. Esto implica crear clases de datos serializables para los parámetros y las respuestas, y, luego, proporcionar la lógica principal dentro del método de la función.
En el siguiente código, se muestra un ejemplo de implementación para crear una tarea en la app de tareas pendientes, incluida la definición de parámetros personalizados y tipos de respuesta, y la lógica de la función principal con un repositorio.
@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) }
Puntos clave sobre el código
- De forma predeterminada, una implementación de AppFunction se ejecuta en el subproceso de IU de Android.
Por lo tanto, una operación de larga duración debe hacer lo siguiente:
- Declara la AppFunction como una función de suspensión.
- Cambia a un despachador de corrutinas adecuado cuando la operación pueda bloquear el subproceso.
- Cuando
isDescribedByKDocse establece entrue, la descripción de la función o la descripción serializable se codifica como parte deAppFunctionMetadatapara ayudar al agente a comprender cómo usar la AppFunction de la app. A partir de la versión 1.0.0-beta01,isDescribedByKDocno tiene un valor predeterminado, por lo que debes establecerlo de forma explícita.
Declara el servicio de AppFunction en tu manifiesto
Registra la declaración de servicio generada por KSP y la propiedad app_metadata
dentro del manifiesto del módulo, por ejemplo, en src/main/AndroidManifest.xml. El compilador de KSP genera la clase de servicio concreta (TaskAppFunctionService) que extiende tu clase de punto de entrada abstracta, junto con el esquema XML correspondiente en tu directorio 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" />
Opcional: Activa o desactiva la disponibilidad de AppFunction en el entorno de ejecución
Usa la API de AppFunctionManager para habilitar o inhabilitar funciones de forma explícita cuando
restrinjas tus AppFunctions. La restricción puede ser útil cuando algunas funciones de tu app no están disponibles para todos los usuarios. Cuando se habilitan o inhabilitan de forma dinámica las AppFunctions, el sistema de inteligencia sabe exactamente qué funciones están disponibles para el usuario en un momento determinado.
Para restringir de forma segura las AppFunctions que requieren un estado de cuenta específico, sigue un proceso de dos pasos:
Paso 1: Inhabilitar la función de forma predeterminada
Para evitar que se pueda acceder a la función antes de que se verifique la marca de función, establece el parámetro isEnabled de la anotación @AppFunctionDeclaration
en false.
@AppFunctionDeclaration(isEnabled = false, isDescribedByKDoc = true) suspend fun createTask( createTaskParams: CreateTaskParams, ): Task = TODO()
Paso 2: Habilitar la función de forma dinámica en el entorno de ejecución
Para cada clase @AppFunctionServiceEntryPoint, el compilador genera una clase correspondiente que contiene constantes de ID de función (con un sufijo Ids).
Puedes usar estas constantes de ID generadas junto con el método setAppFunctionEnabled de AppFunctionManager para cambiar el estado habilitado de una función durante el tiempo de ejecución.
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 } }
Consideraciones sobre los tipos de funciones que se deben poner a disposición
La seguridad siempre es primordial. Cuando elijas qué funciones de tu app estarán disponibles como AppFunctions, ten en cuenta que los agentes de IA podrían procesar las consultas de los usuarios en el servidor para usar funciones avanzadas de LLM.
Para proporcionar una excelente experiencia del usuario que también evite exponer información sensible, te recomendamos que sigas estos lineamientos:
- Funcionalidad que se beneficia del lenguaje natural: Haz que estén disponibles las tareas que son más fáciles de expresar para un usuario en una conversación que a través de la navegación manual por la IU.
- Restringe el acceso: Crea AppFunctions que solo le den al agente acceso a los datos y las acciones que se requieren para completar la solicitud específica del usuario.
- Información no sensible: Solo comparte datos que no sean información sensible o confidencial, o datos que el usuario acepte compartir de forma explícita en el contexto de la acción.
- Acciones seguras y no destructivas: Solo debes permitir que se realicen tareas seguras y no destructivas que los usuarios normalmente harían en tu app, como crear una tarea o buscar notas. Para obtener más información, consulta Acciones permitidas y uso compartido de datos.
Verifica la integración de AppFunction
Debido a que tus AppFunctions actúan como servicios a los que llaman los agentes de IA, las pruebas tienen dos lados: cómo se comporta tu función y cómo se comportan los agentes cuando la llaman.
Prueba la función
Comienza con pruebas de unidades para la lógica de tu función y ten en cuenta que una llamada de agente a través de la biblioteca de AppFunctions difiere de una llamada directa de Kotlin:
- Valores predeterminados: No se aplican los valores de parámetros predeterminados de Kotlin. Un parámetro opcional omitido llega como
null,0,falseo una lista o un array vacíos, por lo que un parámetrolimit: Int = 10llega como0. Prueba los parámetros omitidos con esos valores y resuelve los valores predeterminados en el cuerpo de la función. Para obtener más información, consulta Parámetros opcionales. - Subproceso principal: Las llamadas a la plataforma se inician en el subproceso principal, y llamar a tu función
suspenddirectamente desde una prueba de unidades no detecta el bloqueo del subproceso principal. Asegúrate de que la base de datos, la red y la E/S de disco se ejecuten en un despachador de corrutinas en segundo plano, comoDispatchers.IO. - Excepciones: Cuando una solicitud no puede tener éxito, arroja una subclase
AppFunctionExceptionespecífica. Otras excepciones no detectadas llegan al agente comoAppFunctionAppUnknownExceptioncon el mensaje de excepción sin procesar adjunto, que no identifica el tipo de falla. Para obtener más información, consulta Manejo de errores. - Entradas del modelo: Debido a que las entradas provienen de un modelo y no de controles de la IU restringidos, prueba cadenas en blanco, sinónimos como "dólares" para "USD" y valores fuera de rango.
En un dispositivo o emulador, usa adb shell cmd app_function para verificar que la plataforma haya indexado los metadatos generados y pueda invocar tu servicio.
Usa adb shell cmd app_function list-app-functions --package $myPackageName para ver los detalles de las AppFunctions que proporciona tu app.
También puedes ejecutar una AppFunction directamente desde la línea de comandos con su identificador explícito ("$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\"}}'"
Prueba con agentes
Realiza pruebas con un agente para verificar que seleccione la función correcta de tus descripciones y que la solicitud funcione como esperas. Como cada agente se comporta de manera diferente, realiza pruebas con los agentes que llaman a tus AppFunctions:
- Agente de muestra: Para probar el descubrimiento de herramientas y los flujos de trabajo de extremo a extremo de forma local, instala y ejecuta el agente de pruebas de AppFunctions de código abierto en tu dispositivo.
- Gemini: Para probar cómo Gemini en Android llama a tus AppFunctions, únete a la versión preliminar para desarrolladores de Connected Apps Platform y sigue las instrucciones de Crea y administra apps conectadas.
- Agente integrado en la app: Si tu app incluye su propio agente que llama a
AppFunctionManagerpara las funciones del mismo paquete, también prueba tus funciones a través de ese agente.
Durante el desarrollo, también puedes verificar tu integración con asistentes basados en chat, como Gemini en Android Studio, con la habilidad de agente de AppFunctions, o bien proporcionar una instrucción como la siguiente:
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.
Migra desde versiones de la API inferiores
En la versión 1.0.0-alpha10, AppFunctions introdujo una arquitectura de @AppFunctionServiceEntryPoint en tiempo de compilación que consolida las dependencias de la biblioteca y reemplaza los proveedores de configuración heredados (AppFunctionConfiguration.Provider). La versión 1.0.0-alpha12 quitó los proveedores heredados. En la versión 1.0.0-alpha13, se cambió el nombre de la anotación @AppFunction por @AppFunctionDeclaration, y en la versión 1.0.0-beta01, se cambió el nombre del atributo appfn:description en el archivo XML de metadatos de tu app por appfn:instructions. La versión 1.0.0-rc01 quitó la opción de compilador heredada appfunctions:aggregateAppFunctions. Si tu compilación la pasa como un argumento de KSP, quítala.
Si tu app usa una versión anterior de AppFunctions (como 1.0.0-alpha09 o
1.0.0-alpha10), puedes automatizar la migración con la habilidad del agente de
AppFunctions en un IDE de IA, como Gemini en Android Studio. La habilidad contiene
reglas de migración dedicadas que guían a un agente para consolidar tus dependencias de
compilación, crear el wrapper de servicio @AppFunctionServiceEntryPoint
necesario, desacoplar los parámetros de contexto, actualizar tus declaraciones de manifiesto, aplicar
los cambios de nombre de la versión 1.0.0-beta01 y quitar las opciones de compilador retiradas.
Habilidades de Android
Ver en GitHubImplementa AppFunctions
android skills add appfunctionsUse the AppFunctions skill to upgrade my app's AppFunctions implementation to 1.0.0-rc01.