Como resolver CAPTCHA com o TinyFish AgentQL – Guia passo a passo usando o CapSolver

Quando sua automação web com inteligência artificial atinge um muro de CAPTCHA, todo o pipeline trava. Páginas não carregam, formulários não podem ser enviados e a extração de dados para em andar — tudo porque um desafio foi criado para bloquear robôs. TinyFish AgentQL é um conjunto poderoso de ferramentas para conectar inteligência artificial à web, com consultas em linguagem natural, integrações com Playwright e extração de dados estruturados em escala empresarial. Mas, como qualquer framework de automação de navegador, ele fica travado em CAPTCHAs.

CapSolver muda isso completamente. Carregando a extensão CapSolver no contexto do navegador do AgentQL baseado em Playwright, os CAPTCHAs são resolvidos automaticamente e invisivelmente no fundo. Nenhuma resolução manual. Nenhuma orquestração complexa de API do seu lado. Seus scripts de automação continuam a funcionar como se o CAPTCHA nunca tivesse existido.

O melhor disso? Suas consultas e scripts do AgentQL não precisam de uma única linha de código relacionado a CAPTCHA. A extensão lida com detecção, resolução e injeção de token por conta própria enquanto seu agente se concentra no que faz melhor — extrair dados e automatizar fluxos de trabalho.

O que é TinyFish AgentQL?

TinyFish AgentQL é um kit de ferramentas de nível empresarial para conectar agentes de inteligência artificial e LLMs a ambientes web em tempo real. Desenvolvido pela TinyFish, ele fornece uma linguagem de consulta com inteligência artificial que permite localizar elementos de página e extrair dados estruturados usando linguagem natural — sem a necessidade de seletores CSS frágeis ou XPaths.

Principais Funcionalidades

• Linguagem de Consulta com Inteligência Artificial: Localize elementos de forma intuitiva com base no conteúdo da página. Consultas se reconstroem conforme as mudanças na interface.
• Integração com Playwright: SDKs Python e JavaScript se integram sem problemas com o Playwright para automação avançada de navegadores.
• Extração de Dados Estruturados: Defina formatos de saída e obtenha dados limpos e estruturados de qualquer página — pública ou privada, estática ou dinâmica.
• API REST: Execute consultas sem SDKs por meio de um ponto de extremidade REST.
• Depurador de Navegador: Uma extensão do Chrome para testar e aprimorar consultas em tempo real.
• Resiliência entre Sites: Funciona entre sites semelhantes sem modificações, adaptando-se dinamicamente às mudanças nas páginas.
• Escala Empresarial: Construído para cargas de trabalho de alto throughput, executando centenas de tarefas em paralelo.

O AgentQL opera em qualquer página — incluindo conteúdo autenticado e páginas geradas dinamicamente — tornando-o ideal para automação web em larga escala, coleta de dados e fluxos de trabalho de agentes de inteligência artificial.

O que é CapSolver?

CapSolver é um serviço líder de resolução de CAPTCHA com inteligência artificial que resolve automaticamente desafios diversos de CAPTCHA. Com tempos de resposta rápidos e ampla compatibilidade, o CapSolver se integra sem problemas em fluxos de trabalho automatizados.

Tipos de CAPTCHA Suportados

• reCAPTCHA v2 (caixa de seleção e invisível)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Mais

Por que essa Integração é Diferente

A maioria das integrações de resolução de CAPTCHA exige que você escreva código repetitivo: criar tarefas, verificar resultados, injetar tokens em campos ocultos. Essa é a abordagem padrão com scripts Playwright ou Puppeteer.

AgentQL + CapSolver adota uma abordagem fundamentalmente diferente:

A principal descoberta: A extensão CapSolver roda dentro do contexto do navegador do Playwright do AgentQL. Quando o AgentQL navega para uma página com CAPTCHA, a extensão detecta-o, o resolve no fundo e injeta o token — tudo antes que seu script interaja com o formulário. Seus scripts de automação permanecem limpos, focados e livres de CAPTCHA.

Pré-Requisitos

Antes de configurar a integração, certifique-se de ter:

• TinyFish AgentQL instalado (SDK Python ou JavaScript)
• Conta CapSolver com chave de API (inscreva-se aqui)
• Node.js 16+ e Python 3.8+ (dependendo da escolha do SDK)
• Playwright instalado com Chromium

Importante: Extensões do Chrome só funcionam com Chromium com um contexto persistente no Playwright. Isso é um requisito do Playwright, não uma limitação do AgentQL.

Configuração Passo a Passo

Passo 1: Instale o AgentQL

SDK Python:

pip install agentql
playwright install chromium

SDK JavaScript:

npm install agentql
npx playwright install chromium

