Cómo resolver CAPTCHA con TinyFish AgentQL – Guía paso a paso usando CapSolver

Cuando tu automatización web impulsada por IA choca con un muro de CAPTCHA, toda la cadena se detiene. Las páginas no se cargan, los formularios no se pueden enviar y la extracción de datos se detiene por completo, todo porque un desafío diseñado para bloquear bots. TinyFish AgentQL es un conjunto de herramientas poderosas para conectar la IA con la web, con consultas de lenguaje natural, integraciones con Playwright y extracción de datos estructurados a escala empresarial. Pero como cualquier marco de automatización de navegador, se queda atascado con los CAPTCHAS.

CapSolver lo cambia por completo. Al cargar la extensión CapSolver en el contexto del navegador de AgentQL basado en Playwright, los CAPTCHAS se resuelven automáticamente y de forma invisible en segundo plano. Sin resolver manualmente. Sin orquestación compleja de API por tu parte. Tus scripts de automatización continúan funcionando como si el CAPTCHA nunca hubiera existido.

Lo mejor de todo es que tus consultas y scripts de AgentQL no necesitan ni una línea de código relacionado con CAPTCHA. La extensión se encarga por completo de la detección, resolución e inyección de tokens mientras tu agente se enfoca en lo que hace mejor: extraer datos y automatizar flujos de trabajo.

¿Qué es TinyFish AgentQL?

TinyFish AgentQL es un kit de herramientas de nivel empresarial para conectar agentes de IA y LLMs con entornos web en vivo. Desarrollado por TinyFish, proporciona un lenguaje de consulta impulsado por IA que te permite localizar elementos de página y extraer datos estructurados usando lenguaje natural: sin selectores CSS frágiles o XPaths requeridos.

Características clave

• Lenguaje de consulta impulsado por IA: Encuentra elementos de forma intuitiva basada en el contenido de la página. Las consultas se autocuraran a medida que los cambios de la interfaz de usuario ocurren con el tiempo.
• Integración con Playwright: Los SDKs de Python y JavaScript se integran sin problemas con Playwright para automatización avanzada del navegador.
• Extracción de datos estructurados: Define formas de salida y obtén datos limpios y estructurados de cualquier página: pública o privada, estática o dinámica.
• API REST: Ejecuta consultas sin SDKs a través de un punto final de API.
• Depurador de navegador: Una extensión de Chrome para probar y perfeccionar consultas en tiempo real.
• Resiliencia cruzada de sitios: Funciona en sitios web similares sin modificación, adaptándose dinámicamente a los cambios en la página.
• Escala empresarial: Diseñado para cargas de trabajo de alto rendimiento, ejecutando cientos de tareas en paralelo.

AgentQL opera en cualquier página, incluido contenido autenticado y páginas generadas dinámicamente, lo que lo hace ideal para automatización a gran escala, recolección de datos y flujos de trabajo de agentes de IA.

¿Qué es CapSolver?

CapSolver es un servicio líder de resolución de CAPTCHA impulsado por IA que resuelve automáticamente diversos desafíos de CAPTCHA. Con tiempos de respuesta rápidos y amplia compatibilidad, CapSolver se integra sin problemas en flujos de trabajo automatizados.

Tipos de CAPTCHA compatibles

• reCAPTCHA v2 (casilla y invisible)
• reCAPTCHA v3 y v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Más

¿Por qué esta integración es diferente?

La mayoría de las integraciones de resolución de CAPTCHA requieren que escribas código de plantilla: crear tareas, consultar resultados, inyectar tokens en campos ocultos. Esa es el enfoque estándar con scripts de Playwright o Puppeteer.

AgentQL + CapSolver toma un enfoque fundamentalmente diferente:

La clave del insight: La extensión de CapSolver funciona dentro del contexto del navegador de Playwright de AgentQL. Cuando AgentQL navega a una página con un CAPTCHA, la extensión lo detecta, lo resuelve en segundo plano y inyecta el token — todo antes de que tu script interactúe con el formulario. Tu código de automatización permanece limpio, enfocado y libre de CAPTCHAS.

Requisitos previos

Antes de configurar la integración, asegúrate de tener:

• TinyFish AgentQL instalado (SDK de Python o JavaScript)
• Una cuenta de CapSolver con clave de API (regístrate aquí)
• Node.js 16+ y Python 3.8+ (dependiendo de tu elección de SDK)
• Playwright instalado con Chromium

Importante: Las extensiones de Chrome solo funcionan con Chromium con un contexto persistente en Playwright. Esto es un requisito de Playwright, no una limitación de AgentQL.

Configuración paso a paso

Paso 1: Instalar AgentQL

