Como resolver o Cloudflare Turnstile nos Agentes do LlamaIndex

Resumo

• Envolver uma função CapSolver Turnstile estreita com LlamaIndex FunctionTool.from_defaults().
• Use a tarefa documentada AntiTurnstileTaskProxyLess com a URL exata da página e a chave do site.
• Envie action e cdata apenas quando a página autorizada expuser esses valores opcionais.
• Retorne o token de solução para o código de navegador determinístico em vez de armazená-lo na memória do agente de longo prazo.
• Adicione validação de host aprovado, uma tentativa limitada, redação de rastreamento e uma ramificação de revisão humana antes da produção.

Introdução

A forma mais segura de resolver o Cloudflare Turnstile em agentes LlamaIndex é expor o CapSolver como uma ferramenta de função tipada, mantendo o estado do navegador, segredos e verificações de autorização fora do modelo. O LlamaIndex pode decidir que um desafio suportado bloqueia a próxima etapa aprovada, mas o Python determinístico deve validar o alvo, construir a tarefa documentada AntiTurnstileTaskProxyLess e retornar um token de solução de curto prazo para o controlador do navegador. Isso segue a arquitetura de agente CapSolver: o modelo decide, o adaptador de ferramenta define a ação e a camada de resolução central a executa. Este guia mostra os campos exatos do Turnstile, uma implementação de FunctionTool do LlamaIndex, um fluxo de trabalho de FunctionAgent, transferência segura de token, tentativas limitadas e controles de uso responsável para QA, RPA e automação de navegador permitida.

Por que o FunctionTool do LlamaIndex é uma boa opção

O LlamaIndex trata ferramentas como APIs voltadas para o agente. Sua documentação oficial de ferramentas explica que o FunctionTool pode envolver funções Python síncronas ou assíncronas e inferir um esquema a partir da assinatura da função. O nome da ferramenta, descrição, anotações e docstring influenciam quando o modelo a chama.

Essa fronteira é útil para recuperação de desafios porque o modelo nunca deve gerar código de resolução arbitrário ou receber uma chave de API do CapSolver. Uma função estreita pode aceitar apenas uma URL de página aprovada, uma chave do site do Turnstile e metadados do widget opcionais.

O blog do CapSolver AI aborda integrações de agentes, enquanto a Perguntas Frequentes do CapSolver AI e automação explica como a recuperação de desafios complementa uma pilha de agente existente.

Entenda a Tarefa Oficial do Turnstile

A documentação do Cloudflare Turnstile do CapSolver especifica AntiTurnstileTaskProxyLess. A tarefa requer websiteURL e websiteKey. Metadados opcionais podem incluir os valores do widget action e cdata.

O CapSolver suporta automaticamente apresentações gerenciadas, não interativas e invisíveis do Turnstile, então a tarefa não precisa de um subtipo. A documentação do Turnstile da Cloudflare descreve o widget e o processo de validação do lado do servidor usado pelo proprietário do site.

Instale o LlamaIndex e o CapSolver

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

Para a arquitetura de agente do CapSolver fornecida na documentação do usuário, instale os pacotes principais e de agente também:

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

Configure segredos fora da pergunta:

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

O exemplo direto da SDK abaixo usa os campos exatos da tarefa do Turnstile. O LlamaIndex fornece o shell do framework; o CapSolver executa a tarefa.

Crie uma Função Tipada do Turnstile

Valide a URL antes de enviá-la para o CapSolver. O modelo não deve ser capaz de selecionar um hostname arbitrário.

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 aprovada contendo Turnstile"],
    website_key: Annotated[str, "Chave do site do Turnstile exata da página"],
    action: Annotated[str, "Valor opcional de data-action"] = "",
    cdata: Annotated[str, "Valor opcional de data-cdata"] = "",
) -> dict:
    """Resolva o Cloudflare Turnstile para uma página aprovada e retorne um token."""
    parsed = urlparse(website_url)
    if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
        return {
            "success": False,
            "error": "Alvo fora da lista de hosts aprovados",
        }

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

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

A verificação de formato é um aviso útil, mas não substitui a extração exata de parâmetros da página autorizada. Use o guia da extensão do navegador do CapSolver quando precisar inspecionar a configuração de um widget durante o desenvolvimento.

Envolva a Função com o LlamaIndex

FunctionTool.from_defaults() converte a assinatura da função e o docstring em um esquema de ferramenta de agente.

from llama_index.core.tools import FunctionTool

turnstile_tool = FunctionTool.from_defaults(
    fn=solve_turnstile,
    name="solve_turnstile",
    description=(
        "Resolva o Cloudflare Turnstile apenas para uma página HTTPS aprovada. "
        "Use a URL exata da página, a chave do site e os valores opcionais action/cdata "
        "fornecidos pelo controlador de navegador confiável."
    ),
)

Mantenha o nome curto e a descrição operacional. Não descreva a ferramenta como um mecanismo de acesso geral. O modelo deve entender que é uma ação de recuperação dentro de um fluxo já aprovado.

Adicione a Ferramenta a um FunctionAgent do LlamaIndex