Passo 2: Baixe a Extensão do Chrome do CapSolver

Baixe a extensão do CapSolver do Chrome e extraia-a para um diretório dedicado:

1. Acesse a versão 1.17.0 da extensão do Chrome do CapSolver
2. Baixe CapSolver.Browser.Extension-chrome-v1.17.0.zip
3. Extraia o zip:

mkdir -p ~/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/capsolver-extension/

4. Verifique se a extração funcionou:

ls ~/capsolver-extension/manifest.json

Você deve ver manifest.json — isso confirma que a extensão está no lugar certo.

Passo 3: Configure sua Chave de API do CapSolver

Abra o arquivo de configuração da extensão em ~/capsolver-extension/assets/config.js e substitua o valor apiKey pelo seu:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // ← seu chave aqui
  useCapsolver: true,
  // ... resto da configuração
};

Você pode obter sua chave de API em seu painel do CapSolver.

Passo 4: Inicie o AgentQL com a Extensão do CapSolver

O passo crítico é iniciar o Chromium do Playwright com um contexto persistente que carregue a extensão do CapSolver.

Exemplo em Python:

import agentql
from playwright.sync_api import sync_playwright
import time
import os

# Caminho para a extensão do CapSolver
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")

def main():
    with sync_playwright() as p:
        # Inicie o Chromium com contexto persistente e extensão do CapSolver
        context = p.chromium.launch_persistent_context(
            user_data_dir="./browser-data",
            headless=False,  # Extensões exigem modo não oculto
            args=[
                f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
                f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
            ],
        )

        # Envolver a página com o AgentQL para consultas com inteligência artificial
        page = agentql.wrap(context.pages[0])

        # Navegue para sua página alvo
        page.goto("https://example.com/protected-page")

        # Aguarde o CapSolver detectar e resolver qualquer CAPTCHA
        time.sleep(30)

        # Encontre e clique no botão de envio usando consultas em linguagem natural do AgentQL
        response = page.query_elements("""
        {
            submit_button
        }
        """)

        # Clique no botão de envio — o CAPTCHA já foi resolvido!
        response.submit_button.click()

        # Extraia dados após o envio
        result = page.query_data("""
        {
            confirmation_message
        }
        """)

        print(f"Resultado: {result['confirmation_message']}")

        context.close()

if __name__ == "__main__":
    main()

Exemplo em JavaScript:

const { chromium } = require('playwright');
const agentql = require('agentql');
const path = require('path');
const os = require('os');

const CAPSOLVER_EXTENSION_PATH = path.join(os.homedir(), 'capsolver-extension');

(async () => {
  // Inicie o Chromium com contexto persistente e extensão do CapSolver
  const context = await chromium.launchPersistentContext('./browser-data', {
    headless: false, // Extensões exigem modo não oculto
    args: [
      `--disable-extensions-except=${CAPSOLVER_EXTENSION_PATH}`,
      `--load-extension=${CAPSOLVER_EXTENSION_PATH}`,
    ],
  });

  // Obtenha a primeira página e a envolva com o AgentQL
  const page = agentql.wrap(context.pages()[0]);

  // Navegue para a página alvo
  await page.goto('https://example.com/protected-page');

  // Aguarde o CapSolver lidar com qualquer CAPTCHA
  await page.waitForTimeout(30000);

  // Use consultas do AgentQL para interagir — o CAPTCHA já foi resolvido
  const response = await page.queryElements(`{
    submit_button
  }`);

  await response.submit_button.click();

  // Extraia os dados de resultado
  const result = await page.queryData(`{
    confirmation_message
  }`);

  console.log('Resultado:', result.confirmation_message);

  await context.close();
})();

Passo 5: Verifique se a Extensão foi Carregada

Após iniciar o navegador, você pode verificar se a extensão do CapSolver está ativa navegando até chrome://extensions na janela do navegador. Você deve ver a extensão do CapSolver listada e ativada.

Alternativamente, verifique o console do navegador para mensagens de log do CapSolver indicando que o serviço worker está em execução.

Como Usar

Após a configuração, usar o CapSolver com o AgentQL é simples.

A Regra Dourada

Não escreva código específico para CAPTCHA. Basta adicionar um tempo de espera antes de interagir com formulários protegidos por CAPTCHA e deixe a extensão fazer seu trabalho.

Exemplo 1: Submissão de Formulário com reCAPTCHA

page.goto("https://example.com/contact")

# Preencha o formulário usando consultas do AgentQL
response = page.query_elements("""
{
    contact_form {
        name_field
        email_field
        message_field
        submit_button
    }
}
""")

response.contact_form.name_field.fill("John Doe")
response.contact_form.email_field.fill("john@example.com")
response.contact_form.message_field.fill("Hello, I have a question about your services.")

