Seus modelos de fallback podem estar todos mortos — e nada avisa até a queda

São duas da manhã e o modelo primário começa a responder 429. Você não se preocupa — montou uma cadeia de fallback meses atrás: outro provider primeiro, um modelo local depois. O Hermes tenta os dois, os dois falham, e a tarefa morre no meio. De manhã você abre a configuração e vê: a chave do primeiro provider foi rotacionada no mês passado, e o segundo provider renomeou o modelo duas releases atrás. A cadeia continuava lá. Só nunca tinha sido testada.
Isso não é descuido. É o que todo “backup” faz: nada o exercita, então nada percebe quando ele apodrece — até o minuto em que você precisa dele.
De “deveria funcionar” para “funciona”
hermes fallback check é um novo subcomando que responde a uma única pergunta: cada entrada da sua cadeia pode realmente ser usada agora? Ele não abre sessão de agente e não consome contexto da conversa.
hermes fallback check # apenas configuração e credenciais
hermes fallback check --live # envia uma requisição mínima por entrada
hermes fallback check --json # saída estruturada para scripts
Se qualquer entrada não estiver pronta, o comando sai com status 1. É exatamente esse o ponto: você consegue pendurá-lo no cron, no CI, numa checklist antes do deploy — em vez de descobrir às duas da manhã.
Comece olhando o que você tem:
hermes fallback # o mesmo que hermes fallback list
A cadeia fica em config.yaml, na chave fallback_providers, uma lista ordenada de entradas {provider, model, base_url?, api_mode?}. A chave antiga fallback_model é mesclada automaticamente, então existe uma única fonte de verdade. hermes fallback add usa o mesmo seletor de hermes model.
A checagem estática: o que o próprio switch vai enxergar
Sem --live, o comando resolve cada entrada com os mesmos kwargs que o switch de fallback usa quando faz o failover. Três coisas saem disso.
O provider existe? Um provider escrito errado é erro de configuração, não problema de credencial — o relatório separa os dois, porque o conserto é diferente.
Existem credenciais utilizáveis? Aqui a pergunta é a mesma que o switch faz: essa entrada seria pulada por falta de autenticação? Usar o mesmo predicado significa que a checagem não consegue dizer “pronta” sobre uma entrada que o failover real pularia.
O endpoint e o protocolo resolvidos fazem sentido? base_url e api_mode são impressos, então uma entrada que ainda aponta para um endpoint do qual você migrou aparece na hora.
A saída é uma tabela:
# Provider / model Config Auth Live Latency Status
1 openrouter / gpt-x ok ok ok 210 ms ready
2 anthropic / claude-sonnet ok FAIL — — auth
3 local / qwen3:8b ok ok ok 88 ms ready
As três colunas são independentes. Config falhando significa provider desconhecido. Auth falhando significa que o provider está certo, mas não há credencial para ele. No modo estático a coluna Live vem como travessão, porque nenhuma requisição de inferência foi enviada.
--live: dizer algo de verdade
Uma checagem estática pega o “não configurado”. Ela não pega o “configurado e quebrado” — cota esgotada, conta suspensa, nome de modelo aposentado, um 502 atrás do endpoint. Só uma requisição real revela isso.
--live envia uma completion mínima para cada entrada que passou na checagem estática: o prompt Reply with exactly: OK, no máximo 512 tokens, o timeout de requisição do próprio provider (30 segundos se nenhum for conhecido) e retries do SDK desligados. As entradas são sondadas em paralelo, então o custo em tempo de parede é mais ou menos o da mais lenta.
Uma decisão de projeto vale a pena conhecer: a sonda não passa de propósito pelo call_llm. O call_llm tem uma escada de recuperação — ele tenta de novo e pode responder a partir de outro provider — e isso esconderia justamente o que você quer descobrir. Uma checagem de saúde quer a má notícia, não a notícia salva.
Os veredictos caem em poucas classes:
ready— as duas etapas passaram.auth— nenhuma credencial utilizável; o switch também pularia essa entrada.live_*— a requisição falhou, com o motivo do classificador como sufixo (rate limit, timeout, auth, model not found, e assim por diante).live_response— HTTP 200 sem completion utilizável dentro: um status de falha, ou texto parcial sem nada atrás.model_mismatch— algo respondeu, mas não foi o modelo que você pediu.
Esse último é mais comum do que parece. Muitos gateways agregadores substituem silenciosamente o modelo quando o solicitado está indisponível; a requisição tem sucesso e a qualidade cai sem aviso. A checagem compara o que você pediu com o que o provider diz ter respondido: um snapshot datado (gpt-4o → gpt-4o-2024-08-06) conta como compatível, um ponteiro -latest conta, uma :tag precisa bater. E onde o modelo informado não é evidência nenhuma — endpoints locais, a nomenclatura deployment-versus-base-model do Azure, meta-modelos de roteador como openrouter/auto — ele não finge saber.
Lendo o JSON, travando um pipeline
Humanos leem a tabela; scripts leem o JSON:
hermes fallback check --live --json > fallback-report.json
O formato, por entrada:
{
"profile": "default",
"live": true,
"ready": false,
"checked_at": "2026-11-17T03:12:44+00:00",
"results": [
{
"provider": "openrouter",
"model": "gpt-x",
"base_url": "https://openrouter.ai/api/v1",
"api_mode": "chat_completions",
"auth_source": "env",
"configured": true,
"auth_ready": true,
"inference_ready": true,
"latency_ms": 210,
"model_returned": "gpt-x-2026-09-01",
"error_class": "",
"error": "",
"ready": true,
"status": "ready"
}
]
}
O texto de erro passa por redação: valores de credencial conhecidos são substituídos literalmente primeiro, e depois o redator de suporte roda. Então o arquivo pode ser colado num ticket sem vazar uma chave por acidente.
Pendurar isso é trivial:
# toda manhã às 8: falhe alto em vez de falhar em silêncio
hermes fallback check --live || hermes send --to ops "a cadeia de fallback não está pronta"
Ou use como portão de release. Uma cadeia fora do ar deve parar o deploy, não aparecer como o primeiro incidente depois dele.
Detalhes que valem conhecer
auto e moa ficam estáticos. O auto escolhe o backend a cada chamada e pode percorrer a cadeia sozinho; o moa é um preset de fan-out que só um agente consegue amarrar. Uma requisição de checagem de saúde não prova nada sobre nenhum dos dois, então eles reportam ready (static) e nunca são sondados.
--live custa dinheiro. Uma requisição mínima por entrada — pouca coisa, mas não zero. Numa cadeia longa checada com muita frequência, considere rodar a sonda ao vivo só quando importa.
Passar significa “agora”. Cotas, janelas de rate limit e disponibilidade de modelos mudam. Trate a checagem como um exame físico, não como um seguro.
Sem cadeia configurada, você recebe No fallback providers configured. Add one with: hermes fallback add em vez de uma tabela vazia.
Se você ainda não montou uma cadeia, comece por como o Hermes organiza fallbacks em camadas, use a referência de hermes fallback para adicionar entradas e depois rode hermes fallback check --live. Cinco minutos de trabalho compram a única coisa para a qual um backup serve.
A versão curta
Uma cadeia de fallback normalmente não quebra quando você a configura. Ela quebra nos meses em que ninguém olha para ela. hermes fallback check fecha essa lacuna: checagens estáticas de configuração e credenciais, --live para disponibilidade real, e um código de saída sobre o qual a automação consegue agir. Rode depois de cada hermes update — mais barato do que qualquer quantidade de “deve estar tudo bem”.
Notas completas da release: v0.23.2.