💥 O que acontece quando um modelo falha ou fica lento
O que é
Aceitar que falhas vão acontecer — e projetar o sistema para lidar com elas — é o que diferencia um protótipo de um sistema de produção. A questão não é se vai falhar, mas quando e como recuperar.
Por que aprender
Indisponibilidade de provedor
Ocorre algumas vezes por mês em qualquer provedor. Pode durar minutos ou horas.
Estratégia: Fallback para modelo alternativo via OpenRouter.
Sobrecarga de servidor
Latências de 30–60s em horários de pico. O modelo responde, mas devagar.
Estratégia: Timeout com fallback para provedor menos carregado.
Rate limit excedido (429)
Muitas chamadas em pouco tempo. O provedor bloqueia temporariamente.
Estratégia: Retry com backoff exponencial ou BYOK com limites mais altos.
Resposta truncada ou sem sentido
Modelo retorna output incompleto ou incoerente sem indicar erro.
Estratégia: Validação de output antes de passar ao próximo estágio do pipeline.
Conceitos-chave
Cada provedor tem uma taxa de falha — planejar com base na taxa, não na esperança de 100% de uptime
O sistema deve assumir que vai falhar e ter uma estratégia para cada tipo de falha
Indisponibilidade, sobrecarga, rate limit e qualidade — cada um com estratégia diferente
A diferença é o design para falha — protótipo ignora, produção trata explicitamente
🔀 Configurando fallbacks no OpenRouter
O que é
Fallbacks no OpenRouter são a forma mais simples de resiliência — uma linha de configuração que protege contra indisponibilidade de provedor sem nenhuma mudança no código do Hermes.
Por que aprender
⚙️ Configuração de fallback para o Worker
{
"model": "deepseek/deepseek-chat",
"route": "fallback",
"models": [
"deepseek/deepseek-chat",
"mistral/mistral-large",
"meta-llama/llama-3.1-70b-instruct"
]
}
Se o modelo primário (deepseek) retornar erro ou timeout, o OpenRouter tenta automaticamente o próximo na lista. O Hermes vê apenas um resultado — o fallback é transparente.
💡 Escolhendo os modelos de fallback
Para o Worker: escolha modelos com capacidade de raciocínio similar ao primário e custo comparável. O fallback deve produzir output utilizável, não apenas evitar o erro. Para o Crítico: o fallback deve ter o mesmo rigor — um Crítico mais permissivo vai aprovar outputs que o primário reprovaria.
Conceitos-chave
Lista de modelos em ordem de preferência — o primeiro disponível é usado
O Hermes não sabe qual modelo foi usado — vê apenas o resultado final
Worker fallback deve ser outro modelo capaz de executar trabalho de Worker, não um modelo genérico
Uma linha de configuração no OpenRouter — sem mudança no código do Hermes ou nos prompts
📝 Fallbacks no prompt — instruções defensivas para o Worker
O que é
Instruções defensivas tornam falhas visíveis e nomeadas. PARTIAL_DELIVERY e BRIEFING_CONFLICT são muito mais fáceis de diagnosticar do que um output silenciosamente incompleto.
Por que aprender
📋 Sinais defensivos para o Worker
PARTIAL_DELIVERY
Quando o Worker atingir o limite de contexto antes de completar todos os ângulos:
BRIEFING_CONFLICT
Quando o briefing contiver informações contraditórias que impedem a execução:
MISSING_CONTEXT
Quando o briefing referenciar dados ou informações não fornecidas:
Conceitos-chave
Falha de contexto nomeada — permite retomada parcial sem reiniciar do zero
Contradição no briefing identificada antes de executar trabalho inútil
Um ângulo ausente é recuperável. Um ângulo truncado no meio é trabalho perdido e confuso
Um sinal explícito permite diagnóstico e recuperação — silêncio não permite nenhum dos dois
⛔ Limites de retry — quantas vezes tentar antes de parar
O que é
Limites de retry são o freio de segurança do sistema. Sem eles, um loop mal configurado pode rodar por horas sem progressão — consumindo créditos sem produzir resultado.
Por que aprender
📋 Dois tipos de limite de retry
Loop Worker-Crítico (qualidade)
Se o Crítico retornar REVISE com o mesmo problema pela terceira vez consecutiva, o Worker sinaliza STUCK e escala para o Condutor.
Falha de API (infraestrutura)
Para erros 429, 500, ou timeout: retry automático máximo 3 vezes com backoff exponencial antes de escalar.
⚙️ Backoff exponencial — por que funciona
Conceitos-chave
O padrão da indústria para falhas transitórias — equilibra persistência e custo
O Worker não tenta resolver sozinho indefinidamente — escala quando preso
Cada retry com espera maior — evita bombardear um servidor já sobrecarregado
O sinal que indica que o problema não é de execução mas de configuração — escalar, não persistir
💾 Checkpoints — salvando estado parcial em tarefas longas
O que é
Checkpoints transformam falhas de tarefa longa de catástrofe em inconveniência. Sem eles, qualquer interrupção joga fora todo o trabalho feito.
Por que aprender
📋 Instrução de checkpoint para o Worker
"A cada 5 ângulos completados:
1. Escreva o seguinte antes de continuar:
CHECKPOINT: [X] de [Total] ângulos completos
2. Inclua os ângulos completos até agora
3. Então continue com o próximo lote
Se a tarefa for interrompida após um checkpoint,
o trabalho pode ser retomado a partir desse ponto."
💡 Quando usar checkpoints
Use checkpoints quando a tarefa tiver: mais de 30 minutos de execução esperada, mais de 20 iterações do loop, ou mais de 10 ângulos para explorar. Para tarefas menores, o overhead de checkpoint não vale o benefício.
Conceitos-chave
Formato padronizado que permite ao Condutor retomar de onde parou
Frequência de checkpoint que equilibra overhead e granularidade de recuperação
Com checkpoint, uma interrupção perde no máximo 5 ângulos — não o trabalho inteiro
A diferença entre reiniciar do zero vs retomar do checkpoint
🔧 Recuperação manual — como retomar uma tarefa interrompida
O que é
Saber recuperar uma tarefa interrompida salva o trabalho já feito e o custo já consumido. Sem esse processo, toda interrupção resulta em desperdício.
Por que aprender
Verificar o último estado nos logs do Hermes
hermes logs --last 20 — qual foi o último evento antes da interrupção? Qual modelo estava respondendo? O que estava fazendo?
Identificar o último checkpoint no output parcial
Procurar por CHECKPOINT: no output parcial. Esse é o ponto de retomada — todo trabalho anterior ao checkpoint está completo e válido.
Construir o prompt de continuação
Incluir: o briefing original, os ângulos já completos do checkpoint, e a instrução "continue a partir do ângulo X — os anteriores já foram completados e estão incluídos acima".
Avaliar custo consumido antes de reiniciar
Quanto já foi gasto na tarefa? Se o custo já consumido supera o valor esperado do resultado, avaliar se vale retomar ou abandonar.
Conceitos-chave
O log do Hermes é a fonte de verdade sobre o que aconteceu antes da interrupção
Um prompt que inclui o contexto do checkpoint e instrui a continuar de onde parou
A decisão de retomar ou abandonar baseada em custo já gasto vs valor esperado
Às vezes é mais eficiente reiniciar com um briefing melhorado do que retomar um checkpoint antigo
🧪 Testando resiliência — simulando falhas
O que é
Testar resiliência em condição controlada revela problemas antes de eles aparecerem em produção. É a diferença entre descobrir que o fallback não funciona durante um teste vs durante uma tarefa crítica às 3h da manhã.
Por que aprender
Simular falha de modelo
Configure o modelo primário como um modelo inexistente (ex: test/modelo-inexistente). Verifique se o fallback é acionado automaticamente e qual modelo é usado no lugar.
Testar BRIEFING_CONFLICT
Envie um briefing com instruções contraditorias deliberadas ("faça X" e "não faça X" no mesmo briefing). Verifique se o Worker sinaliza BRIEFING_CONFLICT antes de executar.
Forçar STUCK
Envie um briefing impossível de satisfazer (ex: "produza uma análise usando dados que são secretos e não estão disponíveis"). Verifique se o Worker escala para o Condutor com STUCK após 3 tentativas.
Testar recuperação de tarefa interrompida
Inicie uma tarefa longa com checkpoints, interrompa manualmente no meio, e siga o processo de recuperação. Verifique se a retomada a partir do checkpoint funciona corretamente.
💡 Quando fazer esses testes
Antes de confiar o sistema para qualquer tarefa crítica overnight. Um conjunto de 4 testes leva cerca de 30 minutos e pode economizar horas de diagnóstico posterior. Refaça os testes sempre que mudar a configuração de modelos ou fallbacks.
Conceitos-chave
A forma mais simples de simular falha de provedor e verificar se fallback funciona
Testa se o Worker detecta problemas antes de executar trabalho inútil
Verifica se o mecanismo de escalada funciona antes de depender dele em produção
O momento certo de descobrir problemas — antes, não durante uma tarefa crítica
✅ Resumo do Módulo
Próximo Módulo:
3.6 — Expandindo o Pantheon — Novas personas e skills