Módulo 4.3 — Custo, billing e otimização

📊 Dashboard OpenRouter — onde olhar custos

A maioria das instalações de Hermes Agent usa openrouter.ai/activity como ponto único de billing — uma key, dezenas de modelos. O painel mostra custo por requisição, tokens in/out, cache hit rate e modelo escolhido. Aprenda a ler antes de otimizar — caso contrário você otimiza no escuro.

🧭 Painéis que importam

•Activity: linha-a-linha das últimas 7 dias. Permite filtrar por modelo, app e key.
•Credits: saldo atual + auto-recarga. Aqui você define limite mensal real.
•Keys: uma key por projeto, com credit limit e rate limit isolados.
•Models > pricing: tabela oficial atualizada. Sempre confira antes de hard-codar modelo.

# Puxar últimas 24h via API de billing
$ curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
       https://openrouter.ai/api/v1/credits | jq

# Listar gerações da última hora (custo, tokens, modelo)
$ curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
       "https://openrouter.ai/api/v1/generations?limit=50" \
  | jq '.data[] | {model, cost, tokens_prompt, tokens_completion, cache_discount}'

🚨 Alertas de budget — limite mensal, threshold, hard stop

Sem alerta, a primeira notícia de problema é a fatura. Configure três camadas: aviso suave (70%), aviso duro (90%) e parada total (100% = key bloqueia). Isso te dá tempo de investigar antes do estouro real.

Defina o budget mensal por key

OpenRouter → Keys → editar → Credit limit

Comece pequeno (US$ 20-30 para uso pessoal). É mais fácil aumentar depois do que explicar fatura de US$ 400.

Threshold de aviso em 70%

Cron diário que checa /api/v1/credits e dispara ntfy/Slack

70% no dia 10 do mês é normal. 70% no dia 3 = sirene. Threshold relativo ao calendário ajuda a separar anomalia de uso saudável.

Hard stop em 100%

Auto-recarga DESLIGADA até investigação

Auto-recarga é conveniência que vira tragédia em loop infinito. Prefira saldo finito + alerta de saldo baixo.

Limite local em config.yaml

cost.daily_usd_limit: 5 no Hermes

Defesa em profundidade: o agente para sozinho quando estima passar do limite diário, antes mesmo do OpenRouter cortar.

⚠️ Atenção — runaway costs (loop infinito de tool calls)

O cenário clássico de fatura disparada não é "muito uso", é loop: o agente chama uma tool que falha, re-pensa, chama de novo, falha de novo. Em 20 minutos com Opus, isso vira US$ 50 fácil. Defesas: max_tool_iterations: 8 em config.yaml, timeout por sessão (15 min), e alerta de tokens/sessão p99.

🎯 Modelo certo por tarefa — Haiku para classify, Opus para reasoning

Usar Opus para classificar uma string é como contratar Senior Architect para apertar um parafuso. Routing por tarefa é a alavanca mais barata: troca uma linha de config e corta 70% do custo.

📊 Preços por 1M tokens (USD, atualizado 2026-05)

Modelo	Input	Output	Cache write	Cache read
Claude Opus 4.7	US$ 15,00	US$ 75,00	US$ 18,75	US$ 1,50
Claude Sonnet 4.6	US$ 3,00	US$ 15,00	US$ 3,75	US$ 0,30
Claude Haiku 4.5	US$ 1,00	US$ 5,00	US$ 1,25	US$ 0,10
GPT-5	US$ 1,25	US$ 10,00	—	US$ 0,125
Gemini 2.5 Pro	US$ 1,25	US$ 10,00	—	US$ 0,31
DeepSeek v3.2	US$ 0,27	US$ 1,10	—	US$ 0,07

Fonte: openrouter.ai/models. Preços mudam — confira antes de hard-codar.

✓ O que FAZER

