Como adicionar um solucionador de CAPTCHA ao Steel Browser auto-hospedado

TL;DR

• O Steel Local fornece sessões de navegador, mas sua matriz oficial de recursos não lista solução de CAPTCHA integrada.
• Conecte o Python à URL de WebSocket retornada pela sua instância Steel auto-hospedada e, em seguida, passe a página Playwright atual para um SDK de CAPTCHA.
• O exemplo abaixo foi executado contra um servidor Steel local real e leu parâmetros de reCAPTCHA v2 de uma página de desenvolvimento.
• A detecção de parâmetros não requer chave de API da CapSolver; a resolução paga requer sua própria credencial e não foi testada neste exemplo.
• Mantenha a sessão de navegador ativa durante a etapa de CAPTCHA, verifique o resultado na aplicação e libere a sessão em seguida.

Um navegador auto-hospedado pode navegar até a página certa e ainda deixar seu fluxo de trabalho parado em um CAPTCHA. Se você executa o Steel localmente, adicionar a flag de solving do serviço em nuvem não é suficiente: implantações locais e em nuvem têm capacidades diferentes.

Este guia mostra onde um resolvedor de CAPTCHA se encaixa no Steel Browser auto-hospedado, com uma pequena verificação de conexão em Python. O exemplo usa uma página de desenvolvimento local e a chave pública de teste do reCAPTCHA do Google. Ele não tem como alvo um site de terceiros nem requer um modelo de IA.

O que o Steel Browser faz e onde o solver entra

O Steel Browser é uma API de navegador para desenvolvedores que constroem agentes web e aplicações de automação. Ele gerencia uma sessão de navegador que clientes podem controlar com ferramentas de automação familiares. O repositório oficial do Steel documenta auto-hospedagem e conexões a partir de Playwright, Puppeteer e Selenium.

Para um desenvolvedor executando um fluxo de trabalho autorizado com formulário, a divisão de trabalho é direta. O Steel fornece o navegador. O Playwright navega e interage com a página. Um solver de CAPTCHA lida com um desafio suportado quando ele aparece. Seu fluxo de trabalho então verifica se a aplicação aceitou a ação pretendida.

Este tutorial usa o CapSolver Core SDK para essa etapa de CAPTCHA. O SDK pode inspecionar uma página Playwright e expor uma operação de solução separada. Não há necessidade de adicionar um LLM apenas para conectar esses componentes.

O cenário útil é um job de navegador auto-hospedado que já precisa de uma operação de CAPTCHA. Para testes rotineiros de software que você possui, as configurações de teste do fornecedor de CAPTCHA podem ser suficientes. Use o caminho com solver quando o seu fluxo de trabalho autorizado realmente precisar dele, em vez de fazer cada navegação depender de uma requisição paga.

Por que o Steel Local precisa de uma etapa de CAPTCHA separada

O Steel Local não inclui a solução de CAPTCHA integrada do produto em nuvem. A matriz de recursos local versus nuvem do Steel distingue explicitamente as duas implantações.

Essa distinção afeta a implementação. Um tutorial para nuvem pode ativar a solução durante a criação da sessão, enquanto uma integração auto-hospedada precisa fornecer a operação que falta. Não presuma que um campo de configuração da nuvem ative um recurso no servidor local.

O caminho usado aqui é:

1. Criar uma sessão na sua instância Steel local.
2. Ler o websocketUrl dessa sessão.
3. Conectar o Playwright ao navegador que o Steel já gerencia.
4. Passar uma página dessa sessão para o SDK de CAPTCHA.
5. Continuar o fluxo de trabalho da aplicação apenas depois de verificar o resultado.
6. Liberar a sessão do Steel.

Evite lançar um navegador não relacionado no passo três. Um segundo navegador não seria a sessão retornada pelo Steel, o que tornaria fácil inspecionar uma página enquanto o seu job real espera em outra.

Prepare o servidor local e o ambiente Python

Comece com uma instância dedicada do Steel Local em execução e Python 3.12. A configuração verificada usou Steel API 0.5.3 do commit 8362bbd, Playwright 1.64.0 e capsolver-core 0.1.1 no macOS.

Siga as instruções de setup local do repositório para a sua implantação. Para o servidor baseado em código fonte usado aqui, a API foi iniciada com HOST=127.0.0.1, PORT=3300 e CDP_REDIRECT_PORT=9323. Essas são as portas do ambiente de teste, não padrões obrigatórios. Mantenha a sua API de desenvolvimento acessível apenas a partir do cliente pretendido.

Instale as dependências Python em um ambiente isolado:

python -m pip install "playwright==1.64.0" "capsolver-core==0.1.1" "httpx==0.28.1"

