Como resolver CAPTCHA com o Vercel Agent Browser – Guia Passo a Passo usando o CapSolver

Quando seu agente de IA bate em um muro de CAPTCHA, todo o fluxo de trabalho quebra. A navegação para, os formulários não podem ser enviados e a extração de dados falha — tudo porque um desafio foi criado para bloquear o acesso automatizado. O Vercel Agent Browser é um CLI rápido e nativo em Rust para automação de navegador sem cabeça, desenvolvido especificamente para agentes de IA. Ele oferece seleção de elementos com foco em acessibilidade, localizadores semânticos e um fluxo de snapshot-ref otimizado para LLMs. Mas, como qualquer ferramenta de automação de navegador, ele fica travado em CAPTCHAs.

O CapSolver muda isso completamente. Carregando a extensão CapSolver Chrome no Agent Browser usando a bandeira interna --extension, os CAPTCHAs são resolvidos automaticamente e invisivelmente em segundo plano. Nenhuma resolução manual. Nenhuma orquestração complexa de API. Seus comandos CLI continuam a executar como se o CAPTCHA nunca tivesse existido.

O melhor? O Agent Browser suporta extensões em modo com e sem cabeça — diferente do Playwright, que exige modo com cabeça para extensões. Isso significa que seus pipelines de produção, fluxos CI/CD e implantações serverless funcionam com zero requisitos de exibição. Seu agente se concentra no que faz melhor — navegar páginas, extrair dados e automatizar fluxos — enquanto o CapSolver lida com CAPTCHAs em silêncio.

O que é Vercel Agent Browser?

Vercel Agent Browser é um CLI de automação de navegador sem cabeça construído em Rust para desempenho máximo. Desenvolvido pelos Vercel Labs, ele fornece uma interface de linha de comando que controla o Chrome sem exigir Playwright ou Node.js para o daemon do navegador. Seu design com foco em acessibilidade usa localizadores semânticos e referências de snapshot — tornando-o a ferramenta ideal para agentes de IA que precisam interagir com páginas da web.

Principais Recursos

• CLI nativo em Rust: Ferramenta rápida, binária única sem dependências de tempo de execução para o daemon do navegador.
• Fluxo de Snapshot-Ref: Obtenha uma árvore de acessibilidade com referências de elemento, depois interaja por referência — determinístico, rápido e amigável para IA.
• Localizadores semânticos: Encontre elementos por papel ARIA, conteúdo de texto, rótulo, dica ou texto alternativo — sem seletores CSS frágeis.
• Suporte a extensões em modo sem cabeça: Carregue extensões do Chrome em modo com e sem cabeça via Chrome's --headless=new.
• Gerenciamento de sessão: Sessões isoladas, perfis persistentes, armazenamento de estado criptografado e cofre de autenticação para gerenciamento de credenciais.
• Modo de saída JSON: Saída legível por máquina para pipelines de agente com --json.
• Fornecedores de nuvem: Suporte integrado para Browserless, Browserbase, Browser Use, Kernel e Simulador iOS.
• Segurança: Listas de permissão de domínio, políticas de ação, limites de conteúdo e portões de confirmação para implantações seguras de agentes de IA.

O Agent Browser funciona em qualquer página — incluindo conteúdo autenticado, SPAs dinâmicos e sites protegidos por CAPTCHA — tornando-o ideal para fluxos de trabalho de agente de IA, coleta de dados e testes automatizados.

O que é CapSolver?

CapSolver é um serviço de resolução de CAPTCHA baseado em IA que resolve automaticamente desafios de CAPTCHA diversos. Com tempos de resposta rápidos e compatibilidade ampla, o CapSolver se integra sem esforço em fluxos automatizados.

Tipos de CAPTCHA Suportados

• reCAPTCHA v2 (checkbox e invisível)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Mais

Por que essa integração é diferente?

