🎉NUEVOCapSolver para agentes de IA-Integraciones de MCP, herramientas de agente y SDK
Aloísio Vítor
Image Processing Expert
Publicado Oct 30, 2026
Actualizado Oct 30, 2026 · min de lectura
errorId antes de interpretar status o solution.Un agente de navegador puede recibir una respuesta de herramienta válida y aun así no tener nada útil que hacer a continuación. La respuesta podría contener un error de validación, una tarea sin terminar o una solución que la página no ha aceptado. Convertir los tres casos en el mismo mensaje de “listo” hace que el agente continúe demasiado pronto.
CapSolver expone operaciones de CAPTCHA mediante APIs directas e interfaces para agentes. La interfaz que elijas determina la forma del resultado. Esta guía explica cómo interpretar esas formas y diseñar un pequeño resumen de aplicación sin inventar nuevos campos del proveedor.
El caso de uso concreto es un agente que opera un formulario de prueba propio. El navegador llega a un CAPTCHA compatible, se ejecuta el solver seleccionado y la aplicación decide si debe esperar, corregir entradas, aplicar un resultado o detenerse. La pregunta aquí es qué evidencia debe controlar esa decisión.
Identifica la capa de respuesta antes de leer un campo llamado success o status.
Hay tres capas útiles: el transporte de herramienta, la operación de CAPTCHA y la tarea del navegador. Una API define una interfaz concreta; su respuesta debe interpretarse dentro de ese contrato. Un wrapper de herramienta puede añadir otro sobre, y la aplicación puede añadir su propio estado de flujo de trabajo.
| Capa | Pregunta que responde | Lo que no puede establecer por sí sola |
|---|---|---|
| Transporte MCP/herramienta | ¿La llamada a la herramienta devolvió respuesta o informó de un error de herramienta? | Si existe una solución de CAPTCHA utilizable |
| Servicio CAPTCHA | ¿La operación de resolución falló, sigue pendiente o produjo su resultado documentado? | Si el formulario o página previstos aceptaron ese resultado |
| Navegador/aplicación | ¿La operación prevista alcanzó su estado esperado? | Si todos los diagnósticos anteriores se registraron correctamente |
Conserva disponible el resultado original para depuración. Si tu aplicación normaliza resultados, etiqueta sus campos como propiedad de la aplicación. No presentes un campo interno conveniente como workflow_state como si fuera un campo documentado de la API de CapSolver.
Revisa la señal de error de herramienta MCP y luego inspecciona el payload según el contrato propio de la herramienta.
La especificación de herramientas MCP describe el contenido del resultado de la herramienta y el indicador isError. Las bibliotecas cliente pueden exponer esto con un nombre distinto según el lenguaje de programación. Por ejemplo, los resultados de herramientas de FastMCP exponen .is_error, .content y datos ya parseados.
No supongas que cada respuesta de herramienta es un diccionario JSON desnudo. Algunos servidores devuelven contenido de texto que contiene JSON serializado; algunos también proporcionan contenido estructurado. Lee la propiedad documentada del cliente y luego parsea solo la capa que realmente contenga JSON. Buscar en toda la cadena de respuesta la palabra “success” no es fiable.
En una prueba de conexión local con FastMCP 3.4.11 y capsolver-mcp 0.1.3, una llamada deliberadamente incompleta a solve_captcha devolvió un error de herramienta que identificaba las entradas website_url y website_key como faltantes. Una llamada de registro separada se devolvió correctamente. Esas observaciones confirman la ruta de lectura de errores y la ejecución del registro, no la resolución de pago.
Una herramienta también puede devolver un sobre MCP normal que contenga un fallo a nivel de servicio. Por lo tanto, “sin excepción de herramienta” es solo la primera comprobación. A continuación inspecciona el resultado de negocio documentado para esa herramienta concreta. No traduzcas los campos de la API directa a campos MCP por conjeturas.
Para un ejemplo específico de registro en un framework, la guía de herramientas de Pydantic AI cubre entradas tipadas y ejecución del adaptador. Aquí nos centramos en la decisión tras la llegada de una respuesta, independientemente del framework que haya registrado la herramienta.
Con la API directa, comienza por errorId y luego sigue el estado de tarea documentado.
Las referencias de createTask y getTaskResult definen este flujo. Una creación de tarea satisfactoria puede devolver un identificador de tarea para su posterior recuperación. Ese identificador es un “handle” de la operación, no la respuesta resuelta.
Para un resultado consultado por sondeo, una respuesta de error debe tratarse antes de leer una solución. Los estados documentados idle y processing son estados sin terminar. Continúa el flujo de recuperación existente dentro de su plazo configurado; la referencia instruye a los llamadores a esperar tres segundos antes de reintentar un resultado en procesamiento. Un resultado listo debe seguir conteniendo la forma de solución documentada para ese tipo de tarea.
| Observación de la respuesta | Interpretación | Acción de la aplicación |
|---|---|---|
errorId distinto de cero |
El servicio informa de un error | Conserva errorCode y errorDescription; elige corregir o detener |
| Tarea aceptada, resultado aún en procesamiento | Aún no hay solución final | Sondea la misma tarea dentro de los límites documentados |
| Resultado listo con el campo de solución esperado | Hay una solución candidata disponible | Pásala al componente responsable del mismo desafío |
| Campos de resultado faltantes o inesperados | Contrato no establecido | Detén la interpretación e inspecciona la respuesta; no fabriques un token |
| El navegador confirma la tarea prevista | Resultado de la aplicación establecido | Registra la finalización del flujo de trabajo por separado |
Algunos tipos de tarea pueden completarse de forma sincrónica. Sigue la respuesta documentada para el tipo seleccionado en lugar de forzar todas las tareas a un bucle de sondeo. A la inversa, no llames repetidamente a createTask solo porque un resultado asíncrono aún no esté listo.
La referencia de reCAPTCHA v2 describe sus campos de solución. Otras familias de tareas pueden devolver datos distintos. Un wrapper que suponga que todos los resultados contienen el mismo campo de token puede descartar silenciosamente una respuesta válida o confundir un campo no relacionado con uno.
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% extra de bonificación en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver
Devuelve suficiente información para el siguiente paso permitido del agente, conservando los datos detallados del servicio en el componente que los consume.
Un pequeño resumen de aplicación puede contener la etapa de la operación, un resultado normalizado, una explicación segura y la siguiente acción permitida. Estos son campos de tu aplicación, no un reemplazo de la respuesta del proveedor.
Por ejemplo, tras una respuesta pendiente de la API directa, el resumen podría decir: “La tarea de CAPTCHA está en procesamiento; continúa esperando la tarea existente.” Tras un error de entrada, podría decir: “La petición está incompleta; obtén los parámetros de página que faltan antes de otro intento.” Tras un resultado del solver, podría decir: “Hay una solución disponible; la verificación en el navegador está pendiente.”
Observa lo que estos mensajes evitan: ninguno afirma que se envió un formulario o se completó una solicitud de datos. El navegador debe aportar esa evidencia más adelante.
Una implementación práctica mantiene dos registros. El registro operativo almacena la referencia de la tarea, campos de diagnóstico seguros y transiciones de etapa. El componente del navegador mantiene temporalmente el valor de solución que necesita. El resumen visible para el modelo señala la siguiente acción permitida sin copiar el token completo en una respuesta conversacional.
Si la aplicación acepta salidas estructuradas del modelo, valida esas salidas contra su propio esquema. Un esquema válido establece la forma, no la veracidad. No se debe permitir que el modelo cambie una observación de solver pendiente a un resultado de navegador completado simplemente devolviendo una cadena de estado distinta.
Elige la siguiente acción a partir de la descripción del error y del estado actual de la página, no de una regla universal de reintento.
La referencia oficial de errores distingue datos inválidos, tareas no compatibles, credenciales, límites y fallos de resolución. Esas categorías requieren un tratamiento diferente. Reintentar el mismo payload inválido no corrige sus campos. Iniciar otra tarea de pago no repara una credencial faltante.
Usa una secuencia de decisión compacta:
Un stop acotado es un resultado útil. “No se pudo completar este paso” con un motivo preciso es más accionable que una cadena vacía que haga que el agente se comporte como si la resolución hubiera tenido éxito.
La aplicación debe observar el resultado esperado de la tarea original tras el paso de CAPTCHA.
Para un formulario de prueba propio, define esa condición antes de invocar el solver: quizá un elemento de confirmación conocido y el registro de envío de prueba correspondiente. Un iframe que desaparece, un campo de respuesta que se completa o una herramienta que devuelve un token pueden ser evidencias intermedias útiles, pero todas son más débiles que el resultado previsto de la aplicación.
La documentación de verificación de reCAPTCHA de Google explica el paso de verificación del lado del servidor. Por eso un token devuelto al navegador no debe confundirse con la aceptación por parte de la aplicación receptora.
Cuando falle un flujo de trabajo, conserva la última etapa establecida. “El solver devolvió resultado; la aplicación lo rechazó” es diferente de “el solver nunca devolvió resultado”. Esta distinción impide que una sesión de depuración cambie la solicitud al solver cuando el problema real es un campo obligatorio del formulario no relacionado.
Prueba las ramas de resultado de forma independiente y luego realiza una prueba extremo a extremo permitida con credenciales reales y una página propia.
Incluye un fallo de validación de entrada, un fixture de error de servicio, una respuesta de procesamiento, una respuesta lista, un payload inesperado y un rechazo del navegador tras una solución candidata. Los fixtures prueban las decisiones de tu aplicación; no prueban el comportamiento de la API en vivo ni la aceptación del CAPTCHA.
Prueba también una respuesta que llegue después de que la aplicación haya dejado de esperar. La aplicación debe conservar su estado de detenida en lugar de permitir que un resultado tardío reactive un formulario abandonado. Mantén el resultado asociado a su intento original.
Las comprobaciones de este artículo establecen la interpretación documentada de respuestas y una ruta real de validación/registro MCP. No constituyen un benchmark de resolución de pago, un caso de estudio de cliente en producción ni una medición de tasas de éxito de agentes.
Haz que el resultado de CAPTCHA sea accionable preservando su estado real y comprobando el resultado en el navegador. CapSolver proporciona la interfaz de solver documentada para ese paso. Prueba CapSolver con un flujo de trabajo de prueba permitido y mantén la comprobación final de la aplicación por separado.
P: ¿isError en false significa que el CAPTCHA se resolvió?
No. Significa que la respuesta de la herramienta no se marcó como error de ejecución de herramienta. Inspecciona el resultado de negocio documentado en el payload y luego verifica la tarea del navegador por separado.
P: ¿El agente debería recibir el token completo de CAPTCHA?
Solo si el componente que consume el token realmente lo necesita. Muchos diseños pueden mantener el valor en el estado de la aplicación y dar al modelo un breve estado en su lugar.
P: ¿Puedo usar el mismo parser de resultados para REST y MCP?
Solo después de adaptar explícitamente sus diferentes contratos de respuesta. Un resultado de tarea REST y un sobre de herramienta MCP no son objetos intercambiables.
P: ¿Qué debería devolver cuando el resultado sigue en procesamiento?
Devuelve un estado pendiente en el formato propio de tu aplicación y sigue recuperando la tarea existente dentro de tu plazo. No lo etiquetes como completado ni crees otra tarea solo porque la primera no haya terminado.
P: ¿Qué pasa si el solver devuelve un resultado pero el formulario falla?
Registra por separado la finalización del solver y el fallo de la aplicación. Inspecciona el rechazo de la página y el contexto actual de la tarea antes de decidir si es apropiado un nuevo intento de CAPTCHA.
Aloísio Vítor
Image Processing Expert
Interpreting the visual signals behind web workflows.
SOBRE EL AUTOR
Evita que los agentes de navegador paralelos mezclen los resultados de CAPTCHA. Asocia los ID de tarea con los propietarios de las páginas, rechaza las respuestas obsoletas y prueba el enrutamiento antes de aplicar una solución.
Elige una API de CAPTCHA o un MCP para tu agente de IA comparando el control de tareas, el descubrimiento de herramientas, el manejo de resultados y las responsabilidades del navegador antes de integrarlo.
