Agentes de IA em menus de contexto: validar a ação do botão direito

Agentes de IA que operam interfaces (o chamado computer use) precisam lidar com um problema que passa despercebido: o menu de contexto, aquele que abre com o botão direito do mouse. Ele parece simples, mas é uma das áreas mais traiçoeiras para automação, porque o mesmo clique que abre uma opção no seu computador pode abrir outra coisa, nada, ou um menu diferente no computador do seu cliente.

Antes de clicar em qualquer item, o agente precisa revalidar o que está na tela naquele instante. Este artigo explica por que, quais são os pontos de falha e como construir automações que clicam no item certo com confiabilidade.

Resumo rápido

• Menu de contexto nativo (do sistema operacional) e menu personalizado (desenhado pela própria página) se comportam de formas diferentes.
• Itens desabilitados, ocultos ou que mudam de posição derrubam automações que dependem de “clicar no terceiro item”.
• Nomes duplicados, submenus e ordem que muda por contexto são as causas mais comuns de clique no lugar errado.
• A IA deve localizar o item por papel e nome acessível, não por coordenada de tela, e reconferir antes de agir.
• Teclado e foco são aliados: se o item não é alcançável pelo teclado, ele raramente é confiável para automação.
• Revalidar o item imediatamente antes do clique é a diferença entre automação estável e automação que quebra sozinha.

O que é o menu de contexto e por que ele engana agentes

O menu de contexto é a lista de ações que aparece quando o usuário pede, tipicamente com o botão direito do mouse ou com a tecla de menu do teclado. Segundo a documentação da MDN, o evento que dispara esse menu se chama contextmenu, e ele pode ser aberto tanto pelo botão direito quanto pela tecla dedicada do teclado.

O problema começa aí: existem dois tipos de menu de contexto, e eles se comportam de maneiras diferentes.

• Menu nativo: é desenhado pelo sistema operacional ou pelo navegador. A página quase não tem controle sobre ele. Você vê opções como “Salvar imagem”, “Abrir em nova aba” ou “Inspecionar”.
• Menu personalizado: é a página que desenha o próprio menu, normalmente interceptando o evento e escondendo o nativo. Você vê opções como “Editar tarefa” ou “Marcar como concluído”, definidas pelo site.

Um agente que não distingue os dois vai errar. Se ele espera o menu nativo e o site bloqueou o nativo para mostrar o próprio, ele pode não encontrar nada. Se ele espera o menu personalizado e o site deixou o nativo passar, ele vai clicar numa opção do navegador que não tem nada a ver com a tarefa. Detectar qual dos dois está na tela é o primeiro passo obrigatório.

Por que automação por coordenada quebra

A abordagem mais frágil é clicar em uma posição fixa na tela. Parece funcionar no computador de quem montou o fluxo e falha em qualquer outro: resolução diferente, barra de tarefas mais alta, zoom do navegador, idioma do sistema ou fonte maior mudam tudo. A posição do item três vira a posição do item um.

Documentações de automação de navegador, como a do Playwright, são explícitas sobre isso: a recomendação é localizar elementos por atributos voltados ao usuário, como o papel (role) e o nome acessível, em vez de por posição ou caminho frágil no HTML. O motivo é simples: papel e nome mudam menos e descrevem a intenção, não a aparência.

Para um menu, isso significa que o agente deve procurar o item pelo que ele é e pelo que ele diz, e tratar a posição como detalhe, não como contrato.

Os seis pontos de falha que mais derrubam agentes

1. Itens desabilitados

Um item pode estar visível mas indisponível, porque alguma condição não foi atendida: nada selecionado, permissão faltando, objeto em estado que não permite a ação. Clicar nele não faz nada e o agente acredita ter agido. O agente precisa ler o estado do item, não só a existência dele.

2. Itens ocultos

Às vezes a ação existe na estrutura da página, mas está escondida para o usuário naquele contexto. Uma automação que varre o código em vez da tela pode “encontrar” um item que nenhum humano conseguiria clicar, e o clique não tem o efeito esperado.

3. Submenus

A ação desejada não está no primeiro nível: ela vive dentro de um submenu. O agente precisa saber que precisa primeiro passar o mouse ou teclar para abrir o submenu, e só então alcançar o item. Pular essa etapa é uma das falhas mais comuns.

4. Ordem que muda por contexto

