Resolución de captchas para
agentes de LangChain
Un agente que se encuentra con un desafío no tiene nada en su conjunto de herramientas que pueda responderlo, así que se atasca o alucina para sortearlo. Dale un solucionador como herramienta y el bloqueo se convierte en una llamada más.
import time
import requests
CAPTCHANO_KEY = "cn-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {CAPTCHANO_KEY}"}
def solve(task: dict) -> dict:
"""Block until solved; returns e.g. {"token": "...", "userAgent": "..."}."""
r = requests.post(
"https://api.captchano.com/v1/solve",
params={"wait": 60},
json=task,
headers=HEADERS,
timeout=75,
)
data = r.json()
# A solve can outlast the 60 s wait: poll the task until it finishes.
while data.get("status") in ("queued", "solving"):
time.sleep(5)
data = requests.get(
f"https://api.captchano.com/v1/task/{data['id']}",
headers=HEADERS,
timeout=30,
).json()
if data.get("status") != "ready":
raise RuntimeError(data.get("error") or data)
return data["solution"]
from langchain_core.tools import tool
@tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Call when a captcha blocks the task. kind is recaptcha_v2, recaptcha_v3
or turnstile. Returns the token to submit with the form."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
# add solve_captcha to your agent's tools listPor qué los agentes necesitan esto en concreto
Un scraper que se encuentra con un desafío falla de forma visible y lo arreglas. Un agente falla en silencio: razona sobre la página bloqueada, inventa un siguiente paso verosímil e informa de un progreso que nunca hizo. El fallo es peor porque es silencioso. Una herramienta de resolución tipada convierte un callejón sin salida ambiguo en un resultado determinista sobre el que el agente puede ramificar.
Qué devuelve la herramienta
- Un token o una cookie, según el tipo de desafío. Los sistemas que evalúan la sesión devuelven una cookie junto con el conjunto de encabezados usado para obtenerla.
- El user agent usado, para que el agente pueda reutilizarlo al enviar.
- El costo de la resolución, para que un agente que opera con un presupuesto pueda tenerlo en cuenta en lugar de gastar a ciegas.
Mantener el bucle acotado
Dale al agente un presupuesto de resoluciones por ejecución. Cada respuesta indica su costo, así que un supervisor puede cortar el bucle cuando el gasto supera un umbral en lugar de descubrirlo en la factura. A $0.00598 por resolución, una ejecución típica de un agente cuesta unos pocos centavos o menos, pero un bucle de reintentos sin límite sigue siendo un bucle de reintentos sin límite.
Mantén la llamada a la herramienta bloqueante
Los ejemplos llaman a ?wait=60, así que la herramienta devuelve un token terminado en un solo paso. Eso importa más en los agentes que en los scripts: una herramienta que devuelve "todavía resolviendo" obliga al modelo a razonar sobre el sondeo, algo que hace mal. Si necesitas un límite mayor, sube wait hasta 120 segundos. Las estructuras de solicitud de cada tipo de desafío están en la referencia de la API.
Cómo encaja la resolución en LangChain
En LangChain, el solucionador es una herramienta con un esquema tipado. El agente la llama cuando su herramienta de navegador informa de un desafío.
- 01Define la herramienta
Envuelve la llamada a la API con el decorador @tool y un docstring claro.
- 02Vincúlala al agente
Añádela a la lista de herramientas junto a tus herramientas de navegador.
- 03Describe cuándo usarla
El docstring le indica al modelo que la llame solo cuando haya un captcha.
- 04Devuelve un resultado claro
Devuelve el token o un error breve con el que el modelo pueda actuar.
Cómo introducir el token en la página
La herramienta devuelve el token como una cadena que el agente pasa a su herramienta de navegador o HTTP.
Dónde suelen fallar las integraciones
El modelo decide cuándo llamar a una herramienta a partir de su descripción. Indica exactamente qué entradas necesita y qué devuelve.
Limita las resoluciones por ejecución para que un agente confundido no entre en bucle en una página que lo sigue desafiando.
Preguntas frecuentes sobre captchas en LangChain
¿Funciona con LangGraph?
Sí. Una herramienta de LangChain también es una función invocable desde un nodo en LangGraph, así que la misma definición funciona en ambos.
¿Qué modelo funciona mejor con la herramienta?
Cualquier modelo que admita llamadas a herramientas. Las entradas de la herramienta son cadenas simples, así que los modelos más pequeños la manejan sin problema.
¿Cómo sabe el agente que hay un captcha?
Su herramienta de navegador o de scraping debería informarlo, por ejemplo devolviendo la sitekey cuando la encuentre. Haz que eso forme parte de la salida de la herramienta.
¿Puedo usarla en un agente asíncrono?
Sí. Usa un cliente HTTP asíncrono dentro de la herramienta y defínela con async def.
Guías útiles
¿Listo para construir?
Empieza con una prueba gratuita de 3 días y luego paga por cada resolución exitosa a medida que crece tu tráfico. No necesitas tarjeta para la prueba.