AppFunctions: Making Your Android App Discoverable by AI Agents

Ioannis Anifantakis — Fri, 29 May 2026 12:27:21 +0000

A practical first look at Google's new Jetpack API for exposing on-device app capabilities as tools an agent like Gemini can call

Introduction

Google just shipped the first public docs and the first usable alpha of AppFunctions — a Jetpack library paired with a new Android platform API that turns parts of your app into tools that AI agents can discover and execute. If you have ever used the Model Context Protocol (MCP) on the server side, AppFunctions is the Android-native equivalent: same idea, but the tool lives inside your app and runs locally on the device.

It helps to be precise about what is actually new here, because the capability is not — its universality is. Until now, getting an assistant to act inside an app on your behalf was overwhelmingly a first-party affair: you could ask Google Assistant to add an event to Google Calendar, Bixby to create one in Samsung's calendar, or Siri to do the same on Apple's — each assistant wired tightly to its own vendor's apps. Third-party apps were not completely shut out, but every door was a different shape. Android's App Actions let you expose a fixed catalog of built-in intents to Google Assistant (and frequently resolved them by launching your UI rather than running logic headlessly); Apple's App Intents / SiriKit did the analogous thing for Siri; Bixby had its Capsules. Each was assistant-specific, usually limited to a predefined vocabulary, and never portable — meaningful agentic control was either a vendor privilege or a stack of per-assistant integrations, with your app carrying code that targeted one agent and one agent only. AppFunctions sets out to replace all of that with a single, OS-level, agent-agnostic interface: your app declares what it can do once, and any caller the platform trusts can discover and execute it — no per-assistant code.

This article is an early hands-on walkthrough. I started from a minimal "hello world" AppFunction on an existing app I have been using as a teaching sample — a small jokes app with a Room database and an MVI presentation layer — and then grew it into a small but rounded demo: three functions that, between them, cover a plain-text result, structured data, typed parameters and errors, explicit threading, and where this kind of code belongs in a layered codebase. It is still a demo rather than a large body of work, and I will walk through it piece by piece so you can do the same in your own project today. You will find all of it on the sample app's branch, linked below.

Repository branch: 07-App-Functions
Google's docs: AppFunctions overview and Add the AppFunctions API to your app

A note up front: AppFunctions is experimental. As of May 2026, Gemini integration is in a private preview with trusted testers. The developer-side path, however, is open — you can build, register, and execute AppFunctions today using adb, which is exactly what we will do at the end of this article.

What MCP actually is

If you have not worked with the Model Context Protocol (MCP) before, a one-paragraph primer will make everything that follows easier.

MCP is an open standard, originally published by Anthropic in late 2024 and now adopted by a growing number of AI products, that defines a single way for AI agents to connect to external tools and data sources. The model is straightforward:

An MCP server is a small process that exposes a list of tools. Each tool has a name, a plain-language description, and a JSON Schema that describes its parameters and return value.
An MCP client — typically the AI agent — connects to the server, asks "what tools do you have?", reads the descriptions, and decides which tool to call based on the user's request.
The conversation between them is JSON-RPC, carried over stdio (for local servers) or HTTP (for remote ones).

Before MCP, each integration was bespoke — every AI product had its own way of plugging in tools. With MCP, a single server that exposes "search my email" can be consumed by any MCP-compatible agent without rewriting the integration on each side.

The friction is that traditional MCP servers run outside your application, often as separate processes or cloud services. They have no privileged access to your app's state. If you wanted an MCP-style tool that can read an unsent draft inside a note-taking app, you would either have to expose that draft through some API or run the MCP server inside the app's own process. Neither is convenient on mobile.

That is the gap AppFunctions fills.

What AppFunctions actually is

AppFunctions is best understood as MCP for Android, but on-device. Your app declares a class, annotates some of its methods with @AppFunction, and the Jetpack annotation processor generates the metadata and the wiring needed for the OS to index those methods. From that moment on, any caller with the EXECUTE_APP_FUNCTIONS permission — including system agents — can discover your function, read its description, and invoke it with parameters.

Three properties make this interesting:

It is local. No network round-trip, no server to maintain. The agent calls into your already-running app and reads its current state.
It is indexed by the OS. You do not register anything at runtime. The annotation processor emits a generated schema into your APK (assets/app_function_v2.xml), the OS reads it at install time, and it maintains a registry that agents can query.
The function's documentation becomes part of its contract. When you mark a function with @AppFunction(isDescribedByKDoc = true), your KDoc is encoded into the function's metadata and shown to the agent. Writing good KDoc stops being only a documentation concern — it becomes a runtime concern.