O mesmo menu pode apresentar os itens em ordem diferente conforme o que está selecionado ou conforme o tipo de objeto. “Renomear” pode ser o segundo item num caso e o quarto em outro. Automatizar por índice é apostar na sorte.

5. Nomes duplicados

Dois itens podem ter o mesmo texto. “Remover” pode aparecer para remover a etiqueta e, mais abaixo, para remover o item inteiro. Sem uma distinção adicional (papel, hierarquia, posição dentro do grupo), o agente escolhe o errado. Nesse caso, clicar errado não é ruído: é uma ação destrutiva.

6. Sobreposição e menus nativos do sistema

O menu do sistema operacional pode aparecer por cima do menu da página, ou o contrário. Em aplicações que rodam em tela cheia, como em ambientes de treinamento por headset, esse conflito é ainda mais provável. O agente precisa confirmar qual menu está realmente na frente antes de interagir.

Como a IA deve validar o item antes de clicar

A regra central é: localizar por significado, confirmar por estado, agir só depois. Traduzindo em passos que um agente pode executar:

1. Detectar o tipo de menu. É nativo ou é desenhado pela página? O tratamento é diferente.
2. Localizar o item por papel e nome. Procurar por “o item de menu chamado X”, não por “a terceira linha”.
3. Checar o estado. O item está habilitado? Está visível? Se não, parar e reportar, em vez de clicar.
4. Resolver ambiguidade. Se houver mais de um item com o mesmo nome, usar a hierarquia e o contexto para desempatar. Se não for possível, não clicar.
5. Navegar submenu quando existir. Abrir o nível intermediário antes de alcançar o item final.
6. Revalidar imediatamente antes do clique. A tela pode ter mudado entre a leitura e a ação. Confirmar de novo, no último instante, evita agir sobre um estado que já não existe.
7. Verificar o resultado depois. O clique produziu o efeito esperado? Se não, o agente deve registrar a falha, não assumir sucesso.

O passo seis é o mais negligenciado e o mais importante. Entre o momento em que a IA “olha” a tela e o momento em que ela “clica”, o mundo pode ter mudado: um aviso apareceu, a página recarregou, outra janela roubou o foco. Automatizações confiáveis funcionam como um humano atento, que confere de novo antes de apertar.

Papéis acessíveis e por que ajudam a automação

Semântica de acessibilidade e confiabilidade de agente andam juntas. Quando um menu é construído com os papéis corretos, definidos na especificação WAI-ARIA do W3C, ele fica navegável por leitores de tela e, de quebra, fica legível para a IA.

Os papéis relevantes para menus são menu, menubar e menuitem, além de variações como menuitemcheckbox e menuitemradio. Segundo a documentação de menuitem da MDN, esse papel indica que o elemento é uma opção dentro de um conjunto de escolhas contido por um menu ou barra de menu. O guia de padrões de autoria do W3C (ARIA Authoring Practices Guide) descreve o comportamento de teclado esperado, incluindo como o foco se move entre os itens e o que acontece quando um item é ativado.

Isso importa na prática por uma razão direta: se um item de menu está marcado corretamente, o agente consegue encontrá-lo por role e nome, exatamente como faria um leitor de tela. Se o site usou div genérica sem papel nenhum, o agente cai na tentativa e erro por texto ou posição, e a confiabilidade despenca.

Teclado e foco: o teste mais barato de confiabilidade

Antes de escrever automação, faça um teste simples: navegue pelo menu usando apenas o teclado. Se as setas movem o foco pelos itens, se o Enter ativa a opção, se o Esc fecha o menu e se o foco volta para o lugar certo, o menu foi construído com semântica decente. Esse menu será confiável para a IA.

Se o menu só responde ao mouse, com foco que se perde ou que pula para o início da página, a automação vai sofrer. Isso porque foco e acessibilidade são a base sobre a qual a localização por papel funciona. Um menu que respeita ordenação de foco, navegação por setas e ativação por teclado está, na prática, entregando à IA um mapa do que está clicável e em que ordem.

A especificação HTML define os atributos e comportamentos base dos elementos interativos, e a especificação de ARIA em HTML descreve como papéis e atributos se aplicam a esses elementos. Seguir essas definições não é preciosismo: é o que separa automação estável de automação que quebra na próxima atualização do site.

Exemplo: sistema de gestão de chamados em Curitiba (PR)

