Fazendo agentes de IA entenderem a tela: Guia prático de design de Semantics no Jetpack Compose

Fazendo agentes de IA entenderem a tela: Guia prático de design de Semantics no Jetpack Compose

Introdução

Para fazer agentes de IA e ferramentas de automação de testes no Jetpack Compose entenderem com precisão "o que este botão faz", o design adequado de Semantics é fundamental.

O Compose tem internamente uma "Semantics Tree" que funciona como estrutura semântica referenciada por acessibilidade, testes de UI e IA de operação automática (como Appium/UIAutomator/MCP). É o equivalente ao ARIA e DOM na web.

Atributos principais do Semantics

contentDescription

O atributo mais básico para dar significado a botões que têm apenas ícones.

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

A IA e a acessibilidade o reconhecem como "botão Excluir · clicável · papel Button".

role

Especifica o tipo de UI para componentes personalizados. Um simples Box(clickable) seria "algo clicável", mas adicionando role o significado fica claro: Button, Switch, Checkbox, Tab, etc.

Modifier.semantics {
    role = Role.Button
}

stateDescription

Informa à IA o estado atual da UI.

Modifier.semantics {
    stateDescription =
        if (subscribed) "Inscrito"
        else "Não inscrito"
}

testTag

O identificador mais importante para MCP, Appium e agentes automáticos de UI. Permite identificação estável que não depende de coordenadas, OCR ou mudanças de texto.

Modifier.testTag("login_button")

Configuração para integração com UIAutomator

O Compose não cria diretamente uma hierarquia de Views, então o UIAutomator pode não ver o testTag. Isso é resolvido adicionando o seguinte à raiz:

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

O testTag será reconhecido como resource-id e poderá ser obtido diretamente pelo UIAutomator.

O padrão de implementação mais compreensível para IA

A melhor prática é combinar múltiplos atributos.

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

Unificar uma UI complexa em um único significado

Para apresentar à IA uma composição complexa de ícones, texto e Badge como um único botão, usa-se clearAndSetSemantics.

Modifier.clearAndSetSemantics {
    contentDescription = "Adicionar produto ao carrinho"
    role = Role.Button
}

A estrutura aninhada interna e os grupos de ícones podem ser ignorados, passando apenas o significado para a IA.

O que se pode alcançar com o design de Semantics

Estabilização da automação

Com testTag, é possível operar de forma estável sem coordenadas ou OCR. Mesmo após redesenhar a UI, a automação não quebra enquanto o testTag for o mesmo. O suporte a múltiplos idiomas também se torna mais robusto.

Redução da quantidade de tokens

Quando se depende apenas de screenshots, a análise de imagens requer muitos tokens, mas com Semantics Tree pode ser tratado como dados estruturados leves.

[
  {"type": "Button", "label": "Entrar"},
  {"type": "TextField", "label": "E-mail"},
  {"type": "TextField", "label": "Senha"}
]

Especialmente eficaz em operações automáticas prolongadas e análise de telas em grande escala, contribuindo também para prevenir context overflow.

Compreensão do estado pela IA

Graças ao stateDescription, a IA pode estimar o estado atual da tela e tomar decisões como "agora está pausado, então vou pressionar o botão de reproduzir". Permite entender a tela como uma máquina de estados.

Análise estruturada na integração MCP

Obtendo o Semantics Tree através do MCP Server e passando-o ao LLM Agent, é possível a compreensão do significado de toda a tela, estimativa de candidatos para a próxima operação e análise de transições de estado.

Compose UI → Semantics Tree → MCP Server → LLM Agent

Resumo do uso de atributos Semantics

Conclusão

O Compose permite separar "aparência" de "significado". A essência do design de Semantics está na capacidade de projetar de forma independente a UI para humanos e a estrutura semântica para IA.

Se você vai utilizar agentes de IA, MCP, UIAutomator e testes automáticos E2E, a seguinte padronização para cada componente oferece alto retorno sobre investimento:

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

Transmitir "o que é este botão · o que acontece ao pressioná-lo · qual é seu estado agora" através do Semantics em vez de cor, posição e tamanho — esta é a essência do design de UI preparado para IA.