Como resolver CAPTCHA nos Agentes LlamaIndex

O LlamaIndex agents orquestram a recuperação de dados, indexação e fluxos de trabalho de consulta em fontes diversas. Quando esses agentes acessam fontes de dados baseadas na web protegidas por desafios CAPTCHA, eles precisam de um mecanismo de resolução para continuar a ingestão de dados. O pacote capsolver-agent do CapSolver fornece esquemas de ferramentas compatíveis com o sistema FunctionTool do LlamaIndex, permitindo que seu agente resolva reCAPTCHA, Cloudflare Turnstile e outros desafios de verificação como parte de sua pipeline de dados.

TL;DR

• Agentes LlamaIndex ficam travados quando fontes de dados web são protegidas por verificação CAPTCHA
• O CapSolver se integra através do wrapper FunctionTool do LlamaIndex com resolução assíncrona
• O executor capsolver-agent lida com a resolução e retorna resultados estruturados para o ciclo de raciocínio do agente
• Suporta reCAPTCHA v2/v3 e Cloudflare Turnstile — os tipos mais comuns de verificação na web
• A integração leva menos de 15 linhas usando create_executor() e FunctionTool.from_defaults()

Por que os Agentes LlamaIndex Precisam de Resolução de CAPTCHA

O LlamaIndex se destaca na criação de agentes que recuperam, indexam e consultam dados de múltiplas fontes. Quando essas fontes incluem páginas da web, APIs ou bancos de dados protegidos por sistemas CAPTCHA, a pipeline de ingestão de dados do agente falha. Um agente RAG que precisa indexar documentação de um site protegido por CAPTCHA, ou um agente de pesquisa que consulta múltiplas fontes da web, não pode prosseguir sem a limpeza da verificação.

O problema é particularmente grave para a ecosistema de conectores de dados do LlamaIndex. Conectores baseados na web que buscam páginas para indexação encontram CAPTCHAs após acesso repetido. Sem uma ferramenta de resolução, o agente ou pula a fonte (dados incompletos) ou falha totalmente (pipeline quebrado).

A integração de ferramentas do CapSolver segue o padrão padrão do LlamaIndex: defina uma função, envolva-a como FunctionTool e adicione-a à lista de ferramentas do agente. O motor de raciocínio do agente decide quando invocar a resolução com base no contexto da tarefa.

O que Você Precisa Antes de Começar

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

# LlamaIndex
pip install llama-index llama-index-llms-openai

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

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

import asyncio
from llama_index.core.tools import FunctionTool
from capsolver_agent.schema import create_executor

executor = create_executor(api_key="SUA_CHAVE_DA_API_DO_CAPSOLVER")