Um caso ilustrativo, para fixar as ideias. Uma empresa de logística em Curitiba, no Paraná, montou um agente de IA para automatizar a abertura e o fechamento de ordens de serviço em um sistema interno de gestão de chamados.

O sistema tinha um menu de contexto com dois itens chamados “Fechar”: um fechava o chamado atual, outro fechava todos os chamados relacionados a um pedido. A primeira versão do agente clicava no primeiro item por posição. Em testes, quase sempre funcionava, mas de vez em quando fechava o lote errado, porque em certos estados da tela o item de lote subia para o topo.

A correção não foi aumentar tentativas de clique. Foi mudar a estratégia: o agente passou a localizar o item pelo papel e pelo nome acessível, a checar se o item estava habilitado, a desempatar os dois “Fechar” pelo contexto (fechar o item selecionado versus fechar o lote) e a revalidar o estado imediatamente antes de agir. Quando o sinal ficava ambíguo, o agente parava e pedia confirmação humana em vez de adivinhar.

O resultado foi menos automação “cega” e mais automação confiável, mesmo operando um menu com nome duplicado, que é um dos piores cenários. O ganho não veio de clicar mais rápido, veio de clicar certo.

Erros comuns

• Clicar por coordenada. Funciona na máquina de quem testou e falha em qualquer outra configuração de tela.
• Confiar no índice do item. A ordem muda com o contexto. Ordem não é identificador.
• Ignorar o estado desabilitado. O clique não faz nada e o agente registra sucesso falso.
• Não abrir o submenu. O agente procura o item no nível errado e não encontra.
• Não distinguir menu nativo de personalizado. Resulta em clicar em opções do navegador por engano.
• Achar que a tela é estável. Entre ler e clicar, o estado pode mudar. Revalidar não é opcional.
• Não verificar o resultado. Sem checar o efeito, o agente não sabe se acertou e não consegue reportar falha.
• Apostar em menu sem semântica. Se não há papel acessível, a IA depende de texto solto e a confiabilidade cai.

Perguntas frequentes

Por que o agente clica no item errado do menu?

Na maioria dos casos, porque foi programado para usar posição ou índice em vez de identificar o item por papel e nome. Quando a ordem muda ou aparece um item novo, o índice aponta para outro alvo. Corrigir significa localizar por significado e confirmar o estado antes de agir.

O que é um menu de contexto nativo?

É o menu desenhado pelo sistema operacional ou pelo navegador, não pela página. Exemplos típicos são “Salvar imagem” e “Inspecionar”. Ele se comporta de forma diferente de um menu personalizado pelo site, e o agente precisa saber qual dos dois está lidando.

Como o agente sabe que um item está desabilitado?

Lendo o estado do próprio item, não apenas verificando se ele existe. Um item indisponível pode estar visível, mas não responder ao clique. Sem checar o estado, o agente interpreta ausência de efeito como sucesso.

Dá para automatizar um menu sem semântica de acessibilidade?

Dá, mas com confiabilidade muito menor. Sem papéis como menuitem, a IA precisa recorrer a texto e posição, que são mais frágeis. Uma opção é corrigir a acessibilidade do sistema, o que melhora automação e experiência ao mesmo tempo.

Por que revalidar o item logo antes do clique?

Porque a tela pode mudar entre a leitura e a ação: um aviso aparece, a página recarrega, outra janela assume o foco. Confirmar o estado no último instante evita agir sobre algo que já não existe mais.

Menu com nomes duplicados tem solução?

Tem, mas exige cautela. O agente deve usar a hierarquia e o contexto para desempatar. Quando não consegue distinguir com segurança, o correto é parar e pedir confirmação, nunca chutar, porque um clique errado pode ser destrutivo.

Fontes e leitura recomendada

• MDN: evento contextmenu (Element)
• W3C: WAI-ARIA 1.2 (papéis, estados e propriedades)
• W3C: ARIA Authoring Practices: padrão Menu e Menubar
• MDN: papel ARIA menuitem
• Playwright: Locators (localização por papel e nome acessível)
• Playwright: API Locator
• WHATWG: HTML Standard (elementos e atributos)
• W3C: ARIA in HTML

Se você está construindo agentes que operam interfaces, vale ver também os nossos conteúdos sobre agentes de IA e diálogos modais e sobre permissões de agentes de IA.