Como adicionar ferramentas de detecção de CAPTCHA aos agentes Haystack

Resumo

• Uma ferramenta Haystack pode chamar o SDK oficial CapSolver Core para inspecionar parâmetros de CAPTCHA em uma página de navegador existente.
• Vincule a ferramenta à página que sua aplicação já controla, em vez de deixar um agente navegar para URLs arbitrárias por meio da ferramenta de inspeção.
• O exemplo executável retorna o tipo de CAPTCHA, a URL da página e a chave pública do site a partir de uma página local usando o widget de teste do reCAPTCHA v2 do Google.
• Esta é uma integração nativa em Python: não é necessário servidor nem transporte MCP.
• A detecção não cria uma tarefa de solução, não retorna um token e não prova que a aplicação aceitou a verificação.

Um agente baseado em navegador precisa de informações úteis quando um CAPTCHA interrompe seu trabalho. Apenas o título da página ou uma captura de tela pode não informar ao agente qual família de CAPTCHA está presente ou quais parâmetros o próximo passo precisa. Retornar um pequeno resultado estruturado dá à aplicação um ponto de decisão claro antes de solicitar uma solução.

O Haystack é um framework Python para construir aplicações de IA, pipelines de recuperação e agentes. Suas ferramentas nativas podem encapsular funções usadas por essas aplicações. Este guia conecta uma ferramenta Haystack ao CapSolver para uma tarefa específica: inspecionar a página atual do navegador e retornar parâmetros de CAPTCHA. O exemplo usa uma página de desenvolvimento e não faz nenhuma requisição paga de solução. Ele fornece um componente de inspeção funcional para colocar antes de uma etapa de solução, autorizada separadamente.

Onde a ferramenta de CAPTCHA se encaixa em um fluxo de trabalho Haystack

A ferramenta de inspeção de CAPTCHA pertence ao intervalo entre a ação do navegador que atinge um ponto de verificação e o código que decide como lidar com esse ponto de verificação. O navegador ainda controla a navegação e a página atual. O Haystack fornece a interface da ferramenta; o Core SDK lê as informações dos CAPTCHAs suportados.

Por exemplo, uma equipe que testa seu próprio formulário pode deixar o navegador chegar ao formulário, invocar a ferramenta de inspeção e examinar o tipo e a chave do site retornados. O ambiente de teste pode então escolher seu caminho aprovado de chave de teste ou uma verificação de solução configurada separadamente. Ele não deve tratar o próprio widget de CAPTCHA como o conteúdo de negócio do formulário.

Esta é uma integração para desenvolvedores usando a abstração de Tool documentada do Haystack, e não uma alegação de um plugin dedicado do Haystack. A ferramenta tem um propósito estreito e não precisa de um LLM para ser executada. Chamá-la diretamente é útil antes de adicionar seleção de ferramentas dirigida por modelo.

O que você precisa antes de executar o exemplo

Você precisa de Python, do pacote Haystack, do CapSolver Core SDK com sua dependência Playwright, e do Chromium instalado para o Playwright. O exemplo abaixo foi executado com Python 3.12, haystack-ai 3.4.0, capsolver-core 0.1.1 e Playwright 1.64.0. Essas são versões testadas, não uma afirmação de que são os lançamentos mais recentes disponíveis.

O navegador deve conseguir carregar o script público reCAPTCHA do Google. A página local usa a chave de site de desenvolvimento documentada pelo Google; não é uma chave de produção e não deve ser implantada como tal. A orientação de teste do reCAPTCHA do Google explica a distinção entre chaves de teste e verificação de produção.

Nenhuma chave de API do CapSolver ou chave de provedor de modelo é necessária para este exemplo apenas de inspeção. Uma operação de solução posterior exige uma chave de conta CapSolver válida. Um Agent Haystack dirigido por LLM posteriormente exige seu próprio provedor de modelo configurado. Esses são pré‑requisitos separados, portanto não tente solucionar problemas de credenciais de modelo ausentes alterando os parâmetros do CAPTCHA.

Instale os pacotes testados

Crie um ambiente virtual e instale os pacotes nesse ambiente. Execute a instalação do Chromium através do mesmo interpretador Python para manter a dependência do navegador alinhada com o Playwright.

python3 -m venv .venv
.venv/bin/python -m pip install "haystack-ai==3.4.0" "capsolver-core[playwright]==0.1.1" "playwright==1.64.0"
.venv/bin/python -m playwright install chromium

Os comandos acima usam um caminho de ambiente em estilo POSIX. Se o seu sistema operacional usa um layout diferente de ambiente virtual, use o executável Python desse ambiente. O guia de instalação do Playwright para Python cobre os requisitos de instalação do navegador.

Crie uma ferramenta que inspeciona a página atual

A ferramenta encapsula get_captcha_info(page) do Core SDK oficial. A página é capturada pela função, portanto a ferramenta não tem argumento de navegação. Seu esquema de parâmetros em JSON não aceita campos de entrada.