SDK de Python:

pip install agentql
playwright install chromium

SDK de JavaScript:

npm install agentql
npx playwright install chromium

Paso 2: Descargar la extensión de Chrome de CapSolver

Descarga la extensión de Chrome de CapSolver y cópiala a un directorio dedicado:

1. Ve a la versión 1.17.0 de la extensión de Chrome de CapSolver
2. Descarga CapSolver.Browser.Extension-chrome-v1.17.0.zip
3. Extrae el zip:

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

4. Verifica que la extracción haya funcionado:

ls ~/capsolver-extension/manifest.json

Deberías ver manifest.json — esto confirma que la extensión está en el lugar correcto.

Paso 3: Configurar tu clave de API de CapSolver

Abre el archivo de configuración de la extensión en ~/capsolver-extension/assets/config.js y reemplaza el valor de apiKey con el tuyo:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // ← tu clave aquí
  useCapsolver: true,
  // ... resto de la configuración
};

Puedes obtener tu clave de API desde tu dashboard de CapSolver.

Paso 4: Iniciar AgentQL con la extensión de CapSolver

El paso crítico es iniciar Chromium de Playwright con un contexto persistente que cargue la extensión de CapSolver.

Ejemplo en Python:

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

# Ruta de la extensión de CapSolver
CAPSOLVER_EXTENSION_PATH = os.path.expanduser("~/capsolver-extension")

def main():
    with sync_playwright() as p:
        # Iniciar Chromium con contexto persistente y extensión de CapSolver
        context = p.chromium.launch_persistent_context(
            user_data_dir="./browser-data",
            headless=False,  # Las extensiones requieren modo no oculto
            args=[
                f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}",
                f"--load-extension={CAPSOLVER_EXTENSION_PATH}",
            ],
        )

        # Envolver la página con AgentQL para consultas impulsadas por IA
        page = agentql.wrap(context.pages[0])

        # Navegar a tu página objetivo
        page.goto("https://example.com/protected-page")

        # Esperar a que CapSolver detecte y resuelva cualquier CAPTCHA
        time.sleep(30)

        # Encontrar y hacer clic en el botón de envío usando consultas de lenguaje natural de AgentQL
        response = page.query_elements("""
        {
            submit_button
        }
        """)

        # Hacer clic en el botón de envío — ¡el CAPTCHA ya está resuelto!
        response.submit_button.click()

        # Extraer datos después del envío
        result = page.query_data("""
        {
            confirmation_message
        }
        """)

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

        context.close()

if __name__ == "__main__":
    main()

