Como Configurar um Navegador de Agente Completo: Um Guia Completo para Instalar a Habilidade de Navegação para Scraping em 5 Principais Agentes de IA

Principais Conclusões

• Uma habilidade, cinco agentes. Claude Code, Cursor, VS Code + Copilot, Codex CLI e Gemini CLI leem o mesmo formato SKILL.md + frontmatter YAML de um pequeno conjunto de diretórios convencionais.
• Um CLI subjacente. Um único npm install -g scrapeless-scraping-browser e uma única chave de API do Scrapeless alimentam a habilidade em todos os agentes.
• Um token, qualquer agente. Configure a chave da API uma vez com scrapeless-scraping-browser config set apiKey … — qualquer agente que chamar o CLI lê a mesma chave armazenada.
• Um navegador de agentes construído para a web. O Scraping Browser é projetado para páginas dinâmicas, interação com o navegador, fricção CAPTCHA, roteamento de proxy e automação de grau de produção onde um navegador normal ou um scraper estático não é suficiente. O Scraping Browser resolve reCAPTCHA v2, Cloudflare Turnstile, Cloudflare 5s Challenge e AWS Challenge de forma nativa — sem configurações extras.
• Melhor para casos de uso reais de agentes. Isso é especialmente útil quando seu agente precisa inspecionar painéis, navegar por fluxos de várias etapas, preencher formulários, coletar dados estruturados ou operar em sites com layouts em mudança.

Introdução: Habilidades de Agentes São o Novo Alvo de Instalação

Agentes de IA estão se movendo além da simples geração de texto e entrando na execução web real. Nesse deslocamento, o navegador não é mais apenas uma superfície de exibição; ele se torna a camada operacional onde um agente observa páginas, raciocina sobre o estado e toma ações em sites. É por isso que o termo navegador agentico é importante: ele descreve um ambiente de navegador que pode realizar tarefas em várias etapas com um grau de autonomia, em vez de esperar que um humano clique em cada etapa.

Agentes de codificação de IA modernos — Claude Code, Cursor, VS Code + GitHub Copilot, OpenAI Codex CLI e Gemini CLI — todos suportam habilidades de agentes: pacotes que ensinam a um agente uma nova capacidade sob demanda. O ecossistema convergiu para um único formato de embalagem (SKILL.md com frontmatter YAML), de modo que a mesma pasta de habilidade funcione em todos os agentes acima com ajustes mínimos.

É também aqui que o Scrapeless se encaixa naturalmente. O scrapeless-Agent-browser está posicionado como a ponte entre a lógica do agente e a execução confiável do navegador, permitindo que o agente dirija o Scraping Browser do Scrapeless — um navegador em nuvem personalizável, anti-detecção, criado especificamente para automação web e agentes de IA — para abrir páginas, extrair dados, preencher formulários, rotear tráfego através de proxies residenciais e lidar com CAPTCHA, tudo isso sem escrever código de automação de navegador de baixo nível.

Este guia mostra como instalar a habilidade do Scraping Browser do Scrapeless em 5 principais ambientes de agentes, mantendo a mesma base de navegador subjacente em todos eles.

Por Que os Navegadores de Agentes São Importantes

A automação tradicional de navegador muitas vezes quebra nas mesmas coisas que os usuários reais encontram todos os dias: JavaScript dinâmico, verificações anti-bot, estado da sessão, conteúdo sensível à geolocalização e layouts que mudam rapidamente. Navegadores de agentes resolvem isso ao dar ao agente um navegador que é projetado para interação, persistência e variabilidade na web, em vez de apenas renderização de página. Para equipes que constroem fluxos de trabalho de produção, isso reduz a quantidade de código de colagem necessário em torno da navegação, tentativas e manipulação do estado da página.

