Como resolver CAPTCHA em Agentes AutoGen

A framework AutoGen da Microsoft permite agentes de IA conversacional que colaboram por meio de diálogos de múltiplas rodadas para completar tarefas complexas. Quando os agentes AutoGen realizam operações baseadas na web — recuperação de dados, envio de formulários ou pesquisa automatizada — os desafios CAPTCHA interrompem o fluxo da conversa e bloqueiam a conclusão da tarefa. O pacote capsolver-agent do CapSolver fornece esquemas de ferramentas e um executor assíncrono que se integram diretamente ao mecanismo de chamada de função do AutoGen, dando aos seus agentes a capacidade de resolver reCAPTCHA, Cloudflare Turnstile e outros desafios de verificação durante a conversa.

TL;DR

• Os agentes conversacionais do AutoGen travam quando tarefas web encontram desafios de verificação CAPTCHA
• O CapSolver se integra ao API register_function do AutoGen como uma ferramenta chamável
• O executor capsolver-agent resolve de forma assíncrona e retorna resultados estruturados
• Suporta reCAPTCHA v2/v3 (incluindo Enterprise) e Cloudflare Turnstile
• Funciona com os padrões de chat de dois agentes e chat em grupo do AutoGen

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

A arquitetura multi-agente do AutoGen usa padrões de conversa onde os agentes colaboram por meio de mensagens. Um conjunto típico inclui um AssistantAgent (a IA) e um UserProxyAgent (que executa código e ferramentas). Quando o assistente determina que uma tarefa web requer resolução de CAPTCHA, ele precisa de uma função registrada para chamar — caso contrário, o ciclo de conversa trava sem maneira de prosseguir.

O problema é amplificado em cenários de chat em grupo do AutoGen. Múltiplos agentes podem precisar de acesso à web simultaneamente: um agente pesquisando dados de empresa, outro verificando informações de contato, um terceiro verificando documentos regulatórios. Cada um pode encontrar CAPTCHAs em sites diferentes. Sem um mecanismo de resolução, toda a conversa em grupo para na primeira barreira de verificação.

De acordo com dados de produção do CapSolver, aproximadamente 30% das tarefas web dos agentes encontram desafios de verificação. Para um fluxo de trabalho do AutoGen executando 10 etapas dependentes da web, isso significa 3 possíveis interrupções por conversa — cada uma exigindo intervenção humana ou uma ferramenta de resolução automatizada.

O que você precisa antes de começar

Instale os pacotes necessários:

# Motor do CapSolver (dependência necessária)
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

# Framework AutoGen
pip install autogen-agentchat

Defina variáveis de ambiente:

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

Você precisa de uma conta do CapSolver com créditos de API carregados.

Etapa 1 — Registrar a resolução de CAPTCHA como uma função do AutoGen

O que fazer

O AutoGen usa register_function para tornar ferramentas disponíveis para agentes. Crie uma função de resolução de CAPTCHA e a registre:

import asyncio
from autogen import AssistantAgent, UserProxyAgent, config_list_from_json
from capsolver_agent.schema import create_executor

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

def solve_captcha(
    captcha_type: str,
    website_url: str,
    website_key: str,
    page_action: str = "",
    min_score: float = 0.7
) -> str:
    """Resolva um desafio CAPTCHA e retorne o token de verificação.
    
    Args:
        captcha_type: O tipo de CAPTCHA - 'reCaptchaV2', 'reCaptchaV3' ou 'cloudflare'
        website_url: A URL completa da página com o CAPTCHA
        website_key: A chave do site (atributo data-sitekey)
        page_action: Nome da ação para reCAPTCHA v3 (opcional)
        min_score: Pontuação mínima para reCAPTCHA v3 (padrão 0.7)
    
    Returns:
        O token do CAPTCHA resolvido ou mensagem de erro
    """
    params = {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }
    if page_action and captcha_type == "reCaptchaV3":
        params["page_action"] = page_action
        params["min_score"] = min_score
    
    result = asyncio.run(executor.execute("solve_captcha", params))
    
    if result["success"]:
        token = result["solution"]["token"]
        return f"CAPTCHA resolvido com sucesso. Token (primeiros 80 caracteres): {token[:80]}..."
    return f"Resolução de CAPTCHA falhou: {result['error']}"

Por que isso importa

A registro de funções do AutoGen é o método padrão para dar capacidades executáveis aos agentes. O agente assistente vê a descrição da função, entende seus parâmetros através do docstring e a chama quando a conversa requer resolução de CAPTCHA. Isso segue exatamente o padrão de design do AutoGen.

