Nota do autor: da instalação à validação dos resultados, passando por snapshot e operações com ref, aprenda em 5 passos o ciclo do agent-browser de “ler a página, clicar em um elemento e ler a página novamente” para que um AI Agent controle um navegador real de forma confiável.
Um dos desafios mais comuns ao fazer um AI Agent operar páginas web é que ele não consegue vê-las e tem dificuldade para clicar nos elementos certos com consistência. Usar capturas de tela e cliques por coordenadas consome muitos tokens e ainda pode levar a cliques no lugar errado. Já entregar o HTML inteiro ao modelo esgota rapidamente a janela de contexto. Neste artigo, você vai conhecer o ciclo de operação snapshot-ref do agent-browser e aprender a fazer um Agent controlar o navegador “um comando por vez”.
Este não é mais um artigo conceitual sobre frameworks de automação de navegador. Vamos seguir a ordem de uso na prática: instalação do agent-browser, combinação de snapshot e ref, estratégias para tentar novamente após falhas e integração ao fluxo de trabalho do Agent.
O que você vai aprender: por que o ciclo snapshot-ref do agent-browser funciona bem com Modelos de Linguagem Grande e como executar sua primeira tarefa no navegador com 5 comandos no seu próprio Agent.
Pontos principais do ciclo snapshot-ref do agent-browser
O agent-browser é uma ferramenta de automação de navegador de código aberto criada pela Vercel Labs, sob a licença Apache-2.0. É uma CLI nativa em Rust com um objetivo claro: dar a um Agent de IA um navegador que possa ser controlado por comandos individuais. Depois de abrir uma página, o Agent a lê como um texto compacto em formato de árvore de acessibilidade (accessibility tree) e, em seguida, executa operações nos elementos por meio de comandos shell.
| Ponto principal | Descrição | Valor para o Agent |
|---|---|---|
| Texto compacto do snapshot | A página é apresentada como uma árvore de acessibilidade, com uma ref como @e1 para cada elemento |
Consome menos contexto do que capturas de tela e HTML bruto |
| Localização precisa por ref | Os comandos de operação fazem referência direta à ref, como em click @e1 |
O modelo não precisa montar seletores CSS por conta própria |
| Navegador persistente | Um processo em segundo plano mantém o navegador aberto | Cada etapa exige apenas uma chamada curta ao shell |
| Erros explícitos | Se um elemento estiver obstruído, oculto ou desativado, o clique falha em vez de indicar um sucesso falso | O Agent pode decidir o próximo passo com base no feedback real |
| Skills integradas | A CLI inclui instruções de uso compatíveis com sua versão | As instruções que o Agent lê correspondem à versão instalada |
Como funciona o ciclo snapshot-ref
Esse ciclo pode ser resumido em três ações: primeiro, usar snapshot para ler a página; depois, executar uma ação em um ref; por fim, ler a página novamente para confirmar o resultado. E repetir. O snapshot de example.com mostrado na documentação oficial tem apenas uma linha: - link "Learn more" [ref=e1]. Ao ver essa linha, o modelo sabe que há um link chamado Learn more na página e que pode usar @e1 para clicar nele.
Esse design separa a compreensão da página e a execução de ações em duas etapas verificáveis, o que combina bem com a forma como um Modelo de Linguagem Grande usa ferramentas. O modelo não precisa entender uma estrutura DOM complexa: basta encontrar o elemento correto pelo significado no texto e usar o ref correspondente. Tirar um novo snapshot após cada ação também permite que o Agent tome decisões com base no estado mais recente da página, em vez de depender da memória para adivinhar.
A arquitetura interna do agent-browser
A CLI não controla o navegador diretamente. Quando o primeiro comando é executado, ela inicia um processo em segundo plano (daemon), que controla o navegador por meio do Chrome DevTools Protocol. Todos os comandos posteriores da CLI são enviados a esse daemon. Assim, o navegador permanece aberto entre os comandos, sem perder o estado de login nem a posição na página.
Cada --session tem seu próprio daemon e navegador, o que permite executar várias tarefas em paralelo sem interferência entre elas. Por padrão, o navegador headless é fechado após uma hora sem receber comandos, e o daemon também é encerrado. Se a persistência de sessão (session persistence) estiver configurada, o estado será salvo antes do encerramento.
O “cérebro” que impulsiona esse ciclo é um Modelo de Linguagem Grande. A cada rodada, o texto do snapshot entra no contexto do modelo, que decide qual será o próximo comando. Por isso, a capacidade do modelo de seguir instruções e seu preço unitário afetam diretamente a taxa de sucesso e o custo das tarefas. A APIYI oferece acesso via API aos modelos mencionados neste artigo, como Claude, DeepSeek e Kimi, com compatibilidade com os formatos de interface da OpenAI e da Anthropic. A documentação de integração está em docs.apiyi.com.
Primeiros passos com agent-browser: o ciclo snapshot-ref em 5 etapas
Etapa 1: instalar o agent-browser e o navegador
A forma mais comum é fazer a instalação global via npm e depois baixar o Chrome for Testing. O pacote npm seleciona automaticamente o binário nativo correspondente à plataforma: macOS (ARM64, x64), Linux (ARM64, x64, glibc e musl) ou Windows (x64).
| Método de instalação | Comando | Quando usar |
|---|---|---|
| Instalação global via npm | Primeiro npm install -g agent-browser, depois agent-browser install |
Maioria dos ambientes de desenvolvimento; o navegador precisa ser baixado na primeira instalação |
| Homebrew | Primeiro brew install agent-browser, depois agent-browser install |
Usuários de macOS |
| Linux com dependências | agent-browser install --with-deps |
Servidores e contêineres que também precisam das bibliotecas de sistema do navegador |
| Sem instalação | npx agent-browser open example.com |
Testes rápidos e tarefas pontuais em CI |
| Comandos de manutenção | agent-browser upgrade, agent-browser doctor |
Atualizar a versão e diagnosticar problemas no ambiente |
Para compilar a partir do código-fonte, a documentação oficial exige Node.js 24 ou superior, pnpm 11 ou superior e o conjunto de ferramentas Rust. Execute pnpm install, pnpm build:source e pnpm link --global nessa ordem. Por fim, rode agent-browser install. Para o uso diário, a instalação via npm é suficiente.
Etapas 2 a 5: o ciclo mínimo completo
Após a instalação, o conjunto de comandos abaixo forma um ciclo completo de snapshot-ref. Vale a pena executá-lo primeiro no terminal, conferindo a saída de cada etapa, antes de deixar o Agent executá-lo automaticamente.
| Etapa | Comando | Função | Resultado esperado |
|---|---|---|---|
| 2. Abrir a página | agent-browser open example.com |
Inicia o processo em segundo plano e abre o endereço | Navegador permanece ativo em segundo plano |
| 3. Ler o snapshot | agent-browser snapshot -i |
Lista apenas elementos interativos, cada um com um ref | Saída como link "Learn more" [ref=e1] |
| 4. Operar o ref | agent-browser click @e1 |
Clica em um elemento do snapshot | A página muda ou seu estado é alterado |
| 5. Verificar o resultado | agent-browser get url |
Lê a URL atual para confirmar que a ação funcionou | Retorna o endereço após o redirecionamento |
| Finalizar | agent-browser close |
Fecha o navegador | Libera os recursos |
O parâmetro -i da etapa 3 é essencial: ele mostra apenas os elementos interativos, reduzindo bastante o texto do snapshot. Isso é especialmente útil quando o orçamento de tokens é limitado. A verificação da etapa 5 também não deve ser pulada. O Agent precisa usar o retorno real para determinar se a operação funcionou, em vez de presumir que clicar já significa sucesso.
🚀 Início rápido: depois de testar o ciclo manual, você pode passar esses comandos para o Agent. Uma boa opção é obter créditos de teste no APIYI apiyi.com e experimentar alguns modelos com as mesmas tarefas, observando quais conseguem identificar melhor o ref correto no texto do snapshot. A interface é compatível com os formatos da OpenAI e da Anthropic; na maioria dos frameworks de Agent existentes, basta trocar a chave e o endereço. Consulte a documentação em docs.apiyi.com para mais detalhes.
Validade dos refs do agent-browser e novos snapshots
Um ref descreve a página no momento em que o snapshot foi tirado. Se houver uma navegação ou alteração no DOM, o ref antigo pode deixar de funcionar ou até apontar para o elemento errado. Por isso, a regra é: após cada navegação ou mudança significativa na página, execute snapshot novamente antes de usar um novo ref.
Vale incluir essa regra diretamente no comando de sistema do Agent. Um ciclo confiável é “snapshot, ação, snapshot”, e não “um snapshot seguido de dez ações”. O custo de um snapshot extra é muito menor que o de investigar e reverter um clique no elemento errado.
Como lidar com falhas de clique no agent-browser
O agent-browser não “finge que deu certo” ao clicar. Se o elemento estiver oculto, desabilitado, fora da área visível ou encoberto por outro elemento, como uma janela de consentimento de cookies, o click retornará uma falha. Isso é útil para o Agent, pois a própria mensagem de erro ajuda a decidir o próximo passo.
| Causa da falha | Situação típica | Tratamento recomendado |
|---|---|---|
| Elemento encoberto | Uma janela de consentimento ou camada flutuante cobre o botão | Feche o elemento que está cobrindo o botão, tire um novo snapshot e tente novamente |
| Fora da área visível | O elemento está mais abaixo na página | Role a página com scroll e tire um novo snapshot |
| Elemento desabilitado | O botão não pode ser clicado porque o formulário está incompleto | Preencha os campos obrigatórios com fill e confirme com um novo snapshot |
| Elemento oculto | É preciso expandir um menu para exibi-lo | Clique para expandir, aguarde com wait e tire um snapshot |
| Ref expirado | A página foi atualizada ou houve uma navegação | Execute snapshot novamente para obter um novo ref |
Além de refs, o agent-browser aceita seletores CSS, texto, XPath e localizadores semânticos. Por exemplo, agent-browser find role button click --name "Submit" encontra e clica no botão de envio usando seu papel e nome. Quando a estrutura da página é estável e os elementos têm semântica clara, localizadores semânticos podem complementar o uso de refs.
Grupos de comandos comuns do agent-browser
O agent-browser oferece uma ampla variedade de comandos. Para ver a lista completa, use agent-browser --help. Para consultar um comando específico, use agent-browser <command> --help. Abaixo, os comandos mais comuns estão agrupados por finalidade para ajudar você a decidir quais recursos disponibilizar ao Agent.
| Grupo | Comandos representativos | Usos comuns |
|---|---|---|
| Navegação e leitura | open、back、reload、read、snapshot、get、is |
Abrir páginas, ler snapshots e consultar estados |
| Interação | click、fill、type、press、select、check、scroll、upload、find |
Clicar, preencher formulários e enviar arquivos |
| Espera | wait |
Esperar um elemento aparecer ou uma página carregar |
| Captura | screenshot、pdf、record、download、diff |
Tirar capturas de tela, exportar PDFs, gravar a tela e comparar páginas |
| Estado da página e da rede | cookies、storage、network、eval |
Gerenciar cookies, interceptar tráfego de rede e executar scripts |
| Abas e janelas pop-up | tab、frame、dialog |
Trabalhar com várias abas, iframes e caixas de diálogo |
| Depuração e desempenho | console、errors、trace、vitals、a11y |
Coletar erros do console e métricas de desempenho |
| Sessão e autenticação | session、state、auth、confirm、deny |
Isolar sessões, gerenciar o estado de login e confirmar operações sensíveis |
| Integração com Agent | skills、mcp、flow、batch、plugin |
Carregar habilidades e iniciar serviços MCP |
Quanto ao mecanismo de navegador, o padrão é o Chrome for Testing. Você também pode usar --cdp ou --auto-connect para se conectar a uma instância do Chrome em execução, usar --engine para alternar para o Lightpanda ou o Obscura, controlar o Mobile Safari em um simulador de iOS ou integrar serviços de navegador na nuvem como Browserbase, Browserless, Browser Use, Kernel e AgentCore.
Como integrar o agent-browser a um AI Agent
Ensine o Agent com as skills integradas
Um detalhe interessante do agent-browser é que as instruções de uso são distribuídas junto com a CLI. Ao executar agent-browser skills get core, você recebe o ciclo principal, o uso de refs, as estratégias de espera e os fluxos de trabalho mais comuns. Adicione --ref commands para consultar uma referência específica, como a lista completa de comandos, ou --full para incluir a referência completa e os templates. O comando agent-browser skills list também lista skills especializadas, como electron, slack e dogfood.
Em um framework de Agent, você pode instalar a skill de descoberta com npx skills add vercel-labs/agent-browser. Ela funciona apenas como uma orientação inicial e instrui o Agent a carregar agent-browser skills get core. Assim, as instruções ficam sempre alinhadas à versão instalada da CLI. Se preferir não instalar a skill, você também pode incluir uma linha no AGENTS.md: use o agent-browser para automação de navegador e, antes do primeiro uso, execute agent-browser skills get core e siga as instruções.
Integração via MCP
Se o seu cliente for compatível com MCP, execute agent-browser mcp para iniciar um servidor MCP via stdio. Assim, clientes desktop como o Claude ou Agents desenvolvidos internamente podem invocar operações do navegador como ferramentas padrão, sem precisar implementar uma camada própria de execução de comandos shell.
Escolha do modelo para o ciclo snapshot-ref
Tarefas no navegador costumam ter muitas rodadas, cada uma com um trecho de texto do snapshot. Por isso, a proporção de tokens de entrada geralmente é muito maior que a de saída. Ao escolher um modelo, além da capacidade de seguir instruções, vale prestar atenção ao preço de entrada e ao preço de cache. Os preços da tabela abaixo seguem os dados reais da página de preços da APIYI, docs.apiyi.com/models; consulte a página para conferir as unidades e os critérios de cobrança.
| Modelo | Preço de entrada | Preço de saída | Preço de cache | Uso recomendado | Plataforma disponível |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | Tarefas complexas com várias etapas e páginas problemáticas | APIYI apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | Modelo principal para tarefas do dia a dia | APIYI apiyi.com |
| kimi-k3.1-pro | $2 | $10 | $0.2 | Páginas em chinês | APIYI apiyi.com |
| deepseek-v4.1-flash | $0.3 | $1.2 | $0.006 | Formulários simples e verificações em lote | APIYI apiyi.com |
Uma combinação prática é usar o deepseek-v4.1-flash para tarefas em lote com estrutura simples e etapas fixas, deixar o claude-sonnet-5-5 como modelo principal de uso geral e recorrer ao claude-opus-5-5 para interações complexas ou páginas com falhas frequentes. Como o texto das skills e o comando de sistema se repetem a cada rodada, modelos com preço de cache menor oferecem uma vantagem de custo em ciclos longos.
Vale observar que a série ERNIE, da Wenxin, ainda não aparece na tabela de preços da APIYI. A APIYI ainda não disponibiliza esse modelo, mas ele será lançado em breve. Se o seu Agent depende do ERNIE, você pode testar provisoriamente uma alternativa entre os modelos da tabela.
💡 Sugestão de escolha: nenhum modelo é o melhor em todos os sites. Escolha de 3 a 5 páginas reais do seu negócio para um teste em pequena escala. Na APIYI apiyi.com, alterne entre modelos usando uma interface unificada e compare a taxa de sucesso e o custo por tarefa antes de definir o modelo principal.
Recomendações de segurança para usar o agent-browser
Ao permitir que um agente opere um navegador real, é essencial definir os limites de segurança com antecedência. A seção de segurança da documentação oficial do agent-browser apresenta recursos como cofre de autenticação (auth vault), lista de domínios permitidos, políticas de ação e limites de conteúdo. Nos comandos, auth gerencia as credenciais de login, enquanto confirm e deny permitem confirmar ou recusar ações sensíveis.
Em produção, recomenda-se adotar pelo menos três medidas:
- Limitar os domínios acessíveis: use uma lista de domínios permitidos para restringir o agente aos sites relevantes para a operação e evitar que ele seja induzido a acessar sites desconhecidos.
- Manter credenciais fora do contexto: guarde logins e senhas no auth vault, em vez de colocá-los no comando, para evitar que apareçam nos logs do modelo.
- Exigir confirmação humana para ações sensíveis: configure operações como pagamentos, exclusões e envio de pedidos para exigir confirmação, deixando a decisão final nas mãos de uma pessoa.
O próprio conteúdo das páginas também pode conter instruções maliciosas direcionadas ao agente, por isso vale ativar o mecanismo de limites de conteúdo. Ele ajuda o modelo a distinguir claramente o texto da página das instruções do usuário, reduzindo o risco de injeção de comandos.
Perguntas frequentes (FAQ)
Q1: O que é o ciclo snapshot-ref do agent-browser?
É a forma central de funcionamento do agent-browser: primeiro, ele usa `snapshot` para ler a página como um texto compacto com refs; depois, executa uma ação em um ref e faz um novo snapshot para confirmar o resultado. Esse ciclo se repete, dividindo a compreensão da página e a execução de ações em pequenas etapas verificáveis, o que favorece o raciocínio passo a passo de um Modelo de Linguagem Grande.
Q2: Qual é a diferença entre o agent-browser e um Agent de navegador que usa capturas de tela?
As capturas de tela são mais versáteis para a compreensão visual, mas consomem muitos tokens, e os cliques por coordenadas podem errar o alvo. Já o agent-browser usa o texto da árvore de acessibilidade e refs para localizar elementos. Assim, o contexto fica mais compacto, as ações são mais precisas e os erros são informados claramente, o que o torna mais adequado para tarefas de automação que exigem execução estável.
Q3: Por que não é possível continuar usando um ref antigo depois de navegar para outra página?
Um ref descreve a página apenas no momento em que o snapshot foi feito. Depois de uma navegação ou alteração no DOM, o elemento pode ter desaparecido ou sido substituído. Nesse caso, o ref antigo pode deixar de funcionar ou apontar para o elemento errado. O correto é executar `snapshot` novamente após cada alteração na página e usar os novos refs.
Q4: Para quais aplicações o agent-browser é adequado?
Ele é especialmente útil nos seguintes cenários:
– **Preenchimento automático de formulários**: processos com etapas fixas, como cadastros, inscrições e entrada de dados em sistemas administrativos.
– **Inspeção de sites e testes de regressão**: uso de `errors`, `console` e `vitals` para verificar erros e desempenho das páginas.
– **Coleta de informações**: leitura de dados página por página, seguindo os menus após fazer login em um sistema administrativo.
– **Cenários específicos, como Electron e Slack**: extensão por meio das habilidades especializadas disponíveis em `skills list`.
Q5: Como integrar o modelo que controla o agent-browser?
Siga estas etapas:
1. Acesse APIYI em apiyi.com, crie uma conta e obtenha uma chave API.
2. No framework do Agent, escolha um formato compatível com OpenAI ou Anthropic e preencha os parâmetros de integração conforme a documentação em docs.apiyi.com.
3. Use o ciclo de 5 etapas deste artigo como tarefa de teste e compare o desempenho dos modelos.
A APIYI oferece acesso unificado a vários modelos, incluindo Claude, DeepSeek e Kimi. Para trocar de modelo, basta alterar seu nome.
Q6: Como estimar o custo do modelo para executar o ciclo snapshot-ref?
As tarefas no navegador consomem principalmente tokens de entrada, pois cada rodada inclui o texto do snapshot e o comando de sistema. Para estimar o custo, observe o preço dos tokens de entrada e do cache e procure usar `snapshot -i` para reduzir o tamanho dos snapshots. Consulte os preços atuais de cada modelo na página da APIYI em docs.apiyi.com/models, em vez de usar cotações desatualizadas de terceiros.
Q7: Quais são as limitações conhecidas do agent-browser?
Como os refs têm validade limitada, o Agent precisa gerar novos snapshots com frequência, aumentando o número de rodadas. Em páginas com muitas informações de acessibilidade ausentes, o snapshot pode ficar incompleto. Nesses casos, é preciso recorrer a seletores CSS, XPath ou capturas de tela. Além disso, o navegador em modo headless é fechado automaticamente após uma hora de inatividade; tarefas longas precisam de persistência de sessão configurada.
Principais pontos do snapshot-ref no agent-browser
- Definição: agent-browser é uma CLI em Rust de código aberto da Vercel Labs que permite a um agente controlar o navegador comando por comando.
- Ciclo principal: ler a página com um snapshot, executar uma ação usando um ref e fazer outro snapshot para verificar o resultado. Depois, repetir.
- Regra de ouro dos refs: após uma navegação ou alteração no DOM, faça um novo snapshot antes de usar os refs.
- Falhas são sinais: clicar em um elemento encoberto ou desabilitado gera um erro. O agente deve resolver o problema antes de tentar novamente.
- Integração: use
skills get corepara carregar instruções compatíveis com a versão instalada ouagent-browser mcppara integrar um cliente MCP. - Segurança em primeiro lugar: em produção, ative uma lista de domínios permitidos, o auth vault e a confirmação de operações sensíveis.
- Escolha do modelo: compare modelos que controlam o agente pela interface unificada da APIYI, em apiyi.com. Consulte os preços em docs.apiyi.com/models.
Resumo
Os pontos centrais do ciclo snapshot-ref no agent-browser são:
- Use texto em vez de capturas de tela: snapshots da árvore de acessibilidade com refs ajudam o modelo a entender a página usando o mínimo de contexto.
- Verifique a cada passo: leia a página ou a URL após cada ação para evitar que o agente continue em um estado incorreto.
- Trate as falhas: há caminhos claros para lidar com elementos encobertos ou desabilitados, problemas de área visível e refs expirados.
- Integre rapidamente: instalação via npm, skills integradas e servidor MCP são três formas de conectar a ferramenta a um agente existente.
Comece executando manualmente no terminal os cinco comandos open, snapshot, click, get e close. Depois, inclua as regras do ciclo no comando de sistema do agente e escolha o modelo que o controla com base em testes em páginas reais da sua operação.
Para testar rapidamente como diferentes modelos controlam o agent-browser, experimente a APIYI em apiyi.com. A plataforma é compatível com os formatos de interface da OpenAI e da Anthropic. As instruções de integração estão em docs.apiyi.com, e os preços dos modelos, em docs.apiyi.com/models.
📚 Referências
- GitHub – agent-browser: repositório oficial de código aberto
- Link:
github.com/vercel-labs/agent-browser -
Descrição: inclui instruções de instalação, guia rápido, grupos de comandos e orientações de desenvolvimento
-
Documentação oficial do agent-browser: guia completo e referência de comandos
- Link:
agent-browser.dev -
Descrição: aborda snapshots, seletores, sessões, modo CDP e mecanismos de segurança
-
Documentação de segurança do agent-browser: autenticação e controle de acesso
- Link:
agent-browser.dev/security -
Descrição: apresenta o auth vault, a lista de domínios permitidos, as políticas de operação e os limites de conteúdo
-
Central de documentação da APIYI: instruções de integração com modelos
- Link:
docs.apiyi.com -
Descrição: métodos de integração com os formatos compatíveis com OpenAI e Anthropic
-
Página de preços dos modelos da APIYI: valores cobrados por modelo
- Link:
docs.apiyi.com/models - Descrição: todos os preços de modelos neste artigo seguem os valores dessa página
Autor: Equipe técnica da APIYI
Troca de ideias sobre tecnologia: entre em contato conosco pela página inicial da APIYI em apiyi.com. Para mais informações sobre integração, acesse a central de documentação em docs.apiyi.com
