Como resolver reCAPTCHA em Agentes do LangGraph

TL;DR

• Instale capsolver-agent com o extra LangChain e carregue suas ferramentas prontas com get_langchain_tools().
• Vincule essas ferramentas ao modelo de chat e execute-as dentro de um nó de ferramenta do LangGraph.
• Para o modo de token reCAPTCHA v2, forneça a URL exata da página autorizada e a chave do site; o token retornado é gRecaptchaResponse no nível da API.
• Adicione listas de permissões, limites de tentativas, isolamento de segredos e roteamento para revisão humana ao nó de ferramenta.
• Use o modo navegador para recuperação quando uma página dinâmica exigir detecção e injeção de token na mesma sessão.

Introdução

A maneira mais sustentável de resolver reCAPTCHA em agentes LangGraph é tratar a recuperação de desafios como um nó de ferramenta tipado, em vez de embutir lógica de rede na pergunta do modelo. O SDK de Agent da CapSolver fornece ferramentas compatíveis com LangChain, enquanto o LangGraph fornece estado explícito, roteamento, tratamento de erros e resumabilidade. O modelo pode decidir que um desafio suportado bloqueia o próximo passo autorizado, mas uma ferramenta determinística valida os parâmetros da página, chama o solucionador e retorna um resultado estruturado. Essa arquitetura mantém chaves de API fora das mensagens, torna as tentativas observáveis e evita que objetivos não relacionados sejam enviados. Este tutorial constrói um gráfico mínimo, mostra como rotear chamadas de ferramenta, explica os parâmetros reCAPTCHA v2 e adiciona salvaguardas de produção para automação de navegador, QA, RPA e fluxos de trabalho de dados públicos aprovados.

Onde a CapSolver se encaixa em uma Máquina de Estados LangGraph

O LangGraph é projetado para fluxos de trabalho com estado, em que os nós realizam trabalho limitado e as arestas controlam o que acontece em seguida. A CapSolver se encaixa naturalmente em um nó de ferramenta dedicado:

Tarefa direcionada pelo usuário
      ↓
Nó de raciocínio identifica um desafio suportado
      ↓
Nó de ferramenta executa a ferramenta CapSolver
      ↓
Solução estruturada ou erro normalizado
      ↓
Navegador retoma, tenta novamente ou solicita revisão humana

O modelo deve decidir quando a recuperação é necessária. Ele não deve decidir onde os segredos são armazenados, quais hosts são autorizados ou quantas tentativas são permitidas. Essas decisões pertencem ao código de aplicativo determinístico.

O blog da CapSolver AI inclui padrões de integração de agentes, e a FAQ da CapSolver AI e automação explica como uma camada de recuperação complementa uma pilha de agentes existente.

Instale as Ferramentas do Agente e o LangGraph

A documentação do CapSolver Agent fornecida pelo usuário especifica que capsolver-agent depende de capsolver-core. Instale o núcleo primeiro, depois o pacote do agente com sua integração LangChain.

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
pip install langchain-openai langgraph

Configure as credenciais por meio do ambiente de execução:

export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

O repositório oficial do CapSolver Agent documenta esse caminho de importação:

from capsolver_agent.langchain_tools import get_langchain_tools

tools = get_langchain_tools(api_key="SUA_CHAVE_DE_API")

Os objetos retornados são instâncias BaseTool compatíveis com LangChain. O guia oficial de ferramentas do LangChain explica que as ferramentas expõem entradas e saídas definidas ao modelo, enquanto a informação de tipo e descrições ajudam o modelo a escolher a ação correta.

Entenda os Parâmetros da Tarefa reCAPTCHA v2

Para uma tarefa reCAPTCHA v2 sem proxy, as entradas necessárias são a URL da página e a chave do site. A documentação oficial reCAPTCHA v2 da CapSolver lista ReCaptchaV2TaskProxyLess para o caminho de proxy embutido e tipos de tarefa empresarial separados quando a página usa reCAPTCHA Enterprise.

No nível da tarefa REST, o token de solução é retornado como solution.gRecaptchaResponse. O SDK do Agente encapsula o resultado do núcleo em um dicionário estruturado para que o gráfico possa rotear com sucesso ou falha sem analisar prosa arbitrária.

Para descoberta de parâmetros, veja o guia da extensão do navegador da CapSolver e o guia de implementação reCAPTCHA v2.

Crie um LangGraph com Ferramentas da CapSolver

O exemplo abaixo carrega as ferramentas oficiais da CapSolver, as vincula a um modelo de chat e as coloca em um ToolNode. O gráfico retorna ao nó de raciocínio após cada resposta da ferramenta.

import os
from typing import Literal

from capsolver_agent.langchain_tools import get_langchain_tools
from langchain_openai import ChatOpenAI
from langgraph.graph import START, StateGraph
from langgraph.graph.message import MessagesState
from langgraph.prebuilt import ToolNode, tools_condition

capsolver_tools = get_langchain_tools(
    api_key=os.environ["CAPSOLVER_API_KEY"]
)

model = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
).bind_tools(capsolver_tools)


def agent_node(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}


def safe_tool_error(error: Exception) -> str:
    return (
        "A ferramenta de desafio falhou. Não tente novamente automaticamente. "
        "Retorne o fluxo de trabalho para revisão do operador."
    )

builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node(
    "tools",
    ToolNode(
        capsolver_tools,
        handle_tool_errors=safe_tool_error,
    ),
)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")

graph = builder.compile()

A referência do ToolNode do LangGraph documenta que o ToolNode aceita instâncias BaseTool, executa chamadas de ferramenta e suporta tratamento de erros configurável. Isso o torna adequado para uma ramificação de recuperação que deve ser observável e previsível.

Dê ao Agente uma Instrução Estreita

O modelo precisa de contexto suficiente para chamar a ferramenta correta, mas não deve receber autoridade ilimitada. Construa a mensagem a partir de dados de aplicativo validados:

request = {
    "website_url": "https://staging.example.com/approved-form",
    "website_key": "6LcXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
}

messages = [
    (
        "system",
        "Você opera apenas em fluxos aprovados. Se um reCAPTCHA suportado "
        "bloquear o próximo passo, chame a ferramenta solve_captcha da CapSolver uma vez "
        "com a URL e chave do site exatos fornecidos pelo aplicativo. "
        "Nunca invente um alvo ou peça credenciais. Se a solução falhar, "
        "pare e peça revisão do operador.",
    ),
    (
        "user",
        "Continue a tarefa aprovada no ambiente de staging. O navegador relatou um "
        f"reCAPTCHA v2 em {request['website_url']} com chave do site "
        f"{request['website_key']}.",
    ),
]

result = graph.invoke(
    {"messages": messages},
    config={"recursion_limit": 6},
)

Um limite de recursão evita loops de gráfico não controlados. Na produção, também restrinja o hostname permitido antes de construir a mensagem e evite armazenar tokens de solução em rastreamentos.

Adicione uma Lista de Permissões de Host Antes do Gráfico

As ferramentas da CapSolver resolvem o que são solicitadas; seu aplicativo deve decidir quais tarefas são autorizadas. Valide a URL da página fora do modelo:

from urllib.parse import urlparse

ALLOWED_HOSTS = {
    "staging.example.com",
    "qa.example.com",
}


def validate_target(url: str) -> str:
    parsed = urlparse(url)
    if parsed.scheme != "https":
        raise ValueError("Apenas alvos HTTPS são permitidos")
    if parsed.hostname not in ALLOWED_HOSTS:
        raise PermissionError("O host do alvo não é aprovado")
    return url

Use uma lista de permissões específica para o inquilino ou manifesto de fluxo assinado quando múltiplos clientes compartilham a mesma plataforma. Não permita que instruções em linguagem natural modifiquem essa política.

Roteie Sucesso, Falha e Revisão Humana

Um gráfico de recuperação útil precisa de três resultados, não apenas "resolvido" e "falha". Normalize a saída da ferramenta em uma decisão de fluxo:

from typing import TypedDict

class RecoveryDecision(TypedDict):
    status: Literal["continue", "retry", "review"]
    reason: str


def classify_recovery(result: dict, attempt: int) -> RecoveryDecision:
    if result.get("success"):
        return {"status": "continue", "reason": "solução retornada"}

    error = str(result.get("error", "erro desconhecido"))
    if attempt == 0 and "timeout" in error.lower():
        return {"status": "retry", "reason": "uma tentativa limitada é permitida"}

    return {"status": "review", "reason": error}

Não exponha tokens brutos nas mensagens do modelo quando o navegador puder consumi-los diretamente. A fronteira ideal é: resultado da ferramenta → controlador de navegador confiável → resultado da submissão → status redigido de volta ao gráfico.

A FAQ de erros e solução de problemas da CapSolver fornece caminhos de diagnóstico comuns, enquanto a guia da API de resposta da CapSolver explica o tratamento de resultados.

Modo de Token vs Modo de Navegador

O modo de token é geralmente mais simples para parâmetros reCAPTCHA conhecidos. O modo de navegador é útil quando um fluxo autorizado do Playwright precisa de detect() e solve_on_page() na mesma sessão. A documentação do Agente da CapSolver mapeia solve_captcha para resolução de token do núcleo e solve_on_page para recuperação de navegador.

Observabilidade sem Expor Segredos

Registre transições de gráfico e métricas operacionais, não valores sensíveis. Campos úteis incluem:

safe_event = {
    "workflow_id": "wf_01J...",
    "node": "tools",
    "tool": "solve_captcha",
    "target_host": "staging.example.com",
    "challenge_type": "recaptcha_v2",
    "attempt": 1,
    "duration_ms": 6420,
    "outcome": "success",
}

Nunca registre a chave da API da CapSolver, o token de solução completo, cookies autenticados ou dados de formulário. Aplicar redação de rastreamento antes de enviar eventos para sistemas de observabilidade externos.

Código Bônus: Use o código WEBS no Painel da CapSolver para obter um bônus adicional de 5% em cada recarga.

Checklist de Produção

Um solucionador de reCAPTCHA do LangGraph de produção deve ter uma lista de permissões de hostname, política de tarefa fixa, tratamento de vida útil curta de token, tentativas limitadas, redação de rastreamento, condições de parada explícitas e um nó de revisão do operador. Teste-o contra uma página de staging aprovada antes de conectá-lo a automação não supervisionada.

A FAQ de resolução de CAPTCHA da CapSolver cobre o comportamento da tarefa, e o guia de raspagem com Python da CapSolver fornece práticas de automação de navegador.

Uso Responsável

Use esse fluxo apenas em sistemas que você possua, teste ou tenha permissão explícita para automatizar. A resolução de desafios não concede direitos de acesso. Respeite os termos do site, limites de taxa, obrigações de privacidade e restrições de propósito. Exija confirmação humana antes que o gráfico envie formulários, altere dados de conta ou realize qualquer ação de alto impacto.

Conclusão

Um solucionador de reCAPTCHA do LangGraph é mais confiável quando a resolução é um nó de ferramenta explícito com roteamento estrito. Carregue as ferramentas prontas da CapSolver, vincule-as ao modelo, execute-as através de ToolNode e mantenha autorização, segredos, tentativas e consumo de token no código de aplicativo determinístico. Isso dá ao agente uma capacidade de recuperação sem lhe dar controle ilimitado.

Comece com a CapSolver, valide o gráfico contra um fluxo de trabalho de staging aprovado e adicione redação de rastreamento e revisão humana antes de escalar.

Perguntas Frequentes

Qual importação da CapSolver devo usar com o LangGraph?

Use from capsolver_agent.langchain_tools import get_langchain_tools, depois chame get_langchain_tools(api_key=...) para obter ferramentas compatíveis com LangChain que podem ser passadas para ToolNode.

Quais entradas são necessárias para o modo de token reCAPTCHA v2?

A URL da página e a chave do site reCAPTCHA são necessárias. Campos empresarial, invisível, ação ou sessão devem ser incluídos apenas quando a página autorizada realmente os usa.

O modelo do LangGraph deve receber o token de solução?

Prefira enviar o token diretamente da camada de ferramenta confiável para o controlador do navegador. Retorne apenas um evento de sucesso ou falha redigido ao gráfico de raciocínio quando possível.

Quantas tentativas automáticas o gráfico deve permitir?

Geralmente uma tentativa limitada é suficiente para um tempo limite transitório. Rejeições repetidas devem rotear para revisão humana, pois a URL, chave, sessão ou configuração da página podem estar incorretas.

Esse padrão pode lidar com desafios de navegador dinâmicos?

Sim. Use os métodos do núcleo da CapSolver capazes de navegador por meio de uma ferramenta controlada quando o fluxo precisar de detecção e recuperação no nível da página na mesma sessão do Playwright.