O FunctionAgent do LlamaIndex usa a capacidade de chamada de ferramenta do LLM para escolher e executar ferramentas.

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=(
        "Você opera apenas fluxos de trabalho de navegador aprovados. "
        "Chame solve_turnstile apenas quando a aplicação confiável fornecer "
        "uma URL e chave exatas. Nunca invente destinos, chaves, "
        "ações ou cdata. Chame a ferramenta uma vez. Se falhar, pare e "
        "solicite revisão do operador."
    ),
)

Inicie a execução com parâmetros produzidos por código de navegador determinístico:

import asyncio

async def main():
    response = await agent.run(
        "O fluxo de staging aprovado encontrou Turnstile em "
        "https://staging.example.com/account-check com chave do site "
        "0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA e ação "
        "account_check. Chame a ferramenta registrada uma vez e retorne "
        "o resultado estruturado."
    )
    print(response)

asyncio.run(main())

Em produção, evite construir esta mensagem diretamente a partir de texto não confiável. O controlador de navegador deve extrair, validar e serializar os valores.

Mantenha o consumo de token fora do modelo

Um token do Turnstile é de curto prazo e vinculado ao fluxo do site. Passe-o diretamente do resultado da ferramenta confiável para o código de navegador determinístico quando possível.

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 resposta do Turnstile não encontrado');
          }
          field.value = token;
          field.dispatchEvent(new Event('input', { bubbles: true }));
          field.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

Algumas aplicações usam renderização baseada em callback ou submissão gerenciada pelo servidor. Teste contra sua própria aplicação de staging e siga sua integração suportada. A documentação do Siteverify da Cloudflare explica que o proprietário do site valida o token no lado do servidor.

O guia do Turnstile do CapSolver fornece contexto de implementação, e a Perguntas Frequentes do CapSolver sobre erros ajuda a diagnosticar soluções rejeitadas.

Adicione uma Tentativa Limitada

Não deixe o agente loopar indefinidamente. Classifique falhas de validação como finais e permita no máximo uma tentativa para um tempo limite temporário.

import asyncio

async def solve_with_policy(params: dict) -> dict:
    last_error = "erro desconhecido"

    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 o hostname, tipo de tarefa, duração, número de tentativas e resultado normalizado. Nunca registre o token completo, chave de API, cookies ou conteúdo de formulário.

Modo de Token vs Modo de Navegador

A documentação do agente do CapSolver fornecida pelo usuário mapeia solve_captcha para resolução de token e solve_on_page para recuperação de navegador. Se a página for dinâmica, instale o extra do navegador e mantenha a sessão do navegador original intacta:

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

Use os tutoriais de automação do CapSolver para fluxos de trabalho de navegador relacionados e a página de produtos do CapSolver para categorias de soluções suportadas.

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

Controles de Produção

Uma integração de Turnstile do LlamaIndex em produção deve usar um registro de hosts aprovados, armazenamento de segredos isolado, transferência de token de curto prazo, uma tentativa limitada, redação de rastreamento, revisão humana e uma separação estrita entre automação de leitura e ações de alto impacto.

A Perguntas Frequentes do CapSolver sobre resolução de CAPTCHA explica o ciclo de vida da tarefa, e a Perguntas Frequentes do CapSolver sobre raspagem de web aborda considerações operacionais.

Uso Responsável

Use esta integração apenas em aplicações que você possua, teste ou tenha permissão explícita para automatizar. A resolução de desafios não concede autorização para acessar dados privados, criar contas, submeter transações ou ignorar termos do site. Aplicar limites de taxa, manter um registro de auditoria e exigir confirmação antes de qualquer ação que altere dados ou afete usuários.

Conclusão

Para resolver o Cloudflare Turnstile no LlamaIndex de forma confiável, faça do CapSolver uma FunctionTool estreita e mantenha autorização, segredos, tentativas e consumo de token em código determinístico. O agente LlamaIndex decide quando a recuperação é necessária, a ferramenta cria a AntiTurnstileTaskProxyLess documentada e o navegador retoma o mesmo fluxo aprovado com o token retornado.

Comece com o CapSolver, valide a integração contra uma página de staging que você controle e adicione listas de hosts e redação de rastreamento antes da produção.

Perguntas Frequentes

Qual classe de ferramenta LlamaIndex devo usar?

Use FunctionTool.from_defaults() para envolver uma função Python sincronizada ou assíncrona tipada. Para um modelo de chamada de ferramenta, passe a ferramenta resultante para FunctionAgent.

A tarefa do Turnstile requer um proxy?

A tarefa documentada AntiTurnstileTaskProxyLess usa o caminho sem proxy do CapSolver, então você não precisa fornecer um proxy na tarefa.

Quais campos são obrigatórios?

websiteURL e websiteKey são obrigatórios. Inclua metadata.action e metadata.cdata apenas quando o widget autorizado os expuser.

O token deve ser armazenado na memória do LlamaIndex?

Não. Prefira a transferência direta para o código de navegador confiável e retorne apenas um estado de sucesso ou falha redigido para o agente.

O que deve acontecer após falhas repetidas?

Verifique a URL, chave do site, metadados opcionais e estado da página. Após uma tentativa limitada, pare e direcione o fluxo para revisão do operador.