AI 에이전트가 내 Android 앱을 조작하게 할까? AppFunctions 공개 전 6칸 capability 카드

핵심 요약

• AppFunctions는 앱의 서비스·데이터·동작을 Android OS registry에 제공하고, 권한을 가진 caller가 이를 발견·실행하는 표면입니다. 따라서 앱 화면 안의 권한과 외부 호출 권한을 같은 것으로 보면 안 됩니다.
• 조회, 되돌릴 수 있는 변경, 되돌릴 수 없는 변경을 한 줄로 취급하지 마세요. 첫 공개는 조회와 제한적인 가역 변경부터 시작하는 편이 안전합니다.
• 사용자 확인은 caller 식별이나 앱 권한을 대신하지 않습니다. 세 층은 각각 누락될 수 있으므로 별도로 검증해야 합니다.
• 결제·송금·계정 삭제·민감정보 대량 내보내기처럼 복구가 어렵거나 피해 범위가 큰 기능은, 확인 화면이 있다는 이유만으로 첫 공개에 넣지 않는 편이 좋습니다.

왜 화면의 버튼 권한만으로는 부족할까요?

Android Developers의 AppFunctions 개요에 따르면 AppFunctions는 앱의 서비스·데이터·동작을 OS registry에 제공하고, 권한을 가진 agent·앱·AI assistant가 발견하고 실행할 수 있도록 설계된 표면입니다. 즉 사용자가 앱 화면에서 직접 버튼을 누르는 흐름과, 허용된 외부 caller가 기능을 찾아 호출하는 흐름은 같은 문제가 아닙니다.

여기서 가장 흔한 실수는 “앱 로그인 상태면 괜찮다”라고 한 번에 묶는 것입니다. 로그인 상태는 사용자 세션을 설명할 수 있지만, 어떤 caller가 어떤 범위로 호출했는지, 바뀐 상태를 사용자가 이해하고 취소할 수 있는지는 별도의 질문입니다.

AppFunctions의 현재 제공 조건과 접근 범위는 구현·배포 시점에 공식 문서로 다시 확인해야 합니다. 이 글은 특정 API 세부값을 고정하지 않고, 공개 범위를 판단하는 계약을 먼저 만드는 방법에 집중합니다.

기능 등급별 첫 공개 기준

첫 공개 후보를 고를 때는 기능 이름보다 실패했을 때 남는 상태를 먼저 보세요. 아래 표는 시작 범위를 줄이기 위한 판단표입니다.

이 표의 목적은 기능을 영구히 막는 것이 아닙니다. 관측 가능한 실패와 복구 경로를 먼저 확보할 수 있는 기능부터 공개하자는 뜻입니다. 비용도 이 지점에서 드러납니다. 호출 한 번의 모델 비용보다, 잘못된 변경 뒤 고객지원·수동 복구·감사 대응에 드는 비용이 훨씬 커질 수 있습니다.

기능 하나당 6칸 capability 카드를 만드세요

기능을 등록하기 전, 문서 한 장 또는 티켓 한 장에 아래 여섯 칸을 채웁니다. 이 카드는 개발 문서가 아니라 출시 판단을 위한 최소 계약입니다.

1. 목적: 사용자가 얻는 결과를 한 문장으로 씁니다.
2. 입력과 출력: 필요한 값과 반환할 최소 결과를 정합니다.
3. 상태 변경: 조회인지, 되돌릴 수 있는지, 되돌릴 수 없는지 밝힙니다.
4. caller와 권한: 허용 caller와 데이터 범위를 기록합니다.
5. 확인: 변경 전 사용자가 보게 될 요약과 취소 경로를 씁니다.
6. 복구와 감사: undo 방법, 이벤트에 남길 정보, 실패 후 재시도 규칙을 적습니다.

예시 1: 다음 예약 조회

목적은 “오늘 이후 예약을 간단히 알려준다”입니다. 입력은 기간이고 출력은 날짜·제목 같은 필요한 최소 항목입니다. 상태 변경은 없지만, caller가 모든 과거 예약이나 상세 메모까지 보지 못하도록 데이터 범위를 분명히 해야 합니다. 결과가 비어 있는 경우와 권한이 없는 경우도 같은 문장으로 뭉개지지 않게 반환 규칙을 나눕니다.

예시 2: 알림 시간 변경

상태가 바뀌는 기능이므로 요청값만 받아 바로 실행하지 않습니다. “평일 알림을 오전 9시에서 오전 10시로 바꿉니다”처럼 변경 전후를 보여 주고, 확인 뒤 적용합니다. 적용 결과에는 undo에 쓸 식별자나 이전 값을 복구할 수 있는 정보를 남깁니다. 취소·네트워크 실패·중복 호출 뒤 화면 표시와 실제 저장 상태가 어긋나지 않는지도 확인해야 합니다.

AppFunctions 구현 안내는 destructive action에 대해 앱이 명확하고 모호하지 않은 확인 절차를 제공해야 한다고 안내합니다. 이 원칙은 가역 변경에도 유용하지만, 확인 화면 하나로 고위험 변경의 모든 위험이 사라진다는 뜻은 아닙니다.

