Como resolver o Cloudflare Turnstile nos Agentes CrewAI

O Cloudflare Turnstile está rapidamente substituindo os tradicionais CAPTCHAs em aplicações web modernas. Quando fluxos de trabalho multi-agentes do CrewAI encontram páginas protegidas pelo Turnstile durante pesquisas na web, coleta de dados ou fluxos automatizados, toda a equipe para. O SDK capsolver-core do CapSolver resolve desafios do Turnstile em 2-5 segundos, integrando-se de forma transparente ao sistema de ferramentas do CrewAI para manter seus pipelines multi-agentes em execução sem interrupções.

TL;DR

• O Cloudflare Turnstile está implantado em mais de 25% das aplicações web modernas, tornando-se o sistema de verificação mais rápido em crescimento
• O CapSolver resolve o Turnstile em 2-5 segundos — mais rápido que o reCAPTCHA — usando o tipo de tarefa cloudflare
• A integração com o CrewAI usa o decorador @tool envolvendo o executor assíncrono do CapSolver
• Requer apenas website_url e website_key (a chave do site do Turnstile que começa com 0x)
• Funciona nos modos Token (sem navegador) e Browser (detecção automática e preenchimento em páginas ao vivo)

Por que os Agentes do CrewAI Encontram o Cloudflare Turnstile

O Cloudflare Turnstile tornou-se o sistema de verificação padrão para uma parcela crescente da web. Ao contrário do reCAPTCHA, o Turnstile opera como um "desafio não interativo" — ele roda em segundo plano e apresenta um widget visível apenas quando o score de risco é elevado. Isso torna mais difícil para os agentes detectarem e lidarem com ele em comparação com os tradicionais CAPTCHAs com checkbox.

Os agentes do CrewAI encontram o Turnstile em plataformas SaaS, sites de documentação de APIs, lojas de e-commerce modernas (especialmente Shopify), portais de fintech e sistemas de gerenciamento de conteúdo. A documentação do Cloudflare Turnstile indica que o sistema processa bilhões de desafios mensalmente em milhões de sites, com adesão crescendo 40% ou mais ano a ano.

Para equipes do CrewAI que realizam pesquisas na web ou coleta de dados, o Turnstile aparece sem aviso — uma página que carregou normalmente ontem pode ter implementado o Turnstile hoje após a ativação do gerenciamento de bots do Cloudflare. O tipo de tarefa cloudflare do CapSolver lida com isso de forma transparente.

O que Você Precisa Antes de Começar

# Motor do CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-core.git
# Ferramentas do agente do CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
# CrewAI
pip install crewai crewai-tools

export CAPSOLVER_API_KEY="sua-chave-da-api-do-capsolver"
export OPENAI_API_KEY="sua-chave-da-api-do-openai"

Etapa 1 — Criar uma Ferramenta de Resolução do Turnstile para o CrewAI

import asyncio
from crewai.tools import tool
from capsolver_agent.schema import create_executor

executor = create_executor(api_key="SUA_CHAVE_DA_API_DO_CAPSOLVER")

