앱에 AppFunctions API 추가

이 가이드에서는 AppFunctions API를 Android 앱에 통합하고, 함수의 로직을 구현하고, 통합이 올바르게 작동하는지 확인하는 방법을 설명합니다.

버전 호환성

이 구현을 사용하려면 프로젝트 compileSdk가 API 수준 37 이상으로 설정되어 있어야 합니다. 프로젝트에서 Android Gradle 플러그인 9.1.0 이상을 사용해야 합니다.

앱에서 AppFunctions가 지원되는지 확인할 필요는 없습니다. 이는 AppFunctions Jetpack 라이브러리 내에서 자동으로 처리됩니다. AppFunctionManager는 기능이 지원되는 경우 인스턴스를 반환하고 지원되지 않는 경우 null을 반환합니다.

종속 항목

모듈의 build.gradle.kts(또는 build.gradle) 파일에 필수 라이브러리 종속 항목을 추가하고 다음과 같이 최상위 앱 모듈에서 KSP 플러그인을 구성합니다.

dependencies {
  implementation("androidx.appfunctions:appfunctions:1.0.0-rc01")
  // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
  // See Add the KSP plugin to your project
  ksp("androidx.appfunctions:appfunctions-compiler:1.0.0-rc01")
}

AppFunctions 로직 구현

Android 앱에 AppFunction을 구현하려면 특정 AppFunctions 로직을 구현하는 클래스를 만듭니다. 여기에는 매개변수 및 응답에 대한 직렬화 가능한 데이터 클래스를 만든 다음 함수 메서드 내에 핵심 로직을 제공하는 작업이 포함됩니다.

다음 코드는 할 일 앱에서 작업을 만드는 구현 예시를 보여줍니다. 여기에는 맞춤 매개변수와 응답 유형, 저장소를 사용하는 기본 함수 로직을 정의하는 것이 포함됩니다.

@RequiresApi(36)
@AndroidEntryPoint
@AppFunctionServiceEntryPoint(
    serviceName = "TaskAppFunctionService",
    appFunctionXmlFileName = "task_app_function_service",
)
abstract class BaseTaskAppFunctionService : AppFunctionService() {
    @Inject internal lateinit var taskRepository: TaskRepository