첫 공개에서 제외할 조건과 실패 신호

다음 중 하나라도 답하기 어렵다면 기능을 빼고, 조회 기능이나 좁은 가역 변경으로 범위를 줄이는 편이 낫습니다.

• 되돌릴 수 없는 금전·계정·데이터 변경인가요?
• 호출 주체를 충분히 식별하거나 범위를 제한할 수 없나요?
• 민감정보를 필요한 것보다 넓게 반환할 가능성이 있나요?
• 취소, 타임아웃, 재시도 뒤의 최종 상태를 사용자와 운영자가 함께 확인할 수 없나요?
• 사후에 caller·기능·입력 요약·결과·실패 원인을 확인할 감사 기록이 없나요?

특히 “요청은 성공으로 보였지만 실제 저장은 실패한” 경우가 위험합니다. agent는 다음 행동을 이어갈 수 있고 사용자는 이미 결과를 믿을 수 있기 때문입니다. 이때 필요한 것은 더 화려한 대화가 아니라, 상태를 다시 읽어 확인하고 실패를 명시적으로 돌려주는 신뢰성 규칙입니다.

서버 측 도구 호출의 승인 경계도 함께 정리하고 싶다면 병렬 처리와 승인 경계를 나누는 결정표를 이어서 보셔도 좋습니다. 모바일 capability 공개 계약은 이와 닮은 점이 있지만, OS registry와 앱 상태라는 추가 경계가 있다는 점에서 별도 설계가 필요합니다.

릴리스 전에는 기능 수가 아니라 실패 경로를 테스트하세요

공식 Android 문서는 AppFunctions의 플랫폼 맥락을 설명하고, Android용 ADK 문서와 Google ADK Kotlin quickstart는 앱 안에서의 agent·function tool·action confirmation 문맥을 보완합니다. ADK는 AppFunctions의 필수 조건으로 단정할 수 없지만, 확인을 독립된 설계 요소로 보는 데 도움이 됩니다.

1. 등록 확인: 실제 대상 기기에서 의도한 기능만 registry에 나타나는지 확인합니다.
2. 차단 확인: 허용되지 않은 caller가 발견하거나 실행하지 못하는지 확인합니다.
3. 변경 확인: 가역 변경은 실행 전 요약, 실행 후 결과, undo 가능 여부를 차례로 확인합니다.
4. 실패 정합성 확인: 취소·타임아웃·네트워크 실패·중복 호출 뒤 저장 상태와 표시가 일치하는지 다시 읽어 봅니다.
5. 감사와 롤백 확인: 이벤트 기록을 통해 호출자·기능·결과를 추적할 수 있는지, 기능을 빠르게 제한하거나 되돌릴 수 있는지 확인합니다.

자주 묻는 질문

AppFunctions는 MCP와 같은 것인가요?

둘 다 도구를 발견하고 호출하는 문제를 떠올리게 하지만, 같은 표준이나 같은 보안 모델이라고 단정할 수는 없습니다. AppFunctions는 Android OS registry에 앱 기능을 제공하는 현재 플랫폼 문맥에서 검토하고, 구현 시점의 공식 조건을 확인하세요.

ADK를 반드시 사용해야 하나요?

아닙니다. 이 글의 capability 카드와 공개 범위 판단은 특정 agent 프레임워크에 종속되지 않습니다. ADK 문서는 앱 안에서 agent와 confirmation을 설계하는 한 가지 공식 문맥으로 참고할 수 있습니다.

사용자 확인을 넣으면 삭제나 결제도 첫 공개에 넣어도 될까요?

권하지 않습니다. 명확한 확인은 중요하지만 caller 권한, 추가 인증, 복구 가능성, 감사와 피해 범위 평가를 대체하지 않습니다. 복구가 어렵고 피해가 큰 기능은 별도 검토가 필요합니다.

조회 기능은 항상 안전한가요?

아닙니다. 조회도 민감한 일정·메모·식별 정보를 너무 넓게 반환할 수 있습니다. 필요한 최소 출력, caller 범위, 권한 없는 경우의 처리까지 카드에 적어야 합니다.

참고 자료

• Android Developers — Overview of AppFunctions: AppFunctions가 OS registry를 통해 앱의 서비스·데이터·동작을 제공하는 방식과 적용 환경을 확인할 때 참고했습니다.
• Android Developers — Add AppFunctions to your app: 등록·구현 맥락과 destructive action의 명확한 확인 원칙을 확인할 때 참고했습니다.
• Android Developers — Build ADK agents for Android: Android 앱 안에서 agent를 설계하는 공식 플랫폼 문맥을 보완할 때 참고했습니다.
• Google ADK — Kotlin quickstart: function tools와 action confirmations를 분리해 보는 개발 문맥을 보완할 때 참고했습니다.

Android AI 통합 전반의 안전 맥락은 FLOWIT의 Android AI 안전장치 글에서 함께 확인하실 수 있습니다.