Cómo resolver Cloudflare Turnstile en agentes de AutoGen

TL;DR

• Registra una función Python estrecha solve_turnstile con AutoGen en lugar de permitir que los agentes escriban código de resolución arbitrario.
• Usa la tarea AntiTurnstileTaskProxyLess documentada de CapSolver con websiteURL y websiteKey.
• Incluye la acción y cdata de Turnstile opcionales solo cuando estén presentes en la página autorizada.
• Devuelve el token de solución a la capa del navegador determinista, que debe inyectarlo y enviar el flujo de trabajo original.
• Mantén las claves de API, sesiones del navegador y permisos de objetivo fuera del prompt del modelo de lenguaje.

Introducción

La forma más segura de resolver Cloudflare Turnstile en AutoGen es registrar CapSolver como una herramienta de función con tipo y alcance estrecho. AutoGen puede decidir cuándo el flujo de trabajo necesita una solución de Turnstile, pero el código Python determinista debe validar la URL de destino y la clave del sitio, crear la tarea AntiTurnstileTaskProxyLess documentada y devolver solo el token resultante. La capa del navegador luego aplica ese token al mismo flujo de trabajo autorizado y continúa. Esta arquitectura sigue el límite "el modelo decide, el núcleo ejecuta" descrito en la documentación de CapSolver AI Agent y el modelo de registro de herramientas oficial de AutoGen. En esta guía, creará la función solucionadora, la registrará con los agentes llamador y ejecutor, manejará metadatos opcionales del widget, agregará reintentos limitados y diseñará controles de producción que eviten que credenciales o objetivos sin restricciones lleguen al modelo.

¿Por qué usar una herramienta en lugar de código generado por el agente?

Las herramientas de AutoGen son funciones predefinidas que los agentes pueden llamar. La guía oficial de uso de herramientas de AutoGen explica que las herramientas restringen lo que puede hacer un agente de manera más efectiva que permitirle generar código ejecutable arbitrario. Las anotaciones de tipo y descripciones concisas se usan para crear automáticamente el esquema de la herramienta.

Ese límite es especialmente importante para el manejo de desafíos. El agente no debe recibir su clave de API de CapSolver, elegir sitios arbitrarios o controlar directamente el contexto del navegador. Debe solicitar solo una solución para una página validada ya aprobada por el flujo de trabajo de automatización.

El blog de CapSolver AI cubre patrones orientados a agentes, mientras que la FAQ de CapSolver AI y automatización explica cómo se integran las herramientas de resolución en la automatización controlada.

Parámetros de Cloudflare Turnstile que necesita

La documentación oficial de Turnstile de CapSolver especifica el tipo de tarea sin proxy AntiTurnstileTaskProxyLess. Los parámetros requeridos son websiteURL y websiteKey. Los metadatos opcionales pueden incluir los valores action y cdata del widget.

Cloudflare documenta los modos de widget gestionados, no interactivos e invisibles. La visión general de Cloudflare Turnstile describe cómo un widget evalúa señales del navegador e emite un token para validación del lado del servidor. CapSolver maneja automáticamente el subtipo compatible, por lo que la tarea no necesita un campo de subtipo.

Instalar AutoGen y CapSolver

pip install pyautogen capsolver

Almacene las credenciales en variables de entorno:

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

Para la nueva arquitectura de agente de CapSolver descrita en la documentación proporcionada por el usuario, los equipos también pueden instalar los paquetes principales y adaptadores:

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

La función directa capsolver.solve() que se muestra a continuación usa los campos de tarea oficiales de Turnstile y se envuelve como una herramienta de AutoGen. Esto mantiene la integración del framework simple y hace que la carga de tarea sea fácil de auditar.

Crear una función solucionadora de Turnstile tipada

El modelo debe recibir solo entradas no secretas. La clave de CapSolver permanece dentro del entorno de ejecución de la función.

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",
    "app.example.com",
}


