¿Agente de IA programado no se ejecuta? Diagnostícalo rápido

Un agente programado puede pararse en dos sitios: el scheduler que lo dispara, o el propio agente. Recorre estos puntos en orden.

1. ¿Llegó a dispararse el trigger?

Antes de depurar el agente, confirma que algo lo arrancó de verdad. Mira primero el log de la capa del scheduler:

grep run_agent /var/log/syslog          # cron clásico
kubectl get jobs --sort-by=.metadata.creationTimestamp   # CronJob de Kubernetes

Cada disparador tiene sus propios modos de fallo — consulta cron de Docker no se ejecuta, CronJob de Kubernetes no se ejecuta o schedule de GitHub Actions no se ejecuta. Si nada arrancó el proceso, detente aquí: el problema es el disparador, no el agente.

2. Rate limits, límites de gasto y claves API muertas

La causa específica de agentes más común. Una tormenta de 429, un presupuesto mensual agotado o una clave API que alguien rotó cortan la ejecución antes de que produzca nada:

python run_agent.py 2>&1 | grep -iE "429|rate.?limit|quota|401|invalid.*key"

Revisa el panel de consumo del proveedor y registra el error crudo de la API — un bucle de agente que captura la excepción y la parafrasea («No pude completar la tarea») destruye exactamente la información que necesitas ahora.

3. La ejecución se cuelga en una llamada API atascada

Muchos SDK vienen sin timeout de petición. Una sola conexión congelada y la ejecución no termina nunca — y según tu configuración de cron, las siguientes se apilan detrás. Acota tanto la llamada como la ejecución completa:

# crontab: plazo duro para toda la ejecución, sin instancias solapadas
0 2 * * * flock -n /tmp/agent.lock timeout 30m python run_agent.py

Y fija el timeout a nivel de SDK explícitamente (timeout=60 o equivalente) para que una sola generación lenta no se coma todo el plazo.

4. El modelo o la API cambiaron debajo de ti

Los proveedores deprecan IDs de modelos y remodelan respuestas a su propio ritmo. Tu job se rompe sin ningún despliegue por tu parte. Síntomas: 400/404 repentinos sobre el nombre del modelo, o errores de parsing en una respuesta que antes funcionaba.

Fija lo que puedas — una versión de modelo explícita y con fecha, y una versión de SDK bloqueada — para que las subidas de versión ocurran cuando tú lo decidas, no cuando lo decida el proveedor:

# requirements.txt — fija el SDK, no flotes en «latest»
openai==1.54.3

5. El agente «tuvo éxito» pero no produjo nada

Un código de salida 0 significa que el proceso terminó, no que hubo trabajo. Los bucles de agentes se tragan errores de herramientas por diseño: la herramienta de búsqueda falló, el modelo se disculpó, el bucle terminó «con éxito» sin escribir nada. Valida el artefacto, no el código de salida:

python run_agent.py --task nightly-digest
test -s out/digest.md || { echo "resumen vacío" >&2; exit 1; }

El problema de fondo: para un agente sin supervisión, el silencio parece éxito

Todas las causas anteriores terminan igual — sin salida, y sin nada que te lo diga. El disparador no avisará de un horario muerto, el proveedor no avisará de tu límite de gasto, y el agente no avisará de su propia ejecución vacía.

Haz que la ejecución haga ping a un heartbeat solo después de validar su salida. Si deja de llegar un resultado válido — por cualquiera de las razones anteriores — el ping se pierde y recibes una alerta, independientemente de qué capa se rompió:

curl -fsS https://ping.steadycron.com/<tu-ping-token>/start
python run_agent.py --task nightly-digest && test -s out/digest.md \
  && curl -fsS https://ping.steadycron.com/<tu-ping-token> \
  || curl -fsS https://ping.steadycron.com/<tu-ping-token>/fail

Consulta Cron jobs para agentes de IA para el patrón completo — incluida la opción de mover el propio disparador a un job HTTP, para que horario, reintentos y alertas vivan fuera de la máquina que ejecuta el agente.