Resolución de captchas para
agentes de OpenAI Agents SDK
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 agents import Agent, function_tool
@function_tool
def solve_captcha(kind: str, sitekey: str, url: str) -> str:
"""Return a token for a captcha blocking the current page."""
return solve({"type": kind, "sitekey": sitekey, "url": url})["token"]
agent = Agent(name="browser", 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 OpenAI Agents SDK
El OpenAI Agents SDK convierte una función de Python tipada en una herramienta con function_tool. El solucionador pasa a ser una de las herramientas del agente.
- 01Decora una función
Envuelve la llamada a la API con @function_tool y argumentos tipados.
- 02Añádela al agente
Pásala en la lista de herramientas del agente.
- 03Da instrucciones al agente
Indícale que llame a la herramienta, con la sitekey y la URL, cuando una página muestre un captcha.
- 04Trázala
El tracing del SDK muestra cada llamada a herramienta y su resultado, incluido el costo que devolvemos.
Cómo introducir el token en la página
El agente recibe el token y se lo pasa a su herramienta de navegador o HTTP.
Dónde suelen fallar las integraciones
Tipa todos los argumentos para que el esquema generado sea preciso y el modelo lo rellene correctamente.
Configura el timeout HTTP por encima del valor de wait para que la herramienta no falle mientras la resolución sigue en curso.
Preguntas frecuentes sobre captchas en OpenAI Agents SDK
¿Funciona con modelos que no sean de OpenAI?
El SDK admite otros proveedores a través de su interfaz de modelos, y la herramienta en sí es HTTP sin más, así que sí.
¿Puedo usarla con handoffs?
Sí. Dale la herramienta al agente que controla el navegador; los demás pueden hacerle handoff.
¿Dónde debe guardarse la clave de API?
En una variable de entorno leída dentro de la función de la herramienta, nunca en las instrucciones del agente.
¿Cómo limito el gasto?
Lleva la cuenta del campo cost de cada resultado en el contexto de ejecución y rechaza más resoluciones al superar un presupuesto.
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.