Lineamientos de calidad de AppFunctions

Las AppFunctions son el equivalente práctico de los servidores de MCP en Android. Te permiten compartir partes de la lógica de tu app con agentes y asistentes de IA.

Los agentes usan descripciones para seleccionar la AppFunction que entrega una solicitud. Este proceso de selección funciona como el descubrimiento tradicional de herramientas de MCP, en el que las aplicaciones de IA usan las descripciones de las herramientas y del servidor de MCP para guiar sus elecciones. Tu app actúa como el servidor de MCP de Android, y cada AppFunction actúa como una de sus herramientas. Proporciona las siguientes descripciones:

• Descripción de la app (el servidor de MCP de Android). La descripción de la app es el primer punto de entrada para que los agentes comprendan lo que puede hacer. Para ayudar a los agentes a descubrir tu app, comienza con su dominio principal y enumera de forma concisa las tareas que tus AppFunctions le permiten realizar.
  • Escribe la descripción de la app en el archivo XML de metadatos de la app.
  • Usa la descripción de la app para describir lo que no pueden hacer las descripciones de las funciones individuales, como el orden en el que se deben llamar las funciones.
• Descripciones de AppFunction (las herramientas) Cada descripción de función explica el comportamiento de una AppFunction. Las descripciones de las funciones suelen estructurarse en torno a un verbo, como actualizar, crear o reservar, y un recurso, como configuración, canal o sala.

Lineamientos para la descripción de funciones

Los agentes se basan en las descripciones de las funciones para decidir qué función se adapta a una solicitud y cómo llamarla.

Escribe descripciones de AppFunction concisas y sin ambigüedades

Cuanto menos ambigua sea una descripción, más confiable será que un agente elija la función correcta para una solicitud. En la siguiente tabla, se indica qué hacer y qué evitar en las descripciones de las funciones:

Escribe con la encapsulación en mente

Mantén cada descripción de función independiente, de modo que guíe al agente en el uso de esa función y no de otra. En la siguiente tabla, se indican los lineamientos de encapsulamiento:

Acciones permitidas y uso compartido de datos

Sigue estos lineamientos para proteger la privacidad y la seguridad de los usuarios cuando los agentes usen las funciones de tu app:

Diseño de parámetros y valores que se muestran

El diseño cuidadoso de los parámetros y los valores de retorno evita la ambigüedad y reduce la posibilidad de llamadas no válidas. Sigue estas convenciones:

Parámetros opcionales

Solo los tipos anulables, primitivos, de lista y de array pueden ser opcionales. Cuando el agente omite un parámetro opcional, la biblioteca pasa el valor predeterminado del tipo (null, cero, false o vacío) en lugar del valor predeterminado que declaras. Resuelve los valores predeterminados significativos en el cuerpo de la función, como en el siguiente ejemplo:

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

Actualizaciones de los recursos existentes

En el siguiente ejemplo, se usa un wrapper SetField que acepta valores nulos para cada campo que el agente puede actualizar. Un SetField nulo significa "no cambiar" y SetField(null) significa "establecer como nulo":

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

Manejo de errores

Cuando falla una llamada, el agente recibe la excepción que arroja tu función, incluidos su tipo y mensaje. Sigue estas convenciones para que el agente pueda recuperarse de la falla o informarla al usuario: