Last updated on

Ajusté cada línea del config.yaml de Hermes — 3 configuraciones que evitan que las tareas largas se queden atascadas

Lo más frustrante de usar Hermes Agent en tareas complejas no es obtener una respuesta incorrecta, sino ver cómo el trabajo se congela a mitad de camino: las llamadas a la API se cuelgan, la longitud del contexto explota tras muchos turnos, o una herramienta fallida se queda atrapada en un bucle de reintento interminable. La mayoría de las veces, estos no son problemas del modelo. Son valores predeterminados en ~/.hermes/config.yaml que no se han ajustado para trabajos de larga duración.

Después de ejecutar cientos de tareas largas, revisé mi configuración línea por línea y descubrí que solo tres ajustes deciden realmente si una tarea larga termina sin problemas. Configúralos según tu carga de trabajo y la mayoría de los trabajos complejos se completarán sin intervención manual.

A continuación, cada sección sigue el patrón: síntoma → causa → solución → valores recomendados, con fragmentos de YAML listos para copiar y pegar.

Configuración 1: Pon un límite estricto a las llamadas a la API — Tiempos de espera de proveedores

Síntomas

  • La tarea llega al 50%, la terminal se queda en silencio y, tras treinta segundos, aparece “Connection timed out.”
  • Un trabajo en segundo plano o cron muestra running, pero el registro no avanza desde hace minutos.
  • Después de cambiar a otro proveedor de OpenRouter, las respuestas se vuelven erráticas y, en ocasiones, se cuelgan por completo.

Causa

Las llamadas a la API de Hermes recurren por defecto a dos variables de entorno: HERMES_API_TIMEOUT (1800 s) y HERMES_API_CALL_STALE_TIMEOUT (90 s). Sin embargo, las claves request_timeout_seconds y stale_timeout_seconds bajo el bloque providers en config.yaml tienen prioridad; las variables de entorno solo se usan cuando no hay configuración establecida.

Sin ajuste por proveedor:

  • Los modelos en la nube con razonamiento prolongado (Claude Opus, o1, deep-research) pueden ser interrumpidos antes de terminar.
  • Los endpoints locales (LM Studio, Ollama, vLLM) pueden tardar decenas de segundos en iniciarse en frío, pero los tiempos de espera de solicitud predeterminados son mucho más cortos.
  • Un único proveedor inestable puede bloquear toda la ejecución porque no hay un tiempo de espera explícito.

Solución

Agrega un bloque providers al principio de config.yaml y ajústalo por proveedor:

providers:
  anthropic:
    request_timeout_seconds: 600      # tolera 10 min de razonamiento lento
    stale_timeout_seconds: 300      # solo llamadas no streaming
  openrouter:
    request_timeout_seconds: 300
    stale_timeout_seconds: 120
  lmstudio:
    request_timeout_seconds: 300      # el inicio en frío local es lento
    stale_timeout_seconds: 900        # reactiva explícitamente la detección de inactividad
  ollama-local:
    request_timeout_seconds: 300
    stale_timeout_seconds: 900

Si usas principalmente un solo proveedor, configurar solo ese proveedor es suficiente. request_timeout_seconds se pasa directamente al SDK como timeout=, anulando la variable de entorno heredada.

Valores recomendados

Escenario request_timeout_seconds stale_timeout_seconds
Modelos rápidos en la nube (Claude 3.5 Sonnet, GPT-4o mini) 60–120 60–90
Modelos de razonamiento prolongado (Claude Opus, o1, deep-research) 300–600 120–300
Modelos locales (LM Studio / Ollama / vLLM) 180–300 600–900
Trabajos en segundo plano / cron 300–600 120–300

Nota: stale_timeout_seconds solo aplica a llamadas no streaming. Las llamadas streaming se consideran activas mientras sigan llegando tokens.

Configuración 2: No dejes que el contexto explote primero — Estrategia de compresión

Síntomas

  • Después de muchos turnos de herramientas, el modelo comienza a responder fuera de tema o arroja “context length exceeded.”
  • La compresión se activa demasiado tarde, al 80% de la ventana, y ya comprime resultados intermedios importantes.
  • Después de la compresión, el agente “olvida” cosas que acabas de confirmar: claves de API, rutas de archivos, restricciones.

Causa

El bloque compression de Hermes se activa cuando el uso de tokens alcanza threshold × context_length. Los valores predeterminados pueden no ajustarse a tu carga de trabajo:

  • threshold: 0.50 es agresivo para un contexto de 200K, pero demasiado tarde para uno de 32K.
  • protect_last_n: 20 conserva solo los últimos 20 mensajes, lo que puede cubrir solo 2–3 turnos críticos en una tarea larga.
  • target_ratio: 0.20 decide cuánto de la cola reciente se conserva; demasiado pequeño pierde detalle, demasiado grande desperdicia espacio.

También hay una regla oculta en el código: para modelos con ventanas de contexto menores a 512K, el umbral se fija en 0.75. Por lo tanto, los modelos con ventana pequeña no se activan al 50%, sino al 75%. Saber esto ayuda a estimar el punto real de compresión.

Solución

compression:
  enabled: true
  threshold: 0.65           # activa antes que el valor predeterminado
  target_ratio: 0.25        # conserva el 25% de la cola reciente
  protect_last_n: 30        # ~15 turnos completos
  protect_first_n: 1        # solo system prompt + primer mensaje del usuario
  codex_app_server_auto: native

