Z tego przewodnika dowiesz się, jak zintegrować interfejs AppFunctions API z aplikacją na Androida, zaimplementować logikę funkcji i sprawdzić, czy integracja działa prawidłowo.
Zgodność wersji
Ta implementacja wymaga, aby projekt compileSdk był ustawiony na poziom interfejsu API 37 lub wyższy. Projekt musi używać wtyczki Androida do obsługi Gradle w wersji 9.1.0 lub nowszej.
Aplikacja nie musi sprawdzać, czy funkcje AppFunctions są obsługiwane. Jest to automatycznie obsługiwane w bibliotece AppFunctions Jetpack.
AppFunctionManager zwraca instancję, jeśli funkcja jest obsługiwana, a jeśli nie, zwraca wartość null.
Zależności
Dodaj wymagane zależności biblioteki do pliku build.gradle.kts (lub build.gradle) modułu i skonfiguruj wtyczkę KSP w module aplikacji najwyższego poziomu w ten sposób:
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")
}
Implementowanie logiki AppFunctions
Aby zaimplementować funkcję AppFunction w aplikacji na Androida, utwórz klasę, która implementuje określoną logikę funkcji AppFunctions. Obejmuje to tworzenie klas danych możliwych do serializacji dla parametrów i odpowiedzi, a następnie dostarczanie podstawowej logiki w metodzie funkcji.
Poniższy kod pokazuje przykładową implementację tworzenia zadania w aplikacji TODO, w tym definiowanie parametrów niestandardowych i typów odpowiedzi oraz główną logikę funkcji z użyciem repozytorium.
@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) }
Najważniejsze informacje o kodzie
- Domyślnie implementacja AppFunction działa w wątku UI Androida.
Dlatego długotrwała operacja powinna:
- Zadeklaruj AppFunction jako funkcję zawieszenia.
- Przełącz się na odpowiedni dyspozytor współprogramu, gdy operacja może zablokować wątek.
- Gdy parametr
isDescribedByKDocjest ustawiony natrue, opis funkcji lub opis możliwy do serializacji jest kodowany jako częśćAppFunctionMetadata, aby pomóc agentowi zrozumieć, jak korzystać z funkcji AppFunction aplikacji. Począwszy od wersji 1.0.0-beta01,isDescribedByKDocnie ma wartości domyślnej, więc ustaw ją bezpośrednio.
Zadeklaruj usługę AppFunction w pliku manifestu
Zarejestruj deklarację usługi wygenerowaną przez KSP i właściwość app_metadata w pliku manifestu modułu, np. w src/main/AndroidManifest.xml. Kompilator KSP generuje konkretną klasę usługi (TaskAppFunctionService) rozszerzającą abstrakcyjną klasę punktu wejścia wraz z odpowiednim schematem XML w katalogu 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" />
Opcjonalnie: przełączanie dostępności funkcji AppFunction w czasie działania
Użyj interfejsu AppFunctionManager API, aby wyraźnie włączyć lub wyłączyć funkcje podczas ograniczania dostępu do funkcji aplikacji. Blokowanie może być przydatne, gdy niektóre funkcje aplikacji nie są dostępne dla wszystkich użytkowników. Dzięki dynamicznemu włączaniu i wyłączaniu funkcji AppFunctions system inteligentny dokładnie wie, które funkcje są dostępne dla użytkownika w danym momencie.
Aby bezpiecznie ograniczyć dostęp do funkcji AppFunctions, które wymagają określonego stanu konta, wykonaj te 2 czynności:
Krok 1. Domyślnie wyłącz funkcję
Aby uniemożliwić dostęp do funkcji, zanim flaga funkcji zostanie zweryfikowana, ustaw parametr isEnabled adnotacji @AppFunctionDeclaration na false.
@AppFunctionDeclaration(isEnabled = false, isDescribedByKDoc = true) suspend fun createTask( createTaskParams: CreateTaskParams, ): Task = TODO()
Krok 2. Dynamiczne włączanie funkcji w czasie działania
Dla każdej klasy @AppFunctionServiceEntryPoint kompilator generuje odpowiednią klasę zawierającą stałe identyfikatorów funkcji (z przyrostkiem Ids).
Możesz używać tych wygenerowanych stałych identyfikatorów wraz z metodą setAppFunctionEnabled z AppFunctionManager, aby zmieniać stan włączenia funkcji w czasie działania.
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 } }
Uwagi dotyczące typów funkcji, które można udostępnić
Bezpieczeństwo jest zawsze najważniejsze. Gdy wybierasz, które funkcje aplikacji chcesz udostępnić jako AppFunctions, pamiętaj, że agenty AI mogą przetwarzać zapytania użytkowników na serwerze, aby korzystać z zaawansowanych funkcji LLM.
Aby zapewnić użytkownikom wygodę i uniknąć ujawniania informacji poufnych, zalecamy przestrzeganie tych wytycznych:
- Funkcje, które korzystają z języka naturalnego: udostępniaj zadania, które użytkownikowi łatwiej jest wyrazić w rozmowie niż za pomocą ręcznej nawigacji w interfejsie.
- Ogranicz dostęp: utwórz funkcje AppFunctions, które dają agentowi dostęp tylko do danych i działań wymaganych do spełnienia konkretnej prośby użytkownika.
- Informacje, które nie są poufne: udostępniaj tylko te dane, które nie są ściśle osobiste ani poufne, lub dane, na których udostępnienie użytkownik wyraźnie wyraził zgodę w kontekście działania.
- Bezpieczne, nieniszczące działania: udostępniaj tylko bezpieczne, nieniszczące zadania, które użytkownicy zwykle wykonują w Twojej aplikacji, takie jak tworzenie zadania lub wyszukiwanie notatek. Więcej informacji znajdziesz w artykule Dozwolone działania i udostępnianie danych.
Weryfikowanie integracji AppFunction
Funkcje aplikacji działają jako usługi wywoływane przez agentów AI, dlatego testowanie ma 2 aspekty: zachowanie funkcji i zachowanie agentów podczas jej wywoływania.
Testowanie funkcji
Zacznij od testów jednostkowych logiki funkcji, biorąc pod uwagę, że połączenia (telefoniczne) wykonywane przez agenta AI przez bibliotekę AppFunctions różnią się od bezpośredniego wywołania w Kotlinie:
- Wartości domyślne: domyślne wartości parametrów w języku Kotlin nie mają zastosowania. Pominięty parametr opcjonalny jest dostarczany jako
null,0,falselub pusta lista bądź tablica, więc parametrlimit: Int = 10jest dostarczany jako0. Przetestuj pominięte parametry z tymi wartościami i rozwiąż wartości domyślne w treści funkcji. Więcej informacji znajdziesz w sekcji Parametry opcjonalne. - Wątek główny: wywołania platformy zaczynają się w wątku głównym, a wywołanie funkcji
suspendbezpośrednio z testu jednostkowego nie wykrywa blokowania wątku głównego. Upewnij się, że operacje we/wy bazy danych, sieci i dysku są wykonywane w dyspozytorze współprogramu działającym w tle, takim jakDispatchers.IO. - Wyjątki: gdy żądanie nie może zostać zrealizowane, zgłoś konkretną podklasę
AppFunctionException. Inne nieprzechwycone wyjątki docierają do agenta jakoAppFunctionAppUnknownExceptionz dołączonym nieprzetworzonym komunikatem o wyjątku, który nie identyfikuje rodzaju błędu. Więcej informacji znajdziesz w artykule Obsługa błędów. - Dane wejściowe modelu: ponieważ dane wejściowe pochodzą z modelu, a nie z ograniczonych elementów sterujących interfejsu, przetestuj puste ciągi znaków, synonimy takie jak „dolary” zamiast „USD” i wartości spoza zakresu.
Na urządzeniu lub emulatorze użyj adb shell cmd app_function, aby sprawdzić, czy platforma zindeksowała wygenerowane metadane i może wywołać Twoją usługę.
Użyj adb shell cmd app_function list-app-functions --package $myPackageName, aby zobaczyć szczegóły funkcji AppFunctions, które udostępnia Twoja aplikacja.
Możesz też wykonać funkcję AppFunction bezpośrednio z wiersza poleceń, używając jej jawnego identyfikatora ("$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\"}}'"
Testowanie z agentami
Przetestuj agenta, aby sprawdzić, czy wybiera właściwą funkcję na podstawie opisów i czy żądanie działa zgodnie z oczekiwaniami. Każdy agent zachowuje się inaczej, dlatego przetestuj te, które wywołują funkcje AppFunctions:
- Przykładowy agent: aby przetestować wykrywanie narzędzi i kompleksowe przepływy pracy lokalnie, zainstaluj i uruchom na urządzeniu agenta testowego AppFunctions o otwartym kodzie źródłowym.
- Gemini Aby przetestować, jak Gemini na Androidzie wywołuje funkcje AppFunctions, dołącz do wersji przedpremierowej dla programistów platformy Connected Apps Platform i wykonaj czynności opisane w artykule Tworzenie połączonych aplikacji i zarządzanie nimi.
- Agent w aplikacji: jeśli aplikacja zawiera własnego agenta, który wywołuje
AppFunctionManagerw przypadku funkcji w tym samym pakiecie, przetestuj funkcje również za pomocą tego agenta.
Podczas tworzenia aplikacji możesz też zweryfikować integrację, korzystając z asystentów opartych na czacie, takich jak Gemini w Android Studio, z umiejętnością agenta AppFunctions, lub podać prompta, np.:
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.
Migracja z niższych wersji interfejsu API
W wersji 1.0.0-alpha10 AppFunctions wprowadziło architekturę @AppFunctionServiceEntryPoint czasu kompilacji, która konsoliduje zależności bibliotek i zastępuje starszych dostawców konfiguracji (AppFunctionConfiguration.Provider). W wersji 1.0.0-alpha12 usunięto starszych dostawców. W wersji 1.0.0-alpha13 zmieniono nazwę adnotacji @AppFunction na @AppFunctionDeclaration, a w wersji 1.0.0-beta01 zmieniono nazwę atrybutu appfn:description w pliku XML metadanych aplikacji na appfn:instructions. W wersji 1.0.0-rc01 usunięto starszą opcję kompilatora appfunctions:aggregateAppFunctions. Jeśli kompilacja przekazuje ją jako argument KSP, usuń ją.
Jeśli Twoja aplikacja używa starszej wersji AppFunctions (np. 1.0.0-alpha09 lub 1.0.0-alpha10), możesz zautomatyzować migrację, korzystając z umiejętności agenta AppFunctions w środowisku IDE opartym na AI, takim jak Gemini w Android Studio. Umiejętność zawiera dedykowane reguły migracji, które pomagają agentowi skonsolidować zależności kompilacji, utworzyć wymagany kod otaczający usługi @AppFunctionServiceEntryPoint, rozdzielić parametry kontekstu, zaktualizować deklaracje w pliku manifestu, zastosować zmiany nazw w wersji 1.0.0-beta01 i usunąć wycofane opcje kompilatora.
Umiejętności związane z Androidem
Wyświetl na GitHubieImplementowanie AppFunctions
android skills add appfunctionsUse the AppFunctions skill to upgrade my app's AppFunctions implementation to 1.0.0-rc01.