Last updated on

Ajustei Cada Linha do config.yaml do Hermes — 3 Configurações Que Impedem Tarefas Longas de Travar

A coisa mais frustrante ao usar o Hermes Agent em tarefas complexas não é receber uma resposta errada — é ver a tarefa travar no meio do caminho: chamadas de API paradas, limite de contexto explodindo após várias rodadas, ou uma ferramenta falhando presa em um loop de retry infinito. Na maioria das vezes, esses não são problemas do modelo. São valores padrão no ~/.hermes/config.yaml que não foram ajustados para execuções longas.

Depois de rodar centenas de tarefas longas, revisei minha configuração linha por linha e descobri que apenas três configurações realmente decidem se uma tarefa longa termina bem. Configure-as de acordo com sua carga de trabalho e a maioria dos trabalhos complexos terminará sem intervenção manual.

Abaixo, cada seção segue o padrão: sintoma → causa → solução → valores recomendados, com trechos de YAML prontos para copiar e colar.

Configuração 1: Coloque uma Coleira Curta nas Chamadas de API — Timeouts de Provider

Sintomas

  • A tarefa chega a 50%, o terminal fica em silêncio e, depois de trinta segundos, você vê “Connection timed out.”
  • Um job em background ou cron mostra running, mas o log não avança há minutos.
  • Após mudar para outro provider da OpenRouter, as respostas ficam irregulares e ocasionalmente travam.

Causa

As chamadas de API do Hermes recaem por padrão sobre duas variáveis de ambiente: HERMES_API_TIMEOUT (1800 s) e HERMES_API_CALL_STALE_TIMEOUT (90 s). No entanto, as chaves request_timeout_seconds e stale_timeout_seconds sob o bloco providers no config.yaml têm prioridade; as variáveis de ambiente só são usadas quando nenhuma configuração está definida.

Sem ajuste por provider:

  • Modelos de nuvem com longo raciocínio (Claude Opus, o1, deep-research) podem ser mortos antes de terminar.
  • Endpoints locais (LM Studio, Ollama, vLLM) podem levar dezenas de segundos para iniciar, mas os timeouts de request padrão são muito menores.
  • Um único provider instável pode travar toda a execução porque não há timeout explícito.

Solução

Adicione um bloco providers no topo do config.yaml e ajuste por provider:

providers:
  anthropic:
    request_timeout_seconds: 600      # tolera 10 min para raciocínio lento
    stale_timeout_seconds: 300      # apenas chamadas não-streaming
  openrouter:
    request_timeout_seconds: 300
    stale_timeout_seconds: 120
  lmstudio:
    request_timeout_seconds: 300      # cold-start local é lento
    stale_timeout_seconds: 900        # reativa explicitamente a detecção de stale
  ollama-local:
    request_timeout_seconds: 300
    stale_timeout_seconds: 900

Se você usa principalmente um provider, configurar apenas aquele provider é suficiente. request_timeout_seconds é passado diretamente ao SDK como timeout=, substituindo a variável de ambiente legada.

Valores recomendados

Cenário request_timeout_seconds stale_timeout_seconds
Modelos de nuvem rápidos (Claude 3.5 Sonnet, GPT-4o mini) 60–120 60–90
Modelos de raciocínio longo (Claude Opus, o1, deep-research) 300–600 120–300
Modelos locais (LM Studio / Ollama / vLLM) 180–300 600–900
Jobs em background / cron 300–600 120–300

Nota: stale_timeout_seconds só se aplica a chamadas não-streaming. Chamadas em streaming são consideradas ativas enquanto tokens continuam chegando.

Configuração 2: Não Deixe o Contexto Explodir Primeiro — Estratégia de Compressão

Sintomas

  • Depois de muitas rodadas de ferramentas, o modelo começa a responder fora do tema ou lança “context length exceeded.”
  • A compressão dispara tarde demais, em 80% da janela, e já comprime resultados intermediários importantes.
  • Após a compressão, o agente “esquece” coisas que você acabou de confirmar: chaves de API, caminhos de arquivo, restrições.

Causa

O bloco compression do Hermes dispara quando o uso de tokens atinge threshold × context_length. Os padrões podem não se adequar à sua carga de trabalho:

  • threshold: 0.50 é agressivo para 200K de contexto, mas tarde demais para 32K.
  • protect_last_n: 20 mantém apenas as últimas 20 mensagens, o que em uma tarefa longa pode cobrir apenas 2–3 turnos críticos.
  • target_ratio: 0.20 decide quanto do final recente manter; muito pequeno perde detalhes, muito grande desperdiça espaço.

Há também uma regra oculta no código: para modelos com janela de contexto menor que 512K, o threshold é fixado em 0.75. Então modelos de janela pequena não disparam em 50%, mas sim em 75%. Saber disso ajuda a estimar o ponto real de compressão.

