Cómo resolver Cloudflare Turnstile en Agentes de CrewAI

Cloudflare Turnstile está reemplazando rápidamente los CAPTCHAs tradicionales en las aplicaciones web modernas. Cuando los flujos de trabajo multiagente de CrewAI encuentran páginas protegidas por Turnstile durante la investigación web, la recopilación de datos o los flujos de trabajo automatizados, todo el equipo se detiene. El SDK capsolver-core de CapSolver resuelve los desafíos de Turnstile en 2-5 segundos, integrándose sin problemas con el sistema de herramientas de CrewAI para mantener sus flujos de trabajo multiagente en funcionamiento sin interrupciones.

TL;DR

• Cloudflare Turnstile está implementado en el 25%+ de las aplicaciones web modernas, convirtiéndolo en el sistema de verificación más rápido en crecimiento
• CapSolver resuelve Turnstile en 2-5 segundos — más rápido que reCAPTCHA — utilizando el tipo de tarea cloudflare
• La integración con CrewAI utiliza el decorador @tool que envuelve el ejecutor asincrónico de CapSolver
• Solo requiere website_url y website_key (la clave del sitio de Turnstile que comienza con 0x)
• Funciona en modo Token (sin navegador) y modo Browser (detección automática y relleno en páginas en vivo)

¿Por qué los agentes de CrewAI encuentran Cloudflare Turnstile?

Cloudflare Turnstile se ha convertido en el sistema de verificación predeterminado para una parte creciente de la web. A diferencia de reCAPTCHA, Turnstile opera como un "desafío no interactivo" — se ejecuta en segundo plano y solo presenta un widget visible cuando el puntaje de riesgo es elevado. Esto lo hace más difícil de detectar y manejar para los agentes en comparación con los CAPTCHAs tradicionales con casilla de verificación.

Los agentes de CrewAI encuentran Turnstile en plataformas SaaS, sitios de documentación de API, tiendas en línea modernas (especialmente Shopify), portales de fintech y sistemas de gestión de contenido. La documentación de Cloudflare Turnstile indica que el sistema procesa miles de millones de desafíos mensuales en millones de sitios, con un crecimiento del 40%+ anual.

Para los equipos de CrewAI que realizan investigación web o recopilación de datos, Turnstile aparece sin aviso: una página que cargó correctamente ayer puede implementar Turnstile hoy después de que el sitio active el manejo de bots de Cloudflare. El tipo de tarea cloudflare de CapSolver maneja esto de forma transparente.

Lo que necesitas antes de comenzar

# Motor de CapSolver core
pip install git+https://github.com/capsolver-ai/capsolver-core.git
# Herramientas de agente de CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
# CrewAI
pip install crewai crewai-tools

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

Paso 1 — Crear una herramienta para resolver Turnstile en CrewAI

import asyncio
from crewai.tools import tool
from capsolver_agent.schema import create_executor

executor = create_executor(api_key="TU_CLAVE_DE_API_DE_CAPSOLVER")

