Cómo resolver CAPTCHA en flujos de trabajo multiagente de CrewAI

CrewAI orquesta múltiples agentes de IA trabajando juntos en tareas complejas: investigación, recolección de datos, creación de contenido y automatización de flujos de trabajo. Cuando cualquier agente en el equipo se enfrenta a un desafío CAPTCHA durante una interacción web, toda la pipeline de múltiples agentes se detiene. El paquete capsolver-agent de CapSolver se integra directamente en los flujos de trabajo de CrewAI, otorgando a sus agentes la capacidad de resolver reCAPTCHA, Cloudflare Turnstile y otros desafíos de verificación sin interrumpir el flujo de ejecución colaborativa.

TL;DR

• Los flujos de trabajo de múltiples agentes de CrewAI se detienen cuando algún miembro del equipo encuentra un CAPTCHA durante tareas web
• CapSolver proporciona esquemas de herramientas compatibles con el sistema de registro de herramientas personalizado de CrewAI
• El ejecutor capsolver-agent resuelve mediante el servicio de inteligencia artificial de CapSolver y devuelve resultados estructurados
• Soporta reCAPTCHA v2/v3 (incluyendo Enterprise) y Cloudflare Turnstile
• La integración requiere menos de 15 líneas de código usando create_executor() y el decorador @tool de CrewAI

¿Por qué los agentes de CrewAI necesitan resolver CAPTCHA?

CrewAI permite a equipos de agentes de IA especializados colaborar en tareas que requieren múltiples capacidades. Un equipo típico podría incluir un agente investigador que navegue por la web, un agente analista que procese datos y un agente escritor que produzca informes. Cuando el agente investigador se encuentra con un CAPTCHA en un sitio web objetivo, no puede continuar - y como los agentes de CrewAI pasan salidas secuencialmente, todo el flujo de trabajo del equipo se detiene.

Este problema se agrava en CrewAI porque múltiples agentes pueden necesitar acceso a la web. Un equipo de enriquecimiento de clientes podría tener un agente que extraiga datos de empresas y otro que verifique información de contacto - ambos encontrando CAPTCHAS en sitios diferentes simultáneamente. Sin un mecanismo de resolución, los equipos de producción requieren supervisión constante por parte de humanos, lo que contradice el propósito de la orquestación autónoma de múltiples agentes.

Según los datos de producción de CapSolver, aproximadamente el 30% de las tareas web de los agentes encuentran desafíos de verificación. Para un equipo de CrewAI que ejecuta 10 tareas dependientes de la web, eso significa 3 puntos potenciales de detención por ejecución - cada uno requiriendo intervención manual sin resolución automatizada.

Lo que necesitas antes de comenzar

Instale los paquetes requeridos:

# Motor de CapSolver (dependencia requerida)
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

# Marco de CrewAI
pip install crewai crewai-tools

Establezca las variables de entorno:

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

Asegúrese de tener una cuenta de CapSolver con créditos de API cargados. La página de precios de CapSolver muestra las tarifas actuales por tipo de CAPTCHA.

Paso 1 — Crear una herramienta para resolver CAPTCHA para CrewAI

Qué hacer

CrewAI utiliza herramientas personalizadas definidas con el decorador @tool. Envuelva el ejecutor de CapSolver en una herramienta compatible con CrewAI:

import asyncio
from crewai import Agent, Task, Crew
from crewai.tools import tool
from capsolver_agent.schema import create_executor

# Crear el ejecutor de CapSolver
executor = create_executor(api_key="SU_CLAVE_DE_API_DE_CAPSOLVER")

