Cómo resolver Cloudflare Turnstile en LlamaIndex Agentes

TL;DR

• Envolver una función estrecha de CapSolver Turnstile con FunctionTool.from_defaults() de LlamaIndex.
• Usar la tarea documentada AntiTurnstileTaskProxyLess con la URL exacta de la página y la clave del sitio.
• Enviar action y cdata solo cuando la página autorizada exponga estos valores opcionales.
• Devolver el token de solución al código de navegador determinista en lugar de almacenarlo en la memoria del agente de largo plazo.
• Añadir validación de host aprobado, un reintento limitado, redacción de trazas y una rama de revisión humana antes de la producción.

Introducción

La forma más segura de resolver Cloudflare Turnstile en agentes de LlamaIndex es exponer CapSolver como una herramienta de función tipada, manteniendo el estado del navegador, secretos y verificaciones de autorización fuera del modelo. LlamaIndex puede decidir que un desafío compatible bloquea el siguiente paso aprobado, pero Python determinista debe validar el objetivo, construir la tarea documentada AntiTurnstileTaskProxyLess y devolver un token de solución de corta duración al controlador del navegador. Esto sigue la arquitectura de agentes de CapSolver: el modelo decide, el adaptador de herramientas define la acción y la capa de resolución principal la ejecuta. Esta guía muestra los campos exactos de Turnstile, una implementación de FunctionTool de LlamaIndex, un flujo de trabajo de FunctionAgent, el intercambio seguro de tokens, reintentos limitados y controles de uso responsable para QA, RPA y automatización de navegadores permitidos.

¿Por qué FunctionTool de LlamaIndex es una buena opción?

LlamaIndex trata las herramientas como APIs orientadas al agente. Su documentación oficial de herramientas explica que FunctionTool puede envolver funciones Python sincrónicas o asincrónicas e inferir un esquema a partir de la firma de la función. El nombre de la herramienta, la descripción, las anotaciones y el docstring influyen en cuándo el modelo la llama.

Esta frontera es útil para la recuperación de desafíos porque el modelo nunca debe generar código de resolución arbitrario ni recibir una clave de API de CapSolver. Una función estrecha puede aceptar solo una URL de página aprobada, una clave de sitio de Turnstile y metadatos opcionales del widget.

El blog de CapSolver AI cubre integraciones de agentes, mientras que la FAQ de CapSolver AI y automatización explica cómo la recuperación de desafíos complementa una pila de agentes existente.

Comprender la Tarea Oficial de Turnstile

La documentación de Cloudflare Turnstile de CapSolver especifica AntiTurnstileTaskProxyLess. La tarea requiere websiteURL y websiteKey. Los metadatos opcionales pueden incluir los valores action y cdata del widget.

CapSolver admite automáticamente presentaciones gestionadas, no interactivas e invisibles de Turnstile, por lo que la tarea no necesita un subtipo. La documentación de Turnstile de Cloudflare describe el widget y el proceso de validación del lado del servidor utilizado por el propietario del sitio.

Instalar LlamaIndex y CapSolver

pip install llama-index llama-index-llms-openai capsolver

Para la arquitectura de agente de CapSolver proporcionada en la documentación del usuario, instale también los paquetes principales y de agente:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

Configure secretos fuera del prompt:

export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

El ejemplo de SDK directo a continuación utiliza los campos exactos de la tarea de Turnstile. LlamaIndex suministra el marco; CapSolver realiza la tarea.

Crear una Función Tipada de Turnstile

Valide la URL antes de enviarla a CapSolver. El modelo no debe poder seleccionar un hostname arbitrario.

import os
from typing import Annotated
from urllib.parse import urlparse

import capsolver

capsolver.api_key = os.environ["CAPSOLVER_API_KEY"]

ALLOWED_HOSTS = {
    "staging.example.com",
    "qa.example.com",
}