Para muitas empresas, o próprio navegador é agora a interface para dados. Um navegador de agentes pode ler painéis, mover-se através de portais autenticados, coletar sinais de preços ou disponibilidade, verificar estados de conta e completar tarefas web que seriam caras para programar de ponta a ponta. A camada de navegador do Scrapeless é especialmente relevante quando esses fluxos de trabalho precisam de infraestrutura resiliente, controle de proxy e execução confiável em grande escala.

O Que Você Pode Fazer Com Isso

Uma vez instalado, os agentes ganham toda a superfície do Scraping Browser do Scrapeless:

• Abra qualquer URL no Scraping Browser do Scrapeless e descubra o DOM com snapshot -i.
• Interaja com elementos por meio de referências de árvore de acessibilidade curtas @e1, @e2 ou seletores CSS padrão.
• Preencha formulários, clique em botões, envie arquivos, faça capturas de tela, baixe PDFs.
• Roteie o tráfego através de proxies residenciais por país, estado ou cidade.
• Configure impressões digitais de desktop por sessão: plataforma (Windows, macOS, Linux), fuso horário, idiomas e dimensões da tela.
• Grave sessões para revisão posterior no painel do Scrapeless e abra uma visualização ao vivo para inspeção em tempo real.

Os agentes acionam a habilidade automaticamente quando os usuários dizem coisas como "raspe os 5 principais posts do Hacker News", "faça login neste site e tire uma captura de tela do painel" ou "preencha esta aplicação de trabalho com meu currículo e pare antes do envio final".

Por Que Scrapeless

O Scraping Browser do Scrapeless lida com as partes da automação da web que normalmente consomem semanas de tempo de engenharia:

• Anti-detection incluído — A página do produto da Scrapeless descreve como um "navegador em nuvem anti-deteção personalizável alimentado por Chromium desenvolvido internamente."
• Proxies residenciais em mais de 195 países, selecionáveis por sessão.
• Resolução automática de CAPTCHA para reCAPTCHA v2, Cloudflare Turnstile, Cloudflare 5s Challenge e AWS Challenge (lista suportada); qualquer coisa fora desses quatro é coberta pelo produto separado Scrapeless CAPTCHA Solver.
• Gravação de sessão e visualização ao vivo para inspeção e depuração em tempo real das execuções de produção.
• Compatibilidade de protocolo com Puppeteer e Playwright através do Scrapeless SDK.

Produtos relacionados: APIs Universais de Scraping, Soluções de Proxy, e o Servidor MCP Scrapeless para integrações do Protocolo de Contexto de Modelo.

O Formato da Habilidade

Cada agente neste guia lê habilidades da mesma forma:

<skills-dir>/scrapeless-scraping-browser/
├── SKILL.md          # Frontmatter YAML + instruções (obrigatório)
├── skill.json        # metadados ricos (opcional, mas recomendado)
├── SECURITY.md       # notas de segurança (opcional)
└── references/
    └── authentication.md

O frontmatter SKILL.md informa ao agente o que a habilidade faz e quando acioná-la:

---
name: scrapeless-scraping-browser
description: Automação de navegador em nuvem CLI para agentes de IA alimentada pela Scrapeless. Usar quando o usuário precisar interagir com websites usando navegadores em nuvem, incluindo navegar em páginas, preencher formulários, clicar em botões, tirar capturas de tela, extrair dados, testar aplicativos web ou automatizar qualquer tarefa de navegador com proxies residenciais e recursos anti-deteção. Disparadores incluem solicitações para "abrir um site", "preencher um formulário", "clicar em um botão", "tirar uma captura de tela", "extrair dados de uma página", "testar este aplicativo web", "usar um proxy", "burlar detecções" ou qualquer tarefa que exija automação de navegador em nuvem.
allowed-tools: Bash(npx scrapeless-scraping-browser-skills scrapeless-scraping-browser:*), Bash(scrapeless-scraping-browser:*)
---

As principais diferenças entre os agentes são onde colocar a pasta da habilidade, como o agente a descobre na inicialização e quais campos opcionais do frontmatter cada agente realmente lê (os campos principais name + description são universais).