# Aguarde o CapSolver resolver o CAPTCHA
time.sleep(30)

# Envie — o token do CAPTCHA já foi injetado
response.contact_form.submit_button.click()

Exemplo 2: Página de Login com Cloudflare Turnstile

page.goto("https://example.com/login")

# Aguarde o CapSolver resolver o desafio Turnstile
time.sleep(25)

# Encontre elementos do formulário de login com o AgentQL
response = page.query_elements("""
{
    login_form {
        email_input
        password_input
        login_button
    }
}
""")

# Preencha o formulário — Turnstile já foi tratado
response.login_form.email_input.fill("me@example.com")
response.login_form.password_input.fill("mypassword123")

# Clique em login
response.login_form.login_button.click()

Exemplo 3: Extração de Dados de Páginas Protegidas

page.goto("https://example.com/data")

# Aguarde qualquer desafio de CAPTCHA ser resolvido
time.sleep(30)

# Extraia dados estruturados com o AgentQL
data = page.query_data("""
{
    products[] {
        name
        price
        rating
        availability
    }
}
""")

for product in data['products']:
    print(f"{product['name']}: ${product['price']} ({product['rating']} estrelas)")

Tempos Recomendados de Espera

Dica: Quando em dúvida, use 30 segundos. É melhor esperar um pouco mais do que enviar cedo demais. O tempo extra não afeta o resultado.

Como Funciona por Trás das Cenas

Aqui está o que acontece quando o AgentQL é executado com a extensão CapSolver carregada:

Seu Script do AgentQL
───────────────────────────────────────────────────
page.goto("https://...")       ──► O Chromium carrega a página
                                           │
                                           ▼
                               ┌─────────────────────────────┐
                               │  Página com widget de CAPTCHA     │
                               │                               │
                               │  Extensão CapSolver:         │
                               │  1. Script de conteúdo detecta    │
                               │     CAPTCHA na página         │
                               │  2. Trabalhador de serviço chama   │
                               │     API do CapSolver          │
                               │  3. Token recebido            │
                               │  4. Token injetado em campo oculto │
                               └─────────────────────────────┘
                                           │
                                           ▼
time.sleep(30)                   A extensão resolve o CAPTCHA...
                                           │
                                           ▼
page.query_elements(...)         O AgentQL encontra elementos do formulário
submit_button.click()            O formulário é enviado COM token válido
                                           │
                                           ▼
                               "Verificação bem-sucedida!"

Como a Extensão é Carregada

Quando o Playwright inicia o Chromium com a flag --load-extension:

1. O Chromium inicia com a extensão CapSolver carregada
2. A extensão é ativada — seu trabalhador de serviço começa e scripts de conteúdo são injetados em cada página
3. Em páginas com CAPTCHAs — o script de conteúdo detecta o widget, chama a API do CapSolver e injeta o token de solução na página
4. O AgentQL opera normalmente — consultas, cliques e extração de dados funcionam como de costume, com CAPTCHAs já resolvidos

Referência de Configuração Completa

Aqui está uma configuração Python completa com todas as opções de configuração para a integração AgentQL + CapSolver:

import agentql
from playwright.sync_api import sync_playwright
import os

# Configuração
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")
USER_DATA_DIR = "./browser-data"

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        user_data_dir=USER_DATA_DIR,
        headless=False,
        args=[
            f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
            f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
        ],
    )
    page = agentql.wrap(context.pages[0])
    # ... seu código de automação aqui
    context.close()

Opções de Configuração

A chave da API do CapSolver é configurada diretamente no arquivo assets/config.js da extensão (veja a Etapa 3 acima).

Solução de Problemas

Extensão Não Carregando

Sintoma: CAPTCHAs não são resolvidos automaticamente.

Causa: Você pode estar usando um contexto de navegador regular em vez de um contexto persistente, ou executando no modo headless.

Solução: Extensões no Playwright requerem um contexto persistente e modo normal:

# ✅ Correto — contexto persistente, modo normal
context = p.chromium.launch_persistent_context(
    user_data_dir="./browser-data",
    headless=False,
    args=[...argumentos da extensão...]
)

# ❌ Errado — contexto regular (as extensões não carregarão)
browser = p.chromium.launch()
context = browser.new_context()

CAPTCHA Não Resolvido (Formulário Falha)

Possíveis causas:

• Tempo de espera insuficiente — Aumente para 60 segundos
• Chave da API inválida — Verifique seu painel do CapSolver
• Saldo insuficiente — Recarregue sua conta do CapSolver
• Extensão não carregada — Veja "Extensão Não Carregando" acima

Modo Headless Não Suportado

Sintoma: O script roda, mas a extensão não aparece.

Causa: Extensões do Chrome não funcionam no modo headless.