A maioria das integrações de resolução de CAPTCHA exige que você escreva código de boilerplate: crie tarefas, faça polling para resultados, injete tokens em campos ocultos. Essa é a abordagem padrão com scripts Playwright ou Puppeteer.

Agent Browser + Extensão CapSolver adota uma abordagem fundamentalmente diferente:

A principal descoberta: A extensão CapSolver roda dentro da instância do Chrome do Agent Browser. Quando o Agent Browser navega para uma página com CAPTCHA, a extensão o detecta, o resolve em segundo plano e injeta o token — tudo antes que seu próximo comando seja executado. Sua automação permanece limpa, focada e livre de CAPTCHA.

Requisitos Prévios

Antes de configurar a integração, certifique-se de ter:

• Vercel Agent Browser instalado (npm install -g agent-browser)
• Conta CapSolver com chave de API (inscreva-se aqui)
• Node.js 16+ (para instalação via npm)

Nota: Ao contrário de ferramentas baseadas em Playwright, o Agent Browser suporta extensões em modo com e sem cabeça. Nenhum Xvfb ou display virtual é necessário em servidores.

Configuração Passo a Passo

Passo 1: Instalar o Agent Browser

npm install -g agent-browser
agent-browser install  # Baixe o Chrome do Chrome for Testing (apenas na primeira vez)

Métodos alternativos de instalação:

# macOS via Homebrew
brew install agent-browser
agent-browser install

# Via Cargo (Rust)
cargo install agent-browser
agent-browser install

No Linux, inclua dependências do sistema:

agent-browser install --with-deps

Passo 2: Baixar a Extensão CapSolver Chrome

Baixe a extensão CapSolver Chrome e extraia-a para um diretório dedicado:

1. Acesse a versão 1.17.0 da extensão CapSolver Chrome
2. Baixe CapSolver.Browser.Extension-chrome-v1.17.0.zip
3. Extraia o zip:

mkdir -p ~/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/capsolver-extension/

4. Verifique se a extração funcionou:

ls ~/capsolver-extension/manifest.json

Você deve ver manifest.json — isso confirma que a extensão está no lugar certo.

Passo 3: Configurar sua Chave de API do CapSolver

Abra o arquivo de configuração da extensão em ~/capsolver-extension/assets/config.js e substitua o valor apiKey pelo seu:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // ← seu chave aqui
  useCapsolver: true,
  // ... restante da configuração
};

Você pode obter sua chave de API em seu painel do CapSolver.

Passo 4: Iniciar o Agent Browser com a Extensão CapSolver

Carregar a extensão é uma única bandeira — --extension:

agent-browser --extension ~/capsolver-extension open https://example.com/protected-page

Pronto. A extensão CapSolver agora está ativa dentro do navegador e resolverá automaticamente qualquer CAPTCHA que encontrar.

Para modo com cabeça (para ver visualmente o navegador):

agent-browser --extension ~/capsolver-extension --headed open https://example.com/protected-page

Passo 5: Verificar se a Extensão foi Carregada

No modo com cabeça, navegue até chrome://extensions para ver a extensão CapSolver listada e ativada:

agent-browser --extension ~/capsolver-extension --headed open chrome://extensions

No modo sem cabeça, verifique o console do navegador para mensagens de log do CapSolver:

agent-browser --extension ~/capsolver-extension open https://example.com
agent-browser console

Como Usar

Após a configuração, usar o CapSolver com o Agent Browser é simples — basta adicionar a bandeira --extension e um comando de espera.

A Regra Dourada

Não escreva lógica específica para CAPTCHA. Basta adicionar uma espera após navegar para páginas protegidas por CAPTCHA e deixe a extensão fazer seu trabalho.

Exemplo 1: Submissão de Formulário atrás de reCAPTCHA

# Navegue até a página com a extensão CapSolver carregada
agent-browser --extension ~/capsolver-extension open https://example.com/contact

