CrewAI Solucionador de CAPTCHA: Guía de Código de Herramienta de Agente

TL;DR

• El trabajo del solucionador de CAPTCHA de CrewAI debe usar la pila de agentes de IA de CapSolver como una capa de recuperación explícita, no como lógica de reintentos oculta.
• capsolver-core se adapta a scripts de Playwright, capsolver-agent se adapta a agentes de llamada a herramientas y capsolver-mcp se adapta a clientes compatibles con MCP.
• El patrón seguro es detectar, leer parámetros, resolver una vez con reintentos limitados, completar y luego registrar el estado de la solicitud para revisión.
• Los agentes deben detenerse cuando cambie el alcance de la tarea, cuando la página pida acceso restringido o cuando el manejo de desafíos se repita sin progreso.

Introducción

El trabajo del solucionador de CAPTCHA de CrewAI requiere un límite de herramientas a nivel de código entre planificación, control del navegador y revisión. CapSolver debe integrarse como una capacidad de agente documentada: el navegador o el modelo detecta un desafío de verificación, la herramienta aprobada lo maneja y el agente reanuda solo cuando la tarea autorizada por el usuario original aún sea válida. La documentación oficial de CapSolver AI describe tres capas prácticas: CapSolver para agentes de IA para arquitectura, modo de SDK de núcleo para flujos de Playwright, esquemas de herramientas de agente para llamadas controladas por modelos y herramientas del servicio MCP para clientes que descubran herramientas a través del Protocolo de Contexto de Modelo. Este artículo convierte estas documentaciones en un flujo de trabajo de solucionador de CAPTCHA de CrewAI con código, reglas de detención y campos de registro.

Usar los paquetes oficiales de CapSolver AI

La documentación de CapSolver AI describe tres capas. Use la capa más baja que se ajuste a su modelo de propiedad: SDK de núcleo cuando su código controla el navegador, herramientas de agente cuando un modelo decide cuándo llamar a una herramienta y servicio MCP cuando su cliente de IA debe descubrir herramientas de resolución automáticamente.

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium
export CAPSOLVER_API_KEY="su-clave-de-api-de-capsolver"

La Introducción y inicio rápido explica los roles de los paquetes: capsolver-core expone el motor, capsolver-agent lo envuelve como herramientas y capsolver-mcp expone la misma capacidad a clientes de MCP. Mantenga la clave de API en la configuración del entorno y evite colocarla en prompts, registros, capturas de pantalla o ejemplos de artículos.

Diseño de roles para CrewAI

Una implementación de CrewAI debe otorgar a cada rol una responsabilidad estrecha. El planificador identifica que una página está bloqueada por un desafío de verificación. El trabajador del navegador posee la navegación. El manejador de herramientas de CapSolver posee el paso del desafío. El revisor posee la decisión final cuando la ejecución es incierta.

crew_state = {
    "task_id": "lead-enrichment-042",
    "allowed_domains": ["example.com"],
    "captcha_attempts": 0,
    "max_captcha_attempts": 1,
    "final_state": "planning",
}

def may_call_capsolver(state, current_url):
    if state["captcha_attempts"] >= state["max_captcha_attempts"]:
        return False
    return any(domain in current_url for domain in state["allowed_domains"])

Esta pequeña puerta es lo que mantiene el comportamiento del solucionador de CAPTCHA de CrewAI visible. El crew puede pedir ayuda solo cuando la página esté en el alcance y el presupuesto de reintentos esté disponible.

Patrón de herramientas de agente para decisiones controladas por modelo

Use capsolver-agent cuando el modelo deba elegir cuándo se necesita el manejo de desafíos. La guía de herramientas de agente expone definiciones de herramientas con get_all_tools() y enruta las llamadas de herramientas del modelo a través de create_executor().

import json
from openai import OpenAI
from capsolver_agent.schema import create_executor, get_all_tools

client = OpenAI()
executor = create_executor(api_key="SU_CLAVE_DE_CAPSOLVER", default_timeout=120)
tools = [tool.to_openai_function() for tool in get_all_tools()]

messages = [{
    "role": "user",
    "content": "Continúe con la tarea aprobada del navegador. Si aparece un CAPTCHA, llame a la herramienta de CapSolver una vez y reporte el resultado."
}]

