Herramientas Pydantic de IA CAPTCHA: Entradas digitadas y resultados del resolutor

TL;DR

• Pydantic AI puede exponer la resolución de CAPTCHA como una función de Python tipada, respaldada por el adaptador oficial de CapSolver.
• Mantén el wrapper pequeño: recibe los parámetros documentados, llama al ejecutor y devuelve su resultado estructurado sin inventar una respuesta exitosa.
• El ejemplo siguiente ejecuta un bucle de agente de Pydantic AI real con TestModel y llama al catálogo de tipos admitidos del adaptador instalado.
• La función de resolución está registrada, pero se excluye deliberadamente de esta ejecución de prueba; no ocurre ninguna solicitud de modelo-proveedor ni resolución pagada.
• La validación de tipos ayuda a describir las entradas de herramienta. Tu aplicación decide qué página y operación están aprobadas y si la tarea final del navegador tuvo éxito.

Una herramienta CAPTCHA de Pydantic AI le da al agente una operación definida para usar cuando una tarea de navegador aprobada alcanza un desafío admitido. El modelo no necesita inventar un algoritmo de resolución, y la aplicación no necesita un cliente de CAPTCHA nuevo para cada marco de agente.

El adaptador de agente de CapSolver proporciona la capa de ejecución. Pydantic AI proporciona la interfaz de herramienta de función. Esta guía muestra cómo se conectan estas piezas, usando un ejemplo derivado del repositorio de Pydantic AI mantenido por CapSolver y una prueba local que ejecuta la operación del catálogo del adaptador real.

¿Qué agrega la integración de Pydantic AI?

La integración de Pydantic AI convierte una función de Python tipada ordinaria en una herramienta disponible para un agente. La función recibe argumentos con nombre, delega la operación CAPTCHA y devuelve un resultado que el agente puede inspeccionar.

Para un formulario de QA propio, la secuencia útil es concreta: el navegador identifica un desafío admitido, la aplicación proporciona los parámetros de la página, la herramienta solucionadora devuelve su resultado y el navegador continúa la misma intento de formulario. La afirmación final pertenece al flujo de trabajo del formulario.

Una biblioteca de API empaqueta las llamadas al servicio subyacente. En este caso, la documentación de CapSolver agent-tools describe un ejecutor que envía operaciones con nombre a la implementación principal.

La documentación de funciones de herramientas de Pydantic AI explica cómo las firmas y anotaciones de funciones contribuyen a las definiciones de herramientas. Tres cadenas anotadas pueden describir la forma requerida de entrada, pero no establecen que una URL esté aprobada o que una clave de sitio pertenezca a la página actual.

¿Por qué usar el adaptador oficial en lugar de otro cliente HTTP?

Usa el adaptador oficial cuando quieras un pequeño marco de envoltura alrededor de la implementación documentada de resolución. Esto mantiene el wrapper enfocado en la interfaz del agente en lugar de duplicar la creación, recuperación y conversión de tareas.

CapSolver mantiene un repositorio de ejemplo de Pydantic AI que usa create_executor, Agent y @agent.tool_plain. Es una aplicación de ejemplo, no un paquete adicional nombrado después del repositorio.

El ejemplo de este artículo retiene la función de resolución de tres argumentos del repositorio y la llamada al ejecutor. Cambia el entorno de demostración para usar el TestModel de Pydantic AI y una llamada al catálogo de tipos admitidos. Esto permite probar la conexión de herramientas sin proporcionar una clave de modelo ni crear una tarea de resolución pagada.

Este enfoque difiere de adjuntar un servidor MCP. Las funciones llaman al adaptador instalado en la misma aplicación de Python; no hay un proceso de servidor MCP separado en este ejemplo. Elige la interfaz que se ajuste a tu agente existente en lugar de agregar ambas interfaces a la misma tarea pequeña sin razón.

Paso 1: Instalar los paquetes probados

Instala el framework y el adaptador en un entorno Python aislado. La ejecución registrada usó Python 3.12.14, pydantic-ai-slim 2.44.0, capsolver-agent 0.1.1 y capsolver-core 0.1.1.

El paquete slim proporciona la funcionalidad principal de Pydantic AI usada por TestModel sin instalar cada integración de modelo-proveedor. Las siguientes versiones coinciden con la ejecución local:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pydantic-ai-slim==2.44.0 capsolver-agent==0.1.1 capsolver-core==0.1.1

La guía de entorno virtual de Python describe la creación del entorno y la activación específica de la shell. Mantén las versiones de paquetes con tu proyecto para que la demostración pueda reproducirse antes de actualizar.