Etapa 2 — Configurar o chat de dois agentes do AutoGen

O que fazer

Crie um par de AssistantAgent e UserProxyAgent com capacidade de resolução de CAPTCHA:

# Configuração do LLM
llm_config = {
    "config_list": [{"model": "gpt-4o", "api_key": "SUA_CHAVE_DO_OPENAI"}],
    "temperature": 0
}

# Agente assistente (a IA que decide o que fazer)
assistant = AssistantAgent(
    name="web_assistant",
    system_message="""Você é um assistente de pesquisa web com capacidade de resolver CAPTCHA.
    Quando uma tarefa requer acesso a uma página protegida por CAPTCHA, use a função solve_captcha
    com os parâmetros apropriados:
    - captcha_type: 'reCaptchaV2', 'reCaptchaV3' ou 'cloudflare'
    - website_url: a URL completa da página
    - website_key: a chave do site da página
    
    Após resolver, retorne o token ao usuário para submissão do formulário.""",
    llm_config=llm_config
)

# Proxy do usuário (executa funções em nome do assistente)
user_proxy = UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    max_consecutive_auto_reply=5,
    code_execution_config={"work_dir": "workspace", "use_docker": False}
)

# Registrar a função de resolução de CAPTCHA
from autogen import register_function

register_function(
    solve_captcha,
    caller=assistant,      # O assistente decide quando chamar
    executor=user_proxy,   # O proxy do usuário executa a função
    name="solve_captcha",
    description="Resolve um desafio CAPTCHA (reCAPTCHA v2/v3 ou Cloudflare Turnstile) e retorna o token de verificação"
)

Por que isso importa

O padrão de dois agentes é a arquitetura central do AutoGen. O assistente raciocina sobre a tarefa e decide chamar solve_captcha quando necessário. O proxy do usuário executa a chamada da função e retorna o resultado ao assistente, que então continua a conversa com o token disponível.

Etapa 3 — Executar uma conversa com resolução de CAPTCHA

O que fazer

Inicie uma conversa que exija resolução de CAPTCHA:

# Iniciar a conversa
user_proxy.initiate_chat(
    assistant,
    message="""Preciso acessar uma página protegida por reCAPTCHA v2.
    URL: https://example.com/data-portal
    Chave do site: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
    
    Por favor, resolva o CAPTCHA e me forneça o token."""
)

O fluxo da conversa:

1. O proxy do usuário envia a mensagem da tarefa
2. O assistente reconhece que a resolução de CAPTCHA é necessária
3. O assistente chama solve_captcha com os parâmetros
4. O proxy do usuário executa a função (o CapSolver resolve)
5. O resultado retorna ao assistente
6. O assistente apresenta o token para concluir a tarefa

Etapa 4 — Usar em chat em grupo do AutoGen

O que fazer

Para fluxos de trabalho complexos com múltiplos agentes, registre a resolução de CAPTCHA em um chat em grupo:

from autogen import GroupChat, GroupChatManager

# Agentes especializados
researcher = AssistantAgent(
    name="researcher",
    system_message="Você pesquisa sites e coleta dados. Use solve_captcha quando encontrar desafios de verificação.",
    llm_config=llm_config
)

analyst = AssistantAgent(
    name="analyst",
    system_message="Você analisa os dados coletados e produz insights.",
    llm_config=llm_config
)

executor_agent = UserProxyAgent(
    name="executor",
    human_input_mode="NEVER",
    code_execution_config={"work_dir": "workspace", "use_docker": False}
)

# Registrar resolução de CAPTCHA para o researcher
register_function(
    solve_captcha,
    caller=researcher,
    executor=executor_agent,
    name="solve_captcha",
    description="Resolve desafios de CAPTCHA em sites"
)

# Criar chat em grupo
group_chat = GroupChat(
    agents=[researcher, analyst, executor_agent],
    messages=[],
    max_round=10
)

manager = GroupChatManager(groupchat=group_chat, llm_config=llm_config)

# Iniciar tarefa de pesquisa em grupo
executor_agent.initiate_chat(
    manager,
    message="Pesquise os dados em https://example.com/reports. Está protegido por reCAPTCHA v2 (chave: 6Le...). Resolva o CAPTCHA, colete os dados e depois os analise."
)

O guia reCAPTCHA do CapSolver e documentação do Cloudflare Turnstile fornecem detalhes adicionais de parâmetros para cada tipo de CAPTCHA.

Claim Your Bonus Code: Use o código WEBS no Painel do CapSolver para obter um bônus adicional de 5% em cada recarga. Perfeito para equipes executando fluxos de trabalho de agentes multi-AutoGen.