def solve_turnstile(
    website_url: Annotated[str, "Página HTTPS aprobada que contiene Turnstile"],
    website_key: Annotated[str, "Clave exacta del sitio de Turnstile de la página"],
    action: Annotated[str, "Valor opcional de data-action"] = "",
    cdata: Annotated[str, "Valor opcional de data-cdata"] = "",
) -> dict:
    """Resolver Cloudflare Turnstile para una página aprobada y devolver un token."""
    parsed = urlparse(website_url)
    if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
        return {
            "success": False,
            "error": "El objetivo está fuera de la lista de hosts aprobados",
        }

    if not website_key.startswith("0x4"):
        return {
            "success": False,
            "error": "Formato inesperado de clave de sitio de Turnstile",
        }

    task = {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
    }

    metadata = {}
    if action:
        metadata["action"] = action
    if cdata:
        metadata["cdata"] = cdata
    if metadata:
        task["metadata"] = metadata

    try:
        solution = capsolver.solve(task)
        token = solution.get("token")
        if not token:
            return {"success": False, "error": "No se devolvió un token"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

La verificación de formato es una advertencia temprana útil, pero no reemplaza la extracción exacta de parámetros de la página autorizada. Use la guía del complemento de navegador de CapSolver cuando necesite inspeccionar la configuración de un widget durante el desarrollo.

Envolver la Función con LlamaIndex

FunctionTool.from_defaults() convierte la firma de la función y el docstring en un esquema de herramienta de agente.

from llama_index.core.tools import FunctionTool

turnstile_tool = FunctionTool.from_defaults(
    fn=solve_turnstile,
    name="solve_turnstile",
    description=(
        "Resolver Cloudflare Turnstile solo para una página HTTPS aprobada. "
        "Use la URL exacta de la página, la clave del sitio y los valores "
        "opcionales action/cdata proporcionados por el controlador de navegador confiable."
    ),
)

Mantenga el nombre corto y la descripción operativa. No describa la herramienta como un mecanismo de acceso general. El modelo debe entender que es una acción de recuperación dentro de un flujo ya aprobado.

Añadir la Herramienta a un LlamaIndex FunctionAgent

El FunctionAgent de LlamaIndex utiliza la capacidad de llamada de herramientas de un LLM para elegir y ejecutar herramientas.

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini", temperature=0)

agent = FunctionAgent(
    tools=[turnstile_tool],
    llm=llm,
    system_prompt=(
        "Usted opera solo en flujos de navegador aprobados. "
        "Llame a solve_turnstile solo cuando la aplicación confiable proporcione "
        "una URL de página exacta y una clave. Nunca invente objetivos, claves, "
        "acciones o cdata. Llame a la herramienta una vez. Si falla, deténgase y "
        "solicite revisión del operador."
    ),
)

Inicie la ejecución con parámetros producidos por código de navegador determinista:

import asyncio

async def main():
    response = await agent.run(
        "El flujo de trabajo de staging aprobado encontró Turnstile en "
        "https://staging.example.com/account-check con la clave de sitio "
        "0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA y la acción "
        "account_check. Llame a la herramienta registrada una vez y devuelva "
        "el resultado estructurado."
    )
    print(response)

asyncio.run(main())

En producción, evite construir este mensaje directamente a partir de texto no confiable. El controlador de navegador debe extraer, validar y serializar los valores.

Mantener el Consumo de Tokens Fuera del Modelo

Un token de Turnstile es de corta duración y está vinculado al flujo del sitio. Páselo directamente desde el resultado de la herramienta confiable al código de navegador determinista cuando sea posible.

async def apply_turnstile_token(page, token: str) -> None:
    await page.evaluate(
        """
        (token) => {
          const field = document.querySelector(
            'input[name="cf-turnstile-response"]'
          );
          if (!field) {
            throw new Error('Campo de respuesta de Turnstile no encontrado');
          }
          field.value = token;
          field.dispatchEvent(new Event('input', { bubbles: true }));
          field.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

Algunas aplicaciones usan renderizado basado en callbacks o envío gestionado por el servidor. Pruebe contra su propia aplicación de staging y siga su integración admitida. La documentación de Siteverify de Cloudflare explica que el propietario del sitio valida el token del lado del servidor.

La guía de Turnstile de CapSolver proporciona contexto de implementación, y la FAQ de solución de problemas de CapSolver ayuda a diagnosticar soluciones rechazadas.

Añadir un Único Reintento Limitado

No permita que un agente se ejecute indefinidamente. Clasifique los fallos de validación como finales y permita como máximo un reintento para un tiempo de espera transitorio.

import asyncio

async def solve_with_policy(params: dict) -> dict:
    last_error = "error desconocido"

    for attempt in range(1, 3):
        result = solve_turnstile(**params)
        if result.get("success"):
            return {**result, "attempt": attempt}

        last_error = result.get("error", last_error)
        normalized = last_error.lower()
        if "allowlist" in normalized or "site-key" in normalized:
            break
        if attempt == 1:
            await asyncio.sleep(2)

    return {
        "success": False,
        "error": last_error,
        "requires_operator_review": True,
    }

Registre el hostname, tipo de tarea, duración, número de intentos y resultado normalizado. Nunca registre el token completo, clave de API, cookies o contenido de formularios.

Modo de Token vs Modo de Navegador

La documentación del agente de CapSolver proporcionada por el usuario mapea solve_captcha a la resolución de token principal y solve_on_page a la recuperación del navegador. Si la página es dinámica, instale el complemento de navegador y mantenga la sesión de navegador original intacta:

pip install "capsolver-agent[browser] @ git+https://github.com/capsolver-ai/capsolver-agent.git"

Use las tutoriales de automatización de CapSolver para flujos de trabajo de navegador relacionados y la página de productos de CapSolver para categorías de soluciones admitidas.

Código adicional: Use el código WEBS en el Panel de CapSolver para obtener un 5% adicional en cada recarga.

Control en Producción

Una integración de Turnstile de LlamaIndex en producción debe usar un registro de hosts aprobados, almacenamiento de secretos aislado, intercambio de tokens de corta duración, un reintento limitado, redacción de trazas, revisión por operador y una separación estricta entre automatización de solo lectura y acciones de alto impacto.

La FAQ de resolución de CAPTCHA de CapSolver explica el ciclo de vida de la tarea, y la FAQ de raspado web de CapSolver cubre consideraciones operativas.

Uso Responsable

Use esta integración solo en aplicaciones que posea, pruebe o tenga permiso explícito para automatizar. La resolución de desafíos no otorga autorización para acceder a datos privados, crear cuentas, enviar transacciones o ignorar términos del sitio. Aplicar límites de tasa, mantener un registro de auditoría y requerir confirmación antes de cualquier acción que cambie datos o afecte a usuarios.

Conclusión

Para resolver Cloudflare Turnstile de manera confiable en LlamaIndex, haga que CapSolver sea una FunctionTool estrecha y mantenga la autorización, secretos, reintentos y consumo de tokens en código determinista. El agente de LlamaIndex decide cuándo se necesita recuperación, la herramienta crea la tarea documentada AntiTurnstileTaskProxyLess, y el navegador reanuda el mismo flujo aprobado con el token devuelto.

Comience con CapSolver, valide la integración contra una página de staging que controle y agregue listas de hosts y redacción de trazas antes de la producción.

Preguntas Frecuentes

¿Qué clase de herramienta de LlamaIndex debo usar?

Use FunctionTool.from_defaults() para envolver una función Python sincrónica o asincrónica tipada. Para un modelo de llamada de herramientas, pase la herramienta resultante a FunctionAgent.

¿Requiere la tarea de Turnstile un proxy?

La tarea documentada AntiTurnstileTaskProxyLess usa el camino de tarea sin proxy de CapSolver, por lo que no debe proporcionar un proxy en la tarea.

¿Qué campos son obligatorios?

websiteURL y websiteKey son obligatorios. Incluya metadata.action y metadata.cdata solo cuando el widget autorizado los exponga.

¿Debe almacenarse el token en la memoria de LlamaIndex?

No. Prefiera la entrega directa al código de navegador confiable y devuelva solo un estado de éxito o fallo redactado al agente.

¿Qué debe ocurrir tras un fallo repetido?

Verifique la URL, la clave del sitio, los metadatos opcionales y el estado de la página. Tras un reintento limitado, deténgase y redirija el flujo a la revisión del operador.