Como resolver o Cloudflare Turnstile nos Agentes AutoGen

TL;DR

• Registre uma função Python estreita solve_turnstile com AutoGen em vez de permitir que os agentes escrevam código de resolução arbitrário.
• Use a tarefa documentada AntiTurnstileTaskProxyLess do CapSolver com websiteURL e websiteKey.
• Inclua ações e cdata do Turnstile opcionalmente apenas quando estiverem presentes na página autorizada.
• Retorne o token de solução à camada de navegador determinística, que deve injetá-lo e submeter o fluxo original.
• Mantenha chaves de API, sessões de navegador e permissões de destino fora do prompt do modelo de linguagem.

Introdução

A maneira mais segura de resolver o Cloudflare Turnstile no AutoGen é registrar o CapSolver como uma ferramenta de função tipada e com escopo estreito. O AutoGen pode decidir quando o fluxo de trabalho precisa de uma solução do Turnstile, mas o código Python determinístico deve validar a URL de destino e a chave do site, criar a tarefa documentada AntiTurnstileTaskProxyLess e retornar apenas o token resultante. A camada de navegador aplica então esse token ao mesmo fluxo autorizado e continua. Essa arquitetura segue a fronteira "modelo decide, núcleo executa" da documentação do CapSolver AI Agent e o modelo de registro de ferramentas oficial do AutoGen. Neste guia, você criará a função solucionadora, a registrará com agentes de chamador e executor, lidará com metadados de widget opcionais, adicionará tentativas limitadas e projetará controles de produção que evitem que credenciais ou destinos sem restrições cheguem ao modelo.

Por que usar uma ferramenta em vez de código gerado pelo agente?

Ferramentas do AutoGen são funções pré-definidas que os agentes podem chamar. O guia oficial de uso de ferramentas do AutoGen explica que as ferramentas restringem o que um agente pode fazer de forma mais eficaz do que permitir que ele gere código executável arbitrário. Dicas de tipo e descrições concisas são usadas para criar o esquema da ferramenta automaticamente.

Essa fronteira é especialmente importante para o tratamento de desafios. O agente não deve receber sua chave de API do CapSolver, escolher sites arbitrários ou controlar o contexto do navegador diretamente. Ele deve solicitar apenas uma solução para uma página validada já aprovada pelo fluxo de automação.

O blog do CapSolver AI aborda padrões orientados a agentes, enquanto a FAQ do CapSolver AI e automação explica como as ferramentas de resolução se encaixam na automação controlada.

Parâmetros do Cloudflare Turnstile que você precisa

A documentação oficial do Turnstile do CapSolver especifica o tipo de tarefa sem proxy AntiTurnstileTaskProxyLess. Os parâmetros necessários são websiteURL e websiteKey. Metadados opcionais podem incluir os valores action e cdata do widget.

O Cloudflare documenta os modos de widget gerenciados, não interativos e invisíveis. A visão geral do Cloudflare Turnstile descreve como um widget avalia sinais do navegador e emite um token para validação do lado do servidor. O CapSolver lida automaticamente com o subtipo suportado, então a tarefa não precisa de um campo de subtipo.

Instale o AutoGen e o CapSolver

pip install pyautogen capsolver

Armazene as credenciais em variáveis de ambiente:

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

Para a nova arquitetura de agente do CapSolver descrita na documentação fornecida pelo usuário, as equipes também podem instalar os pacotes principais e adaptadores:

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

A função direta capsolver.solve() abaixo usa os campos da tarefa do Turnstile oficial e é encapsulada como uma ferramenta do AutoGen. Isso mantém a integração do framework simples e torna o payload da tarefa fácil de auditar.

Crie uma Função Solucionadora de Turnstile Tipada