# Obtenha um snapshot para descobrir elementos do formulário
agent-browser snapshot -i
# Saída:
# - caixa de texto "Nome" [ref=e1]
# - caixa de texto "Email" [ref=e2]
# - caixa de texto "Mensagem" [ref=e3]
# - botão "Enviar" [ref=e4]

# Preencha o formulário
agent-browser fill @e1 "John Doe"
agent-browser fill @e2 "[email protected]"
agent-browser fill @e3 "Olá, tenho uma pergunta sobre seus serviços."

# Espere a CapSolver resolver o CAPTCHA
agent-browser wait 30000

# Enviar — o token do CAPTCHA já foi injetado
agent-browser click @e4

Exemplo 2: Página de Login com Cloudflare Turnstile

# Navegue até a página de login
agent-browser --extension ~/capsolver-extension open https://example.com/login

# Obtenha elementos interativos
agent-browser snapshot -i

# Preencha as credenciais
agent-browser find label "Email" fill "[email protected]"
agent-browser find label "Senha" fill "mypassword123"

# Espere o Turnstile ser resolvido
agent-browser wait 20000

# Clique em login — Turnstile já foi tratado
agent-browser find role button click --name "Entrar"

Exemplo 3: Extração de Dados de Páginas Protegidas

# Navegue até a página protegida
agent-browser --extension ~/capsolver-extension open https://example.com/data

# Espere que qualquer desafio de CAPTCHA seja resolvido
agent-browser wait 30000

# Extraia o conteúdo da página usando snapshot
agent-browser snapshot --json

# Ou obtenha o texto de um elemento específico
agent-browser get text "body"

Exemplo 4: Comandos Encadeados (Linha Única)

O Agent Browser suporta encadeamento de comandos para automação eficiente:

# Abra, espere pelo CAPTCHA, preencha o formulário e envie — tudo em uma linha
agent-browser --extension ~/capsolver-extension open https://example.com/contact && \
  agent-browser wait 30000 && \
  agent-browser snapshot -i && \
  agent-browser fill @e1 "John Doe" && \
  agent-browser fill @e2 "[email protected]" && \
  agent-browser click @e3

Exemplo 5: Fluxo de Trabalho com Saída JSON

Para pipelines de agentes de IA, use --json para saída legível por máquina:

#!/bin/bash
EXTENSION=~/capsolver-extension

# Abra a página com a extensão
agent-browser --extension "$EXTENSION" open https://example.com/protected

# Espere pelo CAPTCHA ser resolvido
agent-browser wait 30000

# Obtenha o snapshot como JSON para processamento de IA
SNAPSHOT=$(agent-browser snapshot -i --json)

# Analise as referências e interaja
agent-browser click @e2
agent-browser get text "body" --json

Tempos Recomendados de Espera

Dica: Se houver dúvida, use 30 segundos. É melhor esperar um pouco mais do que enviar cedo demais. O tempo extra não afeta o resultado.

Como Funciona em Segundo Plano

Aqui está o que acontece quando o Agent Browser é executado com a extensão CapSolver carregada:

Seus Comandos do Agent Browser
───────────────────────────────────────────────────
agent-browser --extension       ──► Chrome inicia com extensão
  ~/capsolver-extension
  open https://...
                                           │
                                           ▼
                               ┌─────────────────────────────┐
                               │  Página com widget CAPTCHA     │
                               │                               │
                               │  Extensão CapSolver:         │
                               │  1. Script de conteúdo detecta │
                               │     CAPTCHA na página         │
                               │  2. Worker de serviço chama   │
                               │     API CapSolver             │
                               │  3. Token recebido            │
                               │  4. Token injetado em campo   │
                               │     oculto                    │
                               └─────────────────────────────┘
                                           │
                                           ▼
agent-browser wait 30000         Extensão resolve CAPTCHA...
                                           │
                                           ▼
agent-browser snapshot -i        Agent Browser lê elementos
agent-browser click @e2          Formulário é enviado COM token válido
                                           │
                                           ▼
                               "Verificação bem-sucedida!"

Como a Extensão é Carregada