✓Haiku 4.5 / DeepSeek para classify, summarize curto, extração JSON.
✓Sonnet 4.6 como default para chat, refactor pequeno, code review.
✓Opus 4.7 só para planejamento longo, debug difícil, escrita criativa.
✓Definir model_routing por skill, não global.

✗ O que NÃO fazer

✗Usar Opus para classify — 15× mais caro, ganho zero.
✗Hard-codar um único modelo "porque é o melhor".
✗Trocar de modelo sem rodar eval no seu dataset.
✗Esquecer de revisar routing depois de release de modelo novo.

# ~/.hermes/config.yaml — routing por tarefa
model_routing:
  default: anthropic/claude-sonnet-4.6
  tasks:
    classify:       anthropic/claude-haiku-4.5
    summarize_short: anthropic/claude-haiku-4.5
    extract_json:   deepseek/deepseek-v3.2
    code_review:    anthropic/claude-sonnet-4.6
    plan:           anthropic/claude-opus-4.7
    debug_hard:     anthropic/claude-opus-4.7
    creative:       anthropic/claude-opus-4.7

cost:
  daily_usd_limit: 5
  warn_at_pct: 70
  hard_stop_at_pct: 100

💾 Prompt caching — quando funciona, ganho típico (90% off)

Prompt caching da Anthropic dá ~90% de desconto em tokens de input que se repetem entre chamadas. Hermes ativa por padrão a partir de v0.9, mas você precisa estruturar o prompt para o cache pegar: parte estável primeiro (system + ferramentas + contexto fixo), parte volátil por último (mensagem do user).

💾 Quando o cache PEGA (e quando não)

✓System prompt > 1024 tokens, mesmo conteúdo entre requests.
✓Schemas de tools longos repetidos em todas as sessões.
✓Documento grande (RAG) consultado em várias perguntas seguidas.
✗Cache expira em 5 min sem reuso — sessões esparsas perdem o ganho.
✗Qualquer mudança no prefixo invalida o cache inteiro.
✗Modelos sem suporte (alguns OSS no OpenRouter ignoram a flag).

📊 Benchmark de custo por 1k requests (Sonnet 4.6)

Sem cache: system 4k tokens × 1000 reqs × US$ 3/M = US$ 12,00
Cache write (1×): 4k × US$ 3,75/M = US$ 0,015
Cache read (999×): 4k × 999 × US$ 0,30/M = US$ 1,20
Total com cache: US$ 1,21 (-90%)
Ganho líquido: US$ 10,79 a cada 1000 requests com o mesmo system prompt.

# Verificar se cache está pegando (logs Hermes em DEBUG)
$ HERMES_DEBUG=1 hermes chat 2>&1 | grep cache
[cache] write 4127 tokens (system+tools)
[cache] read  4127 tokens (hit, age=42s)   # ← bom
[cache] miss  (prefix changed)             # ← ruim, investigar

# Métrica de hit rate (cache_discount no OpenRouter)
$ curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
       "https://openrouter.ai/api/v1/generations?limit=200" \
  | jq '[.data[] | select(.cache_discount > 0)] | length'

🔄 Fallback dinâmico — cair para modelo barato em load

Em pico de uso (ou outage do provedor primário), fallback automático mantém o agente vivo sem te queimar a fatura. A ordem importa: qualidade alta → qualidade média → custo baixo, com short-circuit em rate-limit ou erro 5xx.

# config.yaml — fallback chain por tarefa
model_routing:
  chat:
    primary:   anthropic/claude-sonnet-4.6
    fallbacks:
      - openai/gpt-5            # se Anthropic 429/5xx
      - google/gemini-2.5-pro   # se OpenAI também cair
      - deepseek/deepseek-v3.2  # último recurso barato

  classify:
    primary:   anthropic/claude-haiku-4.5
    fallbacks: [deepseek/deepseek-v3.2]

fallback:
  trigger_on: [rate_limit, 5xx, timeout_30s]
  max_retries: 2
  log_demotion: true   # gera evento "model_demoted" no log estruturado