Minimum requirements: compileSdk = 37 and targetSdk = 36 or higher, devices running Android 16 or higher. (Google's own AppFunctions tooling lists compileSdk 37 / targetSdk 36 as the floor; the sample app in this article builds against compileSdk = 37 / targetSdk = 37.)

The sample app in 60 seconds

The base app is a small Compose application that fetches jokes from a remote source using Ktor and lets the user mark favorites. It uses Room for offline cache and local favorites storage, and a typical layered architecture — DAO, data source, repository, view model, screen. Nothing here is unusual; it is the same skeleton most production Android apps have.

The first feature I added is intentionally tiny: clear all favorite jokes. The exact same capability is reachable two ways:

The user can tap a menu item in the top bar.
An AI agent can call the clearFavorites AppFunction.

Both paths end up calling the same repository method. That is the principle I want to leave you with before we even look at code: an AppFunction is a thin shell over normal app logic, never a duplicate of it. We start with this one function, then add two more — getFavorites and setFavorite — once the basics are in place.

Step 1 — The dependencies

Open gradle/libs.versions.toml and add the AppFunctions artifacts. The current alpha is 1.0.0-alpha09:

[versions]
appfunctions = "1.0.0-alpha09"

[libraries]
androidx-appfunctions          = { module = "androidx.appfunctions:appfunctions",          version.ref = "appfunctions" }
androidx-appfunctions-service  = { module = "androidx.appfunctions:appfunctions-service",  version.ref = "appfunctions" }
androidx-appfunctions-compiler = { module = "androidx.appfunctions:appfunctions-compiler", version.ref = "appfunctions" }

Then in app/build.gradle.kts:

ksp {
    arg("appfunctions:aggregateAppFunctions", "true")
}

dependencies {
    // App Functions
    implementation(libs.androidx.appfunctions)
    implementation(libs.androidx.appfunctions.service)
    ksp(libs.androidx.appfunctions.compiler)
}

Two things to know:

The ksp(libs.androidx.appfunctions.compiler) dependency registers the AppFunctions compiler as a KSP processor — that is the line that actually wires annotation processing in. The ksp { arg("appfunctions:aggregateAppFunctions", "true") } block above it passes a configuration flag to that processor, telling it to aggregate every @AppFunction declared across your project into one merged schema. In a multi-module project you set this flag only in the application module; library modules that contain @AppFunction declarations just need the ksp(...) compiler dependency.
You also need at least compileSdk = 37 (and targetSdk = 36 or higher). If you are still on a lower level, this is a one-line bump in your build file. The sample app uses compileSdk = 37 and targetSdk = 37.

Step 2 — Manifest plumbing

The OS needs to know two things at install time: where to read your app's AppFunction metadata, and which service to bind when an agent wants to execute one of your functions. Both go inside <application> in AndroidManifest.xml:

<application
    ...>

    <property
        android:name="android.app.appfunctions.app_metadata"
        android:resource="@xml/app_metadata" />

    <service
        android:name="androidx.appfunctions.service.PlatformAppFunctionService"
        android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
        android:exported="true"
        tools:targetApi="36">
        <intent-filter>
            <action android:name="android.app.appfunctions.AppFunctionService" />
        </intent-filter>
    </service>

    <!-- your activities here -->
</application>

What each piece does:

The <property> element points the OS to app_metadata.xml, which carries the app-level description — what this app is about as a whole, so the AI agents can know what each app is about. Per-function descriptions are a separate concern: they come from the KDoc on each @AppFunction method.
The <service> declaration exposes PlatformAppFunctionService, which is the bridge the platform uses to invoke your functions. Luckily, you do not write this service yourself — it ships in the appfunctions-service library. You only need to declare it in the manifest with the right permission and intent filter so the system can find and bind to it.

The BIND_APP_FUNCTION_SERVICE permission ensures only the platform can bind to the service. You do not need to request EXECUTE_APP_FUNCTIONS — that is the caller's permission, not yours.

Step 3 — Describe the app itself in `app_metadata.xml`

The manifest's <property> element points at res/xml/app_metadata.xml. As the file name suggests, this file carries the app-level description that the OS exposes to agents, alongside the schemas of individual functions. Here is the one I added to the sample app:

<?xml version="1.0" encoding="utf-8"?>
<AppFunctionAppMetadata
    xmlns:appfn="http://schemas.android.com/apk/androidx.appfunctions"
    appfn:description="This app allows users to view and manage jokes, including marking them as favorites and clearing the favorites list." />

The structure is intentionally small for now — a single root element, a single description attribute. But the meaning is bigger than the syntax.

AppFunctions actually gives the agent two layers of documentation, and it is worth being explicit about how they relate:

Layer	Where you write it	What it tells the agent
App-level	`app_metadata.xml` (`appfn:description`)	What this app is about as a whole — its purpose, its domain, what kinds of things it can do
Function-level	KDoc above each `@AppFunction` method	What this specific function does, what its parameters mean, and what it returns

This is the same hierarchical model MCP uses on the server side — an MCP server has a description, and each tool within it has its own. The agent uses the high-level description first to decide is this even the right app to look inside?, then drills into the function descriptions to pick the right one within that app.

So treat appfn:description the same way I urged you to treat your KDoc: write it as runtime input to an LLM, not as marketing copy. Short, concrete, focused on the verbs the app supports ("view and manage jokes", "marking as favorites", "clearing the favorites list") rather than on positioning ("the best joke companion on Android"). Be honest about what the app does, because that is what the agent will trust when it has to choose between three different apps that all advertise "jokes".

A second attribute exists alongside it: appfn:displayDescription. The two are aimed at different audiences — appfn:description is the LLM-facing text the agent reasons over, while appfn:displayDescription is a human-readable, user-visible description. That difference shows up in how the library declares the two attributes (in appfunctions's own res/values/values.xml):

<attr format="string"           name="description"/>
<attr format="reference|string" name="displayDescription"/>

So appfn:displayDescription does not have to be a string resource — reference|string means it accepts either a @string/... reference or a literal string. Prefer the resource form (appfn:displayDescription="@string/app_function_user_description") anyway: this text is shown to users, so a string resource gives you localization for free. Note the asymmetry — description is plain string (write it inline, for the model), while displayDescription is reference|string (point it at a localizable resource, for people). The minimal sample above uses only appfn:description; add displayDescription once you have a user-facing surface that should show what your app exposes.

The appfn:description is app-wide — there is exactly one per app (that is why it is declared once, via the manifest <property>), and it never describes an individual function; each function's own description comes from its KDoc. But precisely because it sits above every function, it is the only place that can speak about how your functions relate to each other. With a single function there is nothing cross-cutting to say, so one sentence is plenty. Once an app exposes several functions, Google's own AppFunctions guidance suggests giving that one app-wide description more structure — think of it as server instructions for the agent rather than a tagline:

<AppFunctionAppMetadata
    xmlns:appfn="http://schemas.android.com/apk/androidx.appfunctions"
    appfn:description="This app lets users view and manage jokes and their favorites.
        Operational Patterns:
        - Call 'getFavorites' to obtain a valid joke id before calling 'setFavorite'.
        Constraints:
        - 'clearFavorites' is irreversible; confirm with the user before calling it."
    appfn:displayDescription="@string/app_function_user_description" />

Two conventions worth carrying over from that guidance: an Operational Patterns section that nudges the agent toward token-efficient, correct sequences (for example, "call getFavorites before setFavorite"), and a Constraints section that draws hard boundaries. Avoid repeating individual function descriptions or adding marketing copy here — the per-function KDoc already carries the function-level detail. The release notes for the androidx.appfunctions library are the place to track what else lands as the API stabilizes.

Step 4 — Extend the data layer (the boring, normal part)

Before we touch any AppFunctions code, we add the new business capability through the existing layers. The point I made earlier — that an AppFunction is a thin shell over normal logic — only works if that normal logic exists first.

DAO (JokesDao.kt):

@Query("UPDATE joke SET isFavorite = 0")
suspend fun clearAllFavorites()

Local data source (LocalJokesDataSource.kt and its implementation):

interface LocalJokesDataSource {
    // ...
    suspend fun clearAllFavorites()
}

class LocalJokesDataSourceImpl(/* ... */) : LocalJokesDataSource {
    override suspend fun clearAllFavorites() {
        database.clearAllFavorites()
    }
}

Repository (JokesRepository.kt and its implementation):

interface JokesRepository {
    // ...
    suspend fun clearAllFavorites(): Result<Unit>
}

class JokesRepositoryImpl(/* ... */) : JokesRepository {
    override suspend fun clearAllFavorites(): Result<Unit> {
        return safeCall {
            localDataSource.clearAllFavorites()
        }
    }
}

Nothing here knows or cares about AppFunctions. It is just normal Android architecture, and that is the point.

Step 5 — The AppFunction itself

Now we add the actual function the agent will call. This is a plain Kotlin class — no inheritance, no Android lifecycle:

package eu.anifantakis.networkapp.jokes.features.jokes.appfunctions

import androidx.appfunctions.AppFunctionContext
import androidx.appfunctions.service.AppFunction
import eu.anifantakis.networkapp.jokes.di.AppModule

/**
 * App Functions that can be exposed to AI agents via MCP.
 */
class JokesAppFunctions {

    /**
     * Unmarks every joke the user has previously marked as a favorite, leaving the favorites list empty.
     *
     * Only the favorite flag is affected. The underlying jokes remain in the database and are still
     * visible in the main list. This operation is safe to repeat: calling it on an already-empty favorites
     * list is a no-op. It is irreversible: cleared favorite markers cannot be restored.
     *
     * @return A short human-readable status message describing whether the operation succeeded.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun clearFavorites(context: AppFunctionContext): String {
        val repository = AppModule.jokesRepository
        val result = repository.clearAllFavorites()

        return if (result.isSuccess) {
            "All favorite jokes have been cleared successfully."
        } else {
            "Failed to clear favorite jokes: ${result.exceptionOrNull()?.message}"
        }
    }
}

Things worth pausing on:

isDescribedByKDoc = true — the KDoc above is very useful for the agent. It clearly explains what changes are involved (the favorite flag), what remains unchanged (the underlying jokes), whether the operation is safe to retry (yes, calling it again does no extra harm), and whether it can be undone (no). An agent reading this has enough to decide whether to call this function or ask the user for confirmation first. In comparison, a phrase like "Removes favorites" has the same aim but lacks the details; the agent would not understand what "remove" means or whether the operation can be reversed.
The same care applies to parameter names and types once your function takes any. A parameter called filter: String reads as concrete to a human navigating a UI, but as a black hole to an LLM reading a schema. Names like daysOlderThan: Int or category: JokeCategory carry their meaning forward; vague names quietly widen the space for the agent to guess wrong. Schemas your UI forgave will silently fail here.
The first parameter is always AppFunctionContext. The system passes this in; you do not. It is your hook for accessing system services and identifying the caller.
The return type here is a String. The agent will treat that text as the result it can show back to the user. For more sophisticated functions you would return a serializable data class annotated with @AppFunctionSerializable — the agent then receives structured data and can format it however it wants. For a "Hello World" example like this one, a sentence of plain text is enough.
This function is suspend. That is not optional — by default, AppFunction implementations run on the main thread, so any I/O must suspend. In our case the repository call already handles dispatching internally.

A note on dependencies: this class has a no-arg constructor and reaches into AppModule.jokesRepository directly. That works for a hello world. In a real codebase you would constructor-inject the repository through Hilt or Koin, and then provide a factory so the OS knows how to instantiate the class — which brings us to the next step.

Step 5b — Beyond a string: structured data, parameters, and errors

clearFavorites is a deliberately minimal "hello world": no parameters, a plain String return, no error surface beyond a status sentence. Most real AppFunctions need more, and the three things they most often need are exactly the three the platform supports out of the box: structured return values, typed parameters, and typed errors. Two more functions on the same class show all three.

Returning structured data with `@AppFunctionSerializable`

When you want the agent to receive data it can read, count, or quote — not just a sentence — return a serializable type instead of a String. You annotate a plain data class with @AppFunctionSerializable and return it (or a List of it) directly.

A design point first, because it is the one most likely to feel like duplication. We already have three joke models: the domain Joke, the network JokeDto, and the Room JokeEntity. Adding a fourth — an @AppFunctionSerializable class — looks redundant, but it is the same boundary-model pattern those others follow. We cannot annotate the domain Joke: @AppFunctionSerializable lives in androidx.appfunctions, and dragging an Android dependency into the domain layer would break its purity. So the AppFunctions boundary gets its own DTO, exactly as the network and persistence boundaries do — and, as a bonus, the schema the agent sees can be shaped independently of the domain (note that this DTO drops isFavorite, which is always true in a favorites list and would just be noise for the model). The conversion is a mapper, the analog of the existing toJoke()/toEntity() extensions:

// AppFunctionJoke.kt
// Developer rationale lives in a plain `//` comment on purpose (see the note below): this is the
// agent-facing boundary DTO, the counterpart of the network JokeDto and the Room JokeEntity. We
// can't annotate the domain Joke (androidx code would break domain purity), so the AppFunctions
// boundary gets its own model — and we drop isFavorite, which is noise for a favorites list.
/**
 * A single joke from this app, modelled as a question-and-answer pair: the question is the set-up
 * and the answer is the punchline. Returned by joke-reading functions such as the user's favorites
 * list, and identified by a stable numeric id that other functions accept to act on this joke.
 */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class AppFunctionJoke(
    /** Stable unique identifier of the joke. Pass this back to functions that act on a single joke. */
    val id: Int,
    /** The set-up line of the joke (its "question" part). */
    val question: String,
    /** The punchline of the joke (its "answer" part). */
    val answer: String,
)

// AppFunctionJokeMapper.kt — the boundary mapper, like toJoke()/toEntity()
fun Joke.toAppFunctionJoke(): AppFunctionJoke = AppFunctionJoke(
    id = id, question = question, answer = answer,
)

/**
 * Lists every joke the user has currently marked as a favorite, including its set-up and punchline.
 *
 * Returns structured data rather than a sentence, so a calling agent can read, count, or quote
 * individual jokes. Use the id of a returned joke when calling "setFavorite" to unmark a specific
 * one. An empty list means the user has no favorites.
 *
 * @return The user's favorite jokes; an empty list if there are none.
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun getFavorites(context: AppFunctionContext): List<AppFunctionJoke> = withContext(Dispatchers.IO) {
    val result = AppModule.jokesRepository.getFavorites()
    result.getOrDefault(emptyList()).map { joke -> joke.toAppFunctionJoke() }
}

Two non-obvious things about the KDoc on a serializable are worth saying out loud, because both bite silently — they compile fine and only misbehave at runtime, inside the agent.

First, where KSP looks:

KSP only extracts KDoc that is written inline, directly above each property, for @AppFunctionSerializable classes. If you document the properties with class-level @param or @property tags instead, KSP extracts nothing for those properties, and the function shows up at runtime as "metadata missing" / "AppFunction unavailable". Put the doc on the property, not in the class header.

This is the one place the two documentation styles in this article genuinely diverge, and it is worth pinning down because the instinct to reuse @param is so strong. The properties of a data class are constructor parameters, and for an @AppFunction method you absolutely do document parameters with @param tags — KSP reads them (the @param jokeId … on setFavorite below becomes that parameter's schema description). But for an @AppFunctionSerializable class it is the opposite: @param/@property tags in the class header are ignored, and only the inline KDoc is read. Same word "param," two different KSP code paths. I confirmed this by documenting AppFunctionJoke both ways and diffing the generated assets/app_function_v2.xml: with @param/@property tags, every property's <description> came out empty, and the raw tag text leaked into the type's description instead; with inline KDoc, each property got its proper description. Rule of thumb: @param for functions, inline KDoc for serializable properties.

Second, and easy to miss: the class-level KDoc summary becomes the agent-facing description of the type. With isDescribedByKDoc = true, whatever you write in the KDoc block above the class is emitted into the generated schema as that type's description — exactly as the function's KDoc summary becomes the function description. I learned this the hard way by reading the generated assets/app_function_v2.xml: an earlier version of this class carried a paragraph of developer rationale in its KDoc ("this is the boundary DTO, the counterpart of JokeDto…"), and all of it shipped into the schema as noise the agent would have to read. The rule that falls out of this: KDoc on anything annotated for AppFunctions is agent-facing copy. Keep developer-only rationale in plain // comments, which KSP ignores, and keep the KDoc itself a clean, concrete description.

The same trap explains a small but real detail in the function KDoc above: it says "setFavorite" in plain quotes rather than the KDoc link [setFavorite]. KDoc link brackets are not resolved on the way into the schema — they survive verbatim, so an agent would read raw [setFavorite] (and, worse, internal symbol paths like [AppFunctionJoke.id]). Quote names plainly; save the [...] links for KDoc that humans read in the IDE.

A note on the supported types, since you will reach for them as soon as you leave String behind. As of this alpha, an @AppFunction parameter or return value may be: a primitive (Int, Long, Float, Double, Boolean); a primitive array (IntArray, LongArray, FloatArray, DoubleArray, BooleanArray); a native type (String, PendingIntent, Uri, LocalTime, LocalDate, LocalDateTime, Instant — prefer LocalDateTime or Instant for date/time); an @AppFunctionSerializable object; or a List of any supported non-primitive type. Anything outside that set will not survive the schema round-trip.

Typed parameters and typed errors

The second function takes parameters and reports failure the way the platform expects — by throwing, not by returning an error string:

/**
 * Marks or unmarks a single joke as a favorite, identified by its id.
 *
 * Required workflow: call [getFavorites] first when you need a valid joke id to act on.
 * This sets the favorite flag to an absolute value rather than toggling it, so the call is safe to
 * repeat — requesting `isFavorite = true` on a joke that is already a favorite leaves it a favorite.
 *
 * @param jokeId The unique identifier of the joke to update.
 * @param isFavorite The desired favorite state: `true` to mark as a favorite, `false` to unmark it.
 * @return A short human-readable status message describing the new state of the joke.
 * @throws AppFunctionElementNotFoundException If no joke exists with the given [jokeId]; suggest the
 * user call getFavorites or browse the jokes list to obtain a valid id.
 */
@AppFunction(isDescribedByKDoc = true)
suspend fun setFavorite(
    context: AppFunctionContext,
    jokeId: Int,
    isFavorite: Boolean,
): String = withContext(Dispatchers.IO) {
    val joke = AppModule.jokesRepository.getJokeById(jokeId).getOrNull()
        ?: throw AppFunctionElementNotFoundException("No joke found with id $jokeId.")

    val result = AppModule.jokesRepository.setFavorite(jokeId, isFavorite)
    if (result.isSuccess) {
        if (isFavorite) "Joke ${joke.id} is now a favorite." else "Joke ${joke.id} is no longer a favorite."
    } else {
        "Failed to update joke ${joke.id}: ${result.exceptionOrNull()?.message}"
    }
}

Four things this second function demonstrates:

Typed parameters carry their meaning into the schema. jokeId: Int and isFavorite: Boolean read clearly to a model deciding what to pass — exactly the point made earlier about parameter names being part of the contract.
Errors are thrown, not returned. To report a real failure to the caller, throw a subclass of androidx.appfunctions.AppFunctionException — here, AppFunctionElementNotFoundException when the id does not exist. The agent receives a typed error rather than having to parse a sentence, and the @throws line tells it what recovery to suggest. (The library ships a family of these: invalid-argument, element-not-found, permission-required, and more.)
Required workflow: is a documented convention. When one function depends on another, Google's KDoc guidance is to spell it out with that exact phrase — Required workflow: call getFavorites first… — so the agent learns to call the read before the write.
Threading is explicit. AppFunction implementations run on the UI thread by default, so these two functions switch to withContext(Dispatchers.IO) themselves. (clearFavorites got away without it because its single Room call already hops off the main thread internally — but making the switch explicit is the safer default, and the rule to teach.)

With these, the class now exposes three functions — clearFavorites, getFavorites, and setFavorite — and the factory in the next step covers all of them at once, because they live on the same enclosing class.

Step 6 — Tell the OS how to build your AppFunction class

The OS, not your code, instantiates your AppFunctions class when an agent calls into it. So you need to declare a factory for it. The hook is AppFunctionConfiguration.Provider, implemented on your Application subclass:

package eu.anifantakis.networkapp

import android.app.Application
import androidx.appfunctions.service.AppFunctionConfiguration
import eu.anifantakis.networkapp.jokes.di.AppModule
import eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions

class MyApplication : Application(), AppFunctionConfiguration.Provider {

    override fun onCreate() {
        super.onCreate()
        AppModule.initialize(applicationContext)
    }

    override val appFunctionConfiguration: AppFunctionConfiguration
        get() = AppFunctionConfiguration.Builder()
            .addEnclosingClassFactory(JokesAppFunctions::class.java) { JokesAppFunctions() }
            .build()
}

addEnclosingClassFactory takes the class that contains your AppFunctions and a lambda that knows how to build an instance. For multiple AppFunction classes you chain multiple addEnclosingClassFactory calls before calling build(). With Hilt, you would inject the class through the field and return the injected instance from the lambda — Google's official docs show exactly that pattern.

Do not forget to register MyApplication in your manifest:

<application
    android:name=".MyApplication"
    ...>

Where does this code live?

By this point we have created several new types — JokesAppFunctions, AppFunctionJoke, a mapper — and the natural question for anyone with a layered codebase is: which layer do they belong to? The sample uses the familiar data / domain / presentation split per feature, so the temptation is to drop the AppFunctions code into one of those three. Resist it; the right answer comes straight from clean architecture once you classify what an AppFunction actually is.

An AppFunction is an inbound entry point — a driving (primary) adapter. Something outside your app (the OS, an agent) reaches in and drives your business logic. That is the exact same role your Compose UI plays; the only difference is the caller — a human taps a screen, an agent invokes a function. Both sit in the outer "interface adapters" ring and call inward to the repository. Contrast this with your data layer, which holds driven (secondary) adapters — outbound gateways the app calls (Room, Ktor). AppFunctions point the opposite direction.

That single classification settles the options:

Not data. The data layer is for outbound gateways, and AppFunctionJoke is not a persistence or network DTO — it is the boundary model of an inbound surface. Putting an entry point in data conflates "things that drive us" with "things we drive."
Not the root/app package. Root is for genuinely cross-feature, app-wide glue. clearFavorites, getFavorites, and setFavorite are about jokes, so they belong to the jokes feature.
Not core. A shared, feature-agnostic module must not depend on the jokes domain; feature logic there would invert the dependency rule.

The data / domain / presentation triple is the common shape, not a hard rule. Clean architecture really has the domain at the center surrounded by an outer ring of interface adapters that holds all delivery mechanisms — UI, widgets, tiles, deep links, and AppFunctions alike. Presentation and AppFunctions are siblings in that ring, not parent and child. So the cleanest home is a fourth package beside presentation, scoped to the feature:

features/jokes/
├─ data/          ← driven adapters: Room, Ktor, DTOs, mappers
├─ domain/        ← Joke, JokesRepository (no Android, no androidx.appfunctions)
├─ presentation/  ← Compose screens + ViewModels   (delivery to a human)
└─ appfunctions/  ← JokesAppFunctions, AppFunctionJoke, mapper  (delivery to an agent)

The mental model worth keeping: appfunctions/ is to an agent what presentation/ is to a human — same architectural rank, different audience. And AppFunctionJoke belongs beside its adapter for the same reason a UI model lives in presentation and a JokeDto lives in data: a boundary model lives with its boundary, and it depends only inward on the domain Joke.

One more distinction makes the split clean. There are two kinds of AppFunctions code, and they live in two different places:

Scope	What	Where it lives
Feature-specific	`JokesAppFunctions`, `AppFunctionJoke`, the mapper	inside the feature, `features/jokes/appfunctions/`
App-wide wiring	the `AppFunctionConfiguration.Provider` on `MyApplication`, `app_metadata.xml`, the manifest `<service>`	the app/root level

That is not an accident — the wiring is app-wide precisely because it aggregates every feature's AppFunctions into one schema (recall the aggregateAppFunctions flag from Step 1). Each feature contributes its own functions; the app module assembles them. This also future-proofs a multi-module split: :jokes:appfunctions would depend on :jokes:domain, while the aggregation flag and the Provider stay in :app.

Step 7 — Test it (adb, a real agent, or both)

This is where most readers will pause and ask the right question: I have built and registered an AppFunction, so how do I actually see an agent call it?

There are three answers, each useful for a different reason.

Route A — adb (the developer shortcut)

The fastest way to verify your wiring is through adb shell cmd app_function. It is worth being precise about what this command does, because it is not a fake or a mock — it is a thin shell front-end to the same OS-level AppFunctionService that any agent would talk to through AppFunctionManager from Kotlin code. You are not simulating an agent here; you are bypassing it and speaking to the OS directly. That makes adb the ideal tool for end-to-end verification, because it removes every AI-product variable and leaves only your own wiring under test.

Build and install the app on a device or emulator running Android 16 or higher, then list the registered AppFunctions:

# Type this for the first 10 lines of app functions for our package
adb shell cmd app_function list-app-functions | grep -A 10 "eu.anifantakis.networkapp.jokes"

If everything compiled and the manifest is set up correctly, you should see something like this:

"eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#clearFavorites"
        ],
        "packageNameHash": [
          -1179891122
        ],
        "scope": [
          "global"
        ],
        "mobileApplicationQualifiedId": [
          "android$apps-db/apps#eu.anifantakis.networkapp"
        ],
--
            "android$apps-db/app_functions#eu.anifantakis.networkapp/eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#clearFavorites"
          ],
          "functionId": [
            "eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#clearFavorites"
          ],
          "packageName": [
            "eu.anifantakis.networkapp"
          ]
        }
      }
    }
  ],
  "com.google.android.permissioncontroller": [
    {

A few things worth pointing out in this output:

functionId is the canonical identifier of our AppFunction: eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#clearFavorites. Note the # separator between the fully-qualified class name and the method name. This is exactly the string you pass to --function in the next command, so copy it from this output rather than typing it from memory.
packageName is eu.anifantakis.networkapp — the app's applicationId. This is what you pass to --package, and it is not the same as the package containing the function class. (The function class lives at eu.anifantakis.networkapp.jokes.features.jokes.appfunctions, but the application identifier is just eu.anifantakis.networkapp.)
mobileApplicationQualifiedId points at android$apps-db/apps#eu.anifantakis.networkapp. That apps-db prefix is the OS-level database — AppSearch, internally — that the system uses to index installed apps. Our function has its own entry under app_functions within that same database.
scope: global confirms the function is visible without further gating. If we had used @AppFunction(isEnabled = false, ...) and not yet enabled it at runtime, this entry would not show up here at all.

The point worth taking away is that this output is not a diagnostic surface dressed up to look pretty for developers. It is a literal view into the OS's AppFunctions registry — the same registry an agent reads when it asks "what functions does this app expose?". Everything an agent will see about your function is in here.

Try it end-to-end

To actually see the function in action, run through this short demo:

Run the app and mark some jokes as favorites by tapping the heart icon next to the ones you want to keep.
Close and reopen the app. You should notice that while the rest of the jokes are refreshed from the network, the favorites you marked are preserved.
Run the script below and watch the favorite marks instantly clear from your screen. Note, you do not need to have your app running for this to take effect.

adb shell cmd app_function execute-app-function \
  --package eu.anifantakis.networkapp \
  --function eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#clearFavorites \
  --parameters '{}'

If your favorites table had rows marked isFavorite = 1 before, they are all reset to 0 now, and adb prints the string the function returned.

The two functions from Step 5b are reachable the same way. getFavorites takes no parameters and returns the structured list:

adb shell cmd app_function execute-app-function \
  --package eu.anifantakis.networkapp \
  --function eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#getFavorites \
  --parameters '{}'

setFavorite takes the typed parameters as JSON — note how the keys match the Kotlin parameter names exactly. There is one sharp edge here that is pure shell, not AppFunctions: a JSON payload with quotes and spaces has to survive two shells — your local shell and the shell adb spawns on the device. The naive form fails:

# DON'T: the device-side shell strips the quotes and splits on the space, so `cmd`
# receives only `{jokeId:` →  JSONException: End of input at character 8 of {jokeId:
adb shell cmd app_function execute-app-function \
  --parameters '{"jokeId": 179, "isFavorite": true}'

The fix is to hand adb shell a single double-quoted command and single-quote the JSON inside it (escaping the inner double quotes). This is why the no-argument calls above worked with a bare '{}' — there were no quotes or spaces to mangle:

adb shell "cmd app_function execute-app-function \
  --package eu.anifantakis.networkapp \
  --function eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#setFavorite \
  --parameters '{\"jokeId\":179,\"isFavorite\":true}'"

That returns "Joke 179 is now a favorite.", and a follow-up getFavorites then includes joke 179 in its structured list. Pass a jokeId that does not exist and you can watch the typed-error path fire instead — Error executing app function: android.app.appfunctions.AppFunctionException: No joke found with id 999999. (code 1500) — the caller gets a structured error, not a status sentence.

A few more adb subcommands worth keeping in your back pocket:

# Confirm the device even supports AppFunctions (prints a help page if so).
# If you instead see "cmd: Can't find service: app_function", the device doesn't support the feature.
adb shell cmd app_function help

# Append --brief-yaml to any execute call for terser, more readable output.
adb shell cmd app_function execute-app-function --brief-yaml \
  --package eu.anifantakis.networkapp \
  --function eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#getFavorites \
  --parameters '{}'

# Toggle a single function on or off at runtime (ties into the @AppFunction(isEnabled = false) flag).
adb shell cmd app_function set-enabled \
  --package eu.anifantakis.networkapp \
  --function eu.anifantakis.networkapp.jokes.features.jokes.appfunctions.JokesAppFunctions#setFavorite \
  --state disable

Important observation (also just mentioned above): this works whether your app is in the foreground, in the background, or completely closed. The OS reaches your function through the AppFunctionService independently of your activity lifecycle. That is the practical cash-value of "indexed by the OS" from the start of this article — agents do not need your UI to be alive in order to reach your code.

Other paths (I have not tried yet)

adb is the one route I have actually used to verify this hello world. There are two other ways an external caller can reach an AppFunction, and both are worth knowing exist, even if I cannot speak to them yet from first-hand experience.

Route B — A custom host app that uses AppFunctionManager. This is the closest you can get to the production shape: a second app on the device whose job is to discover and invoke functions exposed by another app over IPC, with no adb in the middle. It is also the pattern Google themselves demonstrated at I/O when AppFunctions was first shown publicly — because there was not yet a real agent to demo, they built a small host app for the purpose. The catch is that EXECUTE_APP_FUNCTIONS is currently a privileged permission on Android 16 release builds, so a host app cannot be installed and granted that permission via a normal adb install; you need a userdebug build, a rooted device, or a /system/priv-app install. I have not built this end-to-end myself yet, so I am not going to pretend to walk through it here — but a follow-up article is on schedule that will showcase a host app calling into the jokes AppFunction we wrote in this one.

Route C — Gemini in Android Studio as an LLM-in-the-loop check. Google's docs suggest using Gemini in Android Studio with a prompt that asks it to "Execute adb shell cmd app_function to learn how the tool works, then act as a chat agent...". In effect this has an LLM drive adb for you, which tests whether your function descriptions are clear enough for a model to pick the right one. I have not personally tried this either, so I cannot say more than what the docs document.

What about Gemini on a real phone?

As of this writing, full Gemini integration with AppFunctions is in a private preview with trusted testers. You cannot just install your app, open Gemini on your phone, and have it call into your functions yet.

A note on destructive functions

The clearFavorites function in this article happens to be safe to repeat by accident. UPDATE SET isFavorite = 0 produces the same result whether called once or ten times. That accident is worth pausing on, because the moment you write a destructive AppFunction where repeating the call would cause harm, you have reopened every problem REST solved for deterministic callers, with one new wrinkle: the caller is now an LLM that can hallucinate, retry, or pick your function for the wrong reasons.

A deleteJoke(id) called twice is a bug at best. A sendPayment(amount) called twice is a real problem. Before you annotate a write with @AppFunction, treat the same questions REST forces you to answer: what happens under retry, what happens under partial failure, and who is allowed to call this in the first place?

A few patterns worth carrying over from the REST era.

1. Make writes safe to repeat by design where you can

Prefer absolute set operations to deltas.
Accept a client-supplied request ID so a duplicate call can be detected and ignored.
Return success identically for a no-op and a real change.

In more detail:

Prefer absolute set operations over deltas. An UPDATE that writes a final value, like SET status = 'active', gives the same result every time it runs. A delta like SET value = value + 1 accumulates with every retry, so two calls leave the counter at +2 even though the caller only meant +1. For AppFunctions, markAsFavorite(jokeId) is absolute and safe to repeat; incrementFavoriteCount(jokeId) is a delta and is not.

Accept a client-supplied request ID. Let the caller send a unique key with every call. Your function keeps a small record of recently-seen keys; if the same key arrives twice, you return the cached result of the first call instead of running the operation again. This is exactly how payment APIs like Stripe survive network retries without double-charging — they require an Idempotency-Key header on every request, and you can borrow the same pattern for any sensitive write.

Return success the same way, whether the operation did real work or was a no-op. Our clearFavorites already does this. Both branches return "All favorite jokes have been cleared successfully," regardless of whether ten jokes were unfavorited or zero. Different messages ("Cleared 10" vs "Nothing to clear") would leak state to the caller and tempt the LLM to pick a different next step depending on the answer.

2. Expose reads liberally, expose writes conservatively

There is no rule that says every method on your repository deserves an @AppFunction. Pick the smallest surface that is genuinely useful to an agent.

3. Assume nothing is guarding the door

EXECUTE_APP_FUNCTIONS is privileged today, but the enforcement story between agent and function is still being defined. The follow-up host-app article will dig into that layer in detail. Until then, your function is the last layer of defence, not the first.

There is a strategic point underneath all of this that is worth saying out loud. We spent a decade optimising deep links, App Indexing, and search to get users into the app. AppFunctions optimises for the opposite — the app never opening, the screen never lighting up, no UI between the agent and your business logic. That changes what "least privilege" looks like in practice: the UI is no longer there to ask "are you sure?" on your behalf.

Closing thought

The line of code I keep coming back to is this one:

@AppFunction(isDescribedByKDoc = true)

That single flag turns documentation into runtime behavior. The KDoc you write is the contract an LLM reads to decide whether to call your function and what to pass into it. Vague KDoc means a confused agent. Precise KDoc, with the same care you would give to a public API description, means the agent picks your function for the right reasons.

That, more than any specific annotation or manifest entry, is the shift AppFunctions is asking us to make.

Useful links

Sample repository (branch): MitropolitikoNetworkApp / 07-App-Functions
AppFunctions overview — Android Developers
Add the AppFunctions API to your app — Android Developers
androidx.appfunctions Jetpack release notes

DEV Community: Ioannis Anifantakis