Como resolver reCAPTCHA no LangChain

O reCAPTCHA é o desafio de verificação mais comum que os agentes de IA encontram ao navegar pela web. Agentes LangChain que realizam coleta de dados, submissão de formulários ou fluxos de trabalho de múltiplas etapas encontram caixas de seleção do reCAPTCHA v2 e desafios invisíveis em páginas de login, resultados de pesquisa e conteúdo protegido. Este tutorial demonstra como resolver o reCAPTCHA v2 especificamente no LangChain usando o pacote capsolver-agent do CapSolver, com exemplos completos de código para os modos Token e Browser.

TL;DR

• O reCAPTCHA v2 é o tipo de CAPTCHA mais frequentemente encontrado para agentes web do LangChain
• As ferramentas do CapSolver para LangChain resolvem o reCAPTCHA v2 (caixa de seleção e invisível) em 5-12 segundos em média
• O modo Token requer apenas a chave do site e a URL - nenhum navegador é necessário
• O modo Browser detecta automaticamente o reCAPTCHA em qualquer página e preenche o token de volta no DOM
• O pacote capsolver-agent fornece implementações nativas de BaseTool para agentes ReAct do LangChain

Por que o reCAPTCHA Bloqueia os Agentes LangChain

O reCAPTCHA v2 é implantado em milhões de sites para distinguir usuários humanos do tráfego automatizado. Quando um agente LangChain navega até uma página protegida - seja para enriquecimento de leads, extração de dados ou automação de fluxos de trabalho - o motor de análise de risco da Google avalia a sessão. Navegação automatizada, ambientes headless e padrões de navegação rápida acionam o desafio reCAPTCHA, interrompendo a execução do agente.

O desafio se manifesta em duas formas: a caixa de seleção visível ("Não sou um robô") que requer interação, e a variante invisível que é acionada silenciosamente com base no score de risco. Ambas as formas exigem a submissão de um token válido para prosseguir. Sem um mecanismo de resolução, o agente LangChain não pode continuar sua tarefa e toda a cadeia falha.

Documentação do reCAPTCHA da Google confirma que o sistema usa análise de risco avançada, incluindo verificações do ambiente do navegador, padrões de interação e comportamento histórico. Isso torna o reCAPTCHA particularmente desafiador para agentes automatizados que não possuem padrões de navegação semelhantes aos humanos.

O serviço de resolução de reCAPTCHA v2 do CapSolver gera tokens válidos por meio de sua infraestrutura em nuvem, evitando a necessidade de interação pixel-perfeita ou reconhecimento de imagens dentro da janela do agente.

O que Você Precisa Antes de Começar

Instale os pacotes necessários:

# Motor principal (dependência necessária)
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Ferramentas de agente com suporte ao LangChain
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

# Ambiente de execução do LangChain
pip install langchain-openai langgraph

Defina variáveis de ambiente:

export CAPSOLVER_API_KEY="sua-chave-api-do-capsolver"
export OPENAI_API_KEY="sua-chave-api-do-openai"

Você também precisa da chave do site do reCAPTCHA do seu site-alvo. Use a extensão do navegador do CapSolver https://www.capsolver.com/blog/Extension/capsolver-captcha-solver-extension para identificá-la, ou inspecione a fonte da página para atributos data-sitekey. O guia de identificação do reCAPTCHA explica como distinguir entre variantes de caixa de seleção v2, invisível v2 e v3.

Etapa 1 — Identificar Parâmetros do reCAPTCHA v2 na Página Alvo

O que Fazer

Localize a chave do site do reCAPTCHA na sua página-alvo. Abra as ferramentas de desenvolvedor do navegador e procure na fonte da página:

<!-- reCAPTCHA v2 visível (caixa de seleção) -->
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>

<!-- reCAPTCHA v2 invisível -->
<div class="g-recaptcha" data-sitekey="6LeIxAcT..." data-size="invisible"></div>

Registre três valores: o data-sitekey, a URL completa da página e se é visível ou invisível (verifique se há data-size="invisible").

Para detecção programática usando o SDK do CapSolver:

from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

async def detect_recaptcha(url: str):
    cap = create_capsolver(api_key="SUA_CHAVE_API")
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto(url)
        
        # Detectar automaticamente todos os CAPTCHAs na página
        infos = await cap.get_captcha_info(page)
        for info in infos:
            print(f"Tipo: {info.type}, Chave: {info.website_key}")
        
        await browser.close()
    await cap.aclose()

Por Que Isso Importa

A chave do site é o parâmetro essencial para a resolução do reCAPTCHA. Sem ela, o serviço de resolução não pode gerar um token válido para o site específico. Páginas diferentes no mesmo domínio podem usar chaves diferentes, então sempre verifique por página.

Erros Comuns a Evitar

• Usar uma chave de teste em produção: O Google fornece chaves de teste (como 6LeIxAcT...) que sempre passam. Sites reais usam chaves únicas que exigem resolução real.
• Confundir v2 com v3: O reCAPTCHA v3 usa um tipo de tarefa diferente e requer page_action. Verifique a origem do script - o v3 carrega via ?render=SITE_KEY em vez de um elemento div.