@tool("Resolver CAPTCHA")
def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """Resolver un desafío CAPTCHA y devolver el token.
    Use esta herramienta cuando encuentre un CAPTCHA en un sitio web.
    
    Args:
        captcha_type: El tipo de CAPTCHA - 'reCaptchaV2', 'reCaptchaV3' o 'cloudflare'
        website_url: La URL completa de la página con el CAPTCHA
        website_key: La clave del sitio (valor del atributo data-sitekey)
    
    Returns:
        El token del CAPTCHA resuelto para enviar con el formulario
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }))
    
    if result["success"]:
        return f"CAPTCHA resuelto exitosamente. Token: {result['solution']['token']}"
    else:
        return f"Fallo al resolver CAPTCHA: {result['error']}"

Esta herramienta sigue el patrón estándar de CrewAI - el decorador @tool la registra con un nombre y descripción que el LLM del agente utiliza para decidir cuándo invocarla.

Por qué esto importa

Los agentes de CrewAI seleccionan herramientas basándose en sus descripciones. Una herramienta de resolución de CAPTCHA bien descrita permite al agente reconocer de forma autónoma cuándo necesita resolverlo y invocar la herramienta con los parámetros correctos. El formato de retorno estructurado da al agente retroalimentación clara sobre éxito o fracaso.

Errores comunes a evitar

• Usar async directamente en herramientas de CrewAI: La ejecución de herramientas de CrewAI es sincrónica. Envuelva las llamadas async de CapSolver con asyncio.run() dentro de la función de herramienta.
• Descripciones de herramientas vagas: El LLM necesita una descripción clara para saber cuándo usar la herramienta. Incluya nombres específicos de tipos de CAPTCHA y explicaciones de parámetros.

Paso 2 — Crear un agente de CrewAI con capacidad de resolver CAPTCHA

Qué hacer

Cree un agente de CrewAI que tenga la capacidad de resolver CAPTCHA como una de sus herramientas disponibles:

from crewai import Agent

# Agente investigador con capacidad de resolver CAPTCHA
researcher = Agent(
    role="Especialista en Investigación Web",
    goal="Recopilar datos de sitios web, manejando cualquier desafío CAPTCHA encontrado",
    backstory="""Eres un experto investigador web que recopila datos de diversas 
    fuentes en línea. Cuando encuentras un desafío CAPTCHA en un sitio web, usas 
    la herramienta solve_captcha para resolverlo y continuar tu investigación. Sabes 
    identificar los tipos de CAPTCHA: reCaptchaV2 (casilla o invisible), reCaptchaV3 
    (basado en puntuación) y cloudflare (widget Turnstile).""",
    tools=[solve_captcha],
    verbose=True
)

Para equipos que necesiten múltiples agentes con acceso a la web, otorgue la herramienta CAPTCHA a cada agente que pueda encontrar verificación:

# Agente recolector de datos
data_collector = Agent(
    role="Especialista en Recolección de Datos",
    goal="Extraer datos estructurados de sitios web objetivo",
    backstory="Recopilas datos de fuentes web y manejas desafíos CAPTCHA usando la herramienta solve_captcha.",
    tools=[solve_captcha],
    verbose=True
)

# Agente de verificación
verifier = Agent(
    role="Especialista en Verificación de Datos", 
    goal="Verificar los datos recopilados contra fuentes autoritativas",
    backstory="Verificas la precisión de los datos revisando fuentes oficiales, resolviendo CAPTCHAS cuando sea necesario.",
    tools=[solve_captcha],
    verbose=True
)

Paso 3 — Ensamblar el equipo con tareas conscientes de CAPTCHA

Qué hacer

Defina tareas que puedan requerir resolución de CAPTCHA y ensámblalas en un equipo:

from crewai import Task, Crew, Process

# Tarea que puede encontrar CAPTCHA
research_task = Task(
    description="""Investiga el sitio web objetivo en {url}. 
    Si encuentras un desafío CAPTCHA, identifica su tipo y clave del sitio,
    luego usa la herramienta solve_captcha para obtener un token.
    El sitio usa reCAPTCHA v2 con clave del sitio: {site_key}.
    Recopila los datos necesarios después de resolver el CAPTCHA.""",
    expected_output="Datos recopilados del sitio web objetivo con token CAPTCHA si es necesario",
    agent=researcher
)

# Tarea de análisis (depende de los resultados de la investigación)
analysis_task = Task(
    description="Analiza los datos recopilados por el investigador y produce un informe de resumen.",
    expected_output="Informe de análisis estructurado de los datos recopilados",
    agent=data_collector
)

# Crear el equipo
crew = Crew(
    agents=[researcher, data_collector],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
    verbose=True
)

# Ejecutar el equipo
result = crew.kickoff(inputs={
    "url": "https://example.com/data",
    "site_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
})
print(result)

El proceso secuencial asegura que el investigador complete (incluyendo la resolución de CAPTCHA) antes de que el recolector de datos comience el análisis. Para ejecución paralela, cada agente maneja por separado los CAPTCHAS en sus sitios asignados.

Por qué esto importa

La fortaleza de CrewAI es la colaboración de múltiples agentes. Al otorgar capacidad de resolución de CAPTCHA a los agentes que la necesiten, el equipo opera de forma autónoma de extremo a extremo. No se necesita intervención humana cuando aparecen desafíos de verificación - el agente reconoce la situación, invoca la herramienta y continúa.

Paso 4 — Manejar múltiples tipos de CAPTCHA en CrewAI

Diferentes sitios web utilizan sistemas de CAPTCHA diferentes. Cree herramientas especializadas para escenarios comunes:

@tool("Resolver reCAPTCHA v3")
def solve_recaptcha_v3(website_url: str, website_key: str, page_action: str = "verify") -> str:
    """Resolver un desafío reCAPTCHA v3 con un token de alta puntuación.
    Úsalo cuando el sitio utilice reCAPTCHA v3 invisible (basado en puntuación, sin casilla visible).
    
    Args:
        website_url: La URL completa de la página
        website_key: La clave del sitio reCAPTCHA
        page_action: El nombre de la acción para la puntuación v3 (predeterminado: 'verify')
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": "reCaptchaV3",
        "website_url": website_url,
        "website_key": website_key,
        "page_action": page_action,
        "min_score": 0.7
    }))
    if result["success"]:
        return f"reCAPTCHA v3 resuelto. Token: {result['solution']['token']}"
    return f"Fallo: {result['error']}"

