Cómo resolver CAPTCHA en LlamaIndex Agents

LlamaIndex orquesta la recuperación de datos, el indexado y los flujos de consulta en fuentes diversas. Cuando estos agentes acceden a fuentes de datos basadas en web protegidas por desafíos CAPTCHA, necesitan un mecanismo para resolverlos y continuar con la ingesta de datos. El paquete capsolver-agent de CapSolver proporciona esquemas de herramientas compatibles con el sistema FunctionTool de LlamaIndex, permitiendo a su agente resolver reCAPTCHA, Cloudflare Turnstile y otros desafíos de verificación como parte de su pipeline de datos.

TL;DR

• Los agentes de LlamaIndex se detienen cuando las fuentes de datos web están protegidas por verificación CAPTCHA
• CapSolver se integra a través del envoltorio FunctionTool de LlamaIndex con resolución asíncrona
• El ejecutor capsolver-agent maneja la resolución y devuelve resultados estructurados para el bucle de razonamiento del agente
• Soporta reCAPTCHA v2/v3 y Cloudflare Turnstile — los tipos más comunes de verificación web
• La integración toma menos de 15 líneas usando create_executor() y FunctionTool.from_defaults()

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

LlamaIndex destaca en la creación de agentes que recuperan, indexan y consultan datos de múltiples fuentes. Cuando estas fuentes incluyen páginas web, APIs o bases de datos protegidas por sistemas CAPTCHA, el pipeline de ingesta de datos del agente se interrumpe. Un agente RAG que necesita indexar documentación de un sitio protegido por CAPTCHA, o un agente de investigación que consulta múltiples fuentes web, no puede continuar sin limpiar la verificación.

El problema es especialmente crítico para la ecosistema de conectores de datos de LlamaIndex. Los conectores basados en web que obtienen páginas para indexar encuentran CAPTCHAS después de múltiples accesos. Sin una herramienta de resolución, el agente o salta la fuente (datos incompletos) o falla por completo (pipeline roto).

La integración de herramientas de CapSolver sigue el patrón estándar de LlamaIndex: definir una función, envolverla como FunctionTool y agregarla a la lista de herramientas del agente. El motor de razonamiento del agente decide cuándo invocar la resolución según el contexto de la tarea.

Lo que necesitas antes de comenzar

# Paquetes de CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# LlamaIndex
pip install llama-index llama-index-llms-openai

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

Paso 1 — Crear una FunctionTool para resolver CAPTCHA

import asyncio
from llama_index.core.tools import FunctionTool
from capsolver_agent.schema import create_executor

executor = create_executor(api_key="TU_CLAVE_DE_API_DE_CAPSOLVER")

def solve_captcha(tipo_captcha: str, url_pagina: str, clave_pagina: str) -> str:
    """Resolver un desafío CAPTCHA y devolver el token de verificación.
    
    Usar cuando se accede a un recurso web protegido por verificación CAPTCHA.
    
    Args:
        tipo_captcha: 'reCaptchaV2', 'reCaptchaV3' o 'cloudflare'
        url_pagina: URL completa de la página protegida por CAPTCHA
        clave_pagina: La clave del sitio (valor del atributo data-sitekey)
    
    Returns:
        Cadena de token resuelto o mensaje de error
    """
    resultado = asyncio.run(executor.execute("solve_captcha", {
        "tipo_captcha": tipo_captcha,
        "url_pagina": url_pagina,
        "clave_pagina": clave_pagina
    }))
    if resultado["éxito"]:
        return f"CAPTCHA resuelto. Token: {resultado['solución']['token']}"
    return f"Fallo: {resultado['error']}"

# Envolver como FunctionTool de LlamaIndex
captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha,
    nombre="solve_captcha",
    descripción="Resolver desafíos CAPTCHA (reCAPTCHA v2/v3, Cloudflare Turnstile) en páginas web protegidas"
)

Paso 2 — Crear un agente de LlamaIndex con capacidad de CAPTCHA

from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

# Crear LLM
llm = OpenAI(model="gpt-4o", temperatura=0)

# Crear agente con herramienta de resolución de CAPTCHA
agente = ReActAgent.from_tools(
    herramientas=[captcha_tool],
    llm=llm,
    verbose=True
)

# Ejecutar al agente
respuesta = agente.chat(
    "Necesito acceder a https://example.com/data que tiene un reCAPTCHA v2. "
    "La clave del sitio es 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
    "Resuélvelo y dime el token."
)
print(respuesta)

