AppFunction

@Retention(value = AnnotationRetention.BINARY)
@Target(allowedTargets = [AnnotationTarget.FUNCTION])
annotation AppFunction

Marks a function within a class as callable by other applications.

The @AppFunction annotation signals that the annotated function can be invoked by external applications with proper permission (e.g., an agent). For instance, a note-taking app could expose a function allowing an agent to create notes based on user commands.

The enclosing class of the function would be instantiated whenever an AppFunction within the class is called. If the enclosing class requires constructor parameters or custom instantiation, add a custom factory in AppFunctionConfiguration.Builder.addEnclosingClassFactory. This allows you to inject dependencies or handle more complex object creation scenarios.

When a function is annotated with @AppFunction, the compiler will automatically:

• Generate an XML file within the APK. This file describes the signatures of all @AppFunction-annotated functions within the application.

• Provide the necessary infrastructure to expose these functions via android.app.appfunctions.AppFunctionService.

Applications with the appropriate permissions can then use android.app.appfunctions.AppFunctionManager to invoke these exposed functions.

The compiler also generates an ID class associated with the class containing @AppFunction annotations. This ID class provides constants for retrieving the unique identifier of each annotated function. Consider this example:

package com.example.mynotes

class NoteFunctions: CreateNote, UpdateNote {
  @AppFunction
  override suspend fun createNote(...): Note { ... }

  @AppFunction
  override suspend fun updateNote(...): Note? { ... }
}

The compiler will generate a NoteFunctionsIds class within the same com.example.mynotes package. This generated class will contain constants like CREATE_NOTE_ID and UPDATE_NOTE_ID, which correspond to the createNote and updateNote functions, respectively.

IMPORTANT: By default, functions annotated with @AppFunction are executed on the main thread. For operations that may take a significant amount of time, it is crucial to use a coroutine dispatcher that runs on a background thread.

In exceptional cases, implementations should throw an appropriate androidx.appfunctions.AppFunctionException. This allows the agent to better understand the cause of the failure. For example, if an input argument is invalid, throw an androidx.appfunctions.AppFunctionInvalidArgumentException with a detailed message explaining why it is invalid.

For a detailed list of supported types and the rules governing their serialization, see androidx.appfunctions.AppFunctionSerializable.

Summary

AppFunction(isEnabled: Boolean = true, isDescribedByKdoc: Boolean = false)

val isDescribedByKdoc: Boolean

/**
* Creates a new note with a given title and content.
*
* @param title The title of the note.
* @param content The main body or text of the note.
* @return The created note.
* @throws IllegalArgumentException if the `title` or `content` is empty or too long.
*/
@AppFunction(isDescribedByKdoc = true)
fun CreateNote(title: String, content: String): Note { .. }

val isEnabled: Boolean