Quando o Agent Browser inicia o Chrome com a bandeira --extension:

1. O Chrome inicia com a extensão CapSolver carregada (usando --headless=new no modo sem cabeça, que suporta extensões Manifest V3)
2. A extensão é ativada — seu worker de serviço começa e scripts de conteúdo são injetados em cada página
3. Em páginas com CAPTCHAs — o script de conteúdo detecta o widget, chama a API CapSolver e injeta o token de solução na página
4. O Agent Browser opera normalmente — snapshots, cliques e extração de dados funcionam como de costume, com CAPTCHAs já resolvidos

Referência de Configuração Completa

Aqui está uma configuração completa com todas as opções de configuração para a integração Agent Browser + CapSolver:

Flags da CLI

agent-browser \
  --extension ~/capsolver-extension \
  --headed \
  --session-name my-session \
  open https://example.com

Variáveis de Ambiente

# Defina o caminho da extensão como variável de ambiente (evita repetir a bandeira --extension)
export AGENT_BROWSER_EXTENSIONS=~/capsolver-extension

# Agora, todos os comandos carregam automaticamente a extensão
agent-browser open https://example.com
agent-browser wait 30000
agent-browser snapshot -i

Arquivo de Configuração (agent-browser.json)

Crie um agent-browser.json no seu diretório de projeto para padrões persistentes:

{
  "extension": ["~/capsolver-extension"],
  "sessionName": "my-project",
  "headed": false
}

Opções de Configuração

Solução de Problemas

Extensão Não Carregando

Sintoma: CAPTCHAs não estão sendo resolvidos automaticamente.

Causas possíveis:

• Caminho da extensão incorreto — certifique-se de que manifest.json existe no diretório especificado
• Extensão não compatível — use a versão do Chrome da extensão CapSolver (não o Firefox)

Solução: Verifique o caminho e confirme que a extensão carrega:

# Verifique se o manifesto existe
ls ~/capsolver-extension/manifest.json

# Teste no modo com interface para confirmar visualmente
agent-browser --extension ~/capsolver-extension --headed open chrome://extensions

CAPTCHA Não Resolvido (Formulário Falha)

Causas possíveis:

• Tempo de espera insuficiente — aumente para 60 segundos
• Chave da API inválida — verifique seu painel do CapSolver
• Saldo insuficiente — faça um recarregamento em sua conta do CapSolver
• Extensão não carregada — veja "Extensão Não Carregando" acima

Depuração com logs do console:

agent-browser --extension ~/capsolver-extension open https://example.com
agent-browser wait 30000
agent-browser console  # Verifique mensagens do CapSolver

Chrome Não Encontrado

Sintoma: agent-browser não consegue encontrar um executável do Chrome.

Solução: Execute o comando de instalação para baixar o Chrome para Testes:

agent-browser install

Ou aponte para um executável personalizado do Chrome:

agent-browser --executable-path /caminho/para/chrome open https://example.com

Múltiplas Extensões

Você pode carregar múltiplas extensões repetindo a flag --extension:

agent-browser \
  --extension ~/capsolver-extension \
  --extension ~/outra-extensão \
  open https://example.com

Boas Práticas

1. Use a variável de ambiente AGENT_BROWSER_EXTENSIONS. Defina-a uma vez no seu perfil de shell ou configuração CI, e todos os comandos agent-browser carregam automaticamente o CapSolver sem repetir a flag.

2. Sempre use tempos de espera generosos. Mais tempo de espera é sempre mais seguro. O CAPTCHA geralmente se resolve em 5-20 segundos, mas latência de rede, desafios complexos ou tentativas podem adicionar tempo. 30-60 segundos é o ponto ideal.

3. Mantenha seus scripts de automação limpos. Não adicione lógica específica para CAPTCHA aos seus comandos. A extensão cuida de tudo — seus scripts devem se concentrar apenas em navegação, interação e extração de dados.

