Hacer que los agentes de IA entiendan la pantalla: Guía práctica de diseño de Semantics en Jetpack Compose

Hacer que los agentes de IA entiendan la pantalla: Guía práctica de diseño de Semantics en Jetpack Compose

Introducción

Para que los agentes de IA y las herramientas de automatización de pruebas en Jetpack Compose entiendan con precisión "qué hace este botón", el diseño adecuado de Semantics es clave.

Compose tiene internamente un "Semantics Tree" que funciona como estructura semántica de referencia para accesibilidad, pruebas de UI y IA de operación automática (como Appium/UIAutomator/MCP). Es el equivalente a ARIA y DOM en la web.

Atributos principales de Semantics

contentDescription

El atributo más básico para dar significado a los botones que solo tienen iconos.

IconButton(
    onClick = onDelete,
    modifier = Modifier.semantics {
        contentDescription = "Eliminar"
    }
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

La IA y la accesibilidad lo reconocen como "botón Eliminar · clicable · rol Button".

role

Especifica el tipo de UI para componentes personalizados. Un simple Box(clickable) sería "algo clicable", pero añadiendo role queda claro el significado: Button, Switch, Checkbox, Tab, etc.

Modifier.semantics {
    role = Role.Button
}

stateDescription

Informa a la IA del estado actual de la UI.

Modifier.semantics {
    stateDescription =
        if (subscribed) "Suscrito"
        else "No suscrito"
}

testTag

El identificador más importante para MCP, Appium y agentes automáticos de UI. Permite una identificación estable que no depende de coordenadas, OCR ni cambios de texto.

Modifier.testTag("login_button")

Configuración para integración con UIAutomator

Compose no crea directamente una jerarquía de vistas, por lo que UIAutomator puede no ver testTag. Esto se soluciona añadiendo lo siguiente a la raíz:

Scaffold(
    modifier = Modifier.semantics {
        testTagsAsResourceId = true
    }
)

testTag se reconocerá como resource-id y podrá obtenerse directamente desde UIAutomator.

El patrón de implementación más comprensible para la IA

La mejor práctica es combinar múltiples atributos.

Button(
    onClick = login,
    modifier = Modifier
        .testTag("login_button")
        .semantics {
            contentDescription = "Iniciar sesión"
            role = Role.Button
        }
) {
    Text("Iniciar sesión")
}

Unificar una UI compleja en un único significado

Para presentar a la IA una composición compleja de iconos, texto y Badge como un único botón, se usa clearAndSetSemantics.

Modifier.clearAndSetSemantics {
    contentDescription = "Agregar producto al carrito"
    role = Role.Button
}

Se puede ignorar la estructura anidada interna y los grupos de iconos, pasando solo el significado a la IA.

Lo que se puede lograr con el diseño de Semantics

Estabilización de la automatización

Con testTag, se puede operar de forma estable sin coordenadas ni OCR. Aunque se rediseñe la UI, la automatización no se rompe mientras el testTag sea el mismo. También mejora la resistencia a la internacionalización.

Reducción de tokens

Cuando se depende solo de capturas de pantalla, el análisis de imágenes requiere muchos tokens, pero con Semantics Tree se puede tratar como datos estructurados ligeros.

[
  {"type": "Button", "label": "Iniciar sesión"},
  {"type": "TextField", "label": "Correo electrónico"},
  {"type": "TextField", "label": "Contraseña"}
]

Especialmente efectivo en operaciones automáticas prolongadas y análisis de pantallas a gran escala, contribuyendo también a prevenir el context overflow.

Comprensión del estado por parte de la IA

Gracias a stateDescription, la IA puede estimar el estado actual de la pantalla y tomar decisiones como "ahora está pausado, así que presionaré el botón de reproducir". Permite entender la pantalla como una máquina de estados.

Análisis estructurado en integración MCP

Obteniendo el Semantics Tree a través de MCP Server y pasándolo al LLM Agent, es posible la comprensión del significado de toda la pantalla, la estimación de candidatos para la siguiente operación y el análisis de transiciones de estado.

Compose UI → Semantics Tree → MCP Server → LLM Agent

Resumen del uso de atributos de Semantics

Conclusión

Compose permite separar "apariencia" de "significado". La esencia del diseño de Semantics radica en poder diseñar de forma independiente la UI para humanos y la estructura semántica para IA.

Si vas a utilizar agentes de IA, MCP, UIAutomator y pruebas automáticas E2E, la siguiente estandarización para cada componente ofrece un alto retorno de inversión:

Modifier
    .testTag(...)
    .semantics {
        contentDescription = ...
        role = ...
    }

Transmitir "qué es este botón · qué pasa al presionarlo · cuál es su estado ahora" a través de Semantics en lugar de color, posición y tamaño — esta es la esencia del diseño de UI preparado para IA.