Solvedor de CAPTCHA da CrewAI: Guia de Código da Ferramenta de Agente

TL;DR

• O trabalho do resolvedor de CAPTCHA do CrewAI deve usar a pilha de agentes de IA do CapSolver como uma camada de recuperação explícita, não como lógica oculta de repetição.
• capsolver-core se adequa a scripts do Playwright, capsolver-agent se adequa a agentes de chamada de ferramenta e capsolver-mcp se adequa a clientes compatíveis com MCP.
• O padrão seguro é detectar, ler os parâmetros, resolver uma vez com tentativas limitadas, preencher de volta e registrar o estado da solicitação para revisão.
• Os agentes devem parar quando o escopo da tarefa mudar, a página pedir acesso restrito ou o tratamento de desafio repetir sem progresso.

Introdução

O trabalho do resolvedor de CAPTCHA do CrewAI precisa de uma fronteira de ferramenta de nível de código entre planejamento, controle do navegador e revisão. CapSolver deve ser configurado como uma capacidade de agente documentada: o navegador ou modelo detecta um desafio de verificação, a ferramenta aprovada o trata e o agente retoma apenas quando a tarefa autorizada pelo usuário original ainda é válida. A documentação oficial do CapSolver AI descreve três camadas práticas: CapSolver para Agentes de IA para arquitetura, modo SDK do Core para fluxos do Playwright, esquemas de ferramentas do agente para chamadas controladas por modelo e ferramentas do serviço MCP para clientes que descobrem ferramentas pelo Protocolo de Contexto do Modelo. Este artigo transforma essas documentações em um fluxo de trabalho de resolvedor de CAPTCHA do CrewAI com código, regras de parada e campos de log.

Use os Pacotes Oficiais do CapSolver AI

A documentação do CapSolver AI descreve três camadas. Use a camada mais baixa que corresponda ao seu modelo de propriedade: SDK do Core quando seu código controla o navegador, ferramentas do agente quando um modelo decide quando chamar uma ferramenta e serviço MCP quando seu cliente de IA deve descobrir ferramentas automaticamente.

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
pip install git+https://github.com/capsolver-ai/capsolver-agent.git
pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium
export CAPSOLVER_API_KEY="sua-chave-da-api-do-capsolver"

A Introdução e Início Rápido explica os papéis dos pacotes: capsolver-core expõe o motor, capsolver-agent o encapsula como ferramentas e capsolver-mcp expõe a mesma capacidade a clientes MCP. Mantenha a chave da API em configuração de ambiente e evite colocá-la em prompts, logs, capturas de tela ou exemplos de artigos.

Design de Papel do CrewAI

Uma implementação do CrewAI deve atribuir a cada papel uma responsabilidade estreita. O planejador identifica que uma página está bloqueada por um desafio de verificação. O trabalhador do navegador é responsável pela navegação. O manipulador de ferramentas do CapSolver é responsável pelo passo do desafio. O revisor é responsável pela decisão final quando a execução é incerta.

crew_state = {
    "task_id": "lead-enrichment-042",
    "allowed_domains": ["example.com"],
    "captcha_attempts": 0,
    "max_captcha_attempts": 1,
    "final_state": "planning",
}

def may_call_capsolver(state, current_url):
    if state["captcha_attempts"] >= state["max_captcha_attempts"]:
        return False
    return any(domain in current_url for domain in state["allowed_domains"])

Essa pequena porta é o que mantém o comportamento do resolvedor de CAPTCHA do CrewAI visível. O crew pode pedir ajuda apenas quando a página estiver no escopo e o orçamento de tentativas estiver disponível.

Padrão de Ferramenta de Agente para Decisões Controladas por Modelo

Use capsolver-agent quando o modelo deve escolher quando o tratamento de desafio for necessário. O guia de Ferramentas de Agente expõe definições de ferramentas com get_all_tools() e roteia chamadas de ferramentas de modelo por meio de create_executor().

import json
from openai import OpenAI
from capsolver_agent.schema import create_executor, get_all_tools

client = OpenAI()
executor = create_executor(api_key="SUA_CHAVE_DO_CAPSOLVER", default_timeout=120)
tools = [tool.to_openai_function() for tool in get_all_tools()]

messages = [{
    "role": "user",
    "content": "Continue a tarefa aprovada do navegador. Se um CAPTCHA aparecer, chame a ferramenta CapSolver uma vez e relate o resultado."
}]