Etapa 5 — Padrões de produção e tratamento de erros

O que fazer

Adicione lógica de repetição e verificação de saldo para implantações de produção:

def solve_captcha_with_retry(
    captcha_type: str,
    website_url: str,
    website_key: str,
    max_retries: int = 3
) -> str:
    """Resolve CAPTCHA com repetição automática em caso de falha."""
    for attempt in range(max_retries):
        params = {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        }
        result = asyncio.run(executor.execute("solve_captcha", params))
        
        if result["success"]:
            return f"Resolvido (tentativa {attempt+1}). Token: {result['solution']['token'][:80]}..."
        
        if attempt < max_retries - 1:
            import time
            time.sleep(3)
    
    return f"Falha após {max_retries} tentativas: {result.get('error', 'Desconhecido')}"

def check_captcha_balance() -> str:
    """Verifica o saldo restante de créditos para resolução de CAPTCHA."""
    result = asyncio.run(executor.execute("get_balance", {}))
    if result["success"]:
        return f"Saldo do CapSolver: ${result['balance']:.2f}"
    return "Não foi possível recuperar o saldo"

Registre ambas as funções para capacidade abrangente:

register_function(solve_captcha_with_retry, caller=assistant, executor=user_proxy,
    name="solve_captcha", description="Resolve CAPTCHA com lógica de repetição")
register_function(check_captcha_balance, caller=assistant, executor=user_proxy,
    name="check_balance", description="Verifica o saldo de créditos para resolução de CAPTCHA")

A documentação de raspagem web do CapSolver aborda padrões adicionais para coleta de dados de alta volume aplicáveis a agentes de pesquisa do AutoGen. Para automação baseada em navegador, a extensão do CapSolver ajuda a identificar parâmetros de CAPTCHA durante o desenvolvimento.

Conclusão

A integração da resolução de CAPTCHA em agentes AutoGen requer o registro de uma função de resolução via register_function, a conexão com o executor do CapSolver e deixar o agente assistente decidir quando invocá-lo durante conversas. CapSolver fornece a infraestrutura de resolução baseada em IA que limpa desafios de verificação em 3-12 segundos, mantendo suas conversas AutoGen fluindo sem intervenção humana.

Comece com o padrão de dois agentes para tarefas simples, depois expanda para chat em grupo para fluxos de trabalho complexos de agentes múltiplos. O método de registro de função significa que os agentes decidem naturalmente quando resolver com base no contexto da conversa — sem detecção de CAPTCHA codificada.

Perguntas Frequentes

O CapSolver funciona com a execução assíncrona do AutoGen?

Sim. Embora o register_function do AutoGen use assinaturas de função síncronas, você pode envolver o executor assíncrono do CapSolver com asyncio.run() dentro da função registrada. Isso fornece os benefícios da resolução assíncrona (agrupamento de conexões, solicitações concorrentes) dentro da interface de chamada de função síncrona do AutoGen.

Múltiplos agentes AutoGen podem compartilhar o mesmo solucionador de CAPTCHA?

Sim. Registre a mesma função de resolução com múltiplos agentes chamadores em um chat em grupo. Cada agente pode invocar independentemente a resolução de CAPTCHA quando sua tarefa específica a exigir. A API do CapSolver lida com solicitações concorrentes sem conflitos.

Como o AutoGen decide quando chamar a função de resolução de CAPTCHA?

O agente assistente do AutoGen usa a descrição da função e o contexto da conversa para decidir. Quando a tarefa menciona acessar um recurso protegido por CAPTCHA, o assistente reconhece a necessidade e gera uma chamada de função com parâmetros apropriados. Você também pode incluir instruções explícitas na mensagem do sistema.

O que acontece se a resolução de CAPTCHA falhar durante a conversa?

A função retorna uma mensagem de erro ao agente assistente. O assistente pode então tentar novamente com parâmetros diferentes, pedir esclarecimento ou relatar a falha. O loop de conversa do AutoGen continua normalmente — a falha é tratada como parte do diálogo em vez de travar o sistema.

Quanto custa a resolução de CAPTCHA por conversa do AutoGen?

Uma conversa do AutoGen que encontre 1-3 CAPTCHAs custa entre 0,002 e 0,009 em taxas de resolução. O reCAPTCHA v2 custa aproximadamente 2-3 por 1.000 resoluções, e o Cloudflare Turnstile custa 1-2 por 1.000. Para a maioria dos fluxos de trabalho, o custo de resolução de CAPTCHA é insignificante comparado aos custos das APIs de LLM.