Solução

compression:
  enabled: true
  threshold: 0.65           # dispara mais cedo que o padrão
  target_ratio: 0.25        # mantém 25% do final recente
  protect_last_n: 30        # ~15 turnos completos
  protect_first_n: 1        # apenas system prompt + primeira mensagem do usuário
  codex_app_server_auto: native

Se sua tarefa precisa frequentemente voltar ao contexto inicial (ex.: “sempre use Python 3.11”, “este projeto usa pnpm”), aumente protect_first_n para 3. Caso contrário, mantenha em 1 para economizar espaço.

Valores recomendados

Janela de contexto threshold target_ratio protect_last_n
≤ 32K (Claude 3.5 Sonnet, GPT-4o) 0.75 (padrão mínimo) 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

Dica: O resumidor de compressão usa Gemini Flash por padrão, que é rápido e barato. Para tarefas com muito código, você pode fixar um modelo diferente em auxiliary.compression, mas o padrão geralmente é suficiente.

Configuração 3: Trave o Loop de Ferramentas — agent.max_turns

Sintomas

  • Uma tarefa simples invoca 50 turnos de ferramentas e o agente ainda está em “deixe-me confirmar novamente.”
  • Uma instabilidade de rede faz uma ferramenta falhar repetidamente, enviando o agente a uma espiral de retry e sua fatura subindo.
  • Uma tarefa em background roda por meia hora e acaba presa em um loop.

Causa

agent.max_turns limita quantas iterações de chamadas de ferramentas o agente pode fazer em uma única requisição do usuário. O padrão de 60 é suficiente para Q&A casual, mas é rapidamente esgotado em debugging complexo, processamento em lote ou confirmação iterativa. Sem um limite, uma ferramenta falhando pode retryar indefinidamente.

Combinar max_turns com tool_loop_guardrails.hard_stop_enabled cria um disjuntor para loops anormais.

Solução

agent:
  max_turns: 100              # espaço para tarefas complexas
  api_max_retries: 2          # falha rápido e deixa o fallback assumir
  reasoning_effort: medium

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true     # disjuntor para loops anormais
  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 tarefa max_turns hard_stop_enabled
Q&A casual / consultas de uma etapa 30–40 false
Debugging de código / complexidade média 60–80 true
Processamento em lote / jobs longos em background 100–150 true
Pesquisa exploratória / refatoração multi-arquivo 100–200 true

Nota: max_turns é o limite de iteração de ferramentas por requisição, não o limite de mensagens da sessão inteira. Você pode resetar o contexto a qualquer momento com /new ou outros comandos de gerenciamento de sessão do nosso panorama de comandos do Hermes v0.18.

Referência Completa: Trecho de config.yaml Pronto para Uso

Aqui está um trecho consolidado para o cenário comum de OpenRouter como provider principal + modelos locais ocasionais + tarefas longas frequentes:

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

Salve em ~/.hermes/config.yaml. Novas sessões o carregam imediatamente; sessões já em execução precisam de /new para recarregá-lo.

Verificação: Realmente Funcionou?

Três verificações rápidas:

  1. Dispare raciocínio longo de propósito. Peça ao agente para processar um arquivo de log de 500 linhas ou ler dez arquivos de código de uma vez. Você não deve mais ver context length exceeded.
  2. Simule instabilidade de API. Bloqueie brevemente o IP do provider com timeout ou iptables e confirme que o agente falha dentro do timeout configurado e tenta fallback, em vez de ficar pendurado para sempre.
  3. Inspecione a compressão. Durante uma tarefa longa, execute /compress ou aguarde a compressão automática e verifique se as últimas ~30 mensagens e o system prompt ainda estão presentes.

Para modos de falha mais complexos, veja nosso mergulho profundo em manipulação de erros e recuperação do Hermes, que combina timeouts, fallbacks e retries em uma única estratégia de resiliência.

Resumo

Tarefas longas geralmente travam não porque o modelo ficou mais lento, mas porque timeouts de API, compressão de contexto e limites do loop de ferramentas não estão alinhados. Depois de ajustar essas três configurações:

  • Chamadas de API expiram de forma limpa e fazem fallback para outro provider em vez de ficar penduradas.
  • O contexto é comprimido no momento certo, preservando detalhes recentes sem atingir o limite da janela.
  • Chamadas de ferramentas têm um teto rígido, impedindo espirais de retry e contas fora de controle.

Se você está começando, leia primeiro o guia de instalação para garantir que seu ambiente esteja sólido, e depois guarde este trecho como um “modelo para tarefas longas” para copiar em trabalhos exigentes.

Referências: este artigo é baseado no cli-config.yaml.example oficial do Hermes Agent e na documentação oficial.