Wskazówki dotyczące jakości funkcji aplikacji

AppFunctions to praktyczny odpowiednik serwerów MCP na Androidzie. Umożliwiają udostępnianie części logiki aplikacji agentom i asystentom AI.

Agenci używają opisów, aby wybrać funkcję AppFunction, która spełnia żądanie. Ten proces wyboru działa jak tradycyjne wykrywanie narzędzi MCP, w którym aplikacje AI wykorzystują opisy serwerów i narzędzi MCP do podejmowania decyzji. Aplikacja działa jako serwer MCP na Androidzie, a każda funkcja AppFunction działa jako jedno z jego narzędzi. Podaj te teksty reklamy:

• Opis aplikacji (serwer MCP na Androida). Opis aplikacji to pierwszy punkt wejścia dla agentów, który pozwala im zrozumieć, co potrafi Twoja aplikacja. Aby pomóc agentom odkryć Twoją aplikację, zacznij od jej głównej domeny i krótko wymień zadania, które można wykonać za pomocą funkcji AppFunctions.
  • Samodzielnie napisz opis aplikacji w pliku XML metadanych aplikacji.
  • Użyj opisu aplikacji, aby opisać to, czego nie można opisać w opisach poszczególnych funkcji, np. kolejność wywoływania funkcji.
• Opisy AppFunction (narzędzia). Każdy opis funkcji wyjaśnia działanie jednej funkcji AppFunction. Opisy funkcji są zwykle zbudowane wokół czasownika, takiego jak zaktualizuj, utwórz lub zarezerwuj, oraz zasobu, takiego jak ustawienia, kanał lub pokój.

Wytyczne dotyczące opisu funkcji

Agenci korzystają z opisów funkcji, aby zdecydować, która funkcja pasuje do żądania i jak ją wywołać.

Tworzenie zwięzłych i jednoznacznych opisów funkcji AppFunction

Im mniej niejednoznaczny jest opis, tym większe prawdopodobieństwo, że agent wybierze odpowiednią funkcję dla żądania. W tabeli poniżej znajdziesz wskazówki dotyczące tego, co należy robić, a czego unikać w opisach funkcji:

Pisanie z myślą o enkapsulacji

Każdy opis funkcji powinien być samodzielny, aby agent mógł korzystać z tej funkcji i żadnej innej. W tabeli poniżej znajdziesz wytyczne dotyczące enkapsulacji:

Dozwolone działania i udostępnianie danych

Aby chronić prywatność użytkownika i bezpieczeństwo użytkowników, gdy agenty korzystają z funkcji aplikacji, postępuj zgodnie z tymi wytycznymi:

Projektowanie parametrów i wartości zwracanych

Staranne projektowanie parametrów i wartości zwracanych zapobiega niejednoznaczności i zmniejsza prawdopodobieństwo nieprawidłowych wywołań. Postępuj zgodnie z tymi konwencjami:

Parametry opcjonalne

Opcjonalne mogą być tylko typy dopuszczające wartość null, typy podstawowe, listy i tablice. Gdy agent pominie opcjonalny parametr, biblioteka przekazuje domyślną wartość typu – null, zero, false lub pustą – zamiast zadeklarowanej przez Ciebie wartości domyślnej. Rozwiąż istotne wartości domyślne w treści funkcji, jak w tym przykładzie:

/**
 * 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(),
    )
}

Aktualizacje istniejących zasobów

W przykładzie poniżej użyto opakowania SetField, które może mieć wartość null, dla każdego pola, które agent może aktualizować. Wartość null SetField oznacza „nie zmieniaj”, a SetField(null) oznacza „ustaw na 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,
    )
}

Obsługa błędów

Gdy wywołanie się nie powiedzie, agent otrzyma wyjątek zgłoszony przez funkcję, w tym jego typ i komunikat. Postępuj zgodnie z tymi konwencjami, aby agent mógł naprawić błąd lub zgłosić go użytkownikowi: