Snapshot

Snapshot é a forma como o agente lê uma página web. Pega a página atual e transforma-a num texto estruturado conciso, e atribui números temporários (@1, @2, …) aos elementos com que se pode interagir: botões, campos, ligações. O agente decide o próximo passo a partir desse snapshot, em vez de ler o HTML em bruto ou tentar adivinhar coordenadas no ecrã.

O que resolve

Para uma pessoa, uma página web é uma interface visual. Para um agente, são dezenas de milhares de tokens de HTML, scripts, estilos e estado dinâmico. Despejar isso tudo num LLM custa duas coisas:

• Custo elevado em tokens. Uma página de backoffice habitual pode ir aos 30 mil tokens e ser relida antes de cada ação.
• Ruído a mais. A maior parte do DOM (estilos, scripts, nós ocultos) não tem nada a ver com a decisão e só atrapalha.

O snapshot apoia-se na accessibility tree do browser — a vista semântica que o browser mantém para leitores de ecrã — e comprime a página em poucas centenas de tokens:

• Título da página e URL atual.
• Texto visível e a estrutura principal.
• Elementos que se podem clicar, preencher ou selecionar, com os respetivos papéis e nomes.
• Um @N temporário para cada elemento interativo.

É o que basta para o agente decidir em que botão carregar e que campo preencher — sem HTML em bruto e sem coordenadas de ecrã.

Como funcionam as refs @N

Cada elemento interativo do snapshot recebe um número temporário:

@1 [input]  "Pesquisar"
@2 [button] "Enviar"
@3 [link]   "Página seguinte"

O agente atua sobre estes números, por exemplo await click('@2').

@N só é válido para este snapshot. Quando a página muda (navegação, refresh, diálogo, submissão de formulário, troca de separador, re-render dinâmico), os números antigos podem deixar de apontar para algo. O hábito seguro é tirar um novo snapshot a seguir a cada mudança, e não guardar um @N por muito tempo.

Se precisa de referenciar de forma estável um elemento ao longo de vários passos, use o seletor loc=... que o snapshot devolve, ou escreva um seletor CSS diretamente. Ver ego-browser.

Quando vai notar o snapshot

Na maior parte das situações nem lhe toca — o agente lê-o sozinho. Pode dar por ele em duas situações:

1. O agente diz "novo snapshot" ou "snapshot da página": detetou uma mudança e está a reler o estado atual.
2. O resultado da tarefa traz um excerto do snapshot como prova.

Descrever a tarefa ao agente

O snapshot ajuda o agente a ver bem a página, mas as fronteiras da tarefa são consigo. Uma boa descrição diz:

• A página ou site alvo.
• O que ler, preencher, clicar ou descarregar.
• O que não pode fazer (apagar, publicar, pagar, enviar e-mail, etc.).
• Se deve parar perante captcha, pagamento ou autorização.
• A forma do resultado pretendido (tabela, resumo, captura de ecrã, caminho local).

Exemplos:

Abre os meus GitHub Notifications, filtra os PR que precisam da minha review e devolve-me nome do repositório, título e link.
Não arquives, não marques como lido.

Abre o backoffice de encomendas, filtra as de ontem, faz download do CSV.
Se houver verificação de login ou confirmação de exportação, para e avisa-me, e diz-me onde guardaste o ficheiro.

Validar o que o agente fez

Quando a tarefa acaba, estes são os indícios para julgar:

• Indicou as páginas que visitou e as ações principais?
• O resultado inclui informação verificável (títulos, identificadores, links, valores, datas)?
• Numa tarefa de download, deu o caminho local do ficheiro?
• Em tarefas que alteram ou submetem dados, parou antes da confirmação final?
• A página continua aberta no Space para poder ir lá ver?

Se algo lhe parecer estranho, peça ao agente um novo snapshot da página em vez de continuar a especular sobre a resposta anterior.

Perguntas frequentes

Porque é que o agente diz que uma ref já não é válida?

A página mudou desde o último snapshot. Diga-lhe para tirar um novo.

O snapshot consegue ler tudo?

Nem sempre. Conteúdo fora do ecrã, texto em imagens, canvas complexos, iframes cross-origin restritas podem não aparecer todos. Nesses casos o agente pode combinar snapshot com captura de ecrã, extração de texto ou confirmação humana.

O snapshot altera dados?

Não. O snapshot só lê estrutura da página. Quem altera o estado é o que vem depois: cliques, preenchimentos, submissões, uploads, eliminações.

Tenho de me lembrar dos @1, @2?

Não. Encare-os como "números temporários para a página atual". Quem os usa é o agente; o seu trabalho é definir bem o objetivo e os limites.