Pré-requisitos

Antes de instalar a habilidade em qualquer agente, configure o CLI subjacente e as credenciais — uma vez.

1. Instale o Node.js 18 ou mais recente

Do nodejs.org, ou através de um gerenciador de versões (nvm, fnm, volta).

2. Instale o CLI do Scrapeless Scraping Browser globalmente

npm install -g scrapeless-scraping-browser

Verifique:

scrapeless-scraping-browser version

3. Obtenha uma chave API da Scrapeless

1. Cadastre-se em app.scrapeless.com — para que você possa começar a usar o Scraping Browser imediatamente.
2. Geração de um token da API a partir do painel.

4. Configure a chave API

Escolha um desses métodos.

Opção A — arquivo de configuração (recomendado, persistente, multiplataforma):

scrapeless-scraping-browser config set apiKey sua_chave_api_aqui
scrapeless-scraping-browser config get apiKey   # verifique

Isso armazena a chave em ~/.scrapeless/config.json no seu diretório home.

Opção B — variável de ambiente:

# macOS / Linux
export SCRAPELESS_API_KEY=sua_chave_api_aqui

# Windows PowerShell
$env:SCRAPELESS_API_KEY="sua_chave_api_aqui"

Adicione a linha ao ~/.zshrc, ~/.bashrc, ou suas variáveis de ambiente do Windows para persistir entre sessões.

Nota: o arquivo de configuração ganha sobre a variável de ambiente quando ambas estão definidas. Apenas SCRAPELESS_API_KEY é lido da ambiente — o Servidor MCP Scrapeless usa uma variável diferente (SCRAPELESS_KEY) e não está relacionado a essa habilidade.

5. Baixe o pacote da habilidade

Clone o pacote da habilidade:

git clone https://github.com/scrapeless-ai/scrapeless-agent-browser.git
cd scrapeless-agent-browser/skills/scraping-browser-skill

Os passos abaixo copiam o conteúdo desta pasta para o diretório de habilidades de cada agente.

Passo 1 — Instalar no Claude Code (Anthropic)

Diretório de habilidades

• Global: ~/.claude/skills/scrapeless-scraping-browser/
• Projeto: <repo>/.claude/skills/scrapeless-scraping-browser/

Instalar (global, macOS / Linux)

