AppFunction

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

Marks a function under AppFunctionServiceEntryPoint 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.

Thread Management

IMPORTANT: By default functions annotated with @AppFunction are executed on the main thread. declare the function as a suspend function and switch threads if the implementation performs blocking operations.

Cancellation Handling

If the system or the calling application cancels the execution of an AppFunction, the coroutine running the function will be canceled. Therefore, the implementation is recommended to handle coroutine cancellation gradefully.

To make a CPU-intensive loop cooperative with cancellation, periodically call kotlinx.coroutines.ensureActive within the loop. This is a lightweight check that throws a kotlinx.coroutines.CancellationException if the execution has been canceled.

For example:

@AppFunction
suspend fun processLargeData(
    context: AppFunctionContext,
    data: List<String>
): List<Result> {
    // Switch to a background dispatcher for CPU-intensive work
    return withContext(backgroundDispatcher) {
        val results = mutableListOf<Result>()
        for (item in data) {
            // Periodically check for cancellation
            ensureActive()
            results.add(heavyProcessing(item))
        }
        results
    }
}

Error Handling

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.

Supported Types

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

Deprecate AppFunction

If an existing AppFunction needs to be deprecated (e.g., a replacement is available, but the old version must remain for backward compatibility), mark the function with the kotlin.Deprecated annotation.

This deprecation status will be exposed in the androidx.appfunctions.metadata.AppFunctionMetadata.deprecation field, allowing clients to identify and migrate away from the deprecated function.

Example:

@AppFunction
@Deprecated(
  message = "Use newSearchFunction(query) instead. " +
    "This function will be removed in a future version.",
)
fun oldSearchFunction(...) {
// ...
}

Summary

public AppFunction(boolean isEnabled, boolean isDescribedByKDoc)

public final boolean isDescribedByKDoc()

/**
* 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 { .. }

public final boolean isEnabled()