O Steel inicia o navegador, então este cliente não lança outra instância do Chromium. O método de conexão CDP do Playwright (BrowserType.connect_over_cdp) se conecta a um navegador baseado em Chromium existente e expõe seu contexto padrão.

O cliente também precisa de acesso ao endereço WebSocket retornado. Se o Steel estiver em um container ou em outra máquina, confirme que o endereço é acessível a partir do Python; 127.0.0.1 se refere à máquina que faz a conexão.

Nenhuma credencial da CapSolver é necessária para a checagem de detecção abaixo. A solução real exige sua própria chave de API válida e recursos em conta. Solução paga, preenchimento de token e aceitação da aplicação não foram executados para este guia. Mantenha essa validação separada na sua checklist de implantação.

Conecte o Steel ao SDK e verifique um widget de desenvolvimento

O script cria uma sessão real do Steel, conecta-se ao navegador dessa sessão e lê um widget de desenvolvimento por meio do SDK oficial. Salve-o como steel_sdk_check.py e execute com Python.

O exemplo usa por padrão um servidor local na porta 3300. Defina STEEL_URL se o seu servidor usar outro endereço. Use uma instância dedicada: criação e liberação de sessão alteram a sessão de navegador ativa dessa instância.

A página é fornecida por meio de uma rota do Playwright, portanto nenhum servidor web é necessário na porta 8765. O script do widget do Google ainda precisa de acesso à rede. A site key pública está documentada na orientação de testes do reCAPTCHA do Google e é destinada a desenvolvimento, não produção.

import asyncio
import json
import os

import httpx
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

