Cómo resolver reCAPTCHA en Agentes de LangGraph

TL;DR

• Instale capsolver-agent con el extra de LangChain y cargue sus herramientas listas con get_langchain_tools().
• Vincule esas herramientas al modelo de chat y ejecútelas dentro de un ToolNode de LangGraph.
• Para el modo de token de reCAPTCHA v2, proporcione la URL exacta de la página autorizada y la clave del sitio; el token devuelto es gRecaptchaResponse a nivel de API.
• Coloque listas de permitidos, límites de reintentos, aislamiento de secretos y enrutamiento de revisión humana alrededor del nodo de herramienta.
• Use el modo de navegador para recuperación cuando una página dinámica requiera detección e inyección de token en la misma sesión.

Introducción

La forma más mantenible de resolver reCAPTCHA en agentes de LangGraph es tratar la recuperación de desafíos como un nodo de herramienta tipado, en lugar de incrustar lógica de red en el prompt del modelo. El SDK de CapSolver proporciona herramientas compatibles con LangChain, mientras que LangGraph ofrece estado explícito, enrutamiento, manejo de errores y reanudabilidad. El modelo puede decidir que un desafío soportado bloquea el siguiente paso autorizado, pero una herramienta determinista valida los parámetros de la página, llama al solucionador y devuelve un resultado estructurado. Esta arquitectura mantiene las claves de API fuera de los mensajes, hace que los reintentos sean observables y evita que se envíen objetivos no relacionados. Este tutorial construye un gráfico mínimo, muestra cómo enrutar las llamadas a herramientas, explica los parámetros de reCAPTCHA v2 y agrega medidas de producción para automatización de navegadores, QA, RPA y flujos de trabajo de datos públicos aprobados.

Dónde encaja CapSolver en una máquina de estados de LangGraph

LangGraph está diseñado para flujos de trabajo con estado en los que los nodos realizan trabajo acotado y las aristas controlan lo que sucede a continuación. CapSolver encaja naturalmente en un nodo de herramienta dedicado:

Tarea dirigida por el usuario
      ↓
El nodo de razonamiento identifica un desafío soportado
      ↓
El nodo de herramienta ejecuta la herramienta de CapSolver
      ↓
Solución estructurada o error normalizado
      ↓
El navegador reanuda, reintentar o solicita revisión humana

El modelo debe decidir cuándo se necesita la recuperación. No debe decidir dónde se almacenan los secretos, qué hosts están autorizados o cuántos reintentos se permiten. Esas decisiones pertenecen al código de aplicación determinista.

El blog de CapSolver AI incluye patrones de integración de agentes, y la FAQ de CapSolver AI y automatización explica cómo una capa de recuperación complementa una pila de agentes existente.

Instalar las herramientas del agente y LangGraph

La documentación del agente proporcionada por el usuario especifica que capsolver-agent depende de capsolver-core. Instale primero el núcleo, luego el paquete del agente con su integración de 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 las credenciales a través del entorno en tiempo de ejecución:

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

El repositorio oficial del agente CapSolver documenta esta ruta de importación:

from capsolver_agent.langchain_tools import get_langchain_tools

tools = get_langchain_tools(api_key="YOUR_API_KEY")

Los objetos devueltos son instancias BaseTool compatibles con LangChain. La guía oficial de herramientas de LangChain explica que las herramientas exponen entradas y salidas definidas al modelo, mientras que la información de tipo y las descripciones ayudan al modelo a elegir la acción correcta.

Comprender los parámetros de la tarea reCAPTCHA v2

Para una tarea estándar de reCAPTCHA v2 sin proxy, los datos de entrada requeridos son la URL de la página y la clave del sitio. La documentación oficial de reCAPTCHA v2 de CapSolver lista ReCaptchaV2TaskProxyLess para el camino de proxy integrado y tipos de tarea empresarial separados cuando la página usa reCAPTCHA Enterprise.

A nivel de tarea REST, el token de solución se devuelve como solution.gRecaptchaResponse. El SDK del agente envuelve el resultado del núcleo en un diccionario estructurado para que el gráfico pueda enrutar en caso de éxito o fracaso sin analizar texto arbitrario.

Para descubrimiento de parámetros, consulte la guía del complemento de CapSolver y la guía de implementación de reCAPTCHA v2.

Crear un LangGraph con herramientas de CapSolver

El ejemplo siguiente carga las herramientas oficiales de CapSolver, las vincula a un modelo de chat y las coloca en un ToolNode. El gráfico vuelve al nodo de razonamiento después de cada respuesta de herramienta.

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 (
        "La herramienta de desafío falló. No intente reintentar automáticamente. "
        "Devuelva el flujo de trabajo a la revisión del 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()

La referencia de ToolNode de LangGraph documenta que ToolNode acepta instancias BaseTool, ejecuta llamadas a herramientas y admite manejo de errores configurable. Esto lo hace adecuado para una rama de recuperación que debe ser observable y predecible.

Proporcione una instrucción estrecha al agente

El modelo necesita suficiente contexto para llamar a la herramienta correcta, pero no debe recibir autoridad sin restricciones. Construya el mensaje desde datos de aplicación validados:

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

messages = [
    (
        "system",
        "Usted opera solo en flujos aprobados. Si un reCAPTCHA soportado bloquea el siguiente paso, llame a la herramienta solve_captcha de CapSolver una vez con la URL y clave del sitio exactas proporcionadas por la aplicación. Nunca invente un objetivo o solicite credenciales. Si la resolución falla, deténgase y solicite revisión del operador.",
    ),
    (
        "user",
        "Continúe con la tarea de staging aprobada. El navegador informó un reCAPTCHA v2 en {request['website_url']} con clave del sitio {request['website_key']}.",
    ),
]

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

Un límite de recursión evita bucles no controlados en el gráfico. En producción, también restrinja el hostname permitido antes de construir el mensaje y evite almacenar tokens de solución en trazas.

Agregar una lista de permitidos de host antes del gráfico

Las herramientas de CapSolver resuelven lo que se les pide resolver; su aplicación debe decidir qué trabajos son autorizados. Valide la URL de la página fuera del 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("Solo se permiten objetivos HTTPS")
    if parsed.hostname not in ALLOWED_HOSTS:
        raise PermissionError("El host objetivo no está aprobado")
    return url

Use una lista de permitidos específica por inquilino o un manifiesto de flujo firmado cuando múltiples clientes compartan la misma plataforma. No permita que instrucciones en lenguaje natural modifiquen esta política.

Enrutar éxito, fracaso y revisión humana

Un gráfico de recuperación útil necesita tres resultados, no solo "resuelto" y "fallido". Normalice la salida de la herramienta en una decisión de flujo de trabajo:

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": "solución devuelta"}

    error = str(result.get("error", "error desconocido"))
    if attempt == 0 and "timeout" in error.lower():
        return {"status": "retry", "reason": "un reintentó limitado permitido"}

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

No exponga tokens en mensajes del modelo cuando el navegador pueda consumirlos directamente. El límite ideal es: resultado de herramienta → controlador de navegador confiable → resultado de envío → estado enmascarado de vuelta al gráfico.

La FAQ de errores y solución de problemas de CapSolver proporciona caminos de diagnóstico comunes, mientras que la guía de API de respuesta de CapSolver explica el manejo de resultados.

Modo de token vs modo de navegador

El modo de token suele ser más sencillo para parámetros de reCAPTCHA conocidos. El modo de navegador es útil cuando un flujo autorizado de Playwright necesita detect() y solve_on_page() en la misma sesión. La documentación del agente de CapSolver mapea solve_captcha a la resolución de token del núcleo y solve_on_page a la recuperación del navegador.

Observabilidad sin revelar secretos

Registre transiciones de gráfico y métricas operativas, no valores sensibles. Los campos útiles incluyen:

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 la clave de API de CapSolver, el token de solución completo, cookies autenticadas o datos de formulario. Aplicar enmascaramiento de trazas antes de enviar eventos a sistemas de observabilidad externos.

Código adicional: Use el código WEBS en Panel de CapSolver para obtener un 5% adicional en cada recarga.

Lista de verificación de producción

Un solucionador de reCAPTCHA de LangGraph en producción debe tener una lista de permitidos de hostname, política de tarea fija, manejo de vida útil corta de token, reintentos acotados, enmascaramiento de trazas, condiciones de parada explícitas y un nodo de revisión del operador. Prúebelo contra una página de staging aprobada antes de conectarlo a automatización no supervisada.

La FAQ de resolución de CAPTCHA de CapSolver cubre el comportamiento de la tarea, y la guía de raspado con Python de CapSolver proporciona prácticas de automatización de navegadores.

Uso responsable

Use este flujo solo en sistemas que posea, pruebe o tenga permiso explícito para automatizar. La resolución de desafíos no otorga derechos de acceso. Respete los términos del sitio, límites de tasa, obligaciones de privacidad y restricciones de propósito. Requiera confirmación humana antes de que el gráfico envíe formularios, cambie datos de cuenta o realice cualquier acción de alto impacto.

Conclusión

Un solucionador de reCAPTCHA de LangGraph es más confiable cuando la resolución es un nodo de herramienta explícito con enrutamiento estricto. Cargue las herramientas listas de CapSolver, víalas al modelo, ejecútelas a través de ToolNode y mantenga la autorización, secretos, reintentos y consumo de token en código de aplicación determinista. Esto da al agente una capacidad de recuperación sin darle control sin restricciones.

Comience con CapSolver, valide el gráfico contra un flujo de trabajo de staging aprobado y agregue enmascaramiento de trazas y revisión humana antes de escalar.

Preguntas frecuentes

¿Qué importación de CapSolver debo usar con LangGraph?

Use from capsolver_agent.langchain_tools import get_langchain_tools, luego llame a get_langchain_tools(api_key=...) para obtener herramientas compatibles con LangChain que se puedan pasar a ToolNode.

¿Qué entradas se requieren para el modo de token de reCAPTCHA v2?

La URL de la página y la clave del sitio de reCAPTCHA son requeridas. Los campos de Enterprise, invisible, acción o sesión deben incluirse solo cuando la página autorizada realmente los use.

¿Debe recibir el modelo de LangGraph el token de solución?

Prefiera enviar el token directamente desde la capa de herramienta confiable al controlador de navegador. Devuelva solo un evento de éxito o fracaso enmascarado al gráfico de razonamiento cuando sea posible.

¿Cuántos reintentos automáticos debe permitir el gráfico?

Normalmente, un reintentó limitado es suficiente para un tiempo de espera transitorio. Los rechazos repetidos deben enrutar a revisión humana porque la URL, clave, sesión o configuración de página pueden ser incorrectas.

¿Puede manejar este patrón desafíos de navegador dinámicos?

Sí. Use los métodos del núcleo de CapSolver capaces de navegador a través de una herramienta controlada cuando el flujo necesite detección y recuperación a nivel de página en la misma sesión de Playwright.