Ejemplo en 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 () => {
  // Iniciar Chromium con contexto persistente y extensión de CapSolver
  const context = await chromium.launchPersistentContext('./browser-data', {
    headless: false, // Las extensiones requieren modo no oculto
    args: [
      `--disable-extensions-except=${CAPSOLVER_EXTENSION_PATH}`,
      `--load-extension=${CAPSOLVER_EXTENSION_PATH}`,
    ],
  });

  // Obtener la primera página y envolverla con AgentQL
  const page = agentql.wrap(context.pages()[0]);

  // Navegar a la página objetivo
  await page.goto('https://example.com/protected-page');

  // Esperar a que CapSolver maneje cualquier CAPTCHA
  await page.waitForTimeout(30000);

  // Usar consultas de AgentQL para interactuar — ¡el CAPTCHA ya está resuelto!
  const response = await page.queryElements(`{
    submit_button
  }`);

  await response.submit_button.click();

  // Extraer datos de resultado
  const result = await page.queryData(`{
    confirmation_message
  }`);

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

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

Paso 5: Verificar que la extensión esté cargada

Después de iniciar el navegador, puedes verificar que la extensión de CapSolver esté activa navegando a chrome://extensions en la ventana del navegador. Deberías ver la extensión de CapSolver listada y activada.

Alternativamente, revisa la consola del navegador en busca de mensajes de registro de CapSolver indicando que el servicio de trabajo está en ejecución.

Cómo usarlo

Una vez que la configuración esté completa, usar CapSolver con AgentQL es sencillo.

La regla dorada

No escribas código específico de CAPTCHA. Solo agrega un tiempo de espera antes de interactuar con formularios protegidos por CAPTCHA y deja que la extensión haga su trabajo.

Ejemplo 1: Envío de formulario detrás de reCAPTCHA

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

# Rellenar el formulario usando consultas de 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("¡Hola, tengo una pregunta sobre sus servicios.")

# Esperar a que CapSolver resuelva el CAPTCHA
time.sleep(30)

# Enviar — ¡el token del CAPTCHA ya está inyectado!
response.contact_form.submit_button.click()

Ejemplo 2: Página de inicio de sesión con Cloudflare Turnstile

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

# Esperar a que CapSolver resuelva el desafío de Turnstile
time.sleep(25)

# Encontrar elementos del formulario de inicio de sesión con AgentQL
response = page.query_elements("""
{
    login_form {
        email_input
        password_input
        login_button
    }
}
""")

# Rellenar el formulario — ¡el Turnstile ya está manejado!
response.login_form.email_input.fill("me@example.com")
response.login_form.password_input.fill("mypassword123")

# Hacer clic en iniciar sesión
response.login_form.login_button.click()

Ejemplo 3: Extracción de datos de páginas protegidas

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

# Esperar a que cualquier desafío de CAPTCHA se resuelva
time.sleep(30)

# Extraer datos estructurados con AgentQL
data = page.query_data("""
{
    products[] {
        name
        price
        rating
        availability
    }
}
""")

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

Tiempos de espera recomendados

Consejo: Cuando estés en duda, usa 30 segundos. Es mejor esperar un poco más que enviar demasiado pronto. El tiempo adicional no afecta el resultado.

Cómo funciona en segundo plano

Esto es lo que ocurre cuando AgentQL se ejecuta con la extensión de CapSolver cargada:

Tu script de AgentQL
───────────────────────────────────────────────────
page.goto("https://...")       ──► Chromium carga la página
                                           │
                                           ▼
                               ┌─────────────────────────────┐
                               │  Página con widget de CAPTCHA     │
                               │                               │
                               │  Extensión de CapSolver:         │
                               │  1. El script de contenido detecta │
                               │     CAPTCHA en la página        │
                               │  2. El servicio de trabajo llama  │
                               │     a la API de CapSolver       │
                               │  3. Token recibido             │
                               │  4. Token inyectado en campo    │
                               │     oculto de formulario        │
                               └─────────────────────────────┘
                                           │
                                           ▼
time.sleep(30)                   La extensión resuelve el CAPTCHA...
                                           │
                                           ▼
page.query_elements(...)         AgentQL encuentra elementos del formulario
submit_button.click()            Formulario envía con token válido
                                           │
                                           ▼
                               "Verificación exitosa!"

Cómo carga la extensión

Cuando Playwright inicia Chromium con la bandera --load-extension:

1. Chromium inicia con la extensión de CapSolver cargada
2. La extensión se activa — su servicio de trabajo comienza y los scripts de contenido se inyectan en cada página
3. En páginas con CAPTCHAS — el script de contenido detecta el widget, llama a la API de CapSolver y inyecta el token de solución en la página
4. AgentQL opera normalmente — consultas, clics y extracción de datos funcionan como de costumbre, con los CAPTCHAS ya resueltos

Referencia de configuración completa

Aquí tienes una configuración completa en Python con todas las opciones de configuración para la integración de AgentQL + CapSolver:

import agentql
from playwright.sync_api import sync_playwright
import os

# Configuración
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])
    # ... tu código de automatización aquí
    context.close()

Opciones de configuración

La clave de la API de CapSolver se configura directamente en el archivo assets/config.js de la extensión (consulte el paso 3 anterior).

Solución de problemas

La extensión no se carga

Síntoma: Los CAPTCHAs no se resuelven automáticamente.

Causa: Es posible que esté usando un contexto de navegador regular en lugar de un contexto persistente, o esté ejecutándose en modo headless.

Solución: Las extensiones en Playwright requieren un contexto persistente y modo con interfaz gráfica:

# ✅ Correcto — contexto persistente, con interfaz gráfica
context = p.chromium.launch_persistent_context(
    user_data_dir="./browser-data",
    headless=False,
    args=[...argumentos de extensión...]
)

# ❌ Incorrecto — contexto regular (las extensiones no se cargarán)
browser = p.chromium.launch()
context = browser.new_context()

CAPTCHA no resuelto (formulario falla)

Posibles causas:

• Tiempo de espera insuficiente — Aumente a 60 segundos
• Clave de API inválida — Verifique su panel de CapSolver
• Saldo insuficiente — Recargue su cuenta de CapSolver
• Extensión no cargada — Consulte "La extensión no se carga" anteriormente

Modo headless no compatible

Síntoma: El script se ejecuta pero no aparece la extensión.

Causa: Las extensiones de Chrome no funcionan en modo headless.

Solución: Use modo con interfaz gráfica con una pantalla virtual en servidores:

# Instalar Xvfb
sudo apt-get install xvfb

# Iniciar una pantalla virtual
Xvfb :99 -screen 0 1280x720x24 &

# Establecer DISPLAY
export DISPLAY=:99

