Ciclo de vida de la sesión de Hermes Agent y tareas programadas

Política de reinicio de sesión

La política de reinicio controla cuándo la sesión "pierde la memoria" automáticamente: se obtiene un nuevo session_id y el contexto anterior se archiva.

Configurar adecuadamente la política de reinicio puede evitar que el contexto del Agente crezca indefinidamente, asegurando al mismo tiempo que la experiencia del usuario no se vea afectada.

Cuatro modos de reinicio

ModoComportamientoCaso de uso adecuado
noneNunca reiniciar automáticamente; el contexto solo se gestiona mediante el mecanismo de compresiónEscenarios que requieren un contexto continuo a largo plazo
idleReinicio automático tras más de N minutos de inactividadAgentes de uso ocasional
dailyReinicio automático a una hora específica cada díaAgentes de uso diario rutinario
bothTiempo de inactividad o reinicio diario, lo que se active primero se ejecutaLa mayoría de los escenarios (recomendado por defecto)

Configurar la política de reinicio

Ejemplo

# config.yaml - política de reinicio global
session_reset
:
  mode
: both              # none | idle | daily | both
  at_hour
: 4              # Hora de reinicio diario (4 a. m., hora local)
  idle_minutes
: 1440      # Tiempo de espera de inactividad (1440 minutos = 24 horas)
  notify
: true            # Notificar al usuario al reiniciar

# Política de reinicio personalizada por plataforma
platforms
:
  telegram
:
    session_reset
:
      mode
: idle
      idle_minutes
: 720   # Las sesiones de Telegram se reinician tras 12 horas de inactividad
  slack
:
    session_reset
:
      mode
: none          # Las sesiones de Slack nunca se reinician automáticamente

Efecto del reinicio

Cuando se activa un reinicio de sesión, ocurre lo siguiente:

  • La sesión anterior se marca como finalizada en SQLite (reason: "session_reset")
  • Se genera un nuevo session_id (formato: YYYYMMDD_HHMMSS_8 caracteres hexadecimales aleatorios)
  • El nuevo SessionEntry tiene was_auto_reset marcado como true
  • La instancia del Agente en caché se limpia
  • En el siguiente mensaje, el usuario recibe un aviso de "sesión reiniciada"

Las sesiones con procesos en segundo plano activos nunca se reinician. Hermes verifica la devolución de llamada has_active_processes para garantizar que no se interrumpan las tareas en ejecución.


Mecanismo de recuperación tras reinicio

El mecanismo de recuperación tras reinicio de Hermes Gateway garantiza que las sesiones en curso no se pierdan después de un bloqueo inesperado o un reinicio planificado.

Dos marcadores de recuperación

MarcadorEscenario de activaciónComportamientoGravedad
resume_pendingRecuperación tras bloqueo, tiempo de espera de drenajeConserva el session_id, la conversación continúa en el próximo accesoRecuperación suave
suspendedComando /stop, 3 fallos consecutivos de reinicioForzar reinicio y generar un nuevo session_idReinicio duro

Proceso de recuperación al inicio

Cuando Gateway se inicia, el proceso de recuperación es el siguiente:

Primer paso: verificar el marcador .clean_shutdown.

Si existe, significa que el apagado anterior fue normal y se omite el proceso de recuperación.

Segundo paso: si el marcador .clean_shutdown no existe, significa que la salida anterior fue anormal.

Gateway llama a suspend_recently_active(), marcando como resume_pending las sesiones que han tenido actividad en los últimos 120 segundos.

Tercer paso: detectar bucle atascado (stuck-loop).

Si una sesión sigue activa después de 3 reinicios consecutivos, es posible que haya caído en un bucle infinito; Gateway la marca como suspended.

Cuarto paso: recuperar sesiones pendientes.

Gateway sintetiza un MessageEvent para cada sesión con resume_pending, lo que hace que el Agente continúe automáticamente.

Marcador de tiempo de espera de drenaje

Durante un apagado/reinicio normal, si una sesión está en proceso pero supera el tiempo de espera de drenaje, Gateway la marca como resume_pending.

Motivos del marcado en diferentes escenarios:

Motivo del marcadoSignificado
restart_timeoutTiempo de espera de drenaje durante el reinicio
shutdown_timeoutTiempo de espera de drenaje durante el apagado
restart_interruptedRecuperación tras bloqueo (activada desde suspend_recently_active)

El marcador resume_pending no se elimina al llamar a get_or_create_session(); se elimina tras la siguiente respuesta exitosa del Agente. Si la sesión recuperada se interrumpe de nuevo, el marcador se conserva, lo que permite reintentarlo en el próximo reinicio. Después de 3 fallos consecutivos, se actualiza a suspended.


Mecanismo de cola de mensajes

Cuando el usuario envía varios mensajes consecutivos mientras el Agente procesa un mensaje, el mecanismo de cola de mensajes de Gateway garantiza que no se pierdan mensajes.

Estructura de la cola

Gateway utiliza un diseño de cola de dos niveles:

  • Ranura única pendiente (_pending_messages): cada sesión tiene solo una ranura de "siguiente mensaje"; los envíos repetidos sobrescriben
  • Cola de desbordamiento (_queued_events): cuando la ranura está ocupada, los mensajes posteriores se añaden al final de la cola de desbordamiento

Comando /queue