@tool("Resolver Cloudflare Turnstile")
def solve_turnstile(website_url: str, website_key: str) -> str:
    """Resolve um desafio do Cloudflare Turnstile e retorna o token de verificação.
    
    Use esta ferramenta quando um site estiver protegido pelo Cloudflare Turnstile.
    A website_key começa com '0x' e pode ser encontrada no atributo data-sitekey do elemento div cf-turnstile da página.
    
    Args:
        website_url: A URL completa da página protegida pelo Turnstile
        website_key: A chave do site do Turnstile (começa com 0x)
    
    Returns:
        O token cf-turnstile-response para enviar com as solicitações
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": "cloudflare",
        "website_url": website_url,
        "website_key": website_key
    }))
    
    if result["success"]:
        return f"Turnstile resolvido em ~3s. Token: {result['solution']['token']}"
    return f"Falha na resolução: {result['error']}"

Etapa 2 — Construir um Agente do CrewAI com Capacidade de Turnstile

from crewai import Agent, Task, Crew, Process

# Agente com resolução de Turnstile
researcher = Agent(
    role="Especialista em Pesquisa Web",
    goal="Acessar sites protegidos pelo Cloudflare e coletar dados",
    backstory="""Você pesquisa sites protegidos pelo Cloudflare Turnstile. 
    Quando você encontrar um desafio do Turnstile (identificado por elementos cf-turnstile 
    ou páginas de desafio do Cloudflare), use a ferramenta solve_turnstile com a URL da página 
    e a chave do site (começa com 0x). Envie o token retornado como 
    cf-turnstile-response.""",
    tools=[solve_turnstile],
    verbose=True
)

# Tarefa que requer resolução de Turnstile
research_task = Task(
    description="""Acesse a página protegida pelo Cloudflare em {url}.
    A chave do site do Turnstile é {site_key}.
    Resolva o desafio do Turnstile e relate o token.""",
    expected_output="Token do Turnstile para acessar o recurso protegido",
    agent=researcher
)

crew = Crew(agents=[researcher], tasks=[research_task], process=Process.sequential)
result = crew.kickoff(inputs={"url": "https://example.com", "site_key": "0x4AAAAAAA..."})

Etapa 3 — Identificar Parâmetros do Turnstile

As chaves do site do Turnstile são encontradas no HTML da página:

<!-- Widget Turnstile -->
<div class="cf-turnstile" data-sitekey="0x4AAAAAAABkMYinukE8nzYS"></div>

<!-- Ou em JavaScript -->
<script>
  turnstile.render('#container', { sitekey: '0x4AAAAAAABkMYinukE8nzYS' });
</script>

A extensão do navegador do CapSolver detecta automaticamente os parâmetros do Turnstile em qualquer página. O guia de resolução do Cloudflare Turnstile fornece padrões de implementação detalhados.

Etapa 4 — Lidar com o Turnstile no Modo Navegador

Para agentes do CrewAI que usam o Playwright, use solve_on_page() para detecção automática:

from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

async def solve_turnstile_on_page(url: str):
    cap = create_capsolver(api_key="SUA_CHAVE_DA_API_DO_CAPSOLVER")
    
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto(url)
        
        # Detectar e resolver automaticamente o Turnstile
        results = await cap.solve_on_page(page)
        for r in results:
            if r.solution:
                print(f"Turnstile resolvido e preenchido: {r.filled}")
        
        await browser.close()
    await cap.aclose()

Claim Your Bonus Code: Use o código WEBS no Painel do CapSolver para obter um bônus adicional de 5% em cada recarga.

Conclusão

Resolver o Cloudflare Turnstile no CrewAI requer o decorador @tool envolvendo o executor do CapSolver com captcha_type: "cloudflare". As resoluções do Turnstile são mais rápidas (2-5 segundos) e mais baratas que o reCAPTCHA, tornando-as eficientes para fluxos de trabalho de alto volume no CrewAI. CapSolver lida com o Turnstile de forma transparente por meio da mesma API usada para o reCAPTCHA, então suas ferramentas do CrewAI funcionam em todos os tipos de CAPTCHA sem alterações no código.

Perguntas Frequentes

O Cloudflare Turnstile é mais difícil de resolver do que o reCAPTCHA?

Não. O Turnstile é mais rápido de resolver (2-5 segundos vs 5-12 segundos para o reCAPTCHA v2) e custa menos por resolução. A API do CapSolver lida com ambos através da mesma interface — basta alterar o parâmetro captcha_type.

Como é a aparência da chave do site do Turnstile?

As chaves do site do Turnstile sempre começam com 0x seguido por caracteres alfanuméricos, como 0x4AAAAAAABkMYinukE8nzYS. Elas são encontradas nos atributos data-sitekey em elementos div.cf-turnstile.

Um único ferramenta do CrewAI pode lidar com o Turnstile e o reCAPTCHA?

Sim. Crie uma ferramenta unificada que aceite captcha_type como um parâmetro. O executor lida com o roteamento para o solucionador correto com base no valor do tipo — cloudflare para o Turnstile, reCaptchaV2 ou reCaptchaV3 para o reCAPTCHA.

A resolução do Turnstile funciona sem um navegador?

Sim. O modo Token requer apenas website_url e website_key. Nenhum navegador, nenhum Playwright, nenhuma renderização de página é necessário. O token é retornado diretamente e pode ser enviado com solicitações HTTP como cf-turnstile-response.