Resolución de captchas para
agentes de CrewAI
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 crewai import Agent
from crewai.tools import tool
@tool("Solve captcha")
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Call when a captcha blocks the task. Returns the token to submit."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
researcher = Agent(role="Researcher", goal="...", backstory="...", tools=[solve_captcha])Por 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 CrewAI
En CrewAI, el solucionador es una herramienta personalizada asignada al agente que navega. Los demás agentes del crew nunca necesitan saber nada de captchas.
- 01Crea una subclase de BaseTool
Define name, description y un args schema, y llama a la API en _run.
- 02Asígnala
Dale la herramienta solo al agente que se encarga de navegar.
- 03Describe el disparador
La descripción indica que se use cuando una página muestre un captcha.
- 04Devuelve el token
Devuelve la cadena del token o un error breve.
Cómo introducir el token en la página
La herramienta devuelve el token al agente que navega, que lo envía con sus propias herramientas.
Dónde suelen fallar las integraciones
Solo la necesita el agente que navega. Dársela a todos provoca llamadas innecesarias.
Los tokens son de un solo uso. Desactiva la caché de resultados de herramientas de CrewAI para el solucionador.
Preguntas frecuentes sobre captchas en CrewAI
¿CrewAI tiene una herramienta de captchas integrada?
No para resolverlos. Una herramienta personalizada de pocas líneas lo cubre y mantiene la clave bajo tu control.
¿Pueden varios agentes compartir una clave?
Sí, o crea una clave por crew en el panel para que el uso se reporte por separado.
¿Funciona con CrewAI Flows?
Sí. La herramienta la llama un agente, dondequiera que se ejecute ese agente.
¿Por qué desactivar la caché?
Un resultado en caché devolvería un token antiguo, que el sitio rechaza porque los tokens son de un solo uso y caducan en unos dos minutos.
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.