async def run_one_turn():
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
    )

    for call in response.choices[0].message.tool_calls or []:
        args = json.loads(call.function.arguments)
        result = await executor.execute(call.function.name, args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

Para o resolvedor de CAPTCHA do CrewAI, vincule esse caminho de ferramenta a uma política de revisor. O modelo pode solicitar a ferramenta, mas seu aplicativo decide o escopo de URL permitido, o número máximo de tentativas e se o resultado pode ser usado para continuar.

Padrão de SDK do Core para Agentes Controlados pelo Navegador

Use capsolver-core quando seu fluxo de resolvedor de CAPTCHA do CrewAI já possuir uma página do Playwright. O caminho oficial do SDK do Core é detectar, ler as informações do CAPTCHA, resolver e preencher o token de volta na página. A chamada do navegador completa é útil quando a estrutura da página é dinâmica.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

TARGET_URL = "https://example.com/approved-workflow"

async def run_agent_step():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        page = await browser.new_page()
        await page.goto(TARGET_URL, wait_until="domcontentloaded")

        async with create_capsolver(api_key="SUA_CHAVE_DO_CAPSOLVER") as cap:
            captcha_types = await cap.detect(page)
            if not captcha_types:
                return "continue_without_challenge"

            results = await cap.solve_on_page(page)
            solved = [r for r in results if r.solution and not r.error]
            if not solved:
                return "stop_for_review"

        return "resume_original_authorized_task"

asyncio.run(run_agent_step())

O detalhe importante de engenharia é o valor de retorno, não apenas o token. Seu agente deve continuar apenas quando a tarefa original ainda for legal, razoável e autorizada pelo usuário. Deve parar quando a página pedir dados privados, restritos, sensíveis ou não autorizados.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus extra de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Guardrails que Pertencem ao Loop do Agente

Verificações de Escopo

Antes de chamar qualquer ferramenta de desafio, confirme que a tarefa foi autorizada pelo usuário, o alvo está na lista de domínios aprovados e os dados acessados são públicos ou de outra forma permitidos. Um fluxo de trabalho de resolvedor de CAPTCHA do CrewAI nunca deve tratar capacidade técnica como permissão.

Limites de Tentativas

Use um orçamento pequeno de tentativas. Uma tentativa de recarregamento do navegador e uma tentativa de cooldown geralmente são suficientes. Eventos de desafio repetidos devem criar um ticket de revisão em vez de continuar em silêncio.

Observabilidade

Capture URL, horário, tipo de desafio, caminho do pacote do CapSolver, número de tentativas, estado do resultado e estado final da página. Não armazene conteúdo de página não relacionado, credenciais, segredos de sessão ou dados pessoais, a menos que sua política permita explicitamente.

Para o resolvedor de CAPTCHA do CrewAI, mantenha a execução legal e baseada em evidências: respeite o comportamento dos códigos de status HTTP, requisitos de acessibilidade, gestão de riscos de privacidade e gestão de dados públicos.

Conclusão

Um artigo forte sobre resolvedor de CAPTCHA do CrewAI deve mostrar caminhos de implementação real, e um fluxo de trabalho produtivo deve fazer o mesmo. A escolha prática é simples: use capsolver-core para automação de navegador controlada pelo código, capsolver-agent para agentes de chamada de ferramenta e capsolver-mcp para clientes compatíveis com MCP. Mantenha o tratamento de desafio limitado, registrado e vinculado a trabalho autorizado pelo usuário. Quando sua equipe estiver pronta para adicionar essa camada de recuperação a um fluxo de agente, comece com CapSolver e a documentação oficial de agentes de IA.

Perguntas Frequentes

Qual pacote do CapSolver um agente de IA deve usar primeiro?

Use capsolver-core quando seu aplicativo controla o código do navegador, capsolver-agent quando um modelo deve chamar uma ferramenta e capsolver-mcp quando o cliente de IA deve descobrir ferramentas através do MCP.

O modelo deve decidir todas as tentativas de CAPTCHA?

Não. O modelo pode solicitar uma chamada de ferramenta, mas o aplicativo deve impor escopo, limites de tentativas e condições de parada.

Esse fluxo pode ser usado em dados privados ou restritos?

Não. O tratamento de CAPTCHA não concede permissão. Use-o apenas em fluxos autorizados pelo usuário, legais e razoáveis, que respeitem os termos do site e os direitos de dados.

O que deve ser registrado para revisão?

Registre a URL de origem, tipo de desafio, caminho da ferramenta, contagem de tentativas, estado do resultado e estado final da página. Mantenha credenciais e conteúdo de página não relacionado fora dos logs.