Como resolver CAPTCHA nos Workflows Multi-Agentes do CrewAI

CrewAI orquestra múltiplos agentes de IA trabalhando juntos em tarefas complexas — pesquisa, coleta de dados, criação de conteúdo e automação de fluxos de trabalho. Quando qualquer agente da equipe enfrenta um desafio CAPTCHA durante a interação na web, todo o pipeline de múltiplos agentes trava. O pacote capsolver-agent do CapSolver se integra diretamente aos fluxos de trabalho do CrewAI, dando aos seus agentes a capacidade de resolver reCAPTCHA, Cloudflare Turnstile e outros desafios de verificação sem interromper o fluxo de execução colaborativa.

TL;DR

• Fluxos de trabalho de múltiplos agentes CrewAI travam quando qualquer membro da equipe encontra um CAPTCHA durante tarefas na web
• O CapSolver fornece esquemas de ferramentas compatíveis com o sistema de registro de ferramentas personalizadas do CrewAI
• O executor capsolver-agent resolve usando o serviço de IA do CapSolver e retorna resultados estruturados
• Suporta reCAPTCHA v2/v3 (incluindo Enterprise) e Cloudflare Turnstile
• A integração requer menos de 15 linhas de código usando create_executor() e o decorador @tool do CrewAI

Por que os agentes CrewAI precisam de resolução de CAPTCHA

O CrewAI permite que equipes de agentes especializados de IA colaborem em tarefas que exigem várias capacidades. Uma equipe típica pode incluir um agente pesquisador que navega na web, um agente analista que processa dados e um agente escritor que produz relatórios. Quando o agente pesquisador encontra um CAPTCHA em um site-alvo, ele não pode prosseguir — e como os agentes do CrewAI passam saídas sequencialmente, todo o fluxo de trabalho da equipe para.

Esse problema é amplificado no CrewAI porque múltiplos agentes podem precisar de acesso à web. Uma equipe de enriquecimento de leads pode ter um agente raspando dados de empresas e outro verificando informações de contato — ambos enfrentando CAPTCHAs em sites diferentes simultaneamente. Sem um mecanismo de resolução, equipes de produção exigem supervisão constante humana, anulando o propósito da orquestração autônoma de múltiplos agentes.

De acordo com os dados de produção do CapSolver, cerca de 30% das tarefas de agentes na web enfrentam desafios de verificação. Para uma equipe CrewAI executando 10 tarefas dependentes da web, isso significa 3 pontos de travamento potenciais por execução — cada um exigindo intervenção manual sem resolução automatizada.

O que você precisa antes de começar

Instale os pacotes necessários:

# Motor do CapSolver (dependência obrigatória)
pip install git+https://github.com/capsolver-ai/capsolver-core.git

# Ferramentas do agente CapSolver
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# Framework CrewAI
pip install crewai crewai-tools

Defina variáveis de ambiente:

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

Certifique-se de ter uma conta CapSolver com créditos de API carregados. A página de preços do CapSolver mostra as taxas atuais por tipo de CAPTCHA.

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

O que fazer

O CrewAI usa ferramentas personalizadas definidas com o decorador @tool. Envolva o executor do CapSolver em uma ferramenta compatível com o CrewAI:

import asyncio
from crewai import Agent, Task, Crew
from crewai.tools import tool
from capsolver_agent.schema import create_executor

# Crie o executor do CapSolver
executor = create_executor(api_key="SUA_CHAVE_API_CAPSOLVER")

@tool("Resolver CAPTCHA")
def resolver_captcha(tipo_captcha: str, url_site: str, chave_site: str) -> str:
    """Resolver um desafio CAPTCHA e retornar o token.
    Use esta ferramenta quando encontrar um CAPTCHA em um site.
    
    Args:
        tipo_captcha: O tipo de CAPTCHA - 'reCaptchaV2', 'reCaptchaV3' ou 'cloudflare'
        url_site: A URL completa da página com o CAPTCHA
        chave_site: A chave do site (valor do atributo data-sitekey)
    
    Returns:
        O token do CAPTCHA resolvido para enviar com o formulário
    """
    resultado = asyncio.run(executor.execute("resolver_captcha", {
        "tipo_captcha": tipo_captcha,
        "url_site": url_site,
        "chave_site": chave_site
    }))
    
    if resultado["sucesso"]:
        return f"CAPTCHA resolvido com sucesso. Token: {resultado['solucao']['token']}"
    else:
        return f"Falha ao resolver CAPTCHA: {resultado['erro']}"