Paso 3 — Integrar con conectores de datos de LlamaIndex

Para agentes que ingieren datos web, combinar resolución de CAPTCHA con carga de datos:

from llama_index.core import VectorStoreIndex, Document

def fetch_pagina_protegida(url: str, clave_sitio: str) -> str:
    """Obtener una página protegida por CAPTCHA resolviendo primero."""
    # Resolver el CAPTCHA
    token = solve_captcha("reCaptchaV2", url, clave_sitio)
    if "Fallo" in token:
        return ""
    
    # Usar el token para acceder a la página
    import requests
    respuesta = requests.post(url, data={"g-recaptcha-response": token.split("Token: ")[1]})
    return respuesta.text

# Crear una herramienta personalizada para ingesta de datos protegidos
herramienta_fetch_protegida = FunctionTool.from_defaults(
    fn=fetch_pagina_protegida,
    nombre="fetch_protected_page",
    descripción="Obtener contenido de una página web protegida por CAPTCHA resolviendo la verificación primero"
)

# Agente con capacidad de resolución y obtención
agente_datos = ReActAgent.from_tools(
    herramientas=[captcha_tool, herramienta_fetch_protegida],
    llm=llm,
    verbose=True
)

Paso 4 — Patrones de producción

def solve_captcha_con_reintento(tipo_captcha: str, url_pagina: str, clave_pagina: str, max_reintentos: int = 3) -> str:
    """Resolución de CAPTCHA de nivel de producción con lógica de reintento."""
    for intento in range(max_reintentos):
        resultado = asyncio.run(executor.execute("solve_captcha", {
            "tipo_captcha": tipo_captcha,
            "url_pagina": url_pagina,
            "clave_pagina": clave_pagina
        }))
        if resultado["éxito"]:
            return f"Resuelto (intento {intento+1}). Token: {resultado['solución']['token']}"
        if intento < max_reintentos - 1:
            import time
            time.sleep(3)
    return f"Fallo tras {max_reintentos} intentos: {resultado.get('error')}"

# Herramienta de producción con reintento
herramienta_captcha_produccion = FunctionTool.from_defaults(
    fn=solve_captcha_con_reintento,
    nombre="solve_captcha",
    descripción="Resolver CAPTCHA con reintento automático en caso de fallo"
)

¡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.

La documentación de la API de CapSolver cubre parámetros adicionales. Para identificar tipos de CAPTCHA, usa la extensión de CapSolver. La guía de scraping web de CapSolver cubre patrones de recolección de datos aplicables a conectores de datos de LlamaIndex.

Conclusión

Integrar la resolución de CAPTCHA en agentes de LlamaIndex requiere envolver el ejecutor de CapSolver en un FunctionTool y agregarlo a la lista de herramientas de su agente ReAct. El bucle de razonamiento del agente decide cuándo invocar la resolución según el contexto de la tarea. CapSolver proporciona la infraestructura de resolución que maneja reCAPTCHA y Cloudflare Turnstile a través de una API unificada, manteniendo sus pipelines de datos de LlamaIndex en funcionamiento sin interrupciones.

Preguntas frecuentes

¿Funciona CapSolver con el agente asíncrono de LlamaIndex?

Sí. El ejecutor capsolver-agent es totalmente asíncrono. Para agentes asíncronos de LlamaIndex, use await executor.execute() directamente en lugar de envolverlo con asyncio.run().

¿Puedo usar esto con los conectores del lector web de LlamaIndex?

Sí. Combine la herramienta de resolución de CAPTCHA con lectores web personalizados que manejen la verificación antes de obtener el contenido de la página. El agente puede resolver el CAPTCHA primero, luego pasar el token al lector web para acceso autenticado.

¿Qué pasa si mi agente de LlamaIndex encuentra un tipo de CAPTCHA desconocido?

La herramienta get_supported_captchas devuelve la lista de tipos soportados. Si el agente encuentra un tipo no soportado, recibe un mensaje de error claro y puede informar esto al usuario en lugar de fallar silenciosamente.

¿Cómo se compara esto con usar capsolver-mcp con LlamaIndex?

capsolver-mcp es para clientes MCP (Claude Desktop, Cursor). Para agentes de LlamaIndex que se ejecutan en código, use capsolver-agent con FunctionTool — le da control programático directo dentro del marco de LlamaIndex.