Compatibilidad con Google Chrome 137+

Síntoma: La bandera de la extensión se ignora silenciosamente.

Causa: Google Chrome 137+ eliminó el soporte para --load-extension en builds oficiales.

Solución: Use el Chromium de Playwright (recomendado) o Chrome for Testing:

# Instalar Chromium de Playwright (recomendado)
npx playwright install chromium

# O descargar Chrome for Testing
# Visite: https://googlechromelabs.github.io/chrome-for-testing/

Buenas prácticas

1. Siempre use tiempos de espera generosos. Más tiempo de espera siempre es más seguro. El CAPTCHA generalmente se resuelve en 5-20 segundos, pero la latencia de red, desafíos complejos o reintentos pueden agregar tiempo. 30-60 segundos es el punto óptimo.

2. Mantenga sus scripts de automatización limpios. No agregue lógica específica para CAPTCHA en sus consultas de AgentQL. La extensión maneja todo — su código debe enfocarse únicamente en la extracción y la interacción de datos.

3. Monitoree su saldo de CapSolver. Cada resolución de CAPTCHA cuesta créditos. Consulte su saldo en capsolver.com/dashboard regularmente para evitar interrupciones.

4. Use consistentemente el contexto persistente. Siempre inicie con launch_persistent_context() cuando necesite extensiones. Esto también preserva las cookies y los datos de sesión entre ejecuciones, lo que puede reducir la frecuencia de CAPTCHA.

5. Use Xvfb en servidores headless. Las extensiones de Chrome requieren un contexto de pantalla. Configure Xvfb para entornos de servidor donde no haya una pantalla física disponible.

Conclusión

La integración de TinyFish AgentQL + CapSolver trae la resolución de CAPTCHA invisible a uno de los conjuntos de herramientas de automatización web más poderosos disponibles. En lugar de escribir código complejo para manejar CAPTCHAs, simplemente:

1. Descargue la extensión de CapSolver y configure su clave de API
2. Inicie el navegador de AgentQL con Playwright con la extensión cargada mediante un contexto persistente
3. Escriba sus scripts de automatización como de costumbre — simplemente agregue un tiempo de espera antes de enviar formularios

La extensión de CapSolver maneja el resto — detecta CAPTCHAs, los resuelve mediante la API de CapSolver y inyecta tokens en la página. Sus scripts de AgentQL nunca necesitan saber nada sobre CAPTCHAs en absoluto.

Este es el aspecto de la resolución de CAPTCHA cuando combina automatización web con inteligencia artificial con resolución de CAPTCHA con inteligencia artificial: invisible, automática y sin código.

¿Listo para comenzar? Regístrese en CapSolver y use el código de bonificación AGENTQL para obtener un 6% adicional en su primer recarga!

Preguntas frecuentes

¿Necesito escribir código específico para CAPTCHA en mis scripts de AgentQL?

No. La extensión de CapSolver funciona completamente en segundo plano dentro del contexto del navegador de Playwright. Simplemente agregue un time.sleep() o waitForTimeout() antes de enviar formularios, y la extensión maneja la detección, resolución e inyección de tokens automáticamente.

¿Por qué necesito un contexto persistente?

Playwright solo admite extensiones de Chrome cuando se usa launch_persistent_context(). Esto es un requisito arquitectónico de Playwright. Los contextos de navegador regulares creados mediante browser.new_context() no pueden cargar extensiones.

¿Puedo ejecutar esto en modo headless?

No. Las extensiones de Chrome requieren un navegador con interfaz gráfica. Para entornos de servidor sin pantalla, use Xvfb (X Virtual Framebuffer) para crear una pantalla virtual.

¿Qué tipos de CAPTCHA admite CapSolver?

CapSolver admite reCAPTCHA v2 (casilla e invisible), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA y más. La extensión detecta automáticamente el tipo de CAPTCHA y lo resuelve en consecuencia.

¿Cuánto cuesta CapSolver?

CapSolver ofrece precios competitivos según el tipo de CAPTCHA y el volumen. Visite capsolver.com para ver los precios actuales.

¿Es gratuito TinyFish AgentQL?

AgentQL ofrece versiones gratuitas y pagadas. El SDK y el lenguaje de consultas están disponibles para desarrollo y pruebas. Visite tinyfish.ai para obtener detalles sobre precios.

¿Cuánto tiempo debo esperar para que se resuelva el CAPTCHA?

Para la mayoría de los CAPTCHAs, 30-60 segundos es suficiente. El tiempo de resolución real suele ser de 5-20 segundos, pero agregar un margen adicional garantiza la confiabilidad. Si hay dudas, use 30 segundos.