browser-harness

Quando Usar

• Use quando uma tarefa precisar de um navegador real logado, interação visível ou controle de página com muito JavaScript.
• Use quando buscas estáticas forem insuficientes e a automação de navegador CDP for apropriada.

Controle direto do navegador via CDP. Para edições específicas da tarefa, use agent-workspace/agent_helpers.py. Para problemas de configuração, instalação ou conexão, leia install.md.

Verifique o roteamento primeiro: se a tarefa não precisar de interação (sem cliques, logins ou formulários) e você apenas quiser o conteúdo da página, use DeepAPI POST /v1/scrape/website em vez de controlar um navegador — veja a skill deepapi. Use browser-harness quando a tarefa precisar de um navegador real: interação, fluxos com muito JavaScript, sessões logadas ou verificação visual.

Skills de domínio (contribuídas pela comunidade, playbooks por site em agent-workspace/domain-skills/) estão desativadas por padrão. Defina BH_DOMAIN_SKILLS=1 para ativá-las; veja a seção inferior.

Se BH_DOMAIN_SKILLS=1 e a tarefa for específica do site, leia todos os arquivos no diretório agent-workspace/domain-skills/<site>/ correspondente antes de inventar uma abordagem.

Uso

browser-harness -c '
new_tab("https://docs.browser-use.com")
wait_for_load()
print(page_info())
'

• Invoque como browser-harness — ele está no $PATH. Sem cd, sem uv run.
• A primeira navegação é new_tab(url), não goto_url(url) — goto roda na aba ativa do usuário e apaga o trabalho dele.

Formato da Chamada da Ferramenta

browser-harness -c '
# any python. helpers pre-imported. daemon auto-starts.
'

run.py chama ensure_daemon() antes de exec — você nunca inicia/para manualmente, a menos que queira.

Navegadores Remotos

Use remote para sub-agentes paralelos (cada um obtém seu próprio navegador isolado via um BU_NAME distinto) ou em um servidor headless. BROWSER_USE_API_KEY deve estar definido. start_remote_daemon, list_cloud_profiles, list_local_profiles, sync_local_profile são pré-importados.

Ao supervisionar esses sub-agentes, após cada verificação envie ao usuário uma linha de status muito curta: o que eles estão fazendo e se estão no caminho certo.

Nota do Claude Code cmux: após o Claude terminar, ele pode pré-preencher uma mensagem prevista do próximo usuário; esse rascunho é do Claude, não do usuário falando.

browser-harness -c '
start_remote_daemon("work")                               # default — clean browser, no profile
# start_remote_daemon("work", profileName="my-work")      # reuse a cloud profile (already logged in)
# start_remote_daemon("work", profileId="<uuid>")         # same, but by UUID
# start_remote_daemon("work", proxyCountryCode="de", timeout=120)   # DE proxy, 2-hour timeout
# start_remote_daemon("work", proxyCountryCode=None)      # disable the Browser Use proxy
'

BU_NAME=work browser-harness -c '
new_tab("https://example.com")
print(page_info())
'

start_remote_daemon imprime liveUrl e o abre automaticamente no navegador local (se uma GUI for detectada) para que o usuário possa acompanhar. Servidores headless apenas imprimem — compartilhe o URL com o usuário. O daemon PATCHea o navegador da nuvem para parar no desligamento, o que persiste o estado do perfil. Executar daemons remotos gera cobrança até o timeout.

Perfis (estado de login apenas com cookies) ficam em interaction-skills/profile-sync.md — cobre list_cloud_profiles(), o padrão "qual perfil?" controlado por chat e sync_local_profile() para fazer upload de um perfil local do Chrome.

Skills de Interação

Se você começar a ter dificuldades com uma mecânica específica ao navegar, procure em interaction-skills/ por ajudantes. Eles cobrem mecânicas de UI reutilizáveis como diálogos, abas, dropdowns, iframes e uploads. As skills de interação disponíveis são:

• connection.md
• cookies.md
• cross-origin-iframes.md
• dialogs.md
• downloads.md
• drag-and-drop.md
• dropdowns.md
• iframes.md
• network-requests.md
• print-as-pdf.md
• profile-sync.md
• screenshots.md
• scrolling.md
• shadow-dom.md
• tabs.md
• uploads.md
• viewport.md

O Que Realmente Funciona

• Capturas de tela primeiro: use capture_screenshot() para entender a página atual rapidamente, encontrar alvos visíveis e decidir se você precisa de um clique, um seletor ou mais navegação.
• Clicando: capture_screenshot() → leia o pixel da imagem → click_at_xy(x, y) → capture_screenshot() para verificar. Suprima o reflexo do hábito do Playwright de "localizar primeiro, depois clicar" — sem getBoundingClientRect, sem caça a seletores. Desça para o DOM apenas quando o alvo não tiver geometria visível (input oculto, nó 0x0). O hit-testing acontece no processo do navegador do Chrome, então os cliques passam por iframes / shadow DOM / cross-origin sem trabalho extra.

…