La demostración del catálogo local no necesita credenciales de resolución. Una llamada posterior solve_captcha en vivo requiere tu clave de API de CapSolver para resolver, y una conversación de modelo real necesita el paquete y la autenticación de tu proveedor elegido. Estos son requisitos previos separados.

No uses una credencial de publicación de blog como clave de resolución. La credencial del ejecutor pertenece fuera del prompt del modelo y del código comprometido.

Paso 2: Registrar las herramientas tipadas

Guarda lo siguiente como quickstart.py. La envoltura de resolución sigue el repositorio oficial; la herramienta de catálogo y la configuración de TestModel son la adaptación ejecutada localmente. El código registra la herramienta de resolución pero no la llama.

import asyncio
import json

from capsolver_agent import create_executor
from pydantic_ai import Agent, models
from pydantic_ai.models.test import TestModel

models.ALLOW_MODEL_REQUESTS = False
capsolver = create_executor()
agent = Agent(TestModel(call_tools=["get_supported_captchas"]))


@agent.tool_plain
async def get_supported_captchas() -> str:
    """Devuelve los tipos de CAPTCHA registrados sin resolver un desafío."""
    return json.dumps(await capsolver.execute("get_supported_captchas", {}))


@agent.tool_plain
async def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """Resolver un CAPTCHA admitido para un flujo de trabajo legal y autorizado por el usuario."""
    result = await capsolver.execute(
        "solve_captcha",
        {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key,
        },
    )
    return json.dumps(result, ensure_ascii=False)


async def main() -> None:
    result = await agent.run("Lista los tipos de CAPTCHA admitidos.")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

Ejecuta el archivo con el intérprete de Python del entorno:

python quickstart.py

El script establece ALLOW_MODEL_REQUESTS en falso para evitar llamadas accidentales a un modelo no de prueba. También restringe TestModel al catálogo de herramientas. Ambas decisiones importan: evitar solicitudes de modelo es diferente de evitar que una herramienta contacte un servicio externo.

La documentación de pruebas de Pydantic AI explica que TestModel puede llamar a herramientas registradas usando datos de entrada generados. Dejar una herramienta de resolución pagada en una ejecución de prueba sin restricciones sería una operación diferente de la verificación de catálogo controlada mostrada aquí.

Paso 3: Leer correctamente el resultado observado

La ejecución local devolvió un resultado exitoso del catálogo desde el adaptador de CapSolver instalado. Informó manejadores nombrados recaptcha y cloudflare, con valores de tipo reCaptchaV2, reCaptchaV3 y cloudflare.

La salida impresa de TestModel contenía la cadena JSON del catálogo dentro de un resumen de resultado de herramienta. Las comillas escapadas en ese resumen impreso son consecuencia de devolver JSON serializado desde la función; no son un token de CAPTCHA recién generado.

El wrapper oficial usa json.dumps para devolver el resultado del ejecutor como una cadena. Preserva la distinción entre esa cadena y el diccionario subyacente si otro componente lo consume. Analiza el valor JSON relevante deliberadamente en lugar de asumir que cada capa devuelve la misma estructura.

La prueba establece que el registro, la ejecución de herramienta sin argumentos, la distribución del adaptador y la devolución del resultado funcionan juntos en las versiones instaladas. No establece que un LLM seleccione la herramienta de resolución correcta o que un formulario protegido en particular acepte un token.

Canjear el código de bonificación de CapSolver

¡Aumenta tu presupuesto de automatización instantáneamente!
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en tu Panel de CapSolver

¿Cómo se mapean las entradas tipadas a una solicitud CAPTCHA?

Las entradas tipadas mapean la llamada de herramienta del agente al diccionario de argumentos aceptado por el adaptador. El mínimo envoltura de resolución acepta captcha_type, website_url y website_key.

Estos nombres pertenecen a la interfaz del adaptador. No son una solicitud REST literal que contenga clientKey y un objeto task. Consulta el esquema de herramienta instalado y la documentación de tarea reCAPTCHA v2 al conectar una página real.

La envoltura de tres campos es intencionalmente mínima. Algunas variantes requieren contexto adicional. No asumas que cada desafío listado por el servicio más amplio puede resolverse solo con estos tres caracteres, o que los nombres de tipo de envoltura pueden reemplazarse con nombres de tarea REST.

Una anotación de cadena no restringe la URL a un host aprobado. Enfuerza el destino y la operación permitidos en la aplicación que proporciona los argumentos de herramienta. El contenido de la página no debe poder autorizar un nuevo destino simplemente pidiéndole al modelo que use uno.