Essa ferramenta segue o padrão padrão do CrewAI — o decorador @tool a registra com um nome e descrição que o LLM do agente usa para decidir quando invocá-la.

Por que isso importa

Os agentes CrewAI selecionam ferramentas com base em suas descrições. Uma ferramenta de resolução de CAPTCHA bem descrita permite que o agente reconheça de forma autônoma quando precisa resolver e invoque a ferramenta com os parâmetros corretos. O formato de retorno estruturado fornece feedback claro ao agente sobre sucesso ou falha.

Erros comuns a evitar

• Usar async diretamente em ferramentas CrewAI: A execução de ferramentas do CrewAI é síncrona. Envolva chamadas assíncronas do CapSolver com asyncio.run() dentro da função da ferramenta.
• Descrições vagas de ferramentas: O LLM precisa de uma descrição clara para saber quando usar a ferramenta. Inclua nomes específicos de tipos de CAPTCHA e explicações de parâmetros.

Etapa 2 — Criar um Agente CrewAI com Capacidade de CAPTCHA

O que fazer

Crie um agente CrewAI que tenha a capacidade de resolver CAPTCHA como uma de suas ferramentas disponíveis:

from crewai import Agent

# Agente de pesquisa com capacidade de resolver CAPTCHA
pesquisador = Agent(
    papel="Especialista em Pesquisa na Web",
    objetivo="Coletar dados de sites, lidando com quaisquer desafios CAPTCHA encontrados",
    histórico="""Você é um especialista em pesquisa na web que coleta dados de várias 
    fontes online. Quando você encontrar um desafio CAPTCHA em um site, use a ferramenta resolver_captcha para limpá-lo 
    e continuar sua pesquisa. Você sabe como identificar os tipos de CAPTCHA: reCaptchaV2 (caixa de seleção ou invisível), reCaptchaV3 
    (baseado em pontuação) e cloudflare (widget Turnstile).""",
    ferramentas=[resolver_captcha],
    verbose=True
)

Para equipes que precisam de múltiplos agentes com acesso à web, forneça a ferramenta CAPTCHA a cada agente que possa encontrar verificação:

# Agente de coleta de dados
coletor_dados = Agent(
    papel="Especialista em Coleta de Dados",
    objetivo="Extrair dados estruturados de sites-alvo",
    histórico="Você coleta dados de fontes da web e lida com desafios CAPTCHA usando a ferramenta resolver_captcha.",
    ferramentas=[resolver_captcha],
    verbose=True
)

# Agente de verificação
verificador = Agent(
    papel="Especialista em Verificação de Dados", 
    objetivo="Verificar dados coletados contra fontes autoritativas",
    histórico="Você verifica a precisão dos dados verificando fontes oficiais, resolvendo CAPTCHAs quando necessário.",
    ferramentas=[resolver_captcha],
    verbose=True
)

Etapa 3 — Montar a Equipe com Tarefas Conscientes de CAPTCHA

O que fazer

Defina tarefas que possam exigir resolução de CAPTCHA e as assemble em uma equipe:

from crewai import Task, Crew, Process

# Tarefa que pode encontrar CAPTCHA
pesquisa_tarefa = Task(
    descrição="""Pesquisar o site-alvo em {url}. 
    Se você encontrar um desafio CAPTCHA, identifique seu tipo e chave do site,
    depois use a ferramenta resolver_captcha para obter um token.
    O site usa reCAPTCHA v2 com chave do site: {chave_site}.
    Colete os dados necessários após resolver o CAPTCHA.""",
    saída_esperada="Dados coletados do site-alvo com token CAPTCHA, se necessário",
    agente=pesquisador
)