Salve o seguinte como haystack_captcha_inspection.py. A resposta HTML local é fornecida pelo roteamento do Playwright; é um fixture de desenvolvimento, não uma aplicação hospedada remotamente. O script do reCAPTCHA em si é carregado do Google. O programa lê parâmetros sem clicar no widget ou enviar um formulário.

import asyncio
import json

from capsolver_core import create_capsolver
from haystack.tools import Tool
from playwright.async_api import async_playwright

TEST_PAGE = """<!doctype html><html><body>
<div id="captcha" class="g-recaptcha"
     data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


async def main():
    async with async_playwright() as pw:
        browser = await pw.chromium.launch()
        try:
            page = await browser.new_page()
            await page.route("http://127.0.0.1:8765/", lambda route: route.fulfill(
                status=200, content_type="text/html", body=TEST_PAGE))
            await page.goto("http://127.0.0.1:8765/")
            await page.wait_for_function(
                "() => window.___grecaptcha_cfg && "
                "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0")
            async with create_capsolver() as cap:
                async def inspect_captcha():
                    infos = await cap.get_captcha_info(page)
                    return {"captchas": [
                        {"type": info.type.value,
                         "website_url": info.website_url,
                         "website_key": info.website_key}
                        for info in infos
                    ]}

                captcha_tool = Tool(
                    name="inspect_current_page_captcha",
                    description="Read CAPTCHA types and public parameters from the current approved page; does not solve or submit.",
                    parameters={"type": "object", "properties": {},
                                "additionalProperties": False},
                    async_function=inspect_captcha,
                )
                result = await captcha_tool.invoke_async()
                print(json.dumps(result, indent=2))
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

O argumento async_function é importante porque as operações do SDK e do Playwright são assíncronas. A referência da API de Tools do Haystack documenta invoke_async() para esse caminho. Colocar uma coroutine em um caminho de chamada somente síncrono pode falhar antes que qualquer inspeção de CAPTCHA ocorra.

Os gerenciadores de contexto e o bloco finally fecham os recursos do SDK e do navegador. Mantenha essa limpeza ao adaptar o exemplo para uma aplicação de execução mais longa; caso contrário, uma falha no carregamento da página pode deixar processos de navegador em aberto.

Resgate Seu Código de Bônus do CapSolver

Aumente instantaneamente o orçamento da sua automação!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para ganhar 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Dashboard CapSolver

Execute a inspeção e entenda o resultado

Executar o script invoca a ferramenta Haystack diretamente e imprime o dicionário retornado. No exemplo, esse dicionário contém uma lista captchas com uma entrada reCAPTCHA v2.

.venv/bin/python haystack_captcha_inspection.py

A execução local retornou type igual a reCaptchaV2, website_url igual a http://127.0.0.1:8765/ e a chave pública de site de teste configurada no HTML. Esses campos foram lidos através do SDK e do navegador reais, não preenchidos em uma resposta de ferramenta simulada.

O resultado é deliberadamente pequeno. O descritor completo do SDK pode incluir campos adicionais, mas um agente deve receber apenas o que precisa para sua próxima decisão. Uma chave de site é um identificador público do widget; não é a chave de conta CapSolver nem o segredo privado de verificação do site.

Esta execução estabelece que o Haystack pode invocar a função assíncrona, que o navegador pode carregar o widget de desenvolvimento e que o Core SDK pode ler seus parâmetros. Ela não estabelece seleção de ferramenta por modelo, detecção de CAPTCHA em produção em todo site, geração bem‑sucedida de token ou aceitação pelo backend de um website. Isso exige suas próprias verificações com a aplicação real.

Anexe a página inspecionada ao seu agente existente

Mantenha o mesmo objeto Tool e o mesmo vínculo com a página ao adicionar essa capacidade ao seu Agent Haystack. O Agent do Haystack aceita ferramentas por meio de sua configuração tools documentada. Registre esse objeto junto com as ferramentas que sua aplicação já usa, mantendo a página do navegador ativa durante a chamada.

Em um fluxo de trabalho de navegador existente, substitua a configuração do fixture local pela página que sua aplicação já abriu e está autorizada a inspecionar. Mantenha a navegação do navegador fora dessa ferramenta. Isso torna a seleção da página explícita e impede que uma URL gerada por modelo altere silenciosamente o alvo da inspeção.

Dê um nome e uma descrição precisos à ferramenta. A descrição no exemplo diz que ela lê informações de CAPTCHA e não resolve nem envia. Uma descrição como “concluir verificação” prometeria mais do que a função executa e poderia incentivar o agente a relatar sucesso cedo demais.

Uma decisão útil da aplicação é: se o resultado contiver um widget reconhecido com os parâmetros necessários, ofereça o próximo passo apropriado; se estiver vazio ou incompleto, colete mais evidências ou solicite revisão humana. Não adicione um loop incondicional que continue inspecionando a mesma página incompleta.

Mantenha detecção e solução como etapas separadas

O resultado da inspeção é uma entrada para a decisão de solução, não uma solução de CAPTCHA. O Core SDK documenta solve(info) para resolver tokens e solve_on_page(page) para o fluxo de trabalho mais amplo do navegador. Eles têm efeitos diferentes de get_captcha_info(page) e exigem configuração e autorização separadas.

Para este guia, mantenha a ferramenta de inspeção com propósito somente de leitura. Se você mais tarde adicionar uma ferramenta de solução, deixe sua aplicação validar o tipo detectado e a página atual, fornecer a credencial da conta fora dos argumentos visíveis ao modelo e aplicar as regras de orçamento e aprovação apropriadas a esse fluxo de trabalho. Retorne um resultado claro que distinga um token de uma ação concluída da aplicação.

Um token retornado ainda precisa do tratamento relevante pela aplicação. A própria verificação do site e o resultado do formulário determinam se a operação pretendida teve sucesso. Nem uma lista captchas não vazia nem uma invocação bem‑sucedida de ferramenta Haystack são evidência de que a aplicação aceitou uma resposta de CAPTCHA.

Solucione a conexão sem adivinhar

A solução de problemas deve identificar qual camada falhou: instalação de pacotes, inicialização do navegador, carregamento do widget, inspeção pelo SDK ou invocação da ferramenta. Altere a camada indicada pelo erro em vez de substituir vários componentes de uma vez.

O executável do navegador está ausente

Instale o Chromium com o comando do Playwright a partir do ambiente virtual ativo. Um pip install bem‑sucedido instala o pacote Python, mas por si só não prova que o binário de navegador correspondente está disponível.

A espera pelo widget atinge o tempo limite

Verifique se o navegador carregou o script do Google e se a página de teste criou o widget. A espera neste exemplo procura por clientes do widget inicializados. Uma falha de rede pode ocorrer antes de o SDK ter algo a inspecionar; repetir a solução não resolveria essa falha.

A ferramenta retorna uma lista vazia

Um resultado vazio significa que esta inspeção não encontrou descritores suportados nessa página naquele momento. Não prova que a página não tem mecanismo de verificação. Verifique o timing da página, o objeto de página que você passou e o widget real. O guia de inspeção de parâmetros de CAPTCHA fornece uma forma complementar de inspecionar o estado do navegador.

A ferramenta funciona diretamente, mas não no agente

Verifique se o mesmo objeto Tool está registrado, se o modelo do agente suporta o fluxo de trabalho de ferramenta pretendido e se a sessão do navegador ainda está aberta. Mantenha a invocação direta bem‑sucedida como um checkpoint separado para que um problema de configuração de modelo não seja relatado erroneamente como falha na API de CAPTCHA.

Torne o resultado da inspeção útil

Uma pequena ferramenta de inspeção de CAPTCHA dá a uma aplicação Haystack um ponto de verificação concreto antes da solução. Comece com a página de desenvolvimento testada, preserve a chamada assíncrona e a limpeza e depois anexe a ferramenta à página que seu fluxo de trabalho existente controla. Expanda suas responsabilidades apenas quando cada operação adicional tiver uma entrada clara, comportamento verificado e resultado observável.

Construa Fluxos de Automação Confiáveis com o CapSolver

Use o CapSolver para a etapa de CAPTCHA suportada em um fluxo de trabalho que você está autorizado a executar. Mantenha navegador, resultado do solucionador e resultado da aplicação como verificações separadas para que uma chamada de ferramenta bem‑sucedida não oculte uma tarefa com falha.

FAQ

P: Esta integração requer MCP?

Não. O exemplo usa uma Tool nativa do Haystack e o Core SDK em Python na mesma aplicação. Ele não inicia um servidor MCP.

P: Preciso de uma chave de API de LLM para executar o script?

Não. O script invoca a Tool diretamente. Uma credencial de provedor de modelo passa a ser relevante quando você adiciona um agente dirigido por LLM em torno dessa ferramenta.

P: O exemplo resolve o CAPTCHA de teste?

Não. Ele carrega o widget e lê parâmetros públicos. Não solicita um token de solução nem envia o formulário.

P: A mesma abordagem pode inspecionar uma página Playwright existente?

Sim. Vincule a ferramenta à página autorizada existente e mantenha essa página ativa durante a invocação. Os campos de descritor suportados dependem do que o SDK consegue detectar nessa página.
P: Por que usar uma ferramenta sem argumentos?

A função já conhece a página aprovada atual. Um esquema de entrada vazio mantém a navegação e a seleção de página sob o controle da aplicação.

P: Um resultado vazio significa que a página é segura para processar como conteúdo normal?

Não. Inspecione o estado da página antes de continuar. Um resultado de detecção vazio também pode refletir questões de tempo, um mecanismo não suportado ou a inicialização incompleta de um widget.