async def run_one_turn():
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
    )

    for call in response.choices[0].message.tool_calls or []:
        args = json.loads(call.function.arguments)
        result = await executor.execute(call.function.name, args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

Para el solucionador de CAPTCHA de CrewAI, vincule este camino de herramientas a una política de revisor. El modelo puede solicitar la herramienta, pero su aplicación decide el alcance de URL permitido, el número máximo de intentos y si el resultado puede usarse para continuar.

Patrón de SDK de núcleo para agentes controlados por navegador

Use capsolver-core cuando su flujo de solucionador de CAPTCHA de CrewAI ya posea una página de Playwright. El camino oficial de SDK de núcleo es detectar, leer la información de CAPTCHA, resolver y devolver el token a la página. La llamada de navegador todo en uno es útil cuando la estructura de la página es dinámica.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

TARGET_URL = "https://example.com/approved-workflow"

async def run_agent_step():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        page = await browser.new_page()
        await page.goto(TARGET_URL, wait_until="domcontentloaded")

        async with create_capsolver(api_key="SU_CLAVE_DE_CAPSOLVER") as cap:
            captcha_types = await cap.detect(page)
            if not captcha_types:
                return "continue_without_challenge"

            results = await cap.solve_on_page(page)
            solved = [r for r in results if r.solution and not r.error]
            if not solved:
                return "stop_for_review"

        return "resume_original_authorized_task"

asyncio.run(run_agent_step())

El detalle de ingeniería importante es el valor de retorno, no solo el token. Su agente debe continuar solo cuando la tarea original aún sea legal, razonable y autorizada por el usuario. Debe detenerse cuando la página pida datos privados, restringidos, sensibles o no autorizados.

Canjear su código promocional de CapSolver

¡Aumente su presupuesto de automatización de inmediato!
Use el código promocional 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

Medidas de seguridad que pertenecen al bucle del agente

Verificaciones de alcance

Antes de llamar a cualquier herramienta de desafío, confirme que la tarea fue autorizada por el usuario, que el objetivo está dentro de la lista de dominios aprobados y que los datos que se acceden son públicos u otros permitidos. Un flujo de trabajo de solucionador de CAPTCHA de CrewAI nunca debe tratar la capacidad técnica como permiso.

Límites de reintentos

Use un pequeño presupuesto de reintentos. Un reintentos de estado de navegador y un reintentos de enfriamiento suelen ser suficientes. Los eventos de desafío repetidos deben crear un ticket de revisión en lugar de continuar en silencio.

Observabilidad

Capture URL, marca de tiempo, tipo de desafío, ruta del paquete de CapSolver, número de intento, estado del resultado y estado final de la página. No almacene contenido de página no relacionado, credenciales, secretos de sesión o datos personales a menos que su política lo permita explícitamente.

Para el solucionador de CAPTCHA de CrewAI, mantenga la ejecución legal y basada en evidencia: respete el comportamiento de los códigos de estado HTTP, los requisitos de accesibilidad, la gestión de riesgos de privacidad y la administración de datos públicos.

Conclusión

Un artículo fuerte sobre solucionador de CAPTCHA de CrewAI debe mostrar caminos de implementación reales, y un flujo de trabajo de producción sólido debe hacer lo mismo. La elección práctica es simple: use capsolver-core para automatización de navegador con código propio, capsolver-agent para agentes de llamada a herramientas y capsolver-mcp para clientes compatibles con MCP. Mantenga el manejo de desafíos acotado, registrado y vinculado a trabajo autorizado por el usuario. Cuando su equipo esté listo para agregar esa capa de recuperación a un flujo de trabajo de agente, comience con CapSolver y la documentación oficial de agentes de IA.

Preguntas frecuentes

¿Qué paquete de CapSolver debe usar un agente de IA primero?

Use capsolver-core cuando su aplicación posea el código del navegador, capsolver-agent cuando un modelo deba llamar a una herramienta y capsolver-mcp cuando el cliente de IA deba descubrir herramientas a través de MCP.

¿Debe el modelo decidir cada reintentos de CAPTCHA?

No. El modelo puede solicitar una llamada a herramienta, pero la aplicación debe imponer el alcance, los límites de reintentos y las condiciones de detención.

¿Puede usarse este flujo en datos privados o restringidos?

No. El manejo de CAPTCHA no otorga permiso. Úselo solo para flujos de trabajo legales, razonables y autorizados por el usuario que respeten los términos del sitio y los derechos de datos.

¿Qué debe registrarse para revisión?

Registre la URL de origen, tipo de desafío, ruta de la herramienta, conteo de intentos, estado del resultado y estado final de la página. Mantenga las credenciales y el contenido de página no relacionado fuera de los registros.