
Anh Tuan
Data Science Expert

Cuando tu automatización web impulsada por IA choca con un muro de CAPTCHA, toda la cadena de procesamiento se detiene. Las páginas no se cargan, los formularios no se pueden enviar y la extracción de datos se detiene — todo porque un desafío diseñado para bloquear bots. TinyFish AgentQL es un potente conjunto de herramientas para conectar la IA con la web, que incluye consultas en lenguaje natural, integraciones con Playwright y extracción de datos estructurados a escala empresarial. Pero como cualquier marco de automatización de navegadores, se queda atascado en los CAPTCHAs.
CapSolver cambia esto por completo. Al cargar la extensión de Chrome 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 ejecutándose 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 que tu agente se enfoca en lo que hace mejor: extraer datos y automatizar flujos de trabajo.
TinyFish AgentQL es una herramienta 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 necesidad de selectores CSS frágiles o XPaths.
AgentQL opera en cualquier página — incluyendo 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.
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.
La mayoría de las integraciones de resolución de CAPTCHA requieren que escribas código repetitivo: crear tareas, consultar resultados, inyectar tokens en campos ocultos. Ese es el enfoque estándar con scripts de Playwright o Puppeteer.
AgentQL + CapSolver toma un enfoque fundamentalmente diferente:
| Tradicional (basado en código) | AgentQL + Extensión CapSolver |
|---|---|
| Escribir una clase de servicio CapSolver | Cargar la extensión en el contexto de Playwright |
Llamar a createTask() / getTaskResult() |
La extensión maneja todo automáticamente |
Inyectar tokens mediante page.evaluate() |
La inyección de tokens es invisible |
| Manejar errores, reintentos, tiempos de espera en código | La extensión gestiona reintentos internamente |
| Código diferente para cada tipo de CAPTCHA | Funciona para todos los tipos automáticamente |
La clave del insight: La extensión de CapSolver se ejecuta 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 CAPTCHA.
Antes de configurar la integración, asegúrate de tener:
Importante: Las extensiones de Chrome solo funcionan en Chromium con un contexto persistente en Playwright. Esto es un requisito de Playwright, no una limitación de AgentQL.
SDK de Python:
pip install agentql
playwright install chromium
SDK de JavaScript:
npm install agentql
npx playwright install chromium
Descarga la extensión de Chrome de CapSolver y cópiala a un directorio dedicado:
CapSolver.Browser.Extension-chrome-v1.17.0.zipmkdir -p ~/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/capsolver-extension/
ls ~/capsolver-extension/manifest.json
Deberías ver manifest.json — esto confirma que la extensión está en el lugar correcto.
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', // ← aquí tu clave
useCapsolver: true,
// ... resto de la configuración
};
Puedes obtener tu clave de API desde tu panel 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 cabeza
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 cabeza
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();
})();
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 habilitada.
Alternativamente, revisa la consola del navegador en busca de mensajes de registro de CapSolver indicando que el servicio de trabajo está en ejecución.
Una vez que la configuración esté completa, usar CapSolver con AgentQL es sencillo.
No escribas código específico de CAPTCHA. Simplemente agrega un tiempo de espera antes de interactuar con formularios protegidos por CAPTCHA y deja que la extensión haga su trabajo.
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("Hello, I have a question about your services.")
# Esperar a que CapSolver resuelva el CAPTCHA
time.sleep(30)
# Enviar — el token de CAPTCHA ya está inyectado
response.contact_form.submit_button.click()
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 — 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()
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)")
| Tipo de CAPTCHA | Tiempo de resolución típico | Tiempo de espera recomendado |
|---|---|---|
| reCAPTCHA v2 (casilla) | 5-15 segundos | 30-60 segundos |
| reCAPTCHA v2 (invisible) | 5-15 segundos | 30 segundos |
| reCAPTCHA v3 | 3-10 segundos | 20-30 segundos |
| Cloudflare Turnstile | 3-10 segundos | 20-30 segundos |
Consejo: Si dudas, usa 30 segundos. Es mejor esperar un poco más que enviar demasiado pronto. El tiempo adicional no afecta el resultado.
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 trabajador de servicio llama │
│ a la API de CapSolver │
│ 3. Se recibe el token │
│ 4. El token se inyecta en │
│ un campo de formulario oculto │
└─────────────────────────────┘
│
▼
time.sleep(30) La extensión resuelve el CAPTCHA...
│
▼
page.query_elements(...) AgentQL encuentra los elementos del formulario
submit_button.click() El formulario se envía CON el token válido
│
▼
"Verificación exitosa!"
Cuando Playwright inicia Chromium con la bandera --load-extension:
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()
| Opción | Descripción |
|---|---|
user_data_dir |
Directorio para almacenar datos del perfil del navegador (cookies, sesiones). Requerido para contexto persistente. |
headless |
Debe ser False — las extensiones de Chrome no funcionan en modo sin cabeza. |
--disable-extensions-except |
Restringe qué extensiones pueden cargarse (previene conflictos). |
--load-extension |
Ruta al directorio de la extensión CapSolver desempaquetado. |
CAPSOLVER_EXTENSION_PATH |
Ruta completa a la extensión CapSolver extraída que contiene manifest.json. |
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).
Todo lo anterior asume que está ejecutando Chromium por su cuenta, localmente, con un contexto de Playwright persistente para que la extensión de CapSolver se pueda cargar. Pero no todos los entornos le dan este tipo de control: si su automatización se ejecuta contra TinyFish Browser, el servicio remoto de sesiones de navegador a demanda de TinyFish, no gestiona directamente el proceso de Chromium, por lo que no puede cargar una extensión desempaquetada de la misma manera.
Para ese escenario, CapSolver se puede integrar a través de su API, directamente en su script: solicita una sesión de navegador remoto desde TinyFish Browser, se conecta a través de CDP con Playwright, resuelve el CAPTCHA con el SDK de CapSolver y inyecta el token resultante en la página usted mismo. Es el enfoque más "tradicional", basado en código, descrito anteriormente en este artículo: pero es la herramienta adecuada cuando no se puede cargar una extensión en la instancia del navegador que está controlando.
Antes de comenzar, instale el SDK de CapSolver:
pip install capsolver
El siguiente código muestra cómo usar CapSolver para resolver un reCAPTCHA dentro de una sesión de TinyFish Browser:
import time
import requests
import capsolver
from playwright.sync_api import sync_playwright
TINYFISH_API_KEY = "SU CLAVE DE API DE TINYFISH"
capsolver.api_key = "SU CLAVE DE API DE CAPSOLVER"
website_url = "https://www.google.com/recaptcha/api2/demo"
website_key = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
captcha_type = "ReCaptchaV2TaskProxyLess"
def create_tinyfish_browser(url):
resp = requests.post(
"https://api.browser.tinyfish.ai",
headers={
"X-API-Key": TINYFISH_API_KEY,
"Content-Type": "application/json",
},
json={
"url": url,
"timeout_seconds": 300,
},
timeout=90,
)
resp.raise_for_status()
return resp.json()
def close_tinyfish_browser(session_id):
try:
requests.delete(
f"https://api.browser.tinyfish.ai/{session_id}",
headers={"X-API-Key": TINYFISH_API_KEY},
timeout=30,
)
except Exception as exc:
print(" Fallo al cerrar la sesión del navegador TinyFish:", repr(exc))
def solve_recaptcha_v2():
print("3. Resolviendo reCAPTCHA con CapSolver")
solution = capsolver.solve({
"type": captcha_type,
"websiteURL": website_url,
"websiteKey": website_key,
})
token = solution.get("gRecaptchaResponse")
if not token:
raise RuntimeError(f"CapSolver no devolvió un token de reCAPTCHA: {solution}")
print(" Tarea de CapSolver resuelta:", token)
return token
def inject_recaptcha_token(page, token):
page.evaluate(
"""
(token) => {
const textarea = document.getElementById('g-recaptcha-response');
if (textarea) {
textarea.value = token;
}
}
""",
token,
)
print(" Token de CapSolver inyectado")
page.click('input[type="submit"]')
print(" Botón de enviar clicado")
def main():
session_id = None
try:
print("1. Creando sesión del navegador TinyFish")
session = create_tinyfish_browser(website_url)
session_id = session["session_id"]
cdp_url = session["cdp_url"]
print(" ID de sesión TinyFish:", session_id)
print(" URL de CDP de TinyFish:", cdp_url)
with sync_playwright() as p:
print("2. Conectando al navegador TinyFish a través de CDP")
browser = p.chromium.connect_over_cdp(cdp_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.wait_for_load_state("domcontentloaded", timeout=60000)
print(" URL de la página actual:", page.url)
token = solve_recaptcha_v2()
print("4. Inyectando el token de Capsolver")
inject_recaptcha_token(page, token)
page.wait_for_load_state("domcontentloaded", timeout=30000)
time.sleep(3)
body_text = page.locator("body").inner_text(timeout=10000)
print("5. Resultado de la página:", " ".join(body_text.split()))
print("6. Cerrando sesiones del navegador")
browser.close()
finally:
if session_id:
close_tinyfish_browser(session_id)
if __name__ == "__main__":
main()
Cualquiera que sea el enfoque que se adapte a su configuración — cargar la extensión de CapSolver en un contexto de Playwright local y persistente, o llamar directamente a la API de CapSolver contra una sesión de TinyFish Browser remoto — el objetivo es el mismo: la automatización de AgentQL nunca debe necesitar lógica de manejo de CAPTCHA propia.
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 que esté ejecutándose en modo sin cabeza.
Solución: Las extensiones en Playwright requieren un contexto persistente y modo con interfaz gráfica:
# ✅ Correcto — contexto persistente, modo 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()
Posibles causas:
Síntoma: El script se ejecuta pero no aparece la extensión.
Causa: Las extensiones de Chrome no funcionan en modo sin cabeza.
Solución: Use el modo con interfaz gráfica con un entorno virtual en servidores:
# Instalar Xvfb
sudo apt-get install xvfb
# Iniciar un entorno virtual
Xvfb :99 -screen 0 1280x720x24 &
# Establecer DISPLAY
export DISPLAY=:99
Síntoma: La bandera de extensión se ignora silenciosamente.
Causa: Chrome 137+ eliminó el soporte para --load-extension en builds oficiales.
Solución: Use el Chromium de Playwright (recomendado) o Chrome para Testing:
# Instalar Chromium de Playwright (recomendado)
npx playwright install chromium
# O descargar Chrome para Testing
# Visite: https://googlechromelabs.github.io/chrome-for-testing/
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.
Mantenga sus scripts de automatización limpios. No agregue lógica específica de CAPTCHA a sus consultas de AgentQL. La extensión maneja todo — su código debe centrarse únicamente en la extracción de datos e interacción.
Monitoree su saldo de CapSolver. Cada resolución de CAPTCHA cuesta créditos. Verifique su saldo en capsolver.com/dashboard regularmente para evitar interrupciones.
Use consistentemente el contexto persistente. Siempre inicie con launch_persistent_context() cuando necesite extensiones. Esto también preserva cookies y datos de sesión entre ejecuciones, lo que puede reducir la frecuencia de CAPTCHA.
Use Xvfb en servidores sin cabeza. Las extensiones de Chrome requieren un contexto de visualización. Configure Xvfb para entornos de servidor donde no haya una pantalla física disponible.
Ajuste la integración a su entorno. Use el enfoque basado en extensión siempre que controle directamente el proceso de Chromium y pueda lanzar un contexto persistente. Use el enfoque basado en API con el SDK de CapSolver siempre que se conecte a un navegador que no controle el lanzamiento — como una sesión de TinyFish Browser remoto a través de CDP.
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:
La extensión de CapSolver maneja el resto — detecta CAPTCHAS, los resuelve a través de la API de CapSolver y inyecta tokens en la página. Sus scripts de AgentQL nunca necesitan saber nada sobre CAPTCHAS en absoluto.
Y cuando su automatización se ejecute contra una sesión remota en lugar de un navegador local — como TinyFish Browser — el SDK y la API de CapSolver le permiten obtener el mismo resultado con unos pocos líneas adicionales de código: solicite la sesión, conéctese a través de CDP, resuelva y inyecte.
Este es el aspecto de la resolución de CAPTCHA cuando combina automatización web impulsada por IA con resolución de CAPTCHA impulsada por IA: 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!

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.
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.
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.
Como no controla directamente el lanzamiento del navegador, no puede cargar la extensión de CapSolver en una sesión de TinyFish Browser. En su lugar, use el SDK de CapSolver para resolver el CAPTCHA e inyectar el token resultante usted mismo a través de page.evaluate() después de conectarse a través de CDP, como se muestra en la sección "Uso de CapSolver con TinyFish Browser" anteriormente.
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.
CapSolver ofrece precios competitivos según el tipo de CAPTCHA y el volumen. Visite capsolver.com para conocer los precios actuales.
AgentQL ofrece tarifas gratuitas y pagadas. El SDK y el lenguaje de consulta están disponibles para desarrollo y pruebas. Visite tinyfish.ai para obtener detalles de precios.
Para la mayoría de los CAPTCHAS, 30-60 segundos son suficientes. El tiempo de resolución real suele ser de 5-20 segundos, pero agregar un tiempo adicional garantiza la fiabilidad. Si hay dudas, use 30 segundos.
Integrar la resolución de CAPTCHA en agentes de LlamaIndex usando FunctionTool y CapSolver para pipelines de ingesta de datos web.

Configurar el servicio CapSolver MCP para la resolución de CAPTCHA sin código en Claude Desktop, Cursor y cualquier cliente MCP.
