Snapshot

Snapshot é como o agente lê uma página web. Ele pega a página atual, transforma em um texto estruturado e enxuto, e atribui números temporários (@1, @2, …) aos elementos com os quais dá pra interagir: botões, campos, links. O agente decide o próximo passo olhando esse snapshot, em vez de ler o HTML cru ou chutar coordenadas de tela.

O que isso resolve

Para uma pessoa, página web é interface visual. Para o agente, é dezena de milhares de tokens de HTML, scripts, estilos e estado dinâmico. Jogar isso direto num LLM tem dois custos recorrentes:

• Custo alto em tokens. Uma página de back-office comum chega a 30 mil tokens, e ainda precisa ser relida antes de cada ação.
• Ruído demais. A maior parte do DOM (estilos, scripts, nós escondidos) não tem nada a ver com a decisão e só atrapalha.

O snapshot é montado a partir da accessibility tree do navegador — a visão semântica que o navegador mantém para leitores de tela — e comprime a página em algumas centenas de tokens:

• Título da página e URL atual.
• Texto visível e estrutura principal.
• Elementos clicáveis, preenchíveis e selecionáveis, com seus papéis e nomes.
• Um @N temporário para cada elemento interativo.

Já é o suficiente para o agente decidir em que botão clicar e qual campo preencher — sem HTML cru e sem coordenadas de tela.

Como as refs @N funcionam

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

@1 [input]  "Buscar"
@2 [button] "Enviar"
@3 [link]   "Próxima página"

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

@N só vale para este snapshot. Depois que a página muda (navegação, refresh, diálogo, envio de formulário, troca de aba, re-render dinâmico), os números antigos podem não apontar mais para nada. O hábito seguro é tirar um snapshot novo depois de cada mudança, e não segurar um @N por muito tempo.

Se você precisa referenciar um elemento de forma estável ao longo de várias etapas, use o seletor loc=... que vem no snapshot, ou escreva CSS selector direto. Veja ego-browser.

Quando você vai notar o snapshot

Na maior parte das vezes você nem encosta nele — o agente lê sozinho. Em duas situações ele aparece:

1. O agente diz "novo snapshot" ou "snapshot da página": detectou mudança e está relendo o estado atual.
2. O resultado da tarefa inclui um trecho do snapshot como evidência.

Descrever a tarefa para o agente

O snapshot ajuda o agente a enxergar a página, mas os limites da tarefa quem define é você. Uma boa descrição diz:

• A página ou site alvo.
• O que ler, preencher, clicar ou baixar.
• O que não pode fazer (apagar, publicar, pagar, mandar e-mail etc.).
• Se deve parar diante de captcha, pagamento ou autorização.
• O formato esperado do retorno (tabela, resumo, screenshot, caminho local).

Exemplos:

Abre meu GitHub Notifications, filtra os PRs esperando minha review e devolve repositório, título e link.
Não arquive, não marque como lido.

Abre o painel de pedidos, filtra os de ontem, baixa o CSV.
Se cair tela de login ou confirmação de exportação, para e me avisa, e diz onde salvou o arquivo.

Conferir o que o agente fez

Quando a tarefa termina, dá pra avaliar por estes sinais:

• Ele explicou as páginas que visitou e as ações principais?
• O retorno traz coisas verificáveis (títulos, IDs, links, valores, datas)?
• Em tarefa de download, ele deu o caminho local do arquivo?
• Em tarefa que altera ou submete, ele parou antes da confirmação final?
• A página continua aberta no Space para você ir lá conferir?

Se algo parecer estranho, peça um snapshot novo da página atual em vez de deixar o agente continuar especulando sobre a resposta anterior.

Perguntas frequentes

Por que o agente diz que uma ref está inválida?

A página mudou desde o snapshot anterior. Manda ele tirar outro.

O snapshot consegue ler tudo?

Nem sempre. Conteúdo fora da tela, texto dentro de imagem, canvas complexos, iframes cross-origin com restrição podem não aparecer completos. Nesses casos o agente costuma combinar snapshot com screenshot, extração de texto, ou confirmação humana.

O snapshot altera dados?

Não. O snapshot só lê a estrutura da página. Quem altera estado vem depois: cliques, preenchimentos, envios, uploads, exclusões.

Eu preciso decorar @1, @2?

Não. Pense neles como "números temporários da página atual". Quem usa é o agente; sua parte é deixar claro o objetivo e os limites.