🎉NUEVOCapSolver para agentes de IA-Integraciones de MCP, herramientas de agente y SDK
Aloísio Vítor
Image Processing Expert
Publicado Oct 22, 2026
Actualizado Oct 22, 2026 · min de lectura
Un agente basado en navegador necesita información útil cuando un CAPTCHA interrumpe su trabajo. Un título de página o una simple captura de pantalla pueden no indicar qué familia de CAPTCHA está presente o qué parámetros se necesitan en el siguiente paso. Devolver un resultado pequeño y estructurado le da a la aplicación un punto de decisión claro antes de solicitar una solución.
Haystack es un framework de Python para construir aplicaciones de IA, canalizaciones de recuperación y agentes. Sus herramientas nativas pueden envolver funciones usadas por esas aplicaciones. Esta guía conecta una herramienta de Haystack con CapSolver para una tarea específica: inspeccionar la página de navegador actual y devolver parámetros de CAPTCHA. El ejemplo usa una página de desarrollo y no realiza ninguna petición de resolución de pago. Te proporciona un componente de inspección funcional para colocar antes de un paso de resolución autorizado por separado.
La herramienta de inspección de CAPTCHA pertenece entre la acción del navegador que llega a un punto de verificación y el código que decide cómo manejar ese punto de verificación. El navegador sigue siendo el dueño de la navegación y de la página actual. Haystack proporciona la interfaz de herramienta; el Core SDK lee la información de los CAPTCHA compatibles.
Por ejemplo, un equipo que está probando su propio formulario puede dejar que el navegador llegue al formulario, invocar la herramienta de inspección y examinar el tipo y la clave de sitio devueltos. El entorno de pruebas puede entonces elegir su ruta aprobada de clave de prueba o una comprobación de resolución configurada por separado. No debe tratar el propio widget de CAPTCHA como el contenido de negocio del formulario.
Se trata de una integración de desarrollador usando la abstracción Tool documentada de Haystack, más que de una afirmación de que exista un plugin dedicado de Haystack. La herramienta tiene un propósito estrecho y no necesita un LLM para ejecutarse. Llamarla directamente es útil antes de añadir selección de herramientas dirigida por modelo.
Necesitas Python, el paquete Haystack, el SDK CapSolver Core con su dependencia Playwright, y Chromium instalado para Playwright. El ejemplo siguiente se ejecutó con Python 3.12, haystack-ai 3.4.0, capsolver-core 0.1.1 y Playwright 1.64.0. Son versiones probadas, no una afirmación de que sean los lanzamientos más recientes disponibles.
El navegador debe poder cargar el script público reCAPTCHA de Google. La página local usa la clave de sitio de desarrollo documentada por Google; no es una clave de producción y no debe desplegarse como tal. La guía de pruebas de reCAPTCHA de Google explica la distinción entre claves de prueba y verificación en producción.
No se necesita una clave de API de CapSolver ni una clave de proveedor de modelos para este ejemplo solo de inspección. Una operación posterior de resolución sí requiere una clave de cuenta CapSolver válida. Un agente de Haystack posterior impulsado por LLM requiere su propio proveedor de modelos configurado. Esos son prerrequisitos separados, así que no intentes solucionar problemas de credenciales de modelo faltantes cambiando los parámetros del CAPTCHA.
Crea un entorno virtual e instala los paquetes en ese entorno. Ejecuta la instalación de Chromium mediante el mismo intérprete de Python para mantener la dependencia del navegador alineada con 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 chromiumLos comandos anteriores usan una ruta de entorno de estilo POSIX. Si tu sistema operativo usa una estructura de entorno virtual diferente, usa el ejecutable de Python de ese entorno. La guía de instalación de Playwright para Python cubre sus requisitos de instalación del navegador.
La herramienta envuelve get_captcha_info(page) del Core SDK oficial. La página es capturada por la función, así que la herramienta no tiene argumento de navegación. Su esquema de parámetros JSON no acepta campos de entrada.
Guarda lo siguiente como haystack_captcha_inspection.py. La respuesta HTML local es suministrada por el enrutamiento de Playwright; es un recurso de desarrollo, no una aplicación alojada de forma remota. El script de reCAPTCHA en sí se carga desde Google. El programa lee los parámetros sin hacer clic en el widget ni enviar un formulario.
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())El argumento async_function es importante porque las operaciones del SDK y de Playwright son asíncronas. La referencia de la API de Tool de Haystack documenta invoke_async() para esta ruta. Colocar una corrutina en una ruta de llamada solo síncrona puede fallar antes de que ocurra cualquier inspección de CAPTCHA.
Los gestores de contexto y el bloque finally cierran los recursos del SDK y del navegador. Mantén esa limpieza al adaptar el ejemplo a una aplicación de ejecución más prolongada; de lo contrario, una carga de página fallida puede dejar procesos de navegador colgados.
Canjea tu código de bonificación de CapSolver
Aumenta tu presupuesto de automatización al instante.
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% de bonificación adicional en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver
Al ejecutar el script se invoca la herramienta de Haystack directamente y se imprime el diccionario que devuelve. En el ejemplo, ese diccionario contiene una lista captchas con una entrada reCAPTCHA v2.
.venv/bin/python haystack_captcha_inspection.pyLa ejecución local devolvió type igual a reCaptchaV2, website_url igual a http://127.0.0.1:8765/, y la clave de sitio pública de prueba configurada en el HTML. Estos campos se leyeron a través del SDK y el navegador reales, no se rellenaron en una respuesta simulada de la herramienta.
El resultado es deliberadamente pequeño. El descriptor completo del SDK puede incluir campos adicionales, pero un agente solo debería recibir lo que necesita para su siguiente decisión. Una clave de sitio es un identificador público del widget; no es la clave de cuenta de CapSolver ni el secreto privado de verificación del sitio.
Esta ejecución establece que Haystack puede invocar la función asíncrona, que el navegador puede cargar el widget de desarrollo y que el Core SDK puede leer sus parámetros. No establece la selección de herramientas por modelo, la detección de CAPTCHA en producción en todos los sitios, la generación correcta de tokens ni su aceptación por el backend de un sitio web. Todo ello requiere sus propias comprobaciones en la aplicación real.
Mantén el mismo objeto Tool y el mismo vínculo a la página cuando añadas esta capacidad a tu agente de Haystack. El agente de Haystack acepta herramientas mediante su configuración documentada tools. Registra este objeto junto con las herramientas que tu aplicación ya usa, manteniendo su página de navegador viva durante la llamada.
En un flujo de trabajo de navegador existente, sustituye la configuración local del recurso por la página que tu aplicación ya ha abierto y está autorizada a inspeccionar. Mantén la navegación del navegador fuera de esta herramienta. Eso hace que la selección de la página sea explícita y evita que una URL generada por el modelo cambie silenciosamente el objetivo de la inspección.
Ponle a la herramienta un nombre y una descripción precisos. La descripción del ejemplo indica que lee información de CAPTCHA y que no resuelve ni envía. Una descripción como “terminar verificación” prometería más de lo que la función realiza y podría animar al agente a informar de éxito demasiado pronto.
Una decisión útil de la aplicación es: si el resultado contiene un widget reconocido con los parámetros necesarios, ofrecer el siguiente paso adecuado; si está vacío o incompleto, recopilar más evidencia o solicitar revisión humana. No añadas un bucle incondicional que siga inspeccionando la misma página incompleta.
El resultado de la inspección es una entrada para la decisión de usar un solver, no una solución de CAPTCHA. El Core SDK documenta solve(info) para la resolución de tokens y solve_on_page(page) para un flujo de trabajo más amplio en el navegador. Tienen efectos diferentes de get_captcha_info(page) y requieren configuración y autorización separadas.
Para esta guía, mantén la herramienta de inspección con un propósito de solo lectura. Si más adelante añades una herramienta de resolución, deja que tu aplicación valide el tipo detectado y la página actual, proporcione la credencial de cuenta fuera de los argumentos visibles por el modelo y aplique las reglas de presupuesto y aprobación adecuadas a ese flujo de trabajo. Devuelve un resultado claro que distinga un token de una acción completada de la aplicación.
Un token devuelto todavía necesita el manejo correspondiente en la aplicación. La propia verificación del sitio y el resultado del formulario determinan si la operación prevista tuvo éxito. Ni una lista captchas no vacía ni la invocación correcta de una herramienta de Haystack son evidencia de que la aplicación aceptó una respuesta de CAPTCHA.
La solución de problemas debe identificar qué capa falló: instalación de paquetes, inicio del navegador, carga del widget, inspección del SDK o invocación de la herramienta. Cambia la capa que indica el error en lugar de sustituir varios componentes a la vez.
Instala Chromium con el comando de Playwright desde el entorno virtual activo. Una instalación pip install correcta instala el paquete de Python, pero por sí sola no demuestra que el binario de navegador correspondiente esté disponible.
Comprueba si el navegador cargó el script de Google y si la página de prueba creó el widget. La espera de este ejemplo busca clientes de widget inicializados. Puede producirse un fallo de red antes de que el SDK tenga algo que inspeccionar; volver a intentar el solver no solucionaría ese fallo.
Un resultado vacío significa que esta inspección no encontró descriptores compatibles en esa página en ese momento. No demuestra que la página no tenga un mecanismo de verificación. Comprueba los tiempos de la página, el objeto de página que has pasado y el widget real. La guía de inspección de parámetros de CAPTCHA proporciona una forma complementaria de inspeccionar el estado del navegador.
Comprueba que el mismo objeto Tool esté registrado, que el modelo del agente admita el flujo de trabajo de herramientas previsto y que la sesión del navegador siga abierta. Mantén la invocación directa correcta como un punto de control separado para que un problema de configuración del modelo no se informe erróneamente como un fallo de la API de CAPTCHA.
Una pequeña herramienta de inspección de CAPTCHA ofrece a una aplicación de Haystack un punto de control concreto antes de resolver. Empieza con la página de desarrollo probada, preserva la llamada asíncrona y la limpieza, y luego adjunta la herramienta a la página que controla tu flujo de trabajo existente. Amplía sus responsabilidades solo cuando cada operación adicional tenga una entrada clara, un comportamiento verificado y un resultado observable.
Usa CapSolver para el paso de CAPTCHA compatible en un flujo de trabajo que estás autorizado a ejecutar. Mantén el navegador, el resultado del solver y el resultado de la aplicación como comprobaciones separadas para que una llamada de herramienta correcta no oculte una tarea fallida.
P: ¿Esta integración requiere MCP?
No. El ejemplo usa una herramienta nativa de Haystack y el Core SDK de Python en la misma aplicación. No inicia un servidor MCP.
P: ¿Necesito una clave de API de LLM para ejecutar el script?
No. El script invoca la herramienta directamente. Una credencial de proveedor de modelos pasa a ser relevante cuando añadas un agente con LLM alrededor de esa herramienta.
P: ¿El ejemplo resuelve el CAPTCHA de prueba?
No. Carga el widget y lee parámetros públicos. No solicita un token de resolución ni envía el formulario.
P: ¿Se puede usar el mismo enfoque para inspeccionar una página de Playwright existente?
Sí. Vincula la herramienta a la página autorizada existente y mantén esa página viva durante la invocación. Los campos de descriptor compatibles dependen de lo que el SDK pueda detectar en esa página.
P: ¿Por qué usar una herramienta sin argumentos?
La función ya conoce la página aprobada actual. Un esquema de entrada vacío mantiene la navegación y la selección de página bajo el control de la aplicación.
P: ¿Un resultado vacío significa que la página es segura para procesarse como contenido normal?
No. Inspecciona el estado de la página antes de continuar. Un resultado de detección vacío también puede reflejar cuestiones de tiempo, un mecanismo no compatible o una inicialización incompleta del widget.
Aloísio Vítor
Image Processing Expert
Interpreting the visual signals behind web workflows.
SOBRE EL AUTOR
Agrega herramientas de resolución de CAPTCHA a Goose con una extensión MCP local. Configura Python, inspecciona el descubrimiento de herramientas y soluciona problemas de la configuración antes de una tarea de resolución.
Conecta Mastra a un solucionador de CAPTCHA con MCPClient, inspecciona las herramientas con espacios de nombres, ejecuta una verificación de capacidades y define el siguiente paso para un flujo de trabajo de agente autorizado.