    /**
     * Creates a task with a title, content, or both.
     *
     * @param createTaskParams The title and content of the task. At least one
     *   of them is required.
     * @return The created task, including its ID.
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    suspend fun createTask(
        createTaskParams: CreateTaskParams,
    ): Task = withContext(Dispatchers.IO) {
        // Developers can use predefined exceptions to let the agent know
        // why it failed.
        if (createTaskParams.title == null && createTaskParams.content == null) {
            throw AppFunctionInvalidArgumentException("A task needs a title, content, or both.")
        }

        val id = taskRepository.createTask(
            createTaskParams.title,
            createTaskParams.content
        )

        return@withContext taskRepository
            .getTask(id)
            ?.toTask()
            ?: throw AppFunctionElementNotFoundException("Task not found for ID = $id")
    }

    // Maps internal TaskEntity
    private fun TaskEntity.toTask() = Task(id = id, title = title, content = description)
}

코드에 관한 핵심 사항

  • 기본적으로 AppFunction 구현은 Android UI 스레드에서 실행됩니다. 따라서 장기 실행 작업은 다음을 수행해야 합니다.
    • AppFunction을 정지 함수로 선언합니다.
    • 작업이 스레드를 차단할 수 있는 경우 적절한 코루틴 디스패처로 전환합니다.
  • isDescribedByKDoc가 true로 설정되면 함수 설명 또는 직렬화 가능한 설명이 AppFunctionMetadata의 일부로 인코딩되어 에이전트가 앱의 AppFunction을 사용하는 방법을 이해하는 데 도움이 됩니다. 버전 1.0.0-beta01부터 isDescribedByKDoc에는 기본값이 없으므로 명시적으로 설정하세요.

매니페스트에서 AppFunction 서비스 선언

모듈 매니페스트(예: src/main/AndroidManifest.xml) 내에 KSP 생성 서비스 선언과 app_metadata 속성을 등록합니다. KSP 컴파일러는 추상 진입점 클래스를 확장하는 구체적인 서비스 클래스(TaskAppFunctionService)와 assets/ 디렉터리의 상응하는 XML 스키마를 생성합니다.

<service
    android:name="com.example.snippets.ai.TaskAppFunctionService"
    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
    android:exported="true"
    tools:targetApi="36">
    <property
        android:name="android.app.appfunctions.schema"
        android:value="app_functions_schema.xsd" />
    <property
        android:name="android.app.appfunctions.v2"
        android:value="task_app_function_service.xml" />
    <intent-filter>
        <action android:name="android.app.appfunctions.AppFunctionService" />
    </intent-filter>
</service>
<property
    android:name="android.app.appfunctions.app_metadata"
    android:resource="@xml/app_metadata" />

선택사항: 런타임 시 AppFunction 사용 가능 여부 전환

AppFunctions를 제어할 때 AppFunctionManager API를 사용하여 함수를 명시적으로 사용 설정하거나 사용 중지합니다. 게이팅은 앱의 특정 기능을 일부 사용자만 사용할 수 있는 경우에 유용할 수 있습니다. AppFunctions를 동적으로 사용 설정하거나 사용 중지하면 인텔리전스 시스템은 특정 시점에 사용자에게 제공되는 기능을 정확하게 파악할 수 있습니다.

특정 계정 상태가 필요한 AppFunctions를 안전하게 제어하려면 다음 두 단계 프로세스를 따르세요.

1단계: 기본적으로 함수 사용 중지

기능 플래그가 확인되기 전에 함수에 액세스할 수 없도록 하려면 @AppFunctionDeclaration 주석의 isEnabled 매개변수를 false로 설정합니다.

@AppFunctionDeclaration(isEnabled = false, isDescribedByKDoc = true)
suspend fun createTask(
    createTaskParams: CreateTaskParams,
): Task = TODO()

2단계: 런타임 시 동적으로 함수 사용 설정

각 @AppFunctionServiceEntryPoint 클래스에 대해 컴파일러는 함수 ID 상수를 포함하는 상응하는 클래스를 생성합니다(Ids 서픽스 사용). 생성된 ID 상수를 AppFunctionManager의 setAppFunctionEnabled 메서드와 함께 사용하여 런타임에 함수의 사용 설정 상태를 변경할 수 있습니다.

suspend fun onFeatureEnabled(context: Context) {
    try {
        AppFunctionManager.getInstance(context)
            ?.setAppFunctionEnabled(
                BaseTaskAppFunctionServiceIds.CREATE_TASK_ID,
                AppFunctionManager.APP_FUNCTION_STATE_ENABLED,
            )
    } catch (e: Exception) {
        // Handle exception: AppFunctions indexation may not be fully completed
        // upon initial app startup.
    }
}

suspend fun onFeatureDisabled(context: Context) {
    try {
        AppFunctionManager.getInstance(context)
            ?.setAppFunctionEnabled(
                BaseTaskAppFunctionServiceIds.CREATE_TASK_ID,
                AppFunctionManager.APP_FUNCTION_STATE_DISABLED,
            )
    } catch (e: Exception) {
        // Handle exception
    }
}

사용 가능한 기능 유형 고려사항

보안은 항상 가장 중요합니다. AppFunction으로 제공할 앱 기능을 선택할 때는 AI 에이전트가 고급 LLM 기능을 사용하기 위해 서버에서 사용자 쿼리를 처리할 수 있다는 점에 유의하세요.

민감한 정보가 노출되지 않도록 하면서 우수한 사용자 환경을 제공하려면 다음 가이드라인을 따르는 것이 좋습니다.

  • 자연어의 이점을 활용하는 기능: 사용자가 수동 UI 탐색을 통해서보다 대화로 표현하기 더 쉬운 작업을 제공합니다.
  • 액세스 제한: 사용자의 특정 요청을 처리하는 데 필요한 데이터와 작업에만 에이전트가 액세스할 수 있도록 AppFunction을 만듭니다.
  • 민감한 정보: 매우 개인적이거나 기밀이 아닌 데이터 또는 사용자가 작업 컨텍스트에서 공유하는 데 명시적으로 동의한 데이터만 공유합니다.
  • 안전하고 비파괴적인 작업: 할 일 만들기나 메모 검색과 같이 사용자가 일반적으로 앱에서 실행하는 안전하고 비파괴적인 작업만 사용할 수 있도록 합니다. 자세한 내용은 허용되는 작업 및 데이터 공유를 참조하세요.

AppFunction 통합 확인

AppFunctions는 AI 에이전트가 호출하는 서비스 역할을 하므로 테스트에는 두 가지 측면이 있습니다. 즉, 함수의 동작 방식과 함수를 호출할 때 에이전트의 동작 방식입니다.

함수 테스트

함수 로직의 단위 테스트부터 시작하여 AppFunctions 라이브러리를 통한 에이전트 호출이 직접 Kotlin 호출과 어떻게 다른지 고려합니다.

  • 기본값: Kotlin 기본 파라미터 값은 적용되지 않습니다. 생략된 선택적 매개변수는 null, 0, false 또는 빈 목록이나 배열로 도착하므로 limit: Int = 10 매개변수는 0로 도착합니다. 이러한 값으로 생략된 매개변수를 테스트하고 함수 본문에서 기본값을 확인합니다. 자세한 내용은 선택적 매개변수를 참조하세요.
  • 기본 스레드: 플랫폼 호출은 기본 스레드에서 시작되며 단위 테스트에서 suspend 함수를 직접 호출하면 기본 스레드 차단이 포착되지 않습니다. 데이터베이스, 네트워크, 디스크 I/O가 백그라운드 코루틴 디스패처(예: Dispatchers.IO)에서 실행되는지 확인합니다.
  • 예외: 요청이 성공할 수 없는 경우 특정 AppFunctionException 서브클래스를 발생시킵니다. 발견되지 않은 다른 예외는 실패 유형을 식별하지 않는 원시 예외 메시지가 첨부된 AppFunctionAppUnknownException로 에이전트에 도달합니다. 자세한 내용은 오류 처리를 참조하세요.
  • 모델 입력: 입력은 제한된 UI 컨트롤이 아닌 모델에서 제공되므로 빈 문자열, 동의어(예: 'USD'의 경우 '달러'), 범위를 벗어난 값을 테스트합니다.

기기 또는 에뮬레이터에서 adb shell cmd app_function를 사용하여 플랫폼이 생성된 메타데이터의 색인을 생성했고 서비스를 호출할 수 있는지 확인합니다.

adb shell cmd app_function list-app-functions --package $myPackageName를 사용하여 앱에서 제공하는 AppFunctions의 세부정보를 확인합니다.

명시적 식별자("$enclosingClassName#$methodName")를 사용하여 명령줄에서 직접 AppFunction을 실행할 수도 있습니다.

adb shell "cmd app_function execute-app-function \
  --package com.example.android.appfunctions \
  --function 'com.example.android.appfunctions.BaseTaskAppFunctionService#createTask' \
  --parameters '{\"createTaskParams\": {\"title\": \"Buy milk\", \"content\": \"From grocery store\"}}'"

에이전트로 테스트

에이전트로 테스트하여 설명에서 올바른 함수를 선택하고 요청이 예상대로 작동하는지 확인합니다. 에이전트마다 다르게 동작하므로 AppFunctions를 호출하는 에이전트로 테스트합니다.

  • 샘플 에이전트: 도구 검색 및 엔드 투 엔드 워크플로를 로컬에서 테스트하려면 기기에 오픈소스 AppFunctions 테스트 에이전트를 설치하고 실행합니다.
  • Gemini: Android의 Gemini가 AppFunctions를 호출하는 방식을 테스트하려면 연결된 앱 플랫폼 개발자 프리뷰에 참여하고 연결된 앱 만들기 및 관리를 따르세요.
  • 인앱 에이전트: 앱에 동일한 패키지의 함수에 대해 AppFunctionManager를 호출하는 자체 에이전트가 포함된 경우 해당 에이전트를 통해 함수를 테스트합니다.

개발 중에 Android 스튜디오의 Gemini와 같은 채팅 기반 어시스턴트를 AppFunctions 에이전트 기술과 함께 사용하여 통합을 확인하거나 다음과 같은 프롬프트를 제공할 수도 있습니다.

Execute `adb shell cmd app_function` to learn how the tool works, then act as a
chat agent aiming to invoke AppFunctions to fulfill user prompts for this app.
Use the AppFunction descriptions to choose functions and parameters.

하위 API 버전에서 이전

버전 1.0.0-alpha10에서 AppFunctions는 라이브러리 종속 항목을 통합하고 기존 구성 제공자(AppFunctionConfiguration.Provider)를 대체하는 컴파일 시간 @AppFunctionServiceEntryPoint 아키텍처를 도입했습니다. 버전 1.0.0-alpha12에서는 기존 제공자가 삭제되었습니다. 버전 1.0.0-alpha13에서는 @AppFunction 주석의 이름이 @AppFunctionDeclaration로 변경되었고 버전 1.0.0-beta01에서는 앱 메타데이터 XML 파일의 appfn:description 속성 이름이 appfn:instructions로 변경되었습니다. 버전 1.0.0-rc01에서는 기존 appfunctions:aggregateAppFunctions 컴파일러 옵션이 삭제되었습니다. 빌드에서 이 옵션을 KSP 인수로 전달하는 경우 삭제하세요.

앱에서 하위 버전의 AppFunctions(예: 1.0.0-alpha09 또는 1.0.0-alpha10)를 사용하는 경우 Android 스튜디오의 Gemini와 같은 AI IDE에서 AppFunctions 에이전트 기술을 사용하여 이전을 자동화할 수 있습니다. 이 기술에는 에이전트가 빌드 종속 항목을 통합하고, 필요한 @AppFunctionServiceEntryPoint 서비스 래퍼를 만들고, 컨텍스트 매개변수를 분리하고, 매니페스트 선언을 업데이트하고, 1.0.0-beta01 이름 변경을 적용하고, 사용 중단된 컴파일러 옵션을 삭제하도록 안내하는 전용 이전 규칙이 포함되어 있습니다.