def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """Resolva um desafio CAPTCHA e retorne o token de verificação.
    
    Use quando acessar um recurso web protegido por verificação CAPTCHA.
    
    Args:
        captcha_type: 'reCaptchaV2', 'reCaptchaV3' ou 'cloudflare'
        website_url: URL completa da página protegida por CAPTCHA
        website_key: A chave do site (valor da atributo data-sitekey)
    
    Returns:
        String do token resolvido ou mensagem de erro
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }))
    if result["success"]:
        return f"CAPTCHA resolvido. Token: {result['solution']['token']}"
    return f"Falha: {result['error']}"

# Envolver como FunctionTool do LlamaIndex
captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha,
    name="solve_captcha",
    description="Resolva desafios CAPTCHA (reCAPTCHA v2/v3, Cloudflare Turnstile) em páginas web protegidas"
)

Etapa 2 — Construir um Agente LlamaIndex com Capacidade de CAPTCHA

from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

# Criar LLM
llm = OpenAI(model="gpt-4o", temperature=0)

# Criar agente com ferramenta de resolução de CAPTCHA
agent = ReActAgent.from_tools(
    tools=[captcha_tool],
    llm=llm,
    verbose=True
)

# Executar o agente
response = agent.chat(
    "Preciso acessar https://example.com/data que tem um reCAPTCHA v2. "
    "A chave do site é 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI. "
    "Resolva e me dê o token."
)
print(response)

Etapa 3 — Integrar com Conectores de Dados do LlamaIndex

Para agentes que ingere dados da web, combine resolução de CAPTCHA com carregamento de dados:

from llama_index.core import VectorStoreIndex, Document

def fetch_protected_page(url: str, site_key: str) -> str:
    """Busque uma página protegida por CAPTCHA resolvendo primeiro."""
    # Resolver o CAPTCHA
    token = solve_captcha("reCaptchaV2", url, site_key)
    if "Falha" in token:
        return ""
    
    # Usar token para acessar a página
    import requests
    response = requests.post(url, data={"g-recaptcha-response": token.split("Token: ")[1]})
    return response.text

# Criar uma ferramenta personalizada para ingestão de dados protegidos
protected_fetch_tool = FunctionTool.from_defaults(
    fn=fetch_protected_page,
    name="fetch_protected_page",
    description="Busque conteúdo de uma página web protegida por CAPTCHA resolvendo a verificação primeiro"
)

# Agente com capacidade de resolução e busca
data_agent = ReActAgent.from_tools(
    tools=[captcha_tool, protected_fetch_tool],
    llm=llm,
    verbose=True
)

Etapa 4 — Padrões de Produção

def solve_captcha_with_retry(captcha_type: str, website_url: str, website_key: str, max_retries: int = 3) -> str:
    """Resolução de CAPTCHA com lógica de tentativa de novo, de produção."""
    for attempt in range(max_retries):
        result = asyncio.run(executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        }))
        if result["success"]:
            return f"Resolvido (tentativa {attempt+1}). Token: {result['solution']['token']}"
        if attempt < max_retries - 1:
            import time
            time.sleep(3)
    return f"Falha após {max_retries} tentativas: {result.get('error')}"

# Ferramenta de produção com tentativa de novo
production_captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha_with_retry,
    name="solve_captcha",
    description="Resolva CAPTCHA com tentativa automática em caso de falha"
)

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

A documentação da API do CapSolver cobre parâmetros adicionais. Para identificar tipos de CAPTCHA, use a extensão CapSolver. O guia de raspagem da web do CapSolver cobre padrões de coleta de dados aplicáveis aos conectores de dados do LlamaIndex.

Conclusão

Integrar a resolução de CAPTCHA em agentes LlamaIndex requer envolver o executor do CapSolver em um FunctionTool e adicioná-lo à lista de ferramentas do seu agente ReAct. O ciclo de raciocínio do agente decide quando invocar a resolução com base no contexto da tarefa. CapSolver fornece a infraestrutura de resolução que lida com reCAPTCHA e Cloudflare Turnstile por meio de uma API unificada, mantendo suas pipelines de dados do LlamaIndex em funcionamento sem interrupções.

Perguntas Frequentes

O CapSolver funciona com o agente assíncrono do LlamaIndex?

Sim. O executor capsolver-agent é totalmente assíncrono. Para agentes assíncronos do LlamaIndex, use await executor.execute() diretamente em vez de envolver com asyncio.run().

Posso usar isso com os conectores do leitor da web do LlamaIndex?

Sim. Combine a ferramenta de resolução de CAPTCHA com leitores da web personalizados que lidem com a verificação antes de buscar o conteúdo da página. O agente pode resolver o CAPTCHA primeiro, depois passar o token para o leitor da web para acesso autenticado.

O que acontece se meu agente LlamaIndex encontrar um tipo de CAPTCHA desconhecido?

A ferramenta get_supported_captchas retorna a lista de tipos suportados. Se o agente encontrar um tipo não suportado, ele recebe uma mensagem de erro clara e pode relatar isso ao usuário em vez de falhar silenciosamente.

Como isso se compara ao uso do capsolver-mcp com o LlamaIndex?

capsolver-mcp é para clientes MCP (Claude Desktop, Cursor). Para agentes LlamaIndex em execução em código, use capsolver-agent com FunctionTool — ele fornece controle programático direto dentro do framework LlamaIndex.