@tool("Resolver Cloudflare Turnstile")
def solve_turnstile(website_url: str, website_key: str) -> str:
    """Resolver un desafío Cloudflare Turnstile.
    Úsalo cuando el sitio esté protegido por Cloudflare y muestre un widget Turnstile.
    
    Args:
        website_url: La URL completa de la página
        website_key: La clave del sitio Turnstile (comienza con 0x)
    """
    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. Token: {result['solution']['token']}"
    return f"Fallo: {result['error']}"

La guía de reCAPTCHA de CapSolver y la guía de Cloudflare Turnstile proporcionan detalles adicionales sobre los parámetros y comportamiento de cada tipo de CAPTCHA.

Obtén tu código de bonificación: Usa el código WEBS en el Panel de CapSolver para obtener un 5% adicional en cada recarga. Perfecto para equipos que ejecutan flujos de trabajo de múltiples agentes de CrewAI a gran escala.

Paso 5 — Patrones de producción para CrewAI + CapSolver

Qué hacer

Para implementaciones de producción de CrewAI, agregue manejo de errores y lógica de reintentos:

@tool("Resolver CAPTCHA con reintentos")
def solve_captcha_robust(captcha_type: str, website_url: str, website_key: str) -> str:
    """Resolver un CAPTCHA con reintentos automáticos en caso de fallo.
    Intenta resolver hasta 3 veces antes de reportar el fallo.
    """
    for attempt in range(3):
        result = asyncio.run(executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        }))
        if result["success"]:
            return f"Resuelto en el intento {attempt + 1}. Token: {result['solution']['token']}"
        if attempt < 2:
            import time
            time.sleep(3)
    return f"Fallo después de 3 intentos: {result.get('error', 'Error desconocido')}"