# Tarefa de análise (depende dos resultados da pesquisa)
análise_tarefa = Task(
    descrição="Analise os dados coletados pelo pesquisador e produza um relatório de resumo.",
    saída_esperada="Relatório de análise estruturado dos dados coletados",
    agente=coletor_dados
)

# Crie a equipe
equipe = Crew(
    agentes=[pesquisador, coletor_dados],
    tarefas=[pesquisa_tarefa, análise_tarefa],
    processo=Process.sequencial,
    verbose=True
)

# Execute a equipe
resultado = equipe.kickoff(inputs={
    "url": "https://exemplo.com/dados",
    "chave_site": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
})
print(resultado)

O processo sequencial garante que o pesquisador conclua (incluindo a resolução do CAPTCHA) antes que o coletor de dados comece a análise. Para execução paralela, cada agente lida independentemente com os CAPTCHAs em seus sites designados.

Por que isso importa

A força do CrewAI está na colaboração entre múltiplos agentes. Ao fornecer capacidade de resolução de CAPTCHA aos agentes que precisam dela, a equipe opera de forma autônoma do início ao fim. Nenhuma intervenção humana é necessária quando os desafios de verificação aparecem — o agente reconhece a situação, invoca a ferramenta e continua.

Etapa 4 — Lidar com Múltiplos Tipos de CAPTCHA no CrewAI

Diferentes sites usam sistemas diferentes de CAPTCHA. Crie ferramentas especializadas para cenários comuns:

@tool("Resolver reCAPTCHA v3")
def resolver_recaptcha_v3(url_site: str, chave_site: str, acao_pagina: str = "verificar") -> str:
    """Resolver um desafio reCAPTCHA v3 com um token de pontuação alta.
    Use quando o site usa reCAPTCHA v3 invisível (baseado em pontuação, sem caixa de seleção visível).
    
    Args:
        url_site: A URL completa da página
        chave_site: A chave do site reCAPTCHA
        acao_pagina: O nome da ação para pontuação v3 (padrão: 'verificar')
    """
    resultado = asyncio.run(executor.execute("resolver_captcha", {
        "tipo_captcha": "reCaptchaV3",
        "url_site": url_site,
        "chave_site": chave_site,
        "acao_pagina": acao_pagina,
        "pontuacao_minima": 0.7
    }))
    if resultado["sucesso"]:
        return f"reCAPTCHA v3 resolvido. Token: {resultado['solucao']['token']}"
    return f"Falha: {resultado['erro']}"

@tool("Resolver Cloudflare Turnstile")
def resolver_turnstile(url_site: str, chave_site: str) -> str:
    """Resolver um desafio Cloudflare Turnstile.
    Use quando o site é protegido pelo Cloudflare e exibe um widget Turnstile.
    
    Args:
        url_site: A URL completa da página
        chave_site: A chave do site Turnstile (começa com 0x)
    """
    resultado = asyncio.run(executor.execute("resolver_captcha", {
        "tipo_captcha": "cloudflare",
        "url_site": url_site,
        "chave_site": chave_site
    }))
    if resultado["sucesso"]:
        return f"Turnstile resolvido. Token: {resultado['solucao']['token']}"
    return f"Falha: {resultado['erro']}"

O guia reCAPTCHA do CapSolver e guia Cloudflare Turnstile fornecem detalhes adicionais sobre os parâmetros e comportamento de cada tipo de CAPTCHA.

Claim Your Bonus Code: Use o código WEBS no Painel CapSolver para obter um bônus adicional de 5% em cada recarga. Perfeito para equipes executando fluxos de trabalho de agentes múltiplos CrewAI em larga escala.

Etapa 5 — Padrões de Produção para CrewAI + CapSolver

O que fazer

Para implantações de produção do CrewAI, adicione tratamento de erros e lógica de repetição:

@tool("Resolver CAPTCHA com Repetição")
def resolver_captcha_robusto(tipo_captcha: str, url_site: str, chave_site: str) -> str:
    """Resolver um CAPTCHA com repetição automática em caso de falha.
    Tenta resolver até 3 vezes antes de relatar falha.
    """
    for tentativa in range(3):
        resultado = asyncio.run(executor.execute("resolver_captcha", {
            "tipo_captcha": tipo_captcha,
            "url_site": url_site,
            "chave_site": chave_site
        }))
        if resultado["sucesso"]:
            return f"Resolvido na tentativa {tentativa + 1}. Token: {resultado['solucao']['token']}"
        if tentativa < 2:
            import time
            time.sleep(3)
    return f"Falha após 3 tentativas: {resultado.get('erro', 'Erro desconhecido')}"

