Cómo integrar un solucionador de CAPTCHA con LangGraph

TL;DR

• Un solucionador de CAPTCHA de LangGraph debe modelarse como un nodo de herramienta acotada, no oculto dentro del prompt general del agente para navegar.
• El gráfico debe pausarse solo cuando un flujo de trabajo autorizado de navegador detecte un punto de control de reCAPTCHA o Cloudflare Turnstile compatible.
• Pasar la URL de la página, la clave del sitio, el tipo de desafío y los metadatos de acción opcionales como estado estructurado; nunca colocar una clave de API de CapSolver en los mensajes del gráfico.
• Enviar los resultados ready, failed y timeout a través de bordes explícitos para que el agente no intente reintentar indefinidamente.
• Validar el token devuelto en la misma sesión del navegador y detenerse cuando la aplicación de destino lo rechace.

Lo que permite la integración de LangGraph

Un solucionador de CAPTCHA de LangGraph brinda a un flujo de trabajo de IA una ruta de recuperación controlada cuando una tarea autorizada del navegador encuentra un punto de control de verificación compatible. LangGraph sigue siendo responsable de la orquestación, mientras que CapSolver maneja la tarea especializada de CAPTCHA a través de una API o herramienta de agente.

El diseño útil es una pequeña máquina de estados: navegar, detectar, solicitar una solución, aplicar el token, verificar el resultado de la página y continuar o detenerse. Esto mantiene el manejo de CAPTCHA observable y evita que el modelo improvise parámetros o repita llamadas sin límite.

Requisitos previos

Use este patrón solo en sitios y entornos de prueba en los que esté autorizado a automatizar. Necesita una aplicación de LangGraph, una capa de control de navegador, una cuenta de CapSolver y un almacén de secretos del lado del servidor para CAPSOLVER_API_KEY. El paso del navegador debe poder identificar el tipo de desafío y recopilar los parámetros documentados por CapSolver.

La guía del agente de CapSolver describe el flujo de trabajo de agente compatible. La documentación del SDK principal cubre la interfaz programática, mientras que la referencia de herramientas de agente documenta el uso orientado a herramientas.

Definir un contrato de estado de CAPTCHA

El estado del gráfico debe contener solo los valores necesarios para el enrutamiento y la verificación:

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

Mantenga la clave de API fuera de este objeto. El estado del gráfico puede ser registrado o verificado, por lo que las credenciales pertenecen a variables de entorno o un administrador de secretos aprobado.

Crear el nodo solucionador

El nodo solucionador debe traducir el estado conocido en una tarea compatible con CapSolver. El siguiente código es un límite ilustrativo; conéctelo al SDK oficial o al esquema REST utilizado por su servicio.

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",
    }

No permita que el modelo de lenguaje invente websiteKey, el tipo de desafío o la acción. Extraiga estos valores de la página activa o la configuración de la aplicación, y válidelos antes de la llamada a la herramienta.

Canjear su código de bonificación de CapSolver

¡Aumente su presupuesto de automatización instantáneamente!
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en tu Panel de CapSolver

Agregar bordes condicionales en el gráfico

LangGraph debe enrutar según el estado observado en lugar de texto libre del 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"

El nodo apply_token debe operar en la misma sesión del navegador que detectó el desafío. Después de la aplicación, un nodo de verificación separado debe inspeccionar la respuesta de aplicación, la navegación esperada o la confirmación del lado del servidor. Un token solo no es prueba de que el flujo de trabajo tuvo éxito.

Manejar fallos sin bucles de reintentos

Clasifique los fallos antes de decidir qué hacer. Parámetros faltantes son problemas de configuración. Un token rechazado puede indicar un token caducado, URL de página, clave del sitio, acción o contexto de navegador incorrectos. Un tiempo de espera del servicio es operativo y puede justificar un reintentó limitado.

Registre task_id, tipo de desafío, tiempo transcurrido y un código de error sanitizado. No almacene tokens, cookies, credenciales o contenido de página sensible en trazas generales del agente. Escalé a un humano cuando la página solicite una acción que no debe ser autónoma.

Lista de verificación para producción

• Permitir dominios autorizados y tipos de desafío.
• Establecer un tiempo límite fijo y un número máximo de intentos.
• Mantener las credenciales fuera de los prompts y puntos de verificación.
• Aplicar y verificar el token en el contexto de navegador original.
• Agregar aprobación humana alrededor de inicio de sesión, envío, pago o cambios de cuenta.
• Registrar la tasa de finalización y los fallos por motivo, no solo por éxito de llamada a herramienta.

Conclusión

Una integración de CAPTCHA confiable de LangGraph es una rama estrecha y observable con entradas explícitas y condiciones de detención. Mantenga la orquestación del navegador en LangGraph, mantenga los parámetros de CAPTCHA estructurados y verifique el resultado del negocio después de la aplicación del token. CapSolver puede proporcionar la capacidad especializada de CAPTCHA sin convertir todo el agente en un bucle de recuperación opaco.

Preguntas frecuentes

P: ¿Puede LangGraph resolver CAPTCHA por sí mismo?

No. LangGraph orquesta nodos y estado; un navegador autorizado y un servicio de CAPTCHA realizan el trabajo especializado.

P: ¿Qué tipos de CAPTCHA debe soportar el gráfico?

Comience solo con los tipos documentados en la superficie actual del agente de CapSolver, como reCAPTCHA v2, reCAPTCHA v3 y Cloudflare Turnstile.

P: ¿Debe almacenarse la clave de API en el estado de LangGraph?

No. Almacene la clave de API en una variable de entorno o administrador de secretos del lado del servidor, ya que el estado del gráfico puede ser persistido o registrado.

P: ¿Cuántas veces debe reintentar el nodo?

Use uno o dos intentos limitados y deténgase ante rechazos repetidos, parámetros faltantes o incertidumbre en la autorización.