💡 Dica — 1-shot > few-shot na maioria dos casos

Engenheiros adoram empilhar 5-10 exemplos para "ensinar" o modelo. Modelos 2026 quase nunca precisam disso — 1 exemplo bem escolhido + instrução clara basta. Reduz tokens de input em 60-80% sem perder acurácia. Teste antes de assumir que precisa de few-shot.

✓ Cache + fallback funcionam juntos

✓Cache para prompts repetidos (system, tools, RAG fixo).
✓Fallback preserva user msg, só troca provedor.
✓Logar a demotion ajuda no post-mortem.

✗ Armadilhas comuns

✗Fallback sem teste — modelo barato pode quebrar formato esperado.
✗Fallback infinito sem max_retries vira loop de re-tentativa.
✗Trocar prefixo do prompt entre tentativas — invalida cache.

📈 Caso real — antes/depois (US$ 120/mês → US$ 28/mês)

Caso típico de instalação Hermes Agent de uso individual intenso (dev + escrita): US$ 120/mês caiu para US$ 28/mês aplicando os 5 tópicos anteriores. Sem mudança perceptível de qualidade nas saídas. Veja a auditoria passo-a-passo.

Baseline (antes): tudo Opus, sem cache

~800 sessões/mês, US$ 0,15/sessão

Modelo único: anthropic/claude-opus-4.7. System prompt 3,8k tokens recriado em toda sessão. Sem fallback. Total: US$ 120/mês.

Passo 1: routing por tarefa (-50%)

classify+summarize → Haiku, default → Sonnet, plan → Opus

35% das sessões eram classify/summarize, agora rodam em Haiku. 50% em Sonnet. Só 15% no Opus. Caiu para US$ 60/mês.

Passo 2: prompt caching (-40% adicional)

System+tools (4k tokens) marcados como cache_control

Cache hit rate de 78% (sessões agrupadas em janelas curtas). System antes custava ~50% do input — agora custa 5%. Caiu para US$ 36/mês.

Passo 3: max_tool_iterations + 1-shot (-22% adicional)

Cortou 3 loops/mês + reduziu few-shot para 1-shot

Loops infinitos consumiam ~US$ 8 cada (Opus). Few-shot longo virou 1-shot com schema. Caiu para US$ 28/mês.

📊 Resultado consolidado

Antes: US$ 120,00 / mês — US$ 0,150 / sessão
Depois: US$ 28,00 / mês — US$ 0,035 / sessão
Economia: US$ 92,00 / mês (-76,7%)
Tempo investido: ~2h de tuning + 30 min/mês de revisão
Payback: dia 1 do mês seguinte.

💡 Dica — auditoria de custo trimestral

Reserve 30 min a cada 3 meses para: (1) baixar CSV de generations do trimestre, (2) ordenar por custo decrescente, (3) ver as 10 sessões mais caras, (4) perguntar "esse modelo era necessário?". 80% das economias futuras saem desse checklist simples.

✅ Resumo do Módulo

✓

Dashboard OpenRouter é a fonte da verdade — Activity, Credits, Keys, Models.

✓

Alertas em 70/90/100% + daily_usd_limit local evitam fatura-surpresa.

✓

Routing por tarefa: Haiku para classify, Sonnet default, Opus só para o que precisa.

✓

Prompt caching dá ~90% off em tokens repetidos — estabilize o prefixo.

✓

Fallback dinâmico mantém o agente vivo em outage + protege da fatura em loop.

✓

Caso real: US$ 120 → US$ 28/mês (-76,7%) com 2h de tuning.

Próximo módulo:

4.4 — Estratégia de upgrade ao longo de meses. Channels (stable/beta/nightly), breaking changes, staging, rollback e calendário anual para manter Hermes saudável por anos.

← Voltar para Trilha Próximo: 4.4 →