Como Configurar o Hermes Agent com OpenRouter

OpenRouter É o Ponto de Partida Recomendado para o Hermes

Quando você configura o Hermes Agent pela primeira vez, precisa apontá-lo para um provedor de LLM. O quickstart oficial suporta Nous Portal, OpenRouter, OpenAI, Anthropic e qualquer endpoint compatível com OpenAI. Na prática, o OpenRouter é a melhor escolha para a maioria dos usuários, especialmente no primeiro deploy.

O motivo é simples: o OpenRouter é uma única API key que dá acesso a centenas de modelos de diferentes provedores. Em vez de gerenciar contas separadas com OpenAI, Anthropic e Nous Portal, você tem uma interface de cobrança, uma API key e um seletor de modelos que não exige reconfigurar o Hermes toda vez que quiser experimentar algo diferente.

Para um agente auto-aprimorável como o Hermes, projetado para melhorar com o tempo, poder trocar de modelo sem mudanças na infraestrutura é muito útil. Você pode começar com um modelo mais barato para uso diário e mudar para um mais capaz em tarefas complexas sem tocar na instalação do Hermes.

Obtendo Sua API Key do OpenRouter

A configuração é rápida:

1. Acesse openrouter.ai e crie uma conta.
2. Navegue até Settings → API Keys e gere uma nova chave.
3. Copie a chave: ela começa com sk-or-.
4. Adicione créditos à sua conta. O OpenRouter suporta cobrança pay-as-you-go, então você pode começar com um valor pequeno.

A chave que você copiar é o que vai fornecer ao Hermes (ou à Hermify se usar hospedagem gerenciada) como OPENROUTER_API_KEY.

Configurando o Hermes para Usar OpenRouter

Se você estiver rodando o Hermes localmente, a configuração acontece no arquivo config.yaml. A seção relevante fica assim:

provider: openrouter
model: anthropic/claude-3-5-sonnet
openrouter_api_key: sk-or-sua-chave-aqui

Você também pode usar o comando de configuração interativa:

hermes setup

Ele guia você pela escolha de provedor e modelo e escreve a configuração por você. Se quiser mudar o modelo depois sem rodar o setup completo novamente, use:

hermes model

Isso abre um seletor de modelos sem resetar o resto da sua configuração.

Escolhendo o Modelo Certo no OpenRouter

O OpenRouter expõe centenas de modelos. A escolha certa depende do seu caso de uso e orçamento. Estas são as opções práticas para o Hermes:

Melhores modelos de uso geral no OpenRouter:

• anthropic/claude-3-5-sonnet: raciocínio forte, segue instruções em múltiplas etapas bem, bom para fluxos de trabalho complexos. É o modelo com que a maioria dos usuários do Hermes começa.
• openai/gpt-4o: rápido, capaz, bom para código e tarefas estruturadas.
• meta-llama/llama-3.1-70b-instruct: pesos abertos, menor custo por token, bom para fluxos de trabalho de alto volume.
• nousresearch/hermes-3-llama-3.1-405b: o próprio modelo da família Hermes da Nous. Naturalmente alinhado com os system prompts do Hermes Agent, já que ambos vêm do mesmo laboratório.
• google/gemini-2.0-flash: rápido e barato, bom para aplicações sensíveis à latência.

Abordagem econômica: comece com llama-3.1-70b-instruct para uso diário. Mude para Claude ou GPT-4o em tarefas que exigem raciocínio mais forte ou janelas de contexto maiores.

A abordagem pelo modelo Nous: nousresearch/hermes-3-llama-3.1-405b vale testar especificamente porque o runtime do agente Hermes foi construído em torno dos modelos Nous. O alinhamento entre o estilo de prompting do agente e o treinamento do modelo tende a ser mais estreito do que com modelos de terceiros.

Dicas de Configuração Específicas do OpenRouter

Algumas coisas que importam especificamente para OpenRouter com Hermes:

Defina uma preferência de provedor. O OpenRouter roteia requisições para múltiplos provedores de infraestrutura. Se você estiver usando modelos Anthropic, pode fixar na infraestrutura própria da Anthropic definindo provider_order na sua configuração. Isso reduz a variação de latência.