@tool("Resolver Cloudflare Turnstile")
def solve_turnstile(website_url: str, website_key: str) -> str:
    """Resolver un desafío de Cloudflare Turnstile y devolver el token de verificación.
    
    Use esta herramienta cuando un sitio esté protegido por Cloudflare Turnstile.
    La website_key comienza con '0x' y se puede encontrar en el atributo data-sitekey del elemento div cf-turnstile de la página.
    
    Args:
        website_url: La URL completa de la página protegida por Turnstile
        website_key: La clave del sitio de Turnstile (comienza con 0x)
    
    Returns:
        El token cf-turnstile-response para enviar con las solicitudes
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": "cloudflare",
        "website_url": website_url,
        "website_key": website_key
    }))
    
    if result["success"]:
        return f"Turnstile resuelto en ~3s. Token: {result['solution']['token']}"
    return f"Falló la resolución: {result['error']}"

Paso 2 — Crear un agente de CrewAI con capacidad para resolver Turnstile

from crewai import Agent, Task, Crew, Process

# Agente con resolución de Turnstile
researcher = Agent(
    role="Especialista en Investigación Web",
    goal="Acceder a sitios web protegidos por Cloudflare y recopilar datos",
    backstory="""Investigas sitios web protegidos por Cloudflare Turnstile. 
    Cuando encuentres un desafío de Turnstile (identificado por elementos cf-turnstile 
    o páginas de desafío de Cloudflare), usa la herramienta solve_turnstile con la URL de la página 
    y la clave del sitio (que comienza con 0x). Envía el token devuelto como 
    cf-turnstile-response.""",
    tools=[solve_turnstile],
    verbose=True
)

# Tarea que requiere resolver Turnstile
research_task = Task(
    description="""Acceder a la página protegida por Cloudflare en {url}.
    La clave del sitio de Turnstile es {site_key}.
    Resolver el desafío de Turnstile y reportar el token.""",
    expected_output="Token de Turnstile para acceder al recurso protegido",
    agent=researcher
)

crew = Crew(agents=[researcher], tasks=[research_task], process=Process.sequential)
result = crew.kickoff(inputs={"url": "https://example.com", "site_key": "0x4AAAAAAA..."})

Paso 3 — Identificar los parámetros de Turnstile

Las claves del sitio de Turnstile se encuentran en el HTML de la página:

<!-- Widget de Turnstile -->
<div class="cf-turnstile" data-sitekey="0x4AAAAAAABkMYinukE8nzYS"></div>

<!-- O en JavaScript -->
<script>
  turnstile.render('#container', { sitekey: '0x4AAAAAAABkMYinukE8nzYS' });
</script>

La extensión de navegador de CapSolver auto-detecta los parámetros de Turnstile en cualquier página. La guía de resolución de Cloudflare Turnstile proporciona patrones de implementación detallados.

Paso 4 — Manejar Turnstile en modo Browser

Para agentes de CrewAI que usan un navegador con Playwright, utiliza solve_on_page() para la detección automática:

from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

async def solve_turnstile_on_page(url: str):
    cap = create_capsolver(api_key="TU_CLAVE_DE_API_DE_CAPSOLVER")
    
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto(url)
        
        # Detectar y resolver Turnstile automáticamente
        results = await cap.solve_on_page(page)
        for r in results:
            if r.solution:
                print(f"Turnstile resuelto y completado: {r.filled}")
        
        await browser.close()
    await cap.aclose()

¡Obtén tu código de bonificación: Usa el código WEBS en Panel de CapSolver para obtener un 5% adicional de bonificación en cada recarga.

Conclusión

Resolver Cloudflare Turnstile en CrewAI requiere el decorador @tool que envuelve el ejecutor de CapSolver con captcha_type: "cloudflare". Las resoluciones de Turnstile son más rápidas (2-5 segundos) y más económicas que reCAPTCHA, lo que las hace eficientes para flujos de trabajo de CrewAI de alto volumen. CapSolver maneja Turnstile de forma transparente a través de la misma API utilizada para reCAPTCHA, por lo que tus herramientas de CrewAI funcionan en todos los tipos de CAPTCHA sin cambios en el código.

Preguntas frecuentes

¿Es más difícil resolver Cloudflare Turnstile que reCAPTCHA?

No. Turnstile es más rápido de resolver (2-5 segundos en lugar de 5-12 segundos para reCAPTCHA v2) y cuesta menos por resolución. La API de CapSolver maneja ambos a través de la misma interfaz — solo cambia el parámetro captcha_type.

¿Cómo se ve la clave del sitio de Turnstile?

Las claves del sitio de Turnstile siempre comienzan con 0x seguido de caracteres alfanuméricos, como 0x4AAAAAAABkMYinukE8nzYS. Se encuentran en los atributos data-sitekey en los elementos div.cf-turnstile.

¿Puede una herramienta de CrewAI manejar tanto Turnstile como reCAPTCHA?

Sí. Crea una herramienta unificada que acepte captcha_type como parámetro. El ejecutor maneja el enrutamiento al solucionador correcto según el valor del tipo — cloudflare para Turnstile, reCaptchaV2 o reCaptchaV3 para reCAPTCHA.

¿Funciona la resolución de Turnstile sin navegador?

Sí. El modo Token solo requiere website_url y website_key. No se necesita navegador, no se necesita Playwright, no se necesita renderizado de página. El token se devuelve directamente y se puede enviar con solicitudes HTTP como cf-turnstile-response.