Si tu tarea necesita contexto temprano con frecuencia (por ejemplo, “usa siempre Python 3.11”, “este proyecto usa pnpm”), sube protect_first_n a 3. De lo contrario, manténlo en 1 para ahorrar espacio.

Valores recomendados

Contexto del modelo threshold target_ratio protect_last_n
≤ 32K (Claude 3.5 Sonnet, GPT-4o) 0.75 (valor mínimo predeterminado) 0.25 30–40
128K–200K 0.60–0.65 0.20–0.25 20–30
≥ 1M (Gemini, Kimi k1.5) 0.50–0.55 0.15–0.20 20

Consejo: El resumidor de compresión usa Gemini Flash por defecto, que es rápido y económico. Para tareas con mucho código, puedes fijar un modelo diferente bajo auxiliary.compression, pero el valor predeterminado suele ser suficiente.

Configuración 3: Cierra el bucle de herramientas — agent.max_turns

Síntomas

  • Una tarea simple invoca 50 turnos de herramientas y el agente sigue diciendo “déjame verificarlo de nuevo.”
  • Un pequeño fallo de red hace que una herramienta falle repetidamente, enviando al agente a un espiral de reintentos y haciendo que tu factura suba.
  • Un trabajo en segundo plano se ejecuta durante media hora y resulta estar atrapado en un bucle.

Causa

agent.max_turns limita cuántas iteraciones de llamadas a herramientas puede realizar el agente en una solicitud del usuario. El valor predeterminado de 60 es suficiente para preguntas casuales, pero se agota rápidamente en depuración compleja, procesamiento por lotes o confirmaciones iterativas. Sin un límite, una herramienta que falla puede reintentar indefinidamente.

Combinar max_turns con tool_loop_guardrails.hard_stop_enabled crea un interruptor automático para bucles anormales.

Solución

agent:
  max_turns: 100              # espacio para tareas complejas
  api_max_retries: 2          # falla rápido y deja que el respaldo tome el control
  reasoning_effort: medium

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true     # interruptor automático para bucles anormales
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5

Valores recomendados

Tipo de tarea max_turns hard_stop_enabled
Preguntas casuales / consultas de un solo paso 30–40 false
Depuración de código / complejidad media 60–80 true
Procesamiento por lotes / trabajos largos en segundo plano 100–150 true
Investigación exploratoria / refactorización multiarchivo 100–200 true

Nota: max_turns es el límite de iteraciones de herramientas por solicitud, no el límite de mensajes de toda la sesión. Puedes restablecer el contexto en cualquier momento con /new u otros comandos de gestión de sesiones de nuestro panorama de comandos de Hermes v0.18.

Referencia completa: Fragmento de config.yaml listo para usar

Aquí tienes un fragmento consolidado para la configuración común de OpenRouter como proveedor principal + modelos locales ocasionales + tareas largas frecuentes:

model:
  default: "anthropic/claude-opus-4.6"
  provider: "auto"
  base_url: "https://openrouter.ai/api/v1"

providers:
  anthropic:
    request_timeout_seconds: 600
    stale_timeout_seconds: 300
  openrouter:
    request_timeout_seconds: 300
    stale_timeout_seconds: 120
  lmstudio:
    request_timeout_seconds: 300
    stale_timeout_seconds: 900

compression:
  enabled: true
  threshold: 0.65
  target_ratio: 0.25
  protect_last_n: 30
  protect_first_n: 1
  codex_app_server_auto: native
  codex_gpt55_autoraise: true

agent:
  max_turns: 100
  api_max_retries: 2
  reasoning_effort: medium

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5

Guárdalo en ~/.hermes/config.yaml. Las nuevas sesiones lo detectan inmediatamente; las sesiones en ejecución necesitan /new para recargarlo.

Verificación: ¿Realmente ayudó?

Tres comprobaciones rápidas:

  1. Dispara un razonamiento prolongado deliberadamente. Pídele al agente que procese un archivo de registro de 500 líneas o lea diez archivos fuente a la vez. Ya no deberías ver context length exceeded.
  2. Simula inestabilidad en la API. Bloquea brevemente la IP del proveedor con timeout o iptables y confirma que el agente falla dentro del tiempo de espera configurado e intenta el respaldo, en lugar de quedarse colgado para siempre.
  3. Inspecciona la compresión. Durante una tarea larga, ejecuta /compress o espera la compresión automática, y luego verifica que los últimos ~30 mensajes y el system prompt sigan presentes.

Para modos de falla más complejos, consulta nuestra inmersión profunda en manejo de errores y recuperación de Hermes, que combina tiempos de espera, respaldos y reintentos en una sola estrategia de resiliencia.

Resumen

Las tareas largas suelen quedarse atascadas no porque el modelo se haya vuelto menos capaz, sino porque los tiempos de espera de la API, la compresión de contexto y los límites del bucle de herramientas no están alineados. Tras ajustar estas tres configuraciones:

  • Las llamadas a la API agotan el tiempo de forma limpia y recurren a otro proveedor en lugar de quedarse colgadas.
  • El contexto se comprime en el momento adecuado, preservando los detalles recientes sin alcanzar el límite de la ventana.
  • Las llamadas a herramientas tienen un techo rígido, evitando espirales de reintento y facturas descontroladas.

Si estás empezando, lee primero la guía de instalación para asegurarte de que tu entorno esté sólido, y luego guarda este fragmento como una “plantilla para tareas largas” que copiar para trabajos exigentes.

Referencias: este artículo se basa en el cli-config.yaml.example oficial de Hermes Agent y en la documentación oficial.