Etapa 2 — Resolver reCAPTCHA v2 com Ferramentas do LangChain (Modo Token)

O que Fazer

Use as ferramentas do capsolver-agent do LangChain para resolver o reCAPTCHA v2 no fluxo de trabalho do seu agente:

import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from capsolver_agent.langchain import get_langchain_tools

async def solve_recaptcha_with_agent():
    # Obter ferramentas do CapSolver para LangChain
    tools = get_langchain_tools(api_key="SUA_CHAVE_CAPSOLVER")
    
    # Criar agente ReAct
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent = create_react_agent(llm, tools=tools)
    
    # Perguntar ao agente resolver reCAPTCHA
    result = await agent.ainvoke({
        "messages": [("user", 
            "Resolva o reCAPTCHA v2 em https://example.com/login. "
            "A chave do site é 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
            "Retorne o token que posso usar para submeter o formulário."
        )]
    })
    
    print(result["messages"][-1].content)

asyncio.run(solve_recaptcha_with_agent())

Para execução direta sem o loop do agente (quando você quer controle programático):

from capsolver_agent.schema import create_executor

async def solve_recaptcha_direct():
    executor = create_executor(api_key="SUA_CHAVE_CAPSOLVER")
    
    result = await executor.execute("solve_captcha", {
        "captcha_type": "reCaptchaV2",
        "website_url": "https://example.com/login",
        "website_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
    })
    
    if result["success"]:
        token = result["solution"]["token"]
        print(f"reCAPTCHA resolvido! Token: {token[:60]}...")
        # Envie este token como 'g-recaptcha-response' no POST do formulário
        return token
    else:
        print(f"Falha: {result['error']}")
        return None

O token retornado deve ser enviado como o campo g-recaptcha-response no pedido POST do formulário. A documentação de resolução do reCAPTCHA v2 fornece detalhes adicionais sobre padrões de envio de token.

Por Que Isso Importa

O modo Token é o método mais rápido para reCAPTCHA v2 - tempo médio de resolução de 5-12 segundos sem sobrecarga de navegador. Para agentes LangChain que já conhecem os parâmetros do site-alvo, isso fornece limpeza imediata de CAPTCHA sem iniciar uma instância de navegador.

Erros Comuns a Evitar

• Não enviar o token rapidamente: Os tokens do reCAPTCHA expiram após aproximadamente 120 segundos. Envie o formulário imediatamente após receber o token.
• Faltar o sinalizador invisível: Para reCAPTCHA v2 invisível, o método de resolução é o mesmo, mas você pode precisar disparar o callback de submissão do formulário após a injeção.

Etapa 3 — Lidar com reCAPTCHA v2 Invisível

O que Fazer

O reCAPTCHA v2 invisível funciona de forma idêntica do ponto de vista da API - o mesmo tipo de tarefa reCaptchaV2 lida com ambas as variantes:

# reCAPTCHA v2 invisível - mesma chamada de API
result = await executor.execute("solve_captcha", {
    "captcha_type": "reCaptchaV2",
    "website_url": "https://example.com/checkout",
    "website_key": "6Ld_SITE_KEY_HERE"
    # Nenhum sinalizador adicional necessário - o CapSolver lida com o invisível automaticamente
})

A diferença está em como você injeta o token. O reCAPTCHA invisível geralmente está vinculado a um clique em botão ou evento de submissão de formulário. Após obter o token, dispare o callback:

# Em um contexto de Playwright/navegador após resolver:
await page.evaluate(f"""() => {{
    document.getElementById('g-recaptcha-response').innerHTML = '{token}';
    // Disparar o callback vinculado
    if (typeof ___grecaptcha_cfg !== 'undefined') {{
        const clients = ___grecaptcha_cfg.clients;
        for (const key in clients) {{
            const client = clients[key];
            // Encontre e chame o callback
            if (client && client.L && client.L.L && client.L.L.callback) {{
                client.L.L.callback('{token}');
            }}
        }}
    }}
}}""")

O guia de identificação do callback do reCAPTCHA explica como localizar a função de callback correta para qualquer site.

Etapa 4 — Usar o Modo Browser para Detecção e Resolução Automática do reCAPTCHA

O que Fazer

Quando seu agente LangChain controla um navegador e encontra reCAPTCHA dinamicamente, use solve_on_page() para detecção e preenchimento automáticos:

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

async def auto_solve_recaptcha(target_url: str):
    """Detectar e resolver automaticamente o reCAPTCHA em qualquer página."""
    cap = create_capsolver(api_key="SUA_CHAVE_CAPSOLVER")
    
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        page = await browser.new_page()
        await page.goto(target_url)
        await page.wait_for_load_state("networkidle")
        
        # Uma chamada resolve tudo: detectar → resolver → preencher de volta
        results = await cap.solve_on_page(page)
        
        for r in results:
            if r.solution:
                print(f"Resolvido {r.info.type}: token={r.solution.token[:50]}...")
                print(f"Token preenchido na página: {r.filled}")
            else:
                print(f"Falha em resolver {r.info.type}: {r.error}")
        
        # Após resolver, a página está pronta - submeta o formulário
        submit_button = page.locator('button[type="submit"]')
        if await submit_button.count() > 0:
            await submit_button.click()
            await page.wait_for_navigation()
            print(f"Formulário submetido. URL atual: {page.url}")
        
        await browser.close()
    await cap.aclose()

