Como Integrar um Resolvedor de CAPTCHA com o LangGraph

TL;DR

• Um resolvedor de CAPTCHA do LangGraph deve ser modelado como um nó de ferramenta limitado, não oculto dentro da pergunta geral do agente para navegação.
• O gráfico deve pausar apenas quando um fluxo de navegação autorizado detectar um checkpoint de reCAPTCHA ou Cloudflare Turnstile suportado.
• Passe a URL da página, a chave do site, o tipo de desafio e metadados de ação opcionais como estado estruturado; nunca coloque uma chave de API do CapSolver em mensagens do gráfico.
• Roteie os resultados ready, failed e timeout por arestas explícitas para que o agente não tente repetidamente para sempre.
• Valide o token retornado na mesma sessão do navegador e pare quando o aplicativo de destino o rejeitar.

O que a Integração do LangGraph Permite

Um resolvedor de CAPTCHA do LangGraph fornece um caminho de recuperação controlado para um fluxo de trabalho de IA quando uma tarefa de navegador autorizado encontra um checkpoint de verificação suportado. O LangGraph permanece responsável pela orquestração, enquanto o CapSolver lida com a tarefa especializada de CAPTCHA por meio de uma API ou ferramenta de agente.

O design útil é uma pequena máquina de estados: navegar, detectar, solicitar uma solução, aplicar o token, verificar o resultado da página e continuar ou parar. Isso mantém o tratamento de CAPTCHA observável e evita que o modelo improvise parâmetros ou repita chamadas sem limites.

Pré-requisitos

Use esse padrão apenas em sites e ambientes de teste nos quais você é autorizado a automatizar. Você precisa de um aplicativo LangGraph, uma camada de controle de navegador, uma conta CapSolver e um armazenamento de segredos do lado do servidor para CAPSOLVER_API_KEY. A etapa do navegador deve ser capaz de identificar o tipo de desafio e coletar os parâmetros documentados pelo CapSolver.

O guia do agente do CapSolver descreve o fluxo de trabalho de agente suportado. A documentação do SDK Core aborda a interface programática, enquanto a referência de ferramentas de agente documenta o uso orientado a ferramentas.

Defina um Contrato de Estado de CAPTCHA

O estado do gráfico deve conter apenas os valores necessários para roteamento e verificação:

from typing import Literal, TypedDict

class AgentState(TypedDict, total=False):
    page_url: str
    captcha_type: Literal["recaptcha_v2", "recaptcha_v3", "turnstile"]
    website_key: str
    action: str
    task_id: str
    token: str
    captcha_status: Literal["not_found", "pending", "ready", "failed", "timeout"]
    attempts: int

Mantenha a chave da API fora deste objeto. O estado do gráfico pode ser registrado ou verificado, então as credenciais pertencem a variáveis de ambiente ou a um gerenciador de segredos aprovado.

Crie o Nó do Resolvedor

O nó do resolvedor deve traduzir o estado conhecido em uma tarefa suportada pelo CapSolver. O código a seguir é um limite ilustrativo; conecte-o ao SDK oficial ou ao esquema REST usado pelo seu serviço.

MAX_ATTEMPTS = 2

def solve_captcha(state: AgentState) -> AgentState:
    attempts = state.get("attempts", 0)
    if attempts >= MAX_ATTEMPTS:
        return {**state, "captcha_status": "timeout"}

    required = ("page_url", "website_key", "captcha_type")
    if any(not state.get(key) for key in required):
        return {**state, "captcha_status": "failed"}

    result = capsolver_client.solve({
        "type": state["captcha_type"],
        "websiteURL": state["page_url"],
        "websiteKey": state["website_key"],
        "action": state.get("action"),
    })
    return {
        **state,
        "attempts": attempts + 1,
        "token": result.get("token", ""),
        "captcha_status": "ready" if result.get("token") else "failed",
    }

Não deixe o modelo de linguagem inventar websiteKey, tipo de desafio ou ação. Extraia esses valores da página ativa ou da configuração do aplicativo, depois valide-os antes da chamada da ferramenta.

Resgate seu Código de Bônus do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código de bônus CAP26 ao recarregar sua conta do CapSolver para obter um bônus extra de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Adicione Arestas Condicionais no Gráfico

O LangGraph deve rotear com base no estado observado, em vez de texto livre do modelo:

def route_after_detection(state: AgentState) -> str:
    if state.get("captcha_status") == "pending":
        return "solve_captcha"
    return "continue_browser"

def route_after_solve(state: AgentState) -> str:
    if state.get("captcha_status") == "ready":
        return "apply_token"
    return "stop_with_diagnostic"

O nó apply_token deve operar na mesma sessão do navegador que detectou o desafio. Após a aplicação, um nó de verificação separado deve inspecionar a resposta da aplicação, a navegação esperada ou a confirmação do lado do servidor. Um token sozinho não é prova de que o fluxo de trabalho tenha sucesso.

Trate Falhas Sem Laços de Repetição

Classifique as falhas antes de decidir o que fazer. Parâmetros ausentes são problemas de configuração. Um token rejeitado pode indicar um token expirado, URL de página incorreta, chave do site, ação ou contexto de navegador incorretos. Um tempo limite do serviço é operacional e pode justificar uma tentativa limitada.

Registre task_id, tipo de desafio, tempo decorrido e um código de erro sanitizado. Não armazene tokens, cookies, credenciais ou conteúdo de página sensível em registros gerais do agente. Esvazie para um humano quando a página solicitar uma ação que não deve ser autônoma.

Checklist de Produção

• Permita domínios autorizados e tipos de desafio.
• Defina um tempo limite rígido e um número máximo de tentativas.
• Mantenha credenciais fora de prompts e checkpoints.
• Aplicar e verificar o token no contexto de navegador original.
• Adicione aprovação humana em login, submissão, pagamento ou alterações de conta.
• Rastreie a taxa de conclusão e falhas por motivo, não apenas pelo sucesso da chamada da ferramenta.

Conclusão

Uma integração de CAPTCHA confiável do LangGraph é uma ramificação estreita, observável com entradas explícitas e condições de parada. Mantenha a orquestração do navegador no LangGraph, mantenha os parâmetros de CAPTCHA estruturados e verifique o resultado do negócio após a aplicação do token. CapSolver pode fornecer a capacidade especializada de CAPTCHA sem transformar todo o agente em um loop de recuperação opaco.

Perguntas Frequentes

Q: O LangGraph pode resolver CAPTCHA por conta própria?

Não. O LangGraph orquestra nós e estado; uma navegação autorizada e um serviço de CAPTCHA realizam o trabalho especializado.

Q: Quais tipos de CAPTCHA o gráfico deve suportar?

Comece apenas com os tipos documentados pela superfície atual do agente do CapSolver, como reCAPTCHA v2, reCAPTCHA v3 e Cloudflare Turnstile.

Q: A chave da API deve ser armazenada no estado do LangGraph?

Não. Armazene a chave da API em uma variável de ambiente ou gerenciador de segredos do lado do servidor, pois o estado do gráfico pode ser persistido ou registrado.

Q: Quantas vezes o nó deve tentar novamente?

Use uma ou duas tentativas limitadas e pare em rejeições repetidas, parâmetros ausentes ou incerteza de autorização.