Solução: Use o modo normal com uma tela virtual em servidores:

# Instale o Xvfb
sudo apt-get install xvfb

# Inicie uma tela virtual
Xvfb :99 -screen 0 1280x720x24 &

# Defina o DISPLAY
export DISPLAY=:99

Compatibilidade com o Google Chrome 137+

Sintoma: A bandeira da extensão é ignorada silenciosamente.

Causa: O Google Chrome 137+ removeu o suporte para --load-extension em builds oficiais.

Solução: Use o Chromium do Playwright (recomendado) ou o Chrome for Testing:

# Instale o Chromium do Playwright (recomendado)
npx playwright install chromium

# Ou baixe o Chrome for Testing
# Visite: https://googlechromelabs.github.io/chrome-for-testing/

Boas Práticas

1. Sempre use tempos de espera generosos. Mais tempo de espera é sempre mais seguro. O CAPTCHA geralmente é resolvido em 5-20 segundos, mas a latência da rede, desafios complexos ou tentativas podem aumentar o tempo. 30-60 segundos é o ponto ideal.

2. Mantenha seus scripts de automação limpos. Não adicione lógica específica para CAPTCHA nas consultas do AgentQL. A extensão cuida de tudo — seu código deve focar apenas na extração de dados e interação.

3. Monitore seu saldo do CapSolver. Cada resolução de CAPTCHA custa créditos. Verifique seu saldo em capsolver.com/dashboard regularmente para evitar interrupções.

4. Use consistentemente o contexto persistente. Sempre inicie com launch_persistent_context() quando precisar de extensões. Isso também preserva cookies e dados de sessão entre as execuções, reduzindo a frequência de CAPTCHA.

5. Use o Xvfb em servidores headless. Extensões do Chrome requerem um contexto de tela. Configure o Xvfb em ambientes de servidor onde não haja tela física disponível.

Conclusão

A integração do TinyFish AgentQL + CapSolver traz a resolução de CAPTCHA invisível a uma das ferramentas de automação web mais poderosas disponíveis. Em vez de escrever código complexo para lidar com CAPTCHA, você simplesmente:

1. Baixe a extensão CapSolver e configure sua chave da API
2. Inicie o navegador do AgentQL com o Playwright carregando a extensão via contexto persistente
3. Escreva seus scripts de automação como de costume — adicione um tempo de espera antes de enviar formulários

A extensão CapSolver cuida do restante — detectando CAPTCHAs, resolvendo-os via API do CapSolver e injetando tokens na página. Seus scripts do AgentQL nunca precisam saber sobre CAPTCHAs de forma alguma.

Essa é a aparência da resolução de CAPTCHA quando você combina automação web com inteligência artificial com resolução de CAPTCHA com inteligência artificial: invisível, automática e sem código.

Pronto para começar? Registre-se no CapSolver e use o código de bônus AGENTQL para obter 6% a mais em seu primeiro recarregamento!

Perguntas Frequentes

Eu preciso escrever código específico para CAPTCHA nos meus scripts do AgentQL?

Não. A extensão CapSolver funciona totalmente no fundo dentro do contexto do navegador do Playwright. Basta adicionar um time.sleep() ou waitForTimeout() antes de enviar formulários, e a extensão cuida da detecção, resolução e injeção de tokens automaticamente.

Por que eu preciso de um contexto persistente?

O Playwright só suporta extensões do Chrome quando usando launch_persistent_context(). Isso é um requisito da arquitetura do Playwright. Contextos de navegador regulares criados via browser.new_context() não podem carregar extensões.

Posso executar isso no modo headless?

Não. Extensões do Chrome requerem um navegador com interface gráfica. Para ambientes de servidor sem tela, use o Xvfb (X Virtual Framebuffer) para criar uma tela virtual.

Quais tipos de CAPTCHA o CapSolver suporta?

O CapSolver suporta reCAPTCHA v2 (checkbox e invisível), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA e mais. A extensão detecta automaticamente o tipo de CAPTCHA e o resolve conforme necessário.

Quanto custa o CapSolver?

O CapSolver oferece preços competitivos com base no tipo de CAPTCHA e volume. Visite capsolver.com para ver os preços atuais.

O TinyFish AgentQL é gratuito?

O AgentQL oferece planos gratuitos e pagos. O SDK e a linguagem de consulta estão disponíveis para desenvolvimento e testes. Visite tinyfish.ai para detalhes de preços.

Quanto tempo devo esperar para o CAPTCHA ser resolvido?

Para a maioria dos CAPTCHAs, 30-60 segundos é suficiente. O tempo real de resolução geralmente é de 5-20 segundos, mas adicionar um buffer extra garante confiabilidade. Quando em dúvida, use 30 segundos.