def solve_turnstile(
    website_url: Annotated[str, "URL de página aprobada que contiene Turnstile"],
    website_key: Annotated[str, "Clave del sitio de Turnstile del widget"],
    action: Annotated[str, "Valor data-action opcional"] = "",
    cdata: Annotated[str, "Valor data-cdata opcional"] = "",
) -> dict:
    """Resolver 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 destino no está en la lista de permitidos",
        }

    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 de Turnstile"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

La lista de permitidos es intencional. Sin ella, un prompt podría dirigir al agente a enviar objetivos no relacionados. Los sistemas de producción pueden construir la lista de permitidos desde la configuración del inquilino, permisos de trabajo o un manifiesto de flujo de trabajo firmado.

Registrar la función con AutoGen

La API clásica de AgentChat de AutoGen separa al agente que propone una llamada a la herramienta del ejecutor que la ejecuta. La documentación oficial proporciona register_function() como forma conveniente de registrar la misma función con ambos agentes.

import os
from autogen import ConversableAgent, register_function

assistant = ConversableAgent(
    name="TurnstileCoordinator",
    system_message=(
        "Continuar solo con flujos de trabajo de automatización aprobados. "
        "Llamar a solve_turnstile solo cuando la aplicación informe un widget de Turnstile "
        "y proporcione la URL exacta de la página y la clave del sitio. "
        "Nunca inventar objetivos o solicitar credenciales. "
        "Si la herramienta falla dos veces, detenerse y solicitar revisión del operador."
    ),
    llm_config={
        "config_list": [{
            "model": "gpt-4o-mini",
            "api_key": os.environ["OPENAI_API_KEY"],
        }]
    },
)

executor = ConversableAgent(
    name="TurnstileToolExecutor",
    llm_config=False,
    human_input_mode="NEVER",
)

register_function(
    solve_turnstile,
    caller=assistant,
    executor=executor,
    name="solve_turnstile",
    description=(
        "Resolver Cloudflare Turnstile para una página HTTPS aprobada usando su clave "
        "de sitio exacta y valores opcionales de acción/cdata."
    ),
)

AutoGen genera el esquema de la herramienta a partir de la firma de la función y las anotaciones de tipo. Mantenga las descripciones operativas y específicas para que el modelo entienda cuándo es adecuada la herramienta.

Para otros patrones de framework, revise las tutoriales de automatización de CapSolver y la página de productos de CapSolver.

Iniciar la conversación de llamada a herramientas

La capa del navegador o de orquestación debe detectar el widget y proporcionar parámetros exactos. El modelo no debe inspeccionar secretos o escanear páginas arbitrarias para descubrir objetivos.

chat_result = executor.initiate_chat(
    assistant,
    message=(
        "El flujo de trabajo de prueba encontró Cloudflare Turnstile.\n"
        "website_url=https://staging.example.com/account-check\n"
        "website_key=0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n"
        "action=account_check\n"
        "cdata=\n"
        "Llame a la herramienta registrada una vez y devuelva el resultado estructurado."
    ),
    max_turns=4,
)

En un diseño de producción, el código de aplicación estructurado debe construir este mensaje a partir de datos en tiempo de ejecución validados. No acepte directamente una clave de sitio o una URL de destino de entrada no confiable.

Aplicar el token en la capa del navegador

Un token de Turnstile generalmente se consume por el formulario original o la solicitud del servidor. La integración exacta depende de la aplicación autorizada. Para un flujo de trabajo del navegador, pase el token devuelto de vuelta a un código determinista que conozca el widget y la ruta de envío.

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

Algunas aplicaciones usan renderizado basado en callback o envío gestionado por el servidor. Pruebe contra su propia aplicación de prueba y siga su integración soportada en lugar de asumir que establecer un campo oculto es suficiente. La documentación de validación del lado del servidor de Cloudflare explica que el propietario del sitio debe validar tokens con Siteverify.

La guía de Turnstile de CapSolver proporciona contexto adicional de implementación, y la FAQ de solución de problemas de CapSolver ayuda a diagnosticar tokens inválidos o rechazados.

Agregar reintentos limitados y errores estructurados

No permita que un agente intente indefinidamente. Limite los intentos y clasifique los fallos para que la automatización pueda detenerse de forma segura.

import asyncio

MAX_ATTEMPTS = 2

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

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

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

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

Registre solo metadatos seguros: hostname de destino, tipo de tarea, duración, resultado, error normalizado y número de intentos. No registre el token completo, clave de API, cookies de sesión o contenido de formularios.

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

Lista de verificación de producción

La FAQ de resolución de CAPTCHA de CapSolver explica el comportamiento general de las tareas, mientras que la FAQ de raspado web de CapSolver cubre controles operativos para la recolección automatizada.

Uso responsable

Use este flujo solo en aplicaciones que posea, pruebe o tenga permiso explícito para automatizar. Un token de solución no otorga autorización para acceder a datos privados, enviar transacciones, crear cuentas o ignorar los términos de un sitio. Aplicar límites de frecuencia, mantener registros de auditoría y requerir confirmación para acciones que cambien datos o afecten a usuarios.

Conclusión

Para resolver Cloudflare Turnstile de manera confiable en AutoGen, haga que CapSolver sea una herramienta restringida en lugar de lógica de agente sin límites. El asistente de AutoGen decide cuándo es adecuada la herramienta, el ejecutor ejecuta un AntiTurnstileTaskProxyLess validado y la capa del navegador consume el token resultante dentro del mismo flujo de trabajo aprobado. Esta división hace que la integración sea más fácil de probar, auditar y garantizar.

Comience con CapSolver, valide el flujo contra una página de prueba que controle y agregue listas de permitidos, reintentos limitados y registro seguro de tokens antes de la implementación en producción.

Preguntas frecuentes

¿Requiere un proxy la tarea de Turnstile de CapSolver?

El tipo de tarea documentado es AntiTurnstileTaskProxyLess, por lo que no debe proporcionar un proxy a la tarea. Su flujo de navegador más amplio puede tener su propia configuración de red.

¿Qué campos son obligatorios para la tarea?

websiteURL y websiteKey son obligatorios. metadata.action y metadata.cdata son opcionales y deben proporcionarse solo cuando el widget los use.

¿Puede AutoGen descubrir la clave del sitio automáticamente?

El diseño más seguro es que una capa de navegador o aplicación determinista extraiga y valide la clave del sitio, luego la proporcione a la herramienta. No deje que el modelo invente o adivine el valor.

¿Por qué usar agentes separados de llamador y ejecutor?

El llamador puede proponer la llamada a la herramienta, mientras que el ejecutor ejecuta código Python controlado sin LLM. Esto mantiene secretos y permisos de tiempo de ejecución alejados del agente de razonamiento.

¿Qué debe ocurrir si el token devuelto es rechazado?

Confirme la URL de la página, la clave del sitio, la acción opcional o cdata, la frescura del token y la ruta de envío. Reintente como máximo una o dos veces, luego pause para revisión del operador en lugar de continuar en bucle.