Android AppFunctions: what your app declares to an agent
AppFunctions turns annotated Kotlin functions into tools an on-device agent can call. What the schema carries, what changed in beta01, and what Play checks.
Need testers who stay active for all 14 days?
TesterBee matches you with 12 real Android testers in under 24 hours. Refund if Google rejects you over tester engagement.
On this page
- 01What AppFunctions actually is
- 02The four steps between your code and an agent call
- 03What the generated schema contains
- 04What changed since the alpha walkthroughs
- 05What Play Console does with a bundle that contains functions
- 06Discovery: the store listing now decides where your agent surface exists
- 07The four ways an AppFunction fails without an error
- 08How to test it before any model is involved
- 09Is it worth building now
- 10Frequently Asked Questions
- 11Sources
What AppFunctions actually is
AppFunctions is an Android platform API, available on devices running Android 16 or higher, with a Jetpack library on top. It lets your app publish a handful of its own functions as tools that a privileged on-device agent can find and call without your UI opening. Google describes them as "the mobile equivalent of tools within the Model Context Protocol": your app behaves like a local MCP server, the Android OS holds the registry, and each annotated Kotlin function becomes one tool in it.
That definition is now easy to find. The harder questions are the ones that decide whether you ship anything: what exactly gets compiled into your APK for an agent to read, and what Play Console does with a bundle that contains functions. Both have first-party answers, and several of them changed within the last month. If you read a guide written against the alpha library, the names in it no longer match the documentation.
It also helps to separate the two agent models Android now has. One taps through your screens on the user's behalf, which our guide to Android 17's agentic Gemini covers. AppFunctions is the other: no screen is drawn, and your code is called directly.
The four steps between your code and an agent call
The mechanism is a pipeline, not a plugin. An app declares functions, the compiler writes a schema, the OS indexes it, and an agent queries that index before it executes anything. Google's overview lays out the order, and the order matters because each step can fail on its own.
- Declare. You annotate a suspend function in a class that extends
AppFunctionService, using@AppFunctionDeclaration(isDescribedByKDoc = true). The KDoc becomes the text an agent reads. - Compile. The Kotlin Symbol Processing compiler generates a concrete service class plus an XML schema file inside your APK's
assets/directory. - Index. On install, the OS reads that schema and adds your functions to the device's registry. This is AppSearch indexing, and it is the step that fails quietly.
- Query. An agent holding the
EXECUTE_APP_FUNCTIONSpermission retrieves metadata for candidate functions, not your code. - Execute. The system binds your service, waking the app if needed, and delivers the call with parameters the agent chose from your descriptions.
Two details in that sequence are worth pausing on. The agent never parses your Kotlin, so your descriptions are the interface. And the system can wake a stopped app to run a function, which is why the entry point is a service with BIND_APP_FUNCTION_SERVICE rather than an activity.
What the generated schema contains
You do not hand-write the function schema. You write two things: the annotated function with its KDoc, and an application-level metadata file. The compiler turns the first into per-function metadata and the manifest properties point the system at both files.
- Function description: the KDoc body of the annotated function, encoded into
AppFunctionMetadatawhenisDescribedByKDocis true. - Parameter descriptions: the
@paramtags, one per argument, which is how an agent decides what to put in each slot. - Return description: the
@returntext, which tells the agent what it gets back and whether it needs to act again. - App-level instructions: a separate XML file at
res/xml/app_metadata.xml, referenced from the manifest, where you describe operational patterns and constraints that span functions, such as the order in which two functions should be called.
The app metadata file uses an appfn:instructions attribute for the text an agent reads. Before library version 1.0.0-beta01 that attribute was called appfn:description, so a snippet copied from a July tutorial will silently stop describing anything. There is also an optional appfn:displayDescription that points to a string resource users can see, which is the only part of this file a human ever reads.
Google's quality guidelines draw a sharp line here: function descriptions describe what a function does, and the app description covers what individual functions cannot, like call order. Putting "search for the contact first" inside a function description is explicitly listed as something not to do, because the agent plans across functions from your app-level text.
Parameter naming carries real risk rather than style risk. The guidelines call out names like full_context or conversation_history as dangerous, because an agent may interpret them as an invitation to pass its entire working context into your app. Name parameters for the data they hold, such as taskId or recipientEmail, and only declare parameters the function actually uses.
What changed since the alpha walkthroughs
This is the part most published explanations have wrong, and it is not their fault: the library moved four times in a few months. As of the pages dated 2026-11-05 and 2026-11-16, these are the current facts.
- Build floor. The integration guide requires
compileSdkat API level 37 or higher and Android Gradle Plugin 9.1.0 or higher. Earlier revisions of the same page said 36. - Library version. The documented dependency is
androidx.appfunctions:appfunctions:1.0.0-beta01with the matchingappfunctions-compilerartifact. The library is no longer alpha, but the platform package summary still labels App Functions "a beta/experimental preview feature". - Annotation rename.
@AppFunctionbecame@AppFunctionDeclarationin 1.0.0-alpha13. Code compiled against the old annotation will not produce the metadata the current docs describe. - Entry point. From 1.0.0-alpha10 the library uses a single
@AppFunctionServiceEntryPointclass that KSP expands into the concrete service; 1.0.0-alpha12 removed the legacy configuration providers entirely. - Required default. Since beta01,
isDescribedByKDochas no default value. Leave it out and the call does not compile, which is the compiler doing you a favour. - Older devices. The Jetpack library also ships
ExtensionsAppFunctionService, documented for API levels 34 through 36 where the AppFunctions extensions module is present on the device. The platform API needs Android 16, but the support story is not simply "Android 16 only".
If you already have an alpha integration, Google publishes migration rules for the entry-point change and the beta01 renames, and the sample app on GitHub is kept in step with the current API. Expect the names to keep moving; pin the version deliberately rather than accepting whatever resolves.
What Play Console does with a bundle that contains functions
This is where an AppFunctions article stops being an API discussion and becomes a release-process one, and it is the half the existing explainers leave out. The Play release page detects AppFunctions in an uploaded bundle and runs automated checks on them before the release can proceed.
- Detection is automatic. After upload, the release page shows an "App functions were detected in your app bundle" section with the connected app name, bundle version code, detected tool count, language count and country targeting. Those numbers are the system's reading of your schema, not yours.
- Checks can block publishing. Issues found by the AppFunctions checks appear on the release preparation page and as a "Fix issues to publish" state on the connected app version. A clean build is not a clean release.
- Version codes lock on publish. While a release stays in draft, you can remove and delete the bundle to reuse the same version code during iteration. Publishing the Play release locks that version code, and every later change needs an incremented one.
- No separate review for the connected app. Google states that an Android MCP connected app, unlike a server-hosted MCP integration, has no separate review or publish action on the connected app page. It is reviewed and published when the Play release containing the bundle reaches production.
- Testers are a second list. Only accounts on the connected app's tester list can see it before publication, and only
@gmail.comaccounts can be added. Your Play testing track has its own tester list; both need the same addresses.
The practical consequence is that AppFunctions work now arrives as a Play release event, with Play review timing attached. If a bundle fails an AppFunctions check, you are not debugging an agent, you are debugging a release. That also means the review question changes shape: you are not asking Google to approve an integration, you are asking it to approve a bundle that happens to contain one.
A small operational detail that costs people an afternoon: propagation is not instant. Google advises waiting about 20 minutes after submission, and up to 10 minutes after saving testers, before expecting a connected app to appear in the Gemini app. Testers also have to be running the exact bundle version code that was submitted, not a later sideload.
Discovery: the store listing now decides where your agent surface exists
For an app that ships functions instead of screens, the store listing stops being a marketing asset and becomes a distribution control. Google's setup guide is explicit that your Play app's store listing languages and country targeting determine where the connected app is available.
That has no equivalent in the pre-agent model, where your APK's availability was the listing's problem and nothing else depended on it. Now a listing targeted at three countries with one language produces an agent surface with the same footprint, even if your functions work everywhere.
- Each Play app can be linked to exactly one Android MCP connected app, and the link cannot be changed after you select it.
- The connected app name is what users type after
@in Gemini, so it has to be the name people would actually say. - The public card needs a description under 30 words, at least three capabilities, and at least three example prompts, two of which start with
@YourAppNameand one of which mentions the name without the prefix. - Category is fixed at creation, and its predefined capabilities are appended to yours and cannot be edited.
Nothing here is optional polish. A vague capability list and three prompts nobody would type are the discovery equivalent of a store listing with no screenshots: technically compliant, functionally invisible. Google's other discovery surface, where an assistant answers questions about Play itself, is worth reading alongside this one, and our breakdown of what Ask Play actually reads covers it.
The four ways an AppFunction fails without an error
Nobody is looking at your app when an agent calls it. There is no spinner, no crash dialog and no user to report a hang, which makes several documented behaviours much more expensive than they look on paper.
- It runs on the UI thread by default. Google states this plainly: an AppFunction implementation runs on the Android UI thread unless you make it a suspend function and switch to a background dispatcher. A database read or network call inside a non-suspend function blocks a screen nobody opened. The damage surfaces later as an ANR in Android vitals, with no obvious connection to the agent.
- Declared default parameter values are ignored. When an agent omits an optional parameter, the library passes
null, zero,falseor an empty collection, not the default you wrote in the signature. Resolve meaningful defaults in the function body, as the optional-parameters example does. - "Set to null" and "do not change" collapse into one value. If your update function takes a nullable field, an omitted parameter and an explicit clear look identical. The documented fix is a nullable wrapper class per updatable field, where a null wrapper means "leave it" and a wrapper holding null means "clear it", and never unwrapping with
?:. - Unexpected exceptions lose their identity. Throw the specific
AppFunctionExceptionsubclass that matches the cause, with a plain-language message. Anything else reaches the agent asAppFunctionAppUnknownException, which tells it nothing about whether to retry, correct an argument, or give up.
One more that is a security decision rather than a bug: if a function should open a specific screen after acting, return a PendingIntent created with an explicit intent and FLAG_IMMUTABLE. The agent launches it as-is and cannot redirect it. And for functions that only your own in-process agent should reach, the access level ACCESS_LEVEL_SELF keeps them out of IPC discovery entirely, rather than relying on a package check inside the function.
How to test it before any model is involved
The most useful property of AppFunctions for a QA process is that the whole pipeline is testable without an LLM. Google documents command-line tools that list and execute functions directly, which means deterministic tests for everything except the agent's choice of function.
To list what your installed app actually registered, run adb shell cmd app_function list-app-functions --package your.package.name. If your functions are missing from that output, the schema did not make it into the APK or the index did not complete, and no amount of prompt tweaking will help.
To execute one, pass the enclosing class and method name with a JSON parameter object through adb shell cmd app_function execute-app-function. The documented identifier format is the fully qualified class name, a hash, and the method name, which is also the string an agent sees when it selects your function. Google's testing agent sample goes further and runs an end-to-end conversational flow on the device, and the overview lists the cases worth covering: omitted defaults, main-thread calls, thrown AppFunctionException types, and model-generated inputs that are shaped differently from what you would write yourself.
Where a closed test fits, and where it does not
A closed test on your Play track proves the app installs, runs and survives real devices. It does not make your AppFunctions reachable to Gemini. The two gates use different tester lists: your Play track decides who can install the build, while the connected app's tester list decides who can see it inside Gemini. During the preview both lists need the same addresses, and only @gmail.com accounts can be added to the connected app.
That gives you a two-pass test plan. The first pass is device-level: install the bundle, confirm adb shell cmd app_function list-app-functions returns the tools you expect, and exercise each one with fixed JSON. The second is conversational, on a device signed into Gemini with an account on the connected app list, using the example prompts you wrote for the public card. If the second pass fails while the first passes, the problem is almost always a description rather than code. The Play side of that first pass is covered in our closed testing guide.
Is it worth building now
Building is possible today; reaching users through Gemini is not, without preview access. The overview directs developers to apply for the Connected Apps Platform developer preview, and until your connected app is published only the testers on your list can use it, on the submitted bundle version only.
That is a reason to scope narrowly, not to wait. Pick the single action users currently open your app to perform, expose it as one function with a description a stranger could follow, and prove it with the command line before you touch the Gemini side. If that one function cannot be described unambiguously in two sentences, the problem is your product surface, not the API.
Do not put AppFunctions on a roadmap as a shipped feature yet. The platform package is still marked beta and experimental, the library renames things between releases, and access to the Gemini integration is granted rather than assumed. What you can do without permission is the part that takes the longest: deciding what your app should be able to be asked.
Frequently Asked Questions
What Android version do AppFunctions require?
The platform API is available on devices running Android 16 or higher, and Google's integration guide asks for compileSdk 37 or higher with Android Gradle Plugin 9.1.0 or higher. The Jetpack library also documents an extensions service covering API levels 34 to 36 where the AppFunctions extensions module exists on the device, so older hardware is not automatically excluded.
Do I need Gemini access to test AppFunctions?
No. The adb shell cmd app_function commands list and execute functions on a device with no model in the loop, and the sample testing agent runs a full workflow without prompts. Gemini integration is a separate gate that requires applying for the Connected Apps Platform developer preview.
Can another app call my AppFunctions?
Only if it holds the privileged EXECUTE_APP_FUNCTIONS permission, which Android grants to authorized system assistants rather than to arbitrary apps. An app can always call functions declared in its own package without that permission. For functions that should stay internal, set the access level to ACCESS_LEVEL_SELF so they are never discoverable over IPC.
Does adding AppFunctions create a second Play review?
No separate review exists for the connected app. Google states that an Android MCP connected app is reviewed and published automatically when the Play production release containing the bundle is approved, unlike server-hosted MCP integrations. The bundle itself still goes through Play review, and automated AppFunctions checks on the release page can block it before that.
Why does the agent not see my function?
The usual cause is failed indexing, not a prompt problem. Confirm adb shell cmd app_function list-app-functions --package shows the function first. Google's troubleshooting note for indexing failure points at three things: @AppFunctionSerializable classes using class-level @param tags instead of inline KDoc, a missing assets/ schema file in the APK, and a missing or misapplied appfunctions-compiler KSP dependency.
Can I hide a function until the user signs in?
Yes. Declare it with isEnabled = false, then enable it at runtime with setAppFunctionEnabled using the generated function ID constant. Google notes that indexing may not be complete on first app startup, so the call should handle failure rather than assume it succeeded.
Should I expose many functions or one?
Few, and narrow ones. The quality guidelines warn that several functions with similar intents make the agent more likely to pick the wrong one, and that broad descriptions cause calls at inappropriate moments. One well-described function that matches how users phrase a request beats five that overlap.
Sources
- Overview of AppFunctions, Android Developers, last updated 2026-11-16.
- Add the AppFunctions API to your app, Android Developers, last updated 2026-11-05.
- AppFunctions quality guidelines, Android Developers, last updated 2026-10-28.
- Create and manage Connected Apps with AppFunctions, Android Developers, last updated 2026-11-16.
- android.app.appfunctions package summary, Android API reference.
- ExtensionsAppFunctionService, AndroidX API reference.

Senior full stack developer specializing in Laravel, React, and Firebase. Helped 1,300+ Android developers pass Google Play Closed Testing and publish apps. Expert in Play Console, production access, and Android app publishing.
Get 12 testers into your closed test in 24 hours
Matched Android testers who open your app every day of the 14-day window, so your production access review has real engagement to look at.
Start your closed testRelated articles
Android 17 Agentic Gemini — What It Means for App Developers in 2026
Android 17 introduces Agentic Gemini, AI that acts inside apps on a user's behalf. What it means for Android developers, and how to prepare your app for it.
How to Install an AAB on a Phone: bundletool, Not a Rename
An .aab will not install on a phone and renaming it to .apk does not work. Here is the bundletool sequence that puts a real app bundle on a test device.
Google Play Content Rating Refused or Overridden: Next Steps
A refused classification and a wrong rating need different fixes. Which remedy applies in Play Console, what an IARC appeal argues, and what it costs.