STEEL_URL = os.environ.get("STEEL_URL", "http://127.0.0.1:3300")
TEST_URL = "http://127.0.0.1:8765/"
HTML = """<!doctype html><html><head><title>Steel CAPTCHA check</title></head>
<body><h1>Página de desenvolvimento própria</h1>
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


async def main():
    async with httpx.AsyncClient(base_url=STEEL_URL, timeout=90) as api:
        response = await api.post("/v1/sessions", json={"headless": True})
        response.raise_for_status()
        session = response.json()
        try:
            async with async_playwright() as playwright:
                browser = await playwright.chromium.connect_over_cdp(session["websocketUrl"])
                try:
                    context = browser.contexts[0]
                    page = await context.new_page()
                    await page.route(TEST_URL, lambda route: route.fulfill(
                        content_type="text/html", body=HTML))
                    await page.goto(TEST_URL)
                    await page.wait_for_function(
                        "() => !!window.___grecaptcha_cfg && "
                        "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0",
                        timeout=30000)
                    async with create_capsolver() as cap:
                        infos = await cap.get_captcha_info(page)
                    result = [{"type": info.type.value,
                               "url": info.website_url,
                               "site_key": info.website_key} for info in infos]
                    print(json.dumps({"session_id": session["id"],
                                      "captcha_parameters": result}))
                    assert result and result[0]["type"] == "reCaptchaV2"
                finally:
                    await browser.close()
        finally:
            released = await api.post(f"/v1/sessions/{session['id']}/release")
            released.raise_for_status()
            print(json.dumps({"released": released.json().get("success")}))


if __name__ == "__main__":
    asyncio.run(main())

A checagem executada retornou um descritor reCaptchaV2 com a URL da página local e a site key pública de teste. A resposta final de liberação retornou true. Essas observações verificam a sessão real do Steel, a conexão CDP, o acesso à página e o caminho de leitura de parâmetros do SDK.

Elas não estabelecem que um CAPTCHA pago foi resolvido. A chave de desenvolvimento não é um desafio de produção e o script deliberadamente não solicita nenhum token de solução.

O código mantém a página no contexto de navegador existente do Steel. A limpeza fecha a conexão do cliente e pede ao servidor para liberar a sessão mesmo se a detecção falhar. Se você adaptá‑lo a um serviço compartilhado, dê a um componente a responsabilidade pelo tempo de vida da sessão em vez de deixar jobs não relacionados liberarem o trabalho uns dos outros.

Adicione a resolução na mesma página atual

Adicione a chamada de resolução depois que a página autorizada da aplicação tiver carregado o CAPTCHA suportado, enquanto a conexão do navegador e o cliente SDK ainda estiverem abertos. Substitua o fixture de desenvolvimento local pelo seu próprio fluxo de trabalho de aplicação; não use a chave de teste como entrada de produção.

Crie o cliente do SDK com a opção documentada api_key, carregando a credencial da sua configuração de segredos aprovada. A CapSolver trata a requisição de desafio; o Steel continua sendo o dono da sessão de navegador.

A linha a seguir é a chamada oficial inalterada no modo browser. Ela requer uma chave de API configurada, e a execução paga por meio desta conexão Steel não foi testada neste tutorial:

results = await cap.solve_on_page(page)

Mantenha a chamada dentro do contexto de cliente ativo. Colá‑la depois da rotina de limpeza do exemplo faria referência a um navegador e cliente fechados.

Inspecione cada resultado retornado antes de continuar. O SDK informa um error, uma possível solution e se o preenchimento foi feito via filled. Um resultado vazio ou sem solução não é evidência de que a sua aplicação passou no CAPTCHA.

O modo de token documentado do Core SDK cobre reCAPTCHA v2/v3 e Cloudflare Turnstile. Não suponha que a mesma chamada resolva todos os tipos de desafio listados em outras partes da API mais ampla da CapSolver. A documentação da tarefa ReCaptchaV2 fornece os requisitos específicos dessa rota suportada.

Verifique o fluxo de trabalho após a etapa de CAPTCHA

O fluxo de trabalho só está completo quando a aplicação atinge o estado pretendido. Uma resposta de token, um campo preenchido e um envio de formulário bem-sucedido são observações distintas.

Para uma aplicação sob seu controle, escolha um sinal concreto de sucesso, como a mensagem de confirmação ou a resposta esperada. Aguarde esse sinal após a ação normal do formulário. Se ele não aparecer, inspecione a resposta da aplicação em vez de enviar solicitações repetidas de resolução sem entender a falha.

Mantenha a identidade da página estável durante a operação. Não navegue para longe, feche a aba ou libere a sessão enquanto uma resolução estiver em andamento. Se a aplicação recarregar o widget, inspecione o desafio atual novamente em vez de reutilizar parâmetros de um estado anterior da página.

O glossário de CAPTCHA explica o conceito de verificação, enquanto o guia sobre tokens e cookies de CAPTCHA ajuda a diferenciar as diversas saídas. Nem um cookie de navegador nem uma string de token devem substituir a checagem de sucesso da sua aplicação.

Solucione o primeiro passo com falha

Comece a depuração na operação que falhou primeiro, para que problemas de conexão não se transformem em requisições de resolução desnecessárias.

Mantenha os logs de diagnóstico pequenos. Registre a etapa e um erro redigido, não chaves de API, tokens de resposta ou o armazenamento completo do navegador. Teste uma única página primeiro e adicione comportamento de retry apenas depois de identificar uma falha temporária que uma nova tentativa possa razoavelmente corrigir.

Complete a integração auto-hospedada

Uma integração com Steel Local precisa de uma transferência clara da página gerenciada de navegador para a operação de CAPTCHA. A verificação de conexão funcional estabelece essa transferência sem fazer uma requisição paga. Antes de usar em produção, valide a resolução com a sua própria credencial e verifique o resultado da aplicação em um ambiente autorizado.

Mantenha a sessão aberta para o trabalho que ela possui e libere-a quando esse trabalho terminar. Isso fornece um limite útil tanto para depuração quanto para futuras atualizações de pacote.

Construa fluxos de automação confiáveis com CapSolver

Conecte a CapSolver na etapa de CAPTCHA suportada do seu fluxo de trabalho com Steel. Comece pelo caminho de detecção verificado e, em seguida, valide sua operação credenciada antes de aumentar a carga de trabalho.

Experimente a CapSolver. Use o código de bônus CAP26 para um bônus de 5% segundo os termos da campanha.

FAQ

P: O Steel Browser auto-hospedado resolve CAPTCHAs automaticamente?

Não. A comparação oficial do Steel não lista solução de CAPTCHA integrada para o Steel Local. O recurso de resolução do produto em nuvem é uma capacidade separada.

P: Eu preciso de uma conta Steel Cloud para este exemplo?

Não. O exemplo se conecta a uma instância local em execução. Você continua responsável por iniciar e operar essa instância.

P: Por que conectar via CDP em vez de lançar o Chromium do Playwright?

O CDP conecta o Python ao navegador gerenciado pelo Steel. Lançar outro navegador criaria uma sessão separada daquela que este exemplo pretende usar.

P: A checagem de detecção consome créditos da CapSolver?
A verificação apenas lê parâmetros do widget e não faz nenhuma solicitação paga de solução. A chamada de solução separada requer uma credencial CapSolver válida.

P: O fluxo completo de solução paga foi testado aqui?

Não. A execução real verificou a criação de sessão, conexão CDP, detecção do SDK e liberação. A solução paga, o preenchimento de volta e a aceitação pela aplicação ainda exigem um teste separado com credenciais.

P: Isto é uma parceria oficial com a Steel ou uma integração nativa?

Não. Este é um exemplo de conexão testada usando a interface pública de navegador da Steel e o SDK oficial da CapSolver. Isso não estabelece uma parceria nem uma garantia de compatibilidade para versões futuras.