asyncio.run(auto_solve_recaptcha("https://example.com/login"))

O modo Browser é particularmente poderoso porque lê os parâmetros do reCAPTCHA diretamente do DOM em tempo real - nenhuma extração manual da chave do site é necessária. O SDK identifica o tipo de CAPTCHA, lê o data-sitekey, resolve-o e escreve o token de volta no campo g-recaptcha-response automaticamente.

Obtenha seu código bônus: Use o código WEBS no Painel do CapSolver para obter um bônus extra de 5% em cada recarga. Ideal para desenvolvedores do LangChain que constroem agentes que lidam com desafios de reCAPTCHA.

Etapa 5 — Construir um Agente de Produção do LangChain com Tratamento de reCAPTCHA

O que Fazer

Combine a resolução de reCAPTCHA com outras ferramentas para um fluxo de trabalho completo:

import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from capsolver_agent.langchain import get_langchain_tools

async def production_agent():
    capsolver_tools = get_langchain_tools(api_key="SUA_CHAVE_CAPSOLVER")
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent = create_react_agent(llm, tools=capsolver_tools)
    
    # Tarefa de múltiplas etapas que requer resolução de reCAPTCHA
    result = await agent.ainvoke({
        "messages": [("user",
            "Preciso acessar um recurso protegido. "
            "Primeiro, resolva o reCAPTCHA v2 em https://example.com/gate "
            "(chave do site: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI), "
            "depois me diga o token para que eu possa prosseguir com minha solicitação."
        )]
    })
    
    return result["messages"][-1].content

asyncio.run(production_agent())

Para agentes que precisam lidar com várias versões do reCAPTCHA em diferentes sites, as mesmas ferramentas lidam com v2 e v3 - basta alterar o parâmetro captcha_type de reCaptchaV2 para reCaptchaV3.

A página de produtos do CapSolver lista todos os tipos de CAPTCHA suportados e seus preços, ajudando você a estimar os custos para sua implantação do agente LangChain.

Conclusão

Resolver o reCAPTCHA no LangChain requer o pacote capsolver-agent com o extra do LangChain, que fornece implementações nativas de BaseTool. O modo Token lida com chaves de site conhecidas em 5-12 segundos sem navegador, enquanto o modo Browser detecta automaticamente e preenche tokens de reCAPTCHA em qualquer página. CapSolver impulsiona a infraestrutura de resolução de IA, suportando variantes de caixa de seleção e invisível do reCAPTCHA através de uma interface unificada.

Comece identificando a chave do site em sua página-alvo, depois integre get_langchain_tools() ao seu agente ReAct. O loop de raciocínio do agente decide naturalmente quando invocar a resolução de reCAPTCHA, tornando o tratamento de verificação uma parte transparente do seu fluxo de automação.

Perguntas Frequentes

Qual é a taxa de sucesso para resolver o reCAPTCHA v2 com o CapSolver?

O CapSolver atinge uma taxa de sucesso de 95-99% em desafios de reCAPTCHA v2. O serviço de resolução com IA lida com as variantes de caixa de seleção e invisível. Tentativas falhas não são cobradas, e a resposta de erro estruturada permite que seu agente retente automaticamente.

Quanto tempo leva para resolver o reCAPTCHA v2?

O tempo médio de resolução do reCAPTCHA v2 é de 5-12 segundos. Isso inclui o tempo de ida e volta da rede para o serviço do CapSolver e o processo de reconhecimento de IA. Para fluxos de trabalho sensíveis ao tempo, o SDK suporta tempos limite configuráveis e intervalos de sondagem.

O recurso do LangChain pode lidar com o reCAPTCHA Enterprise?

Sim. Passe enterprise: true nos parâmetros ao chamar solve_captcha. O reCAPTCHA Enterprise usa os mesmos tipos de tarefa v2/v3, mas pode exigir parâmetros adicionais como o token s. O serviço do CapSolver lida com variantes Enterprise de forma transparente.

Eu preciso de um navegador para resolver o reCAPTCHA no LangChain?

Não. O modo de token funciona sem nenhum navegador — você fornece a chave do site e a URL, e recebe um token de volta. O modo navegador (que requer Playwright) é opcional e usado quando você deseja detecção automática e preenchimento em páginas ao vivo. A maioria das integrações com LangChain usa o modo de token por simplicidade e velocidade.

Como lidar com a expiração do token reCAPTCHA?

Os tokens reCAPTCHA expiram após aproximadamente 120 segundos. Solicite o token o mais próximo possível da submissão do formulário. Se o seu fluxo de trabalho tiver atrasos entre a resolução e a submissão, implemente um padrão de "resolver logo antes da submissão" em vez de resolver cedo no pipeline.