Рекомендации по обеспечению качества AppFunctions

AppFunctions – это практический эквивалент MCP-серверов на Android. Они позволяют делиться частями логики приложения с ИИ-агентами и помощниками.

Агенты используют описания, чтобы выбрать AppFunction, которая выполнит запрос. Этот процесс выбора работает так же, как и традиционный поиск инструментов MCP, когда ИИ-приложения используют описания серверов и инструментов MCP для выбора. Ваше приложение действует как сервер MCP Android, а каждая функция AppFunction – как один из его инструментов. Укажите следующие описания:

• Описание приложения (MCP-сервер Android). Описание приложения – это первое, что помогает агентам понять, что оно может делать. Чтобы агентам было проще найти ваше приложение, укажите его основной домен и кратко перечислите задачи, которые оно может выполнять с помощью AppFunctions.
  • Напишите описание самостоятельно в XML-файле метаданных приложения.
  • В описании приложения можно указать то, что не вошло в описания отдельных функций, например порядок их вызова.
• Описания функций AppFunctions (инструментов). В описании каждой функции объясняется поведение одной AppFunction. Описания функций обычно строятся вокруг глагола, например обновить, создать или забронировать, и ресурса, например настройки, канал или комната.

Рекомендации по описанию функций

Агенты используют описания функций, чтобы определить, какая из них подходит для запроса и как ее вызвать.

Пишите краткие и однозначные описания AppFunction

Чем точнее описание, тем выше вероятность, что агент выберет правильную функцию для запроса. В таблице ниже приведены рекомендации по составлению описаний функций.

Пишите код с учетом инкапсуляции

Описание каждой функции должно быть самодостаточным, чтобы агент мог использовать только ее. В таблице ниже приводятся рекомендации по инкапсуляции.

Допустимые действия и передача данных

Чтобы защитить конфиденциальность пользователей и их безопасность, когда агенты используют функции вашего приложения, следуйте этим рекомендациям:

Разработка параметров и возвращаемых значений

Тщательная разработка параметров и возвращаемых значений предотвращает двусмысленность и снижает вероятность недопустимых вызовов. Следуйте этим правилам:

Необязательные параметры

Необязательными могут быть только типы, допускающие значение NULL, примитивные типы, списки и массивы. Если агент опускает необязательный параметр, библиотека передает значение по умолчанию для типа (null, ноль, false или пустое значение) вместо объявленного вами значения по умолчанию. Задайте в теле функции значения по умолчанию, как в примере ниже.

/**
 * Creates a note.
 *
 * @param title The title of the note.
 * @param content The body text of the note.
 * @param attachments The files to attach to the note.
 * @param owner The ID of the user who owns the note.
 * @return The created note.
 */
@AppFunctionDeclaration(isDescribedByKDoc = true)
suspend fun createNote(
    title: String, // Required
    content: String? = null, // Optional
    attachments: List<Attachment> = emptyList(), // Optional
    owner: String? = null, // Optional
): Note = withContext(Dispatchers.IO) {
    noteRepository.createNote(
        title = title,
        // The library ignores declared default values and passes null for
        // omitted nullable parameters, so resolve meaningful defaults here.
        content = content ?: "",
        attachments = attachments,
        owner = owner ?: currentUserId(),
    )
}

Обновление существующих ресурсов

В следующем примере используется оболочка SetField, допускающая значение NULL, для каждого поля, которое агент может обновить. Нулевое значение SetField означает "не изменять", а SetField(null) – "установить нулевое значение".

/** A new value for a field of an existing item. */
@AppFunctionSerializable(isDescribedByKDoc = true)
data class SetField<T>(
    /** The new value of the field. */
    val value: T,
)

/**
 * Updates an existing note. Omitted fields keep their values.
 *
 * @param noteId The ID of the note to update.
 * @param title The new title of the note.
 * @param content The new body text of the note.
 * @return The updated note.
 */
@AppFunctionDeclaration(isDescribedByKDoc = true)
suspend fun updateNote(
    noteId: String,
    title: SetField<String>? = null,
    content: SetField<String?>? = null,
): Note = withContext(Dispatchers.IO) {
    val note = noteRepository.getNote(noteId)
        ?: throw AppFunctionElementNotFoundException(
            "No note found with ID $noteId"
        )
    noteRepository.updateNote(
        noteId = noteId,
        // A null SetField means "don't change", and SetField(null) means
        // "set to null", so don't use ?: for nullable fields.
        title = title?.value ?: note.title,
        content = if (content != null) content.value else note.content,
    )
}

Обработка ошибок

Если вызов завершается неудачно, агент получает исключение, которое выдает ваша функция, включая его тип и сообщение. Следуйте этим соглашениям, чтобы агент мог восстановить работу после сбоя или сообщить о нем пользователю: