Cómo resolver reCAPTCHA en LangChain

reCAPTCHA es el desafío de verificación más común que los agentes de IA encuentran al navegar por la web. Los agentes de LangChain que realizan recopilación de datos, envío de formularios o flujos de trabajo de múltiples pasos encuentran casillas de reCAPTCHA v2 y desafíos invisibles en páginas de inicio de sesión, resultados de búsqueda y contenido protegido. Este tutorial demuestra cómo resolver reCAPTCHA v2 específicamente dentro de LangChain usando el paquete capsolver-agent de CapSolver, con ejemplos completos de código para los modos Token y Browser.

TL;DR

• reCAPTCHA v2 es el tipo de CAPTCHA más frecuentemente encontrado por los agentes web de LangChain
• Las herramientas de LangChain de CapSolver resuelven reCAPTCHA v2 (casilla y invisible) en 5-12 segundos en promedio
• El modo Token requiere solo la clave del sitio y la URL — no se necesita navegador
• El modo Browser detecta automáticamente reCAPTCHA en cualquier página y llena el token de vuelta en el DOM
• El paquete capsolver-agent proporciona implementaciones nativas de BaseTool para agentes ReAct de LangChain

¿Por qué reCAPTCHA bloquea a los agentes de LangChain?

reCAPTCHA v2 se implementa en millones de sitios web para distinguir usuarios humanos del tráfico automatizado. Cuando un agente de LangChain navega a una página protegida — ya sea para enriquecimiento de clientes, extracción de datos o automatización de flujos de trabajo — el motor de análisis de riesgo de Google evalúa la sesión. Navegadores automatizados, entornos headless y patrones de navegación rápidos activan el desafío de reCAPTCHA, deteniendo la ejecución del agente.

El desafío aparece en dos formas: la casilla visible ("No soy un robot") que requiere interacción, y la variante invisible que se activa silenciosamente basada en el puntaje de riesgo. Ambas formas requieren una presentación válida del token para continuar. Sin un mecanismo de resolución, el agente de LangChain no puede continuar con su tarea y toda la cadena falla.

Documentación de reCAPTCHA de Google confirma que el sistema utiliza análisis de riesgo avanzado incluyendo verificaciones del entorno del navegador, patrones de interacción y comportamiento histórico. Esto hace que reCAPTCHA sea particularmente desafiante para agentes automatizados que carecen de patrones de navegación similares a los humanos.

El servicio de resolución de CapSolver, impulsado por IA, maneja reCAPTCHA v2 generando tokens válidos a través de su infraestructura en la nube, evitando la necesidad de interacción pixel-perfecta o reconocimiento de imágenes dentro del contexto del agente.

Lo que necesitas antes de comenzar

Instala los paquetes requeridos:

# Motor principal (dependencia requerida)
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Herramientas de agente con soporte para LangChain
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

# Entorno de ejecución de LangChain
pip install langchain-openai langgraph

Establece las variables de entorno:

export CAPSOLVER_API_KEY="tu-clave-de-api-de-capsolver"
export OPENAI_API_KEY="tu-clave-de-api-de-openai"

También necesitas la clave del sitio de reCAPTCHA de tu página objetivo. Usa la extensión de navegador de CapSolver para identificarla, o inspecciona el código fuente de la página para encontrar atributos data-sitekey. La guía de identificación de reCAPTCHA explica cómo distinguir entre variantes de v2 (casilla, invisible) y v3.

Paso 1 — Identificar los parámetros de reCAPTCHA v2 en la página objetivo

Qué hacer

Localiza la clave del sitio de reCAPTCHA en tu página objetivo. Abre las herramientas de desarrollador del navegador y busca el código fuente de la página:

<!-- reCAPTCHA v2 visible (casilla) -->
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>

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

Registra tres valores: data-sitekey, la URL completa de la página y si es visible o invisible (verifica si hay data-size="invisible").

Para detección programática usando el SDK de 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="TU_CLAVE_DE_API")
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto(url)
        
        # Detectar automáticamente todos los CAPTCHAs en la página
        infos = await cap.get_captcha_info(page)
        for info in infos:
            print(f"Tipo: {info.type}, Clave: {info.website_key}")
        
        await browser.close()
    await cap.aclose()

Por qué esto importa

La clave del sitio es el parámetro esencial para la resolución de reCAPTCHA. Sin ella, el servicio de resolución no puede generar un token válido para el sitio específico. Páginas diferentes en el mismo dominio pueden usar claves de sitio diferentes, por lo que siempre verifica por página.

Errores comunes a evitar

• Usar una clave de prueba en producción: Google proporciona claves de prueba (como 6LeIxAcT...) que siempre pasan. Los sitios reales usan claves únicas que requieren resolución real.
• Confundir v2 con v3: reCAPTCHA v3 usa un tipo de tarea diferente y requiere page_action. Verifica la fuente del script — v3 carga a través de ?render=SITE_KEY en lugar de un elemento div.

Paso 2 — Resolver reCAPTCHA v2 con herramientas de LangChain (modo Token)

Qué hacer

Usa las herramientas capsolver-agent de LangChain para resolver reCAPTCHA v2 dentro del flujo de trabajo de tu 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():
    # Obtener herramientas de LangChain de CapSolver
    tools = get_langchain_tools(api_key="TU_CLAVE_DE_API_DE_CAPSOLVER")
    
    # Crear agente ReAct
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent = create_react_agent(llm, tools=tools)
    
    # Pedir al agente que resuelva reCAPTCHA
    result = await agent.ainvoke({
        "messages": [("user", 
            "Resuelve el reCAPTCHA v2 en https://example.com/login. "
            "La clave del sitio es 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
            "Devuelve el token que puedo usar para enviar el formulario."
        )]
    })
    
    print(result["messages"][-1].content)

asyncio.run(solve_recaptcha_with_agent())

Para ejecución directa sin el bucle del agente (cuando quieres control programático):

from capsolver_agent.schema import create_executor

async def solve_recaptcha_direct():
    executor = create_executor(api_key="TU_CLAVE_DE_API_DE_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 resuelto! Token: {token[:60]}...")
        # Envía este token como 'g-recaptcha-response' en tu solicitud POST del formulario
        return token
    else:
        print(f"Fallo: {result['error']}")
        return None

El token devuelto debe ser enviado como el campo g-recaptcha-response en la solicitud POST del formulario. La documentación de resolución de reCAPTCHA v2 proporciona detalles adicionales sobre los patrones de envío del token.

Por qué esto importa

El modo Token es el enfoque más rápido para reCAPTCHA v2 — tiempo promedio de resolución de 5-12 segundos sin sobrecarga de navegador. Para agentes de LangChain que ya conocen los parámetros del sitio objetivo, esto proporciona una resolución inmediata de CAPTCHA sin lanzar una instancia de navegador.

Errores comunes a evitar

• No enviar el token rápidamente: los tokens de reCAPTCHA expiran después de aproximadamente 120 segundos. Envía el formulario inmediatamente después de recibir el token.
• Olvidar la bandera invisible: para reCAPTCHA v2 invisible, el enfoque de resolución es el mismo, pero es posible que necesites activar el callback de envío del formulario después de la inyección.

Paso 3 — Manejar reCAPTCHA v2 invisible

Qué hacer

reCAPTCHA v2 invisible funciona de manera idéntica desde la perspectiva de la API — el mismo tipo de tarea reCaptchaV2 maneja ambas variantes:

# reCAPTCHA v2 invisible — misma llamada a la API
result = await executor.execute("solve_captcha", {
    "captcha_type": "reCaptchaV2",
    "website_url": "https://example.com/checkout",
    "website_key": "6Ld_SITE_KEY_HERE"
    # No se necesita bandera adicional — CapSolver maneja invisible automáticamente
})

La diferencia está en cómo inyectas el token. reCAPTCHA invisible generalmente se vincula a un clic de botón o evento de envío de formulario. Después de obtener el token, activa el callback:

# En un contexto de Playwright/navegador después de resolver:
await page.evaluate(f"""() => {{
    document.getElementById('g-recaptcha-response').innerHTML = '{token}';
    // Activar el callback vinculado
    if (typeof ___grecaptcha_cfg !== 'undefined') {{
        const clients = ___grecaptcha_cfg.clients;
        for (const key in clients) {{
            const client = clients[key];
            // Encontrar y llamar al callback
            if (client && client.L && client.L.L && client.L.L.callback) {{
                client.L.L.callback('{token}');
            }}
        }}
    }}
}}""")

La guía para identificar el callback de reCAPTCHA explica cómo localizar la función de callback correcta para cualquier sitio.

Paso 4 — Usar el modo Browser para detección y resolución automáticas de reCAPTCHA

Qué hacer

Cuando tu agente de LangChain maneja un navegador y encuentra reCAPTCHA dinámicamente, usa solve_on_page() para detección y llenado 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 y resolver reCAPTCHA automáticamente en cualquier página."""
    cap = create_capsolver(api_key="TU_CLAVE_DE_API_DE_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")
        
        # Una sola llamada maneja todo: detectar → resolver → llenar
        results = await cap.solve_on_page(page)
        
        for r in results:
            if r.solution:
                print(f"Resuelto {r.info.type}: token={r.solution.token[:50]}...")
                print(f"Token llenado en la página: {r.filled}")
            else:
                print(f"Fallo al resolver {r.info.type}: {r.error}")
        
        # Después de resolver, la página está lista — enviar el formulario
        submit_button = page.locator('button[type="submit"]')
        if await submit_button.count() > 0:
            await submit_button.click()
            await page.wait_for_navigation()
            print(f"Formulario enviado. URL actual: {page.url}")
        
        await browser.close()
    await cap.aclose()

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

El modo Browser es especialmente poderoso porque lee los parámetros de reCAPTCHA directamente del DOM en tiempo real — no se necesita extraer manualmente la clave del sitio. El SDK identifica el tipo de CAPTCHA, lee data-sitekey, lo resuelve y escribe el token de vuelta en el campo g-recaptcha-response automáticamente.

Obtén tu código de bonificación: usa el código WEBS en Dashboard de CapSolver para obtener un 5% adicional de bonificación en cada recarga. Ideal para desarrolladores de LangChain que construyen agentes que manejan desafíos de reCAPTCHA.

Paso 5 — Construir un agente de producción de LangChain con manejo de reCAPTCHA

Qué hacer

Combina la resolución de reCAPTCHA con otras herramientas para un flujo de trabajo 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="TU_CLAVE_DE_API_DE_CAPSOLVER")
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent = create_react_agent(llm, tools=capsolver_tools)
    
    # Tarea de múltiples pasos que requiere resolución de reCAPTCHA
    result = await agent.ainvoke({
        "messages": [("user",
            "Necesito acceder a un recurso protegido. "
            "Primero, resuelve el reCAPTCHA v2 en https://example.com/gate "
            "(clave del sitio: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI), "
            "luego dime el token para que pueda continuar con mi solicitud."
        )]
    })
    
    return result["messages"][-1].content

asyncio.run(production_agent())

Para agentes que necesitan manejar múltiples versiones de reCAPTCHA en diferentes sitios, las mismas herramientas manejan tanto v2 como v3 — solo cambia el parámetro captcha_type de reCaptchaV2 a reCaptchaV3.

La página de productos de CapSolver lista todos los tipos de CAPTCHA soportados y sus precios, ayudándote a estimar los costos para tu despliegue de agente de LangChain.

Conclusión

Resolver reCAPTCHA en LangChain requiere el paquete capsolver-agent con el extra de LangChain, que proporciona implementaciones nativas de BaseTool. El modo Token maneja claves de sitio conocidas en 5-12 segundos sin necesidad de navegador, mientras que el modo Browser detecta y llena tokens de reCAPTCHA en cualquier página. CapSolver impulsa la infraestructura de resolución de IA, soportando variantes de reCAPTCHA v2 (casilla e invisible) a través de una interfaz unificada.

Empieza identificando la clave del sitio en tu página objetivo, luego integra get_langchain_tools() en tu agente ReAct. El bucle de razonamiento del agente decide naturalmente cuándo invocar la resolución de reCAPTCHA, haciendo que el manejo de verificación sea una parte transparente de tu flujo de trabajo de automatización.

Preguntas frecuentes

¿Cuál es la tasa de éxito para resolver reCAPTCHA v2 con CapSolver?

CapSolver alcanza una tasa de éxito del 95-99% en desafíos de reCAPTCHA v2. El servicio de resolución impulsado por IA maneja tanto variantes de casilla como invisibles. Los intentos fallidos no se cobran, y la respuesta estructurada permite a tu agente reintentar automáticamente.

¿Cuánto tiempo tarda en resolver reCAPTCHA v2?

El tiempo promedio de resolución de reCAPTCHA v2 es de 5-12 segundos. Esto incluye el tiempo de ida y vuelta de red al servicio de CapSolver y el proceso de reconocimiento de IA. Para flujos de trabajo sensibles al tiempo, el SDK soporta tiempos de espera y intervalos de sondeo configurables.

¿Puede la herramienta de LangChain manejar reCAPTCHA Enterprise?

Sí. Pasa enterprise: true en los parámetros al llamar a solve_captcha. reCAPTCHA Enterprise usa los mismos tipos de tarea v2/v3 pero puede requerir parámetros adicionales como el token s. El servicio de CapSolver maneja las variantes Enterprise de forma transparente.

¿Necesito un navegador para resolver reCAPTCHA en LangChain?

No. El modo de token funciona sin ningún navegador — proporcionas la clave del sitio y la URL, y recibes un token de vuelta. El modo de navegador (requiriendo Playwright) es opcional y se utiliza cuando quieres detección automática y relleno en páginas en vivo. La mayoría de las integraciones de LangChain usan el modo Token por simplicidad y velocidad.

¿Cómo manejo la expiración del token de reCAPTCHA?

Los tokens de reCAPTCHA expiran después de aproximadamente 120 segundos. Solicita el token lo más cercano posible a la presentación del formulario. Si tu flujo de trabajo tiene demoras entre resolver y enviar, implementa un patrón de "resolver justo antes de enviar" en lugar de resolver temprano en la canalización.