Adicionar a API AppFunctions ao seu app

Este guia explica como integrar a API AppFunctions ao seu app Android, implementar a lógica de uma função e verificar se a integração funciona corretamente.

Compatibilidade de versões

Essa implementação exige que o compileSdk do projeto seja definido como o nível 37 ou mais recente da API. Seu projeto precisa usar o Plug-in do Android para Gradle 9.1.0 ou mais recente.

Seu app não precisa verificar se as AppFunctions são compatíveis. Isso é processado automaticamente na biblioteca AppFunctions do Jetpack. AppFunctionManager vai retornar uma instância se o recurso for compatível e nulo se não for.

Dependências

Adicione as dependências de biblioteca necessárias ao arquivo build.gradle.kts (ou build.gradle) do módulo e configure o plug-in do KSP no módulo do app de nível superior, conforme mostrado:

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

Implementar a lógica de AppFunctions

Para implementar uma AppFunction no seu app Android, crie uma classe que implemente a lógica específica das AppFunctions. Isso envolve a criação de classes de dados serializáveis para parâmetros e respostas e, em seguida, o fornecimento da lógica principal no método da função.

O código a seguir mostra um exemplo de implementação para criar uma tarefa no app TODO, incluindo a definição de parâmetros personalizados e tipos de resposta, além da lógica da função principal usando um repositório.

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

Pontos principais sobre o código

  • Por padrão, uma implementação de AppFunction é executada na linha de execução de interface do Android. Portanto, uma operação de longa duração precisa fazer o seguinte:
    • Declare a AppFunction como uma função de suspensão.
    • Mude para um agente de corrotina adequado quando a operação puder bloquear a linha de execução.
  • Quando isDescribedByKDoc é definido como true, a descrição da função ou a descrição serializável é codificada como parte do AppFunctionMetadata para ajudar o agente a entender como usar a AppFunction do app. A partir da versão 1.0.0-beta01, isDescribedByKDoc não tem valor padrão, então defina-o explicitamente.

Declarar o serviço AppFunction no manifesto

Registre a declaração de serviço gerada pelo KSP e a propriedade app_metadata no manifesto do módulo, por exemplo, em src/main/AndroidManifest.xml. O compilador do KSP gera a classe de serviço concreta (TaskAppFunctionService) que estende a classe de ponto de entrada abstrata, além do esquema XML correspondente no diretório 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: alternar a disponibilidade da AppFunction no ambiente de execução

Use a API AppFunctionManager para ativar ou desativar explicitamente as funções ao restringir as AppFunctions. A restrição pode ser útil quando determinados recursos do app não estão disponíveis para todos os usuários. Ao ativar ou desativar dinamicamente as AppFunctions, o sistema de inteligência sabe exatamente quais recursos estão disponíveis para o usuário em um determinado momento.

Para restringir com segurança as AppFunctions que exigem um estado de conta específico, siga um processo de duas etapas:

Etapa 1. Desativar a função por padrão

Para evitar que a função seja acessada antes que a flag de recurso seja verificada, defina o parâmetro isEnabled da anotação @AppFunctionDeclaration como false.

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

Etapa 2: Ativar dinamicamente a função no ambiente de execução

Para cada classe @AppFunctionServiceEntryPoint, o compilador gera uma classe correspondente que contém constantes de ID de função (usando um sufixo Ids). É possível usar essas constantes de ID geradas com o método setAppFunctionEnabled de AppFunctionManager para mudar o estado ativado de uma função no momento da execução.

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

Considerações sobre os tipos de funcionalidades a serem disponibilizadas

A segurança é sempre fundamental. Ao escolher quais recursos do seu app disponibilizar como AppFunctions, lembre-se de que os agentes de IA podem processar consultas do usuário no servidor para usar recursos avançados de LLM.

Para oferecer uma ótima experiência do usuário que também evite expor informações sensíveis, recomendamos seguir estas diretrizes:

  • Funcionalidade que se beneficia da linguagem natural: disponibilize tarefas que sejam mais fáceis de expressar em uma conversa do que pela navegação manual na interface.
  • Acesso restrito: crie AppFunctions que dão ao agente acesso apenas aos dados e às ações necessárias para atender à solicitação específica do usuário.
  • Informações não sensíveis: compartilhe apenas dados que não sejam altamente pessoais ou confidenciais ou dados que o usuário consente explicitamente em compartilhar no contexto da ação.
  • Ações seguras e não destrutivas: disponibilize apenas tarefas seguras e não destrutivas que os usuários normalmente fariam no app, como criar uma tarefa ou pesquisar notas. Para mais informações, consulte Ações permitidas e compartilhamento de dados pessoais.