mkdir -p ~/.claude/skills/scrapeless-scraping-browser
cp -r ./* ~/.claude/skills/scrapeless-scraping-browser/

Instalar (global, Windows PowerShell)

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.claude\skills\scrapeless-scraping-browser\"

Ativar: O Claude Code detecta alterações nas habilidades ao vivo dentro de um ~/.claude/skills/ existente (não é necessária reinicialização). Somente necessário na primeira instalação se o diretório de nível superior ~/.claude/skills/ não existia quando a sessão começou — nesse caso, reinicie qualquer sessão claude em execução uma vez.

Verificar: dentro do Claude Code, pergunte "quais habilidades estão disponíveis?" — a documentação de solução de problemas de habilidades da Anthropic destaca exatamente esse comando como a verificação de listagem (fonte). Ou execute um comando de gatilho como "abra example.com e capture uma captura de tela da página inicial" e Claude invoca os comandos documentados da habilidade a partir do SKILL.md.

Passo 2 — Instalar no Cursor

Versão mínima: Cursor 2.4 ou mais recente (Habilidades de Agente foram lançadas na versão 2.4, janeiro de 2026).

Diretório de habilidades

• Global (canônico): ~/.agents/skills/scrapeless-scraping-browser/
• Global (também aceito): ~/.cursor/skills/, ~/.claude/skills/, ~/.codex/skills/
• Projeto (canônico): <repo>/.agents/skills/scrapeless-scraping-browser/
• Projeto (também aceito): <repo>/.cursor/skills/, <repo>/.claude/skills/, <repo>/.codex/skills/

Instalar (global, caminho canônico)

mkdir -p ~/.agents/skills/scrapeless-scraping-browser
cp -r ./* ~/.agents/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.agents\skills\scrapeless-scraping-browser\"

Ativar: "Quando o Cursor é iniciado, ele descobre automaticamente habilidades nos diretórios de habilidades e as torna disponíveis para o Agente." (documentos do Cursor)

Verificar: abra as Configurações do Cursor (Cmd/Ctrl+Shift+J) → Regras — scrapeless-scraping-browser aparece sob Decisões do Agente. Ou digite / no chat do Agente para ver a habilidade no seletor de comandos. Ou solicite "extraia as 5 principais histórias do news.ycombinator.com como JSON" — o agente deve encadear os comandos da habilidade (new-session → open → get html → eval) automaticamente.

Passo 3 — Instalar no VS Code + GitHub Copilot

O GitHub Copilot adicionou suporte a Habilidades de Agente em dezembro de 2025 (changelog). O Copilot no VS Code descobre automaticamente habilidades de três grupos de localização:

• Global (pessoal): ~/.copilot/skills/, ~/.claude/skills/, ou ~/.agents/skills/
• Projeto (nativo do Copilot): <repo>/.github/skills/scrapeless-scraping-browser/
• Projeto (cross-agent): <repo>/.claude/skills/... ou <repo>/.agents/skills/...

Nota do Frontmatter: O Copilot requer apenas name e description; allowed-tools e license são opcionais. Documentação de habilidades do Copilot do GitHub afirma textualmente: "No frontmatter do seu SKILL.md, você pode usar o campo allowed-tools para listar as ferramentas que o Copilot pode usar sem pedir confirmação a cada vez." Revise a fonte da habilidade antes de conceder pré-aprovação.

Instalar (global, macOS / Linux)

mkdir -p ~/.copilot/skills/scrapeless-scraping-browser
cp -r ./* ~/.copilot/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.copilot\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.copilot\skills\scrapeless-scraping-browser\"

Instalar (nível de projeto, recomendado para uso em equipe)

cd <seu-repo>
mkdir -p .github/skills/scrapeless-scraping-browser
cp -r /caminho/para/habilidade/* .github/skills/scrapeless-scraping-browser/
git add .github/skills/scrapeless-scraping-browser
git commit -m "Adicionar habilidade scrapeless-scraping-browser"

Ativar: de acordo com o changelog do GitHub de 18 de dezembro de 2025, o Copilot detecta habilidades colocadas nos diretórios suportados sem configuração extra. As habilidades carregam conteúdo progressivamente somente quando relevante para uma tarefa.

Verificar: abra o Chat do Copilot e digite /skills — segundo documentos de habilidades do Copilot do VS Code, isso "abre rapidamente o menu Configurar Habilidades" onde scrapeless-scraping-browser deve aparecer. Ou solicite "raspe os preços dos produtos deste URL" / "capture uma captura de tela de example.com" e veja o Copilot invocar a habilidade.

Passo 4 — Instalar no OpenAI Codex CLI

Versão mínima: Qualquer versão do Codex CLI que documenta Habilidades de Agente — atualize para a versão mais recente do codex CLI para ficar seguro (documentos de Habilidades do Codex).

Diretório de habilidades

• Global: $HOME/.agents/skills/scrapeless-scraping-browser/ — o escopo do usuário documentado.
• Projeto: $CWD/.agents/skills/, qualquer diretório pai .agents/skills/, ou $REPO_ROOT/.agents/skills/. O Codex caminha do CWD até a raiz do repositório.
• ~/.codex/skills/ NÃO é descoberto automaticamente — se você quiser que o Codex leia a partir daí, registre-o explicitamente em ~/.codex/config.toml sob [[skills.config]] com um caminho absoluto, ex. path = "/home/<você>/.codex/skills/scrapeless-scraping-browser/SKILL.md" (a documentação do Codex mostra caminhos absolutos no exemplo de [[skills.config]] — a expansão do til dentro do TOML não está documentada).

Instalação (global)

mkdir -p ~/.agents/skills/scrapeless-scraping-browser
cp -r ./* ~/.agents/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.agents\skills\scrapeless-scraping-browser\"

Ativar: "O Codex detecta mudanças de habilidade automaticamente. Se uma atualização não aparecer, reinicie o Codex." (Documentação de Habilidades do Codex)

Verificar: no prompt do Codex, execute /skills para listar as habilidades disponíveis. Chame a habilidade diretamente digitando $scrapeless-scraping-browser em sua mensagem, ou teste o auto-disparo com "preencha o formulário de inscrição em example.com/signup e pare antes do envio final".

Etapa 5 — Instalar no Gemini CLI (Google)

Diretório de habilidades

• Global: ~/.gemini/skills/scrapeless-scraping-browser/ — ~/.agents/skills/ é um alias oficialmente documentado que tem precedência sobre ~/.gemini/skills/ quando ambos existem.
• Projeto: <repo>/.gemini/skills/scrapeless-scraping-browser/ — ou use o alias <repo>/.agents/skills/.

Instalar

mkdir -p ~/.gemini/skills/scrapeless-scraping-browser
cp -r ./* ~/.gemini/skills/scrapeless-scraping-browser/

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.gemini\skills\scrapeless-scraping-browser"
Copy-Item -Recurse -Force .\* "$HOME\.gemini\skills\scrapeless-scraping-browser\"

Ativar: execute /skills reload na sessão para atualizar a lista de habilidades descobertas de todos os níveis (Documentação de habilidades do Gemini CLI).

Verificar: execute /skills list dentro de uma sessão do Gemini CLI — scrapeless-scraping-browser deve aparecer na lista descoberta. Em seguida, teste com "abra booking.com de um proxy residencial de Tóquio e busque os 5 melhores hotéis de 15 a 18 de junho"; o modelo solicitará ativação antes de executar os comandos da habilidade.

Etapa 6 — Uma Habilidade, Todo Agente (o Truque do Link Simbólico)

Se você usa vários agentes e não quer copiar a habilidade para N diretórios, instale uma vez e crie links simbólicos para os outros.

macOS / Linux

# Instale uma vez como a fonte da verdade:
mkdir -p ~/.agents/skills/scrapeless-scraping-browser
cp -r ./* ~/.agents/skills/scrapeless-scraping-browser/

# Link simbólico para cada outro agente:
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.claude/skills/scrapeless-scraping-browser
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.cursor/skills/scrapeless-scraping-browser
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.copilot/skills/scrapeless-scraping-browser
ln -s ~/.agents/skills/scrapeless-scraping-browser ~/.gemini/skills/scrapeless-scraping-browser

Agora, atualizar a fonte atualiza todos os agentes simultaneamente.

Windows PowerShell — no Windows 10/11 com o Modo Desenvolvedor habilitado (Configurações → Sistema → Avançado → Para desenvolvedores no Windows 11 25H2+; a página Para desenvolvedores diretamente em versões anteriores), links simbólicos funcionam sem elevação. Caso contrário, execute o PowerShell como Administrador. Veja Documentação do Modo Desenvolvedor da Microsoft.

$src = "$HOME\.agents\skills\scrapeless-scraping-browser"
"claude","cursor","copilot","gemini" | ForEach-Object {
  $dest = "$HOME\.$_\skills\scrapeless-scraping-browser"
  New-Item -ItemType Directory -Force -Path (Split-Path $dest)
  New-Item -ItemType SymbolicLink -Path $dest -Target $src
}

Etapa 7 — Nível de Projeto vs Global: Qual Escolher

Etapa 8 — Resolvendo Problemas Comuns

A habilidade não aparece após a cópia. O caminho de atualização de cada agente é diferente: Claude Code — documentos dizem que um diretório ~/.claude/skills/ de nível superior criado após o início da sessão requer reiniciar o claude; mudanças dentro de um diretório existente são capturadas ao vivo. Codex — documentos dizem "Codex detecta mudanças de habilidade automaticamente. Se uma atualização não aparecer, reinicie o Codex." Gemini CLI — execute /skills reload na sessão. Cursor e VS Code / Copilot — seus documentos descrevem a descoberta automática na inicialização; se uma habilidade estiver faltando, reinicie o editor.

O agente diz SCRAPELESS_API_KEY is required. A chave não está no ambiente do processo do agente. Prefira o método do arquivo de configuração (scrapeless-scraping-browser config set apiKey ...) — é independente do processo e funciona em todos os agentes.

O gatilho não é acionado automaticamente. Abra SKILL.md na localização instalada e verifique o frontmatter description — os agentes o usam como um sinal de roteamento. Adicione frases de usuário à lista triggers do skill.json para ampliar a correspondência.

Conclusão

Browsers agenticos estão se tornando um padrão prático para automação intensiva na web, e o Scrapeless se adapta a essa tendência ao fornecer uma camada de navegador em nuvem que os agentes podem realmente confiar. Se seus fluxos de trabalho dependem de navegação, interação, conteúdo dinâmico ou acesso a dados baseados em navegador, a habilidade Scrapeless Scraping Browser é uma base sólida. A grande vantagem é simples: você instala uma habilidade de navegador uma vez, e depois reutiliza-a em vários agentes principais sem reconstruir a camada de execução toda vez. O reposiório scrapeless-agent-browser empacota a execução do navegador em uma camada de agente reutilizável, em vez de tratar o navegador como uma dependência de script única.

Fique ligado para mais casos de uso práticos em nossos futuros guias de blog. Por enquanto, junte-se à comunidade oficial do Scrapeless para receber as últimas atualizações e garantir acesso ao seu plano gratuito!
Discord
Telegram

FAQ

Q1: Preciso de uma chave de API separada para cada agente?
Não. Configure a chave da API Scrapeless uma vez com scrapeless-scraping-browser config set apiKey ... e todo agente que executar a CLI a captará automaticamente.

Q2: Posso usar a habilidade em nível de projeto e enviá-la para meu repositório?
Sim. Cada agente neste guia suporta um diretório de habilidades em nível de projeto (por exemplo, <repo>/.claude/skills/, <repo>/.github/skills/, <repo>/.agents/skills/). Enviar a habilidade a torna disponível para cada membro da equipe que clona o repositório.

Q3: Preciso instalar o pacote npm scrapeless-scraping-browser se já tiver a habilidade instalada?
Sim — a habilidade é a camada de instrução para o agente; o pacote npm é a CLI que ela controla. A CLI deve ser acessível pelo agente, seja instalada globalmente (npm install -g scrapeless-scraping-browser) ou invocada via npx scrapeless-scraping-browser ….

Q4: Como a habilidade lida com CAPTCHAs?
O Scraping Browser resolve automaticamente quatro tipos de CAPTCHA desde o início — reCaptcha v2, Cloudflare Turnstile, Cloudflare 5s Challenge e AWS Challenge (lista oficial de suportados). A documentação observa que "operações subsequentes precisam ser implementadas por você mesmo" — o navegador resolve, seu código (ou o agente) determina o que acontece a seguir. Para qualquer coisa fora desses quatro tipos, o Scrapeless CAPTCHA Solver é um produto separado.

Q5: A habilidade pode ser usada junto com o código do Puppeteer ou Playwright?
Sim. O Scrapeless Scraping Browser é compatível com o protocolo do Puppeteer e Playwright via a documentação do Scrapeless Scraping Browser, assim, os agentes podem combinar sessões dirigidas por habilidades com scripts de automação existentes.