4. Monitore seu saldo do CapSolver. Cada resolução de CAPTCHA custa créditos. Verifique seu saldo em capsolver.com/dashboard regularmente para evitar interrupções.

5. Use persistência de sessão para visitas repetidas. Use --session-name ou --profile para preservar cookies entre execuções. Isso pode reduzir a frequência de CAPTCHA, já que o site pode reconhecer sessões retornando.

6. Aproveite o modo headless em produção. Ao contrário do Playwright, o Agent Browser suporta extensões no modo headless. Não é necessário Xvfb ou displays virtuais em servidores — basta executar seus comandos diretamente.

Conclusão

A integração do Vercel Agent Browser + CapSolver traz a resolução de CAPTCHA invisível para a CLI de automação de navegador mais rápida e otimizada com IA disponível. Em vez de escrever código complexo para lidar com CAPTCHA, você simplesmente:

1. Baixe a extensão CapSolver e configure sua chave da API
2. Adicione --extension ~/capsolver-extension aos seus comandos do Agent Browser
3. Adicione um comando de espera antes de interagir com formulários protegidos por CAPTCHA

A extensão Chrome do CapSolver cuida do restante — detectando CAPTCHAs, resolvendo-os via API do CapSolver e injetando tokens na página. Seus comandos do Agent Browser nunca precisam saber sobre CAPTCHAs de forma alguma.

E, ao contrário de soluções baseadas no Playwright que exigem modo com interface e displays virtuais, o Agent Browser suporta extensões no modo headless de forma nativa — tornando o caminho mais simples para automação sem CAPTCHA em produção.

Pronto para começar? Registre-se no CapSolver e use o código de bônus AGENTBROWSER para obter 6% extras em seu primeiro recarregamento!

Perguntas Frequentes

Preciso escrever código específico para CAPTCHA?

Não. A extensão CapSolver funciona totalmente em segundo plano dentro da instância do Chrome do Agent Browser. Basta adicionar agent-browser wait 30000 antes de enviar formulários, e a extensão cuida automaticamente da detecção, resolução e injeção de tokens.

Posso executar isso no modo headless?

Sim! Essa é uma vantagem principal em comparação com soluções baseadas no Playwright. O Agent Browser usa o modo --headless=new do Chrome, que suporta extensões do Manifest V3. Nenhum Xvfb ou display virtual é necessário.

Preciso do Playwright ou Node.js?

Não. O Agent Browser é um binário Rust autônomo. Você só precisa do Node.js para a etapa npm install. O daemon do navegador roda nativamente sem nenhum runtime JavaScript.

Quais tipos de CAPTCHA o CapSolver suporta?

O CapSolver suporta reCAPTCHA v2 (checkbox e invisível), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA e mais. A extensão detecta automaticamente o tipo de CAPTCHA e o resolve conforme necessário.

Quanto custa o CapSolver?

O CapSolver oferece preços competitivos com base no tipo de CAPTCHA e volume. Visite capsolver.com para ver os preços atuais.

O Vercel Agent Browser é gratuito?

Sim. O Agent Browser é de código aberto sob a licença Apache 2.0. A CLI e todas as funcionalidades são gratuitas para uso. Visite o repositório do GitHub para mais detalhes.

Quanto tempo devo esperar para o CAPTCHA ser resolvido?

Para a maioria dos CAPTCHAs, 30-60 segundos é suficiente. O tempo real de resolução geralmente é de 5-20 segundos, mas adicionar um buffer extra garante confiabilidade. Quando em dúvida, use 30 segundos com agent-browser wait 30000.

Posso usar isso com agentes de IA?

Absolutamente. O Agent Browser foi criado especificamente para agentes de IA (existem algumas opções para comparar). Use --json para saída legível por máquina, o fluxo de trabalho de snapshot-ref para seleção de elementos determinística e a cadeia de comandos para automação de etapas múltiplas eficiente. A extensão CapSolver roda junto aos comandos do seu agente de forma transparente.