Verificar a integração do AppFunction

Como as AppFunctions funcionam como serviços que os agentes de IA chamam, o teste tem dois lados: como a função se comporta e como os agentes se comportam ao chamá-la.

Testar a função

Comece com testes de unidade para a lógica da função, considerando como uma ligação agêntica por meio da biblioteca AppFunctions é diferente de uma chamada direta do Kotlin:

  • Valores padrão: os valores de parâmetro padrão do Kotlin não se aplicam. Um parâmetro opcional omitido chega como null, 0, false ou uma lista ou matriz vazia. Portanto, um parâmetro limit: Int = 10 chega como 0. Teste os parâmetros omitidos com esses valores e resolva os padrões no corpo da função. Para mais informações, consulte Parâmetros opcionais.
  • Linha de execução principal: as chamadas de plataforma começam na linha de execução principal, e chamar a função suspend diretamente de um teste de unidade não captura o bloqueio da linha de execução principal. Verifique se o banco de dados, a rede e a E/S de disco são executados em um agente de corrotina em segundo plano, como Dispatchers.IO.
  • Exceções: quando uma solicitação não pode ser bem-sucedida, gere uma subclasse AppFunctionException específica. Outras exceções não identificadas chegam ao agente como AppFunctionAppUnknownException com a mensagem de exceção bruta anexada, que não identifica o tipo de falha. Para mais informações, consulte Tratamento de erros.
  • Entradas do modelo: como as entradas vêm de um modelo, e não de controles de interface restritos, teste strings em branco, sinônimos como "reais" para "BRL" e valores fora do intervalo.

Em um dispositivo ou emulador, use adb shell cmd app_function para verificar se a plataforma indexou os metadados gerados e pode invocar o serviço.

Use adb shell cmd app_function list-app-functions --package $myPackageName para ver detalhes das AppFunctions que seu app oferece.

Também é possível executar uma AppFunction diretamente na linha de comando usando o 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\"}}'"

Teste com agentes

Teste com um agente para verificar se ele seleciona a função certa nas suas descrições e se a solicitação funciona como esperado. Como cada agente se comporta de maneira diferente, teste com os agentes que chamam suas AppFunctions:

  • Agente de exemplo: para testar a descoberta de ferramentas e os fluxos de trabalho completos localmente, instale e execute o agente de teste de código aberto do AppFunctions no seu dispositivo.
  • Gemini: para testar como o Gemini no Android chama suas AppFunctions, participe da prévia para desenvolvedores do Connected Apps Platform e siga as instruções em Criar e gerenciar apps conectados.
  • Agente no app: se o app incluir um agente próprio que chama AppFunctionManager para funções no mesmo pacote, teste as funções usando esse agente também.

Durante o desenvolvimento, você também pode verificar sua integração usando assistentes baseados em chat, como o Gemini no Android Studio com a habilidade de agente do AppFunctions, ou fornecer um comando como este:

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.

Migrar de versões anteriores da API

Na versão 1.0.0-alpha10, as AppFunctions introduziram uma arquitetura de tempo de compilação @AppFunctionServiceEntryPoint que consolida as dependências de biblioteca e substitui os provedores de configuração legados (AppFunctionConfiguration.Provider). A versão 1.0.0-alpha12 removeu os provedores legados. A versão 1.0.0-alpha13 renomeou a anotação @AppFunction como @AppFunctionDeclaration, e a versão 1.0.0-beta01 renomeou o atributo appfn:description no arquivo XML de metadados do app como appfn:instructions. A versão 1.0.0-rc01 removeu a opção legada do compilador appfunctions:aggregateAppFunctions. Se o build a transmitir como um argumento do KSP, remova-a.

Se o app usa uma versão anterior do AppFunctions (como 1.0.0-alpha09 ou 1.0.0-alpha10), é possível automatizar a migração usando a habilidade do agente do AppFunctions em um ambiente de desenvolvimento integrado de IA, como o Gemini no Android Studio. A habilidade contém regras de migração dedicadas que orientam um agente a consolidar suas dependências de build, criar o wrapper de serviço @AppFunctionServiceEntryPoint necessário, desacoplar parâmetros de contexto, atualizar suas declarações de manifesto, aplicar as renomeações da versão 1.0.0-beta01 e remover opções de compilador desativadas.