El comando /queue te permite enviar tareas por lotes; cada tarea genera un turno completo del Agente.

Ejemplo

# Enviar en Telegram/Discord
/queue revisar src/el estilo de código de main.py
/queue escribir pruebas unitarias para src/utils.py
/queue actualizar las instrucciones de instalación en README.md

Cada tarea en la cola se ejecuta secuencialmente en orden FIFO, y cada tarea produce un turno completo del Agente, sin fusionarse.

Usa el comando /new o /reset para vaciar la cola de mensajes de la sesión actual.

Si se envían varios mensajes consecutivos mientras el Agente procesa un mensaje, los intermedios se sobrescriben (solo se conserva el último); los mensajes del comando /queue no se sobrescriben: cada tarea de /queue se ejecuta en orden.


Tareas programadas (Cron)

Hermes incluye soporte de primera clase para tareas programadas, lo que te permite configurar que el Agente ejecute tareas específicas periódicamente.

Las tareas programadas pueden vincularse a una Skill y enviar el resultado a la plataforma designada.

Configurar tareas programadas

Las tareas programadas se definen en jobs.json y admiten múltiples formatos de programación.

{
  "jobs": [
    {
      "id": "daily-news-summary",
      "schedule": "0 8 * * *",
      "description": "每天早上 8 点抓取 AI 行业新闻并生成摘要",
      "skill": "ai-news-summarizer",
      "deliver_to": {
        "platform": "telegram",
        "chat_id": "-1001234567890"
      }
    },
    {
      "id": "weekly-code-review",
      "schedule": "0 10 * * 1",
      "description": "每周一早上 10 点审查项目代码变更",
      "skill": "code-review-assistant",
      "deliver_to": {
        "platform": "discord",
        "chat_id": "123456789"
      }
    },
    {
      "id": "health-check",
      "schedule": "*/30 * * * *",
      "description": "每 30 分钟检查服务器健康状态",
      "skill": "server-health-checker",
      "deliver_to": {
        "platform": "telegram",
        "chat_id": "123456789"
      }
    }
  ]
}

Formatos de programación admitidos

FormatoEjemploDescripción
Expresión Cron0 8 * * *Expresión cron estándar de 5 campos
Intervalo30mCada 30 minutos
Tiempo relativo+90sEjecutar una vez después de 90 segundos
Número de repeticionesrepeat.times: 5Se detiene automáticamente después de ejecutarse 5 veces

Se puede configurar en la versión de escritorio; haz clic en Programación en la esquina inferior izquierda:

Haz clic en Nueva tarea programada:

Crear tarea:

Cuando una tarea programada está vinculada a una Skill, la salida de la ejecución se formatea automáticamente según el formato de salida definido por la Skill. Esto garantiza que el resultado de la tarea programada se presente de manera consistente y legible al enviarse a la plataforma de mensajería.


Cron gestionado por Chronos (avanzado)

Chronos es la solución de tareas programadas administrada de Hermes, diseñada específicamente para el modo de implementación scale-to-zero.

Cuando tu Gateway se detiene por completo en periodos de inactividad, Chronos aún puede garantizar que las tareas programadas se activen puntualmente.

¿Por qué se necesita Chronos?

El cron ticker integrado requiere que el proceso del Gateway se ejecute continuamente: si el Gateway se reduce a cero, las tareas programadas no se activarán.

Chronos delega la gestión de las tareas programadas en NAS (Nous Account Service), que despierta al Gateway mediante un programador externo cuando se dispara la tarea.

Flujo de trabajo de Chronos

El flujo de trabajo de Chronos consta de cuatro pasos:

Paso 1: El Agent calcula el próximo tiempo de activación y registra un temporizador one-shot en NAS.

Paso 2: NAS usa un programador externo (como el disparo programado de Fly Machines) para activar el callback en el momento especificado.

Paso 3: El programador externo llama de vuelta a NAS, y NAS genera un JWT Token de corta duración.

Paso 4: NAS usa el JWT Token para invocar el endpoint /api/cron/fire del Agent; tras la verificación, el Agent ejecuta la tarea y vuelve a registrar el siguiente one-shot.

Garantía de como máximo una vez

Chronos garantiza que cada tarea programada se ejecute solo una vez mediante operaciones CAS (Compare-And-Set) a nivel de store.

Incluso si el programador envía solicitudes de activación duplicadas debido a reintentos de red, el Agent puede deduplicarlas mediante CAS, asegurando que las tareas no se ejecuten repetidamente.

Configurar Chronos

Ejemplo

# config.yaml - Configuración de Cron administrado por Chronos
cron
:
  provider
: "chronos"                         # Usar Chronos en lugar del ticker integrado
  chronos
:
    portal_url
: "https://portal.nousresearch.com"
    callback_url
: "https://my-agent.fly.dev"  # URL accesible públicamente del Agent
    expected_audience
: "agent:inst_abc123"    # Audience para la verificación JWT
    nas_jwks_url
: "https://portal.nousresearch.com/.well-known/jwks.json"

Chronos es la solución de tareas programadas recomendada para implementaciones de Hermes administradas. Si usas una implementación autohospedada y el Gateway no se reduce a cero, el cron ticker integrado es suficiente. Si callback_url está vacío o el Agent no tiene inicio de sesión de Nous, el sistema volverá automáticamente al ticker integrado.

Otras extensiones