Para equipes que processam múltiplos sites, implemente uma verificação de saldo antes de iniciar:

@tool("Verificar Saldo do Solucionador de CAPTCHA")
def verificar_saldo() -> str:
    """Verifique o saldo restante para créditos de resolução de CAPTCHA."""
    resultado = asyncio.run(executor.execute("obter_saldo", {}))
    if resultado["sucesso"]:
        return f"Saldo: ${resultado['saldo']:.2f}"
    return "Não foi possível verificar o saldo"

A documentação de raspagem da web do CapSolver aborda padrões adicionais para coleta de dados de alta volume que se aplicam aos agentes de pesquisa do CrewAI. Para agentes que usam automação de navegador, a extensão CapSolver ajuda a identificar parâmetros de CAPTCHA durante o desenvolvimento.

Conclusão

Integrar a resolução de CAPTCHA nos fluxos de trabalho de múltiplos agentes CrewAI requer envolver o executor do CapSolver em funções @tool compatíveis com o CrewAI, atribuir essas ferramentas aos agentes que realizam tarefas na web e montar equipes que possam operar de forma autônoma por meio de desafios de verificação. CapSolver fornece a infraestrutura de resolução de IA que mantém seus pipelines de múltiplos agentes funcionando sem intervenção humana.

Comece criando uma única ferramenta de resolução de CAPTCHA, teste-a com um agente e depois expanda para equipes completas com múltiplos agentes que interajam com a web. O enfoque em ferramentas significa que os agentes decidem quando resolver com base no contexto — nenhuma lógica de detecção de CAPTCHA codificada diretamente é necessária.

Perguntas Frequentes

Múltiplos agentes CrewAI podem resolver CAPTCHAs simultaneamente?

Sim. Cada agente que tem a ferramenta de resolução de CAPTCHA pode invocá-la independentemente. A API do CapSolver suporta submissões concorrentes sem limitação de taxa, então a execução paralela da equipe funciona sem conflitos. Cada resolução é rastreada com um ID de solicitação único para depuração.

Como o CrewAI sabe quando um agente precisa resolver um CAPTCHA?

O LLM do agente raciocina sobre a situação com base na descrição da ferramenta e no contexto da tarefa. Quando a tarefa envolve acessar um recurso protegido por CAPTCHA, o agente reconhece a necessidade e chama a ferramenta de resolução com parâmetros apropriados. Você também pode incluir detalhes de CAPTCHA na descrição da tarefa para orientação explícita.

O que acontece se a resolução de CAPTCHA falhar em um fluxo de trabalho CrewAI?

A ferramenta retorna uma mensagem de falha ao agente. O agente pode então tentar novamente, tentar parâmetros alternativos ou relatar a falha em sua saída de tarefa. O tratamento de erros do CrewAI permite que a equipe continue com as tarefas restantes mesmo que uma tarefa encontre um CAPTCHA irrecuperável.

O CapSolver é compatível com o modo de processo hierárquico do CrewAI?

Sim. No modo hierárquico, o agente gerente delega tarefas aos membros da equipe. Se uma tarefa delegada exigir resolução de CAPTCHA, o agente designado usa sua ferramenta independentemente. O gerente recebe o resultado concluído sem precisar entender os detalhes da resolução de CAPTCHA.

Quanto custa a resolução de CAPTCHA por execução CrewAI?

O custo depende do número de CAPTCHAs encontrados e de seus tipos. O reCAPTCHA v2 custa aproximadamente 2-3 por 1.000 resoluções, o reCAPTCHA v3 custa 1-2 por 1.000 e o Cloudflare Turnstile custa 1-2 por 1.000. Uma equipe de pesquisa típica do CrewAI que encontra 3-5 CAPTCHAs por execução custa 0,005-0,015 por execução.