¿Cómo debe manejar el agente los resultados del solucionador?

El agente debe inspeccionar el resultado del ejecutor y mantener el resultado CAPTCHA separado del resultado de la tarea comercial. El adaptador de agente documentado devuelve un sobre de éxito que contiene una solución, o un sobre de fallo que describe el error.

En caso de fallo, la aplicación debe conservar la información de error relevante y decidir si son adecuados los inputs corregidos, un nuevo intento o una revisión por parte del operador. No conviertas un error en un marcador de posición que parezca un token solo para satisfacer un campo de cadena de bajo nivel.

En caso de éxito, pasa el resultado al componente de la aplicación responsable del mismo intento de desafío. La función de esta guía no controla un navegador, localiza un campo de respuesta, envía un formulario ni afirma la aceptación de la aplicación.

Para una prueba de formulario propio, un criterio de finalización adecuado podría ser el registro de confirmación esperado. Un éxito del solucionador y una rechazo de la aplicación deben permanecer como dos observaciones separadas. Esta separación hace distinguible una clave de página incorrecta de un fallo de validación de formulario no relacionado.

Evita colocar credenciales o tokens completos en trazas rutinarias. Si el agente necesita un resumen legible, retén el estado operativo y los campos diagnósticos seguros mientras mantienes el valor del resultado en el componente que realmente lo consume.

¿Cómo pasar de TestModel a un agente real?

Pasa a un agente real configurando el proveedor de modelo deseado, proporcionando su autenticación y habilitando solo las operaciones en vivo que necesita la aplicación. Mantén los wrappers de herramientas probados e inspecciona las llamadas reales de herramienta del nuevo modelo.

El TestModel de la demostración es infraestructura de prueba procedural, no un modelo de lenguaje. Su elección exitosa de catálogo no mide razonamiento de modelo. Una conversación real puede producir un parámetro faltante, seleccionar la herramienta equivocada o solicitar otra operación, por lo que la aplicación debe seguir verificando sus entradas.

Empieza con una página de QA propia y una variante de desafío documentada. Proporciona la URL real de la página y la clave pública del sitio desde la aplicación, luego valida el resultado del solucionador y la respuesta final del formulario. Registra los fallos por etapa en lugar de reducir todo el experimento a si el texto apareció en una respuesta del agente.

La guía de resolución de CAPTCHA empresarial discute la adopción por equipos. Este ejemplo de marco establece una base más estrecha: registro de función tipada y ejecución real del adaptador con una operación controlada, no de resolución.

Try CapSolver para el desafío admitido en tu tarea aprobada una vez que entiendas esa conexión local. Mantén explícito el alcance de cada prueba: registro de herramienta, selección de modelo, resolución pagada y aceptación del navegador son verificaciones diferentes.

Preguntas frecuentes

P: ¿Existe un paquete separado pydantic-ai-capsolver?

El repositorio referenciado contiene ejemplos que usan Pydantic AI y la biblioteca oficial de CapSolver. Esta guía instala esos bibliotecas directamente en lugar de asumir que el nombre del repositorio es un paquete.

P: ¿TestModel llama al servicio CAPTCHA real?

TestModel puede ejecutar herramientas registradas, por lo que la herramienta seleccionada determina lo que ocurre. Este ejemplo llama explícitamente solo al catálogo de tipos admitidos y no invoca una solicitud de resolución.

P: ¿Son suficientes las entradas de cadena tipadas para aprobar una página objetivo?

No. Las anotaciones de tipo describen la forma de entrada. La aplicación debe hacer cumplir la URL, tarea y contexto permitidos por separado.

P: ¿Por qué el resultado impreso contiene JSON escapado?

El wrapper devuelve JSON serializado, y TestModel incluye esa cadena en su resumen de salida. Trata cada capa de serialización deliberadamente en lugar de asumir que el resumen es un objeto solución sin procesar.

P: ¿Puede manejar esta envoltura exacta cada variante de CAPTCHA?

No se establece ninguna cobertura aquí. La función mínima acepta tres parámetros; variantes que requieran contexto adicional requieren los campos y validación documentados correspondientes.

P: ¿Se resolvió un CAPTCHA en vivo durante la prueba?

No. El marco e instalación del adaptador ejecutaron una operación de catálogo real usando TestModel. Una resolución en vivo y aceptación por una aplicación propia permanecen como pruebas separadas que requieren las credenciales y página adecuadas.