Configure modelos de fallback. O Hermes suporta provedores auxiliares no config.yaml. Isso significa que se o seu modelo primário estiver indisponível, o Hermes pode fazer fallback para um secundário. Com OpenRouter, você pode especificar múltiplos modelos como fallbacks em auxiliary_providers.

Atenção à janela de contexto. O Hermes usa memória persistente e arquivos de contexto, o que significa que os prompts podem ser longos. Modelos com janelas de contexto menores (menos de 32k tokens) podem atingir os limites mais rápido do que o esperado. Se você notar respostas que parecem ignorar contexto recente, o modelo pode estar truncando seu arquivo de memória. Mude para um modelo com janela de contexto maior: Claude e Gemini oferecem 128k+.

Erros Comuns de Configuração

Usar a URL base errada. O Hermes espera um endpoint compatível com OpenAI. A URL base do OpenRouter é https://openrouter.ai/api/v1. Alguns usuários usam acidentalmente a URL da OpenAI, o que causa falhas de autenticação com chaves do OpenRouter.

Esquecer o header HTTP-Referer. O OpenRouter exige um header HTTP-Referer nas requisições de API para identificar sua aplicação. O Hermes lida com isso automaticamente quando você configura openrouter como provedor, mas se você estiver usando uma configuração de endpoint customizado, precisa adicionar este header manualmente.

Esgotamento de cota no meio de uma sessão. O OpenRouter bloqueia requisições quando seus créditos estão baixos, o que o Hermes exibe como erro no terminal ou na interface de mensagens. Adicionar um limite de recarga automática nas configurações do OpenRouter evita que isso interrompa fluxos de trabalho longos.

Escolher um modelo que não suporta tool calls. O Hermes depende do uso de ferramentas para muitas de suas capacidades (escritas de arquivo, buscas na web, tarefas agendadas). Alguns modelos mais baratos no OpenRouter não suportam tool calling. Verifique os flags de capacidade do modelo na página do modelo no OpenRouter antes de trocar.

O Que Muda Se Você Usar Hospedagem Gerenciada

Se você fizer o deploy do Hermes pela Hermify, a configuração do provedor funciona da mesma forma, mas você insere sua API key do OpenRouter pelo dashboard de onboarding em vez de editar um arquivo de configuração. A Hermify armazena criptografada e a injeta no runtime na inicialização.

Você também pode atualizar sua chave de provedor ou trocar de modelo pelo dashboard da Hermify sem reiniciar o container manualmente. Essa é a principal diferença operacional: em vez de acesso SSH para editar o config.yaml, você usa a UI de configurações, dispara um restart e a mudança entra em vigor em segundos.

O plano Starter é projetado especificamente para BYOK com OpenRouter: você traz a chave, a Hermify cuida de todo o resto. Se você quiser pular a conta no OpenRouter completamente, os planos Pro e Dedicado incluem acesso a modelos para não precisar configurar um provedor terceiro.

Uma Configuração Inicial Prática

Se você quer um padrão sólido e não quer gastar tempo comparando modelos, esta é a configuração que funciona bem para a maioria dos usuários do Hermes no OpenRouter:

• Provedor: OpenRouter
• Modelo: anthropic/claude-3-5-sonnet para uso primário
• Fallback: meta-llama/llama-3.1-70b-instruct
• Janela de contexto: 200k tokens (Claude suporta isso)
• Crédito inicial: $10–$20 (geralmente dura várias semanas de uso regular)

A partir daí, você pode ajustar o modelo conforme entende seus próprios padrões de uso. O Hermes foi projetado para sessões longas, então o modelo que você escolhe afeta a qualidade da memória e a confiabilidade das ferramentas, não apenas a velocidade de resposta.

Se você quer pular o trabalho de configuração e chegar a um deploy funcionando do Hermes mais rapidamente, a Hermify cuida da configuração do provedor para você. Você também pode ler mais sobre a diferença de custo real entre deploys auto-hospedados e gerenciados do Hermes antes de decidir.