# AppFunctionDeclaration

Artifact: [androidx.appfunctions:appfunctions](https://developer.android.com/jetpack/androidx/releases/appfunctions) [View Source](https://cs.android.com/search?q=file:androidx/appfunctions/AppFunctionDeclaration.kt+class:androidx.appfunctions.AppFunctionDeclaration) Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

*** ** * ** ***


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

<br />

*** ** * ** ***

Marks a function under `https://developer.android.com/reference/androidx/appfunctions/AppFunctionServiceEntryPoint` as callable by other applications.

The `@AppFunctionDeclaration` 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 @AppFunctionDeclaration 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 `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/index.html` within the loop. This is a lightweight check that throws a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html` if the execution has been canceled.

For example:

```
/** Processes large data. */
@AppFunctionDeclaration(isDescribedByKDoc = true)
suspend fun processLargeData(
    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 `https://developer.android.com/reference/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 `https://developer.android.com/reference/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 `https://developer.android.com/reference/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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-deprecated/index.html` annotation.

This deprecation status will be exposed in the `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata#deprecation()` field, allowing clients to identify and migrate away from the deprecated function.

Example:

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

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/appfunctions/AppFunctionServiceEntryPoint` |   |
| `https://developer.android.com/reference/androidx/appfunctions/AppFunctionException` |   |
| `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSerializable` |   |

## Summary

| ### Public methods |
|---|---|
| `final boolean` | `https://developer.android.com/reference/androidx/appfunctions/AppFunctionDeclaration#isDescribedByKDoc()()` Whether to use the function's KDoc as a function's description for the agent. |
| `final boolean` | `https://developer.android.com/reference/androidx/appfunctions/AppFunctionDeclaration#isEnabled()()` Indicates whether this function is enabled. |

## Public methods

### isDescribedByKDoc

Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

```
public final boolean isDescribedByKDoc()
```

Whether to use the function's KDoc as a function's description for the agent.

If set to `true`, the KDoc will be used to populate:

- The function's `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata#description()` as the KDoc, excluding Kotlin's supported tags like `@param`, `@throws`.

- The function's parameters' `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionParameterMetadata#description()` from the KDoc's `@param` tags.

- The function's response's `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionResponseMetadata#description()` from the KDoc's `@return` tags.

Note: If an `https://developer.android.com/reference/androidx/appfunctions/AppFunctionInstruction` annotation is also present on the method, parameter, or return type, its value will take precedence and override the corresponding KDoc description.

Example:

```
/**
* 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.
*/
@AppFunctionDeclaration(isDescribedByKDoc = true)
fun CreateNote(title: String, content: String): Note { .. }
```

In this example:

- `AppFunctionMetadata.description` will be: "Creates a new note with a given title and content."

- `title`'s `AppFunctionParameterMetadata.description` will be: "The title of the note."

- `content`'s `AppFunctionParameterMetadata.description` will be: "The main body or text of the note."

- `AppFunctionResponseMetadata.description` will be: "The created note."

### isEnabled

Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

```
public final boolean isEnabled()
```

Indicates whether this function is enabled. The default value is `true`.

If set to `false`, this function will be unavailable for invocation by other applications unless explicitly enabled at runtime. When disabled, any attempt to call this function by another application will be rejected.