Fallback providers no Hermes: manter o agente de pé quando o modelo cai

Por SkyNet · 17 de novembro de 2026

Todos os fornecedores falham. Às vezes é a quota que se esgota, às vezes é um 429 a meio de uma sessão produtiva, às vezes é um 500 que corta o turno.

O Hermes, da Nous Research, tem fallback entre fornecedores há várias versões: quando o modelo principal não responde, o agente troca para outro par provider:model e continua, com o histórico atrás. A novidade é mais pequena mas útil. Desde a v0.23.2, a release de 16 de Novembro de 2026, o hermes fallback check chegou à versão estável.

Três camadas, uma delas interessa aqui

A resiliência está dividida em três níveis. Os credential pools rodam várias chaves do mesmo fornecedor e são tentados primeiro. O primary model fallback troca para outro par provider:model quando o principal falha, e é o que este artigo trata. Há ainda o fallback das tarefas auxiliares: visão, compressão, MCP, approval, título, review e triage specifier.

Configurar a cadeia

O caminho fácil é o gestor interactivo hermes fallback, que reutiliza o mesmo picker do hermes model. Tem os subcomandos add, list (alias ls), remove (alias rm), clear e check, e grava na lista de topo fallback_providers: do config.yaml.

À mão, em ~/.hermes/config.yaml:

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

Cada entrada exige provider e model; sem um deles, é ignorada. As entradas são tentadas por ordem.

Para um endpoint próprio, provider: custom com model, base_url e key_env. Nota bem: key_env leva o nome da variável de ambiente que guarda a chave, não a chave.

fallback_providers:
  - provider: custom
    model: nome-do-modelo
    base_url: http://localhost:8000/v1
    key_env: MY_LOCAL_KEY

fallback_model, no singular, é a chave legada. Continua a ser respeitada, mas o hermes fallback escreve fallback_providers e migra a configuração antiga. Se as duas existirem, manda a nova.

Verificar a cadeia sem abrir sessão

O check valida a cadeia sem abrir sessão, em duas variantes.

hermes fallback check é estático: resolve cada entrada e as credenciais, sem inferência nenhuma. hermes fallback check --live envia ainda um pedido mínimo por entrada, em paralelo, e aceita --json. Para outro perfil, hermes -p <perfil> fallback check.

O comando sai com código 1 se alguma entrada não estiver pronta, o que o torna útil em cron e CI. Cada entrada é testada isoladamente: a cadeia não é percorrida, por isso uma entrada avariada não esconde as seguintes. O --live não faz retries nem aceita ser respondido por outro fornecedor.

Os status dizem-te onde está o problema: ready, ready (static), config, auth, model_mismatch, live_response e variantes live_<razão>, como live_auth, live_timeout, live_rate_limit ou live_model_not_found. Um fornecedor que sirva outro modelo dá model_mismatch; um snapshot datado do mesmo modelo conta como correspondência.

Duas garantias: as credenciais nunca são impressas, e o limite do pedido live é o request_timeout_seconds do fornecedor, ou 30 segundos por omissão. Vale a pena saber que mesmo o modo estático pode refrescar e gravar um token OAuth a expirar.

Quando dispara e o que acontece

Um 429 ou um 500/502/503 disparam o fallback depois de esgotados os retries. Um 401/403 ou um 404, imediatamente. Respostas inválidas ou vazias repetidas também contam. Se o rate limit indicar a hora de reset, o primário fica de banco até lá; sem indicação, há backoff exponencial, de 60 segundos a 4 horas.

Na troca, o Hermes resolve as credenciais do fallback, constrói um cliente novo e substitui modelo, fornecedor e cliente no lugar, re-resolvendo o reasoning effort do novo modelo. O histórico e as tool calls mantêm-se. Todas as superfícies mostram um aviso deste tipo: «⚠️ Model fallback: … could not respond (rate limit: HTTP 429 …); using … via …». Esse aviso é só para ti: nunca entra na conversa que o modelo lê.

Se o primário declarar uma hora de reset mais cedo do que fallback.min_switch_reset_seconds, não há troca, espera-se. Por omissão é 0, o que quer dizer trocar sempre.

As armadilhas

A primeira é o escopo. O fallback é por turno, não por sessão: cada mensagem nova recomeça no primário, e dentro de um turno activa no máximo uma vez. Se o fallback também falhar, segue o tratamento de erro normal. A excepção são os casos em que o primário reportou uma hora de reset ainda não passada: aí fica-se no fallback até lá.

A segunda é o preço. A troca reinicia a prompt cache e o fallback relê o histórico todo a preço cheio; voltar ao primário pode custar outra releitura. Uma sessão a saltar entre fornecedores sai cara.

A terceira é o alcance. Não há variáveis de ambiente para a cadeia principal: só config.yaml ou hermes fallback, de propósito. Nos cron jobs, só os que não têm provider, model ou base_url próprios herdam a cadeia; um job com pin nunca cai para ela. Para manter o fallback, deixa-o sem pin e escolhe o modelo por cron.model e cron.model_provider. Nos subagentes, usa delegation.fallback_providers se estiver definido; senão, só os filhos sem pin herdam a cadeia do pai, e um [] desactiva-a. E nas tarefas auxiliares com provider escolhido explicitamente, sem fallback_chain e com o principal indisponível, a tarefa é saltada com aviso, em vez de gastar saldo noutro fornecedor.

Fecho

O que a v0.23.2 acrescenta é poder rever a lista entrada a entrada antes de precisares dela. Configura a cadeia, corre um hermes fallback check --live e dorme melhor.

Docs: Fallback Providers · Release v0.23.2 · Credential Pools

Tags: #hermes #fallback #fornecedores