Para equipos que procesen múltiples sitios, implemente una verificación de saldo antes de comenzar:

@tool("Verificar saldo del solucionador de CAPTCHA")
def check_balance() -> str:
    """Verificar el saldo restante para créditos de resolución de CAPTCHA."""
    result = asyncio.run(executor.execute("get_balance", {}))
    if result["success"]:
        return f"Saldo: ${result['balance']:.2f}"
    return "No se pudo verificar el saldo"

La documentación de scraping web de CapSolver cubre patrones adicionales para recolección de datos de alto volumen que aplican a agentes de investigación de CrewAI. Para agentes que usen automatización de navegadores, la extensión de CapSolver ayuda a identificar parámetros de CAPTCHA durante el desarrollo.

Conclusión

Integrar la resolución de CAPTCHA en flujos de trabajo de múltiples agentes de CrewAI requiere envolver el ejecutor de CapSolver en funciones @tool compatibles con CrewAI, asignar esas herramientas a agentes que realicen tareas web y ensamblar equipos que puedan operar de forma autónoma a través de desafíos de verificación. CapSolver proporciona la infraestructura de resolución impulsada por inteligencia artificial que mantiene sus pipelines de múltiples agentes funcionando sin intervención humana.

Comience creando una sola herramienta para resolver CAPTCHA, pruébela con un agente, luego expanda a equipos completos con múltiples agentes que interactúen con la web. El enfoque basado en herramientas significa que los agentes deciden cuándo resolver según el contexto - sin necesidad de lógica de detección de CAPTCHA codificada.

Preguntas frecuentes

¿Pueden múltiples agentes de CrewAI resolver CAPTCHAS simultáneamente?

Sí. Cada agente que tenga la herramienta de resolución de CAPTCHA puede invocarla de forma independiente. La API de CapSolver admite envíos concurrentes de tareas sin límites de tasa, por lo que la ejecución paralela de equipos funciona sin conflictos. Cada resolución se registra con un ID de solicitud único para depuración.

¿Cómo sabe CrewAI cuándo un agente necesita resolver un CAPTCHA?

El LLM del agente razona sobre la situación basándose en la descripción de la herramienta y el contexto de la tarea. Cuando la tarea implica acceder a un recurso protegido por CAPTCHA, el agente reconoce la necesidad y llama a la herramienta de resolución con parámetros adecuados. También puede incluir detalles de CAPTCHA en la descripción de la tarea para guía explícita.

¿Qué ocurre si la resolución de CAPTCHA falla en un flujo de trabajo de CrewAI?

La herramienta devuelve un mensaje de fallo al agente. El agente puede intentar de nuevo, probar parámetros alternativos o reportar el fallo en su salida de tarea. El manejo de errores de CrewAI permite que el equipo continúe con las tareas restantes incluso si una tarea encuentra un CAPTCHA irresoluble.

¿CapSolver es compatible con el modo de proceso jerárquico de CrewAI?

Sí. En el modo jerárquico, el agente gestor delega tareas a los miembros del equipo. Si una tarea delegada requiere resolución de CAPTCHA, el agente asignado usa su herramienta de forma independiente. El gestor recibe el resultado completado sin necesidad de entender los detalles de resolución de CAPTCHA.

¿Cuánto cuesta resolver CAPTCHA por ejecución de CrewAI?

El costo depende del número de CAPTCHAs que se encuentran y de sus tipos. reCAPTCHA v2 cuesta aproximadamente 2-3 por 1.000 resoluciones, reCAPTCHA v3 cuesta 1-2 por 1.000 y Cloudflare Turnstile cuesta 1-2 por 1.000. Un equipo de investigación típico de CrewAI que enfrenta 3-5 CAPTCHAs por ejecución cuesta 0,005-0,015 por ejecución.