O modelo deve receber apenas entradas não secretas. A chave do CapSolver permanece no ambiente de execução da função.

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 da página aprovada contendo Turnstile"],
    website_key: Annotated[str, "Chave do site do Turnstile do widget"],
    action: Annotated[str, "Valor opcional de data-action"] = "",
    cdata: Annotated[str, "Valor opcional de data-cdata"] = "",
) -> dict:
    """Resolva o 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": "Destino não está na lista de permissões aprovada",
        }

    if not website_key.startswith("0x4"):
        return {
            "success": False,
            "error": "Formato inesperado da chave do site do 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": "Nenhum token do Turnstile foi retornado"}
        return {
            "success": True,
            "token": token,
            "solution_type": solution.get("type", "turnstile"),
        }
    except Exception as exc:
        return {"success": False, "error": str(exc)}

A lista de permissões é intencional. Sem ela, um prompt poderia direcionar o agente a enviar destinos não relacionados. Sistemas de produção podem construir a lista de permissões a partir da configuração do inquilino, permissões de trabalho ou um manifesto de fluxo assinado.

Registre a Função com o AutoGen

A API clássica do AgentChat do AutoGen separa o agente que propõe uma chamada de ferramenta do executor que a executa. A documentação oficial fornece register_function() como um meio conveniente para registrar a mesma função com ambos os agentes.

import os
from autogen import ConversableAgent, register_function

assistant = ConversableAgent(
    name="TurnstileCoordinator",
    system_message=(
        "Continue apenas fluxos de automação aprovados. "
        "Chame solve_turnstile apenas quando o aplicativo relatar um widget do Turnstile "
        "e fornecer a URL exata da página e a chave do site. "
        "Nunca invente destinos ou solicite credenciais. "
        "Se a ferramenta falhar duas vezes, pare e solicite revisão do 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=(
        "Resolva o Cloudflare Turnstile para uma página HTTPS aprovada usando sua chave exata "
        "do site e valores opcionais de ação/cdata."
    ),
)

O AutoGen gera o esquema da ferramenta a partir da assinatura da função e das anotações de tipo. Mantenha as descrições operacionais e específicas para que o modelo entenda quando a ferramenta é apropriada.

Para outros padrões de framework, revise os tutoriais de automação do CapSolver e a página de produtos do CapSolver.

Inicie a Conversa de Chamada de Ferramenta

A camada de navegador ou de orquestração deve detectar o widget e fornecer parâmetros exatos. O modelo não deve inspecionar segredos ou varrer páginas arbitrárias para descobrir destinos.

chat_result = executor.initiate_chat(
    assistant,
    message=(
        "O fluxo de trabalho de staging aprovado encontrou Cloudflare Turnstile.\n"
        "website_url=https://staging.example.com/account-check\n"
        "website_key=0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n"
        "action=account_check\n"
        "cdata=\n"
        "Chame a ferramenta registrada uma vez e retorne o resultado estruturado."
    ),
    max_turns=4,
)

Em um design de produção, o código de aplicativo estruturado deve construir essa mensagem a partir de dados de tempo de execução validados. Não aceite uma chave do site ou URL de destino diretamente de entrada de linguagem natural não confiável.

Aplicar o Token na Camada de Navegador

Um token do Turnstile geralmente é consumido pelo formulário original ou pela solicitação do servidor. A integração exata depende do aplicativo autorizado. Para um fluxo de navegador, passe o token retornado de volta para o código determinístico que conhece o widget e o caminho de submissã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 resposta do Turnstile não encontrado');
          }
          response.value = token;
          response.dispatchEvent(new Event('input', { bubbles: true }));
          response.dispatchEvent(new Event('change', { bubbles: true }));
        }
        """,
        token,
    )

Alguns aplicativos usam renderização baseada em callback ou submissão gerenciada pelo servidor. Teste contra seu próprio aplicativo de staging e siga sua integração suportada em vez de assumir que definir um campo oculto é suficiente. A documentação de validação do lado do servidor do Cloudflare explica que o proprietário do site deve validar tokens com Siteverify.

O guia do Turnstile do CapSolver fornece contexto de implementação adicional, e a FAQ de solução de problemas do CapSolver ajuda a diagnosticar tokens inválidos ou rejeitados.

Adicione Tentativas Limitadas e Erros Estruturados

Não permita que um agente tente repetidamente indefinidamente. Limite as tentativas e classifique os falhas para que a automação possa parar com segurança.

import asyncio

MAX_ATTEMPTS = 2

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

    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 apenas metadados seguros: hostname do destino, tipo de tarefa, duração, resultado, erro normalizado e número de tentativas. Não registre o token completo, chave de API, cookies de sessão ou conteúdos de formulário.

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

Checklist de Produção

A Perguntas Frequentes sobre resolução de CAPTCHA do CapSolver explica o comportamento geral das tarefas, enquanto a Perguntas Frequentes sobre raspagem da web do CapSolver aborda controles operacionais para coleta automatizada.

Uso Responsável

Use este fluxo apenas em aplicações que você possua, teste ou tenha permissão explícita para automatizar. Um token de solução não concede autorização para acessar dados privados, submeter transações, criar contas ou ignorar os termos de um site. Aplicar limites de taxa, manter registros de auditoria e exigir confirmação para ações que alterem dados ou afetem usuários.

Conclusão

Para resolver o Cloudflare Turnstile no AutoGen de forma confiável, faça do CapSolver uma ferramenta restrita em vez de lógica de agente aberta. O assistente do AutoGen decide quando a ferramenta é apropriada, o executor executa uma AntiTurnstileTaskProxyLess validada e a camada de navegador consome o token resultante dentro do mesmo fluxo aprovado. Essa divisão torna a integração mais fácil de testar, auditar e proteger.

Comece com o CapSolver, valide o fluxo contra uma página de staging que você controle e adicione listas de permissões de host, tentativas limitadas e logs seguros de tokens antes da implantação em produção.

Perguntas Frequentes

O tipo de tarefa do Turnstile do CapSolver requer um proxy?

O tipo de tarefa documentado é AntiTurnstileTaskProxyLess, então você não precisa fornecer um proxy para a tarefa. Seu fluxo de navegador mais amplo pode ainda ter sua própria configuração de rede.

Quais campos são necessários para a tarefa?

websiteURL e websiteKey são necessários. metadata.action e metadata.cdata são opcionais e devem ser fornecidos apenas quando o widget os usar.

O AutoGen pode descobrir a chave do site automaticamente?

O design mais seguro é que uma camada de navegador ou aplicativo determinístico extraia e valide a chave do site, depois a forneça para a ferramenta. Não deixe o modelo inventar ou adivinhar o valor.

Por que usar agentes separados de chamador e executor?

O chamador pode propor a chamada da ferramenta, enquanto o executor executa código Python controlado sem LLM. Isso mantém segredos e permissões de runtime longe do agente de raciocínio.

O que deve acontecer se o token retornado for rejeitado?

Confirme a URL da página, a chave do site, a ação opcional ou cdata, a atualidade do token e o caminho de submissão. Tente novamente no máximo uma ou duas vezes, depois pausar para revisão do operador em vez de loopar.