DEV Community

Cover image for Como Usar o Hermes Agent: Guia Completo
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar o Hermes Agent: Guia Completo

Em resumo: O Hermes Agent é um assistente de IA de código aberto que aprende continuamente, ficando mais inteligente com o tempo. Instale com um único comando, configure seu provedor de LLM e comece a usá-lo via CLI, Telegram, Discord ou diretamente da sua IDE. Este guia apresenta os passos de instalação, configuração, uso prático, recursos avançados e como maximizar a eficiência do Hermes.

Experimente o Apidog hoje mesmo

O Que É o Hermes Agent?

O Hermes Agent é um assistente pessoal de IA desenvolvido pela NousResearch, funcionando 24/7, com memória persistente e evolutiva sobre seus projetos e preferências. Diferente do ChatGPT ou Claude, que começam do zero em cada conversa, o Hermes constrói um modelo persistente do seu ambiente de trabalho.

Hermes Agent

Principais capacidades:

  • Lembra: Armazena conversas, decisões e código compartilhado
  • Aprende: Cria habilidades reutilizáveis de tarefas repetidas
  • Multiplataforma: Use via CLI, Telegram, Discord, Slack, WhatsApp ou IDE
  • Auto-hospedado: Rode localmente, em VPS baratos ou nuvem
  • Independente de modelo: Compatível com mais de 200 modelos via OpenRouter ou provedores diretos
  • Extensível: Plugins para ferramentas e comandos personalizados

Indicado para:

  • Desenvolvedores buscando um par de programação IA com contexto do código
  • Equipes que necessitam de assistente IA multiusuário
  • Usuários avançados com automação 24/7 (cron)
  • Pesquisadores querendo treinar modelos personalizados com dados reais

Instalação: Passo a Passo

Pré-requisitos

  • SO: macOS, Linux ou Windows (WSL recomendado)
  • Python: 3.10+
  • Git: Necessário para clonar repositórios
  • Chave de API: OpenRouter, Anthropic, OpenAI ou outro LLM

Instalação Rápida (Recomendado)

Execute no terminal:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

O script irá:

  1. Clonar o repositório do Hermes
  2. Instalar o uv (gerenciador rápido de pacotes Python)
  3. Criar um ambiente virtual
  4. Instalar dependências
  5. Adicionar Hermes ao PATH

Após, recarregue seu shell:

source ~/.bashrc   # Para bash
source ~/.zshrc    # Para zsh
Enter fullscreen mode Exit fullscreen mode

Teste a instalação:

hermes --version
Enter fullscreen mode Exit fullscreen mode

O output esperado é algo como Hermes Agent v0.5.0.

Instalação Manual (Para Desenvolvedores)

Para controle detalhado:

# Clone o repositório
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Instale o uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Crie e ative o ambiente virtual
uv venv venv --python 3.11
source venv/bin/activate  # Linux/macOS
# ou
.\venv\Scripts\activate  # Windows

# Instale com todos os recursos
uv pip install -e ".[all,dev]"

# Execute os testes
python -m pytest tests/ -q
Enter fullscreen mode Exit fullscreen mode

Instalação com Suporte a Treinamento RL

Se for treinar modelos:

# Inicialize o submódulo Atropos
git submodule update --init tinker-atropos

# Instale dependências de treinamento
uv pip install -e "./tinker-atropos"
Enter fullscreen mode Exit fullscreen mode

Configuração Inicial

Execute o Assistente de Configuração

Para iniciar rapidamente:

hermes setup
Enter fullscreen mode Exit fullscreen mode

O assistente irá configurar:

  1. Provedor de LLM (OpenRouter, Anthropic, OpenAI, etc.)
  2. Chaves de API (armazenadas em ~/.hermes/.env)
  3. Memória persistente
  4. Backend do terminal (local, Docker, SSH, nuvem)
  5. Integração com Telegram, Discord, Slack (opcional)

Configuração Manual

Edite diretamente:

hermes config edit
Enter fullscreen mode Exit fullscreen mode

Ou use comandos CLI:

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend local
hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set ANTHROPIC_API_KEY sk-ant-...
Enter fullscreen mode Exit fullscreen mode

Localização do Arquivo de Configuração

A configuração fica em ~/.hermes/:

~/.hermes/
├── config.yaml      # Config principal
├── .env            # Chaves de API
├── memory/         # Memória persistente
├── skills/         # Habilidades instaladas
└── plugins/        # Plugins personalizados
Enter fullscreen mode Exit fullscreen mode

Verifique Sua Configuração

Cheque a saúde do setup:

hermes doctor
Enter fullscreen mode Exit fullscreen mode

Verifica validade das configurações, chaves de API, status da memória, gateways e backend.

Escolhendo Seu Provedor de LLM

O Hermes suporta mais de 200 modelos de IA. Veja como configurar:

OpenRouter (Recomendado para Iniciantes)

Acesso a +200 modelos com uma chave de API, incluindo plano gratuito.

hermes config set model openrouter
hermes config set OPENROUTER_API_KEY sk-or-...
Enter fullscreen mode Exit fullscreen mode

Principais modelos no OpenRouter:

Modelo Caso de Uso Custo
anthropic/claude-opus-4 Codificação complexa, lógica $$$
anthropic/claude-sonnet-4 Equilibrado $$
openai/gpt-4o Propósito geral $$
google/gemini-pro-1.5 Contexto extenso $
meta/llama-3-70b Código aberto, rápido $

Anthropic Direto

Acesso direto aos modelos Claude.

hermes config set model anthropic
hermes config set ANTHROPIC_API_KEY sk-ant-...
hermes config set model.default claude-opus-4
Enter fullscreen mode Exit fullscreen mode

OpenAI Direto

Use GPT-4o e outros.

hermes config set model openai
hermes config set OPENAI_API_KEY sk-...
Enter fullscreen mode Exit fullscreen mode

Modelos Locais (Ollama)

Gratuito e privado.

# Instale o Ollama: https://ollama.ai
hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

Exemplos de Configuração de Modelo

Roteamento inteligente:

model:
  provider: openrouter
  default: anthropic/claude-opus-4
  fallback:
    - anthropic/claude-haiku-4-5
    - openai/gpt-4o-mini
Enter fullscreen mode Exit fullscreen mode

Controle de custos:

model:
  budget:
    daily_limit: 5.00  # USD
    monthly_limit: 100.00
Enter fullscreen mode Exit fullscreen mode

Uso Básico: Modo CLI

Iniciando o Hermes 

hermes
Enter fullscreen mode Exit fullscreen mode

Você verá um banner de boas-vindas. Converse imediatamente.

Comandos Básicos

Converse normalmente:

> Ei, pode me ajudar a escrever uma função Python para analisar JSON?
Enter fullscreen mode Exit fullscreen mode

Comandos de barra:

> /help          # Lista comandos
> /skills        # Lista habilidades
> /memory        # Status da memória
> /config        # Configuração atual
> /clear         # Limpar conversa
> /history       # Histórico de conversas
Enter fullscreen mode Exit fullscreen mode

Tarefas com arquivos:

> Olhe o arquivo ./src/main.py e refatore a conexão do banco de dados
Enter fullscreen mode Exit fullscreen mode

Execução de comandos:

> Run: npm install && npm run build
Enter fullscreen mode Exit fullscreen mode

O Hermes sempre pedirá confirmação antes de rodar comandos.

Shell Persistente

O Hermes mantém o estado do shell:

> cd /my/project && source venv/bin/activate
> python src/main.py  # Executa na mesma sessão
Enter fullscreen mode Exit fullscreen mode

Trabalhando com Arquivos

Ler:

> Mostre o conteúdo de config.yaml
Enter fullscreen mode Exit fullscreen mode

Editar:

> Em main.py, mude a porta do banco de dados de 5432 para 5433
Enter fullscreen mode Exit fullscreen mode

Criar:

> Crie utils.py com funções auxiliares para datas
Enter fullscreen mode Exit fullscreen mode

Fluxos de Trabalho Multi-Etapas

Exemplo:

> Preciso adicionar autenticação ao Flask:
> 1. Configurar modelos de banco
> 2. Criar endpoints login/logout
> 3. Adicionar JWT
> 4. Escrever testes
Enter fullscreen mode Exit fullscreen mode

O Hermes executa cada etapa, pedindo confirmação.

Gateway de Mensagens: Telegram, Discord, Slack

Permite interagir com o Hermes por chat.

Configuração do Telegram

  1. Crie um bot:

    • Abra o Telegram e procure por @botfather
    • Envie /newbot e siga as instruções
    • Copie o token do bot

  2. Configure o Hermes:

hermes config set TELEGRAM_BOT_TOKEN 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Enter fullscreen mode Exit fullscreen mode
  1. Inicie o gateway: 
hermes gateway setup telegram
hermes gateway start
Enter fullscreen mode Exit fullscreen mode
  1. Converse com o bot via Telegram.

Configuração do Discord

  1. Crie um aplicativo:

  2. Convide o bot para seu servidor

  3. Configure no Hermes:

hermes config set DISCORD_BOT_TOKEN MTIzNDU2...
hermes gateway setup discord
hermes gateway start
Enter fullscreen mode Exit fullscreen mode
  1. Use no Discord via menção ou DMs.

Configuração do Slack

  1. Crie um app em https://api.slack.com/apps

    • Adicione permissões de bot

  2. Instale no workspace e copie o token

  3. Configure:

hermes config set SLACK_BOT_TOKEN xoxb-...
hermes gateway setup slack
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Uso Multiplataforma

Execute múltiplos gateways:

hermes gateway start --all
Enter fullscreen mode Exit fullscreen mode

O Hermes sincroniza estado entre plataformas.

Integração com IDE: VS Code, JetBrains

VS Code

  1. Instale a extensão "Agent Communication Protocol" (ACP)
  2. Inicie o backend Hermes: 
hermes acp start
Enter fullscreen mode Exit fullscreen mode
  1. Selecione o Hermes como agente na sidebar do ACP

JetBrains (IntelliJ, PyCharm, etc.)

  1. Instale plugin ACP nas configurações
  2. Inicie o servidor ACP do Hermes: 
hermes acp start
Enter fullscreen mode Exit fullscreen mode
  1. Adicione Hermes como backend ACP nas configurações de IA

Editor Zed

  1. Configure no Zed: 
{
  "agent": {
    "provider": "acp",
    "endpoint": "hermes"
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Inicie o Hermes: 
hermes acp start
Enter fullscreen mode Exit fullscreen mode

Sistema de Memória e Aprendizagem

O diferencial do Hermes é sua arquitetura de memória.

Tipos de Memória

  • Episódica: Armazena sessões/conversas
  • Semântica: Constrói grafos de conhecimento
  • Processual (Habilidades): Tarefas reutilizáveis

Buscar interações:

> /memory search "migração de banco de dados"
> /memory projects
> /skills list
Enter fullscreen mode Exit fullscreen mode

Busca de Sessão 

> /memory search "Como lidamos com expiração de JWT na semana passada?"
Enter fullscreen mode Exit fullscreen mode

Dicas de Memória

O Hermes sugere informações relevantes automaticamente.

Compressão de Contexto

  • Compressão automática no gateway (85%)
  • Compressão em nível de agente (50%, ajustável)

Exportar e Backup

Exportar memória:

hermes memory export ~/backup/hermes-memory.json
Enter fullscreen mode Exit fullscreen mode

Importar memória:

hermes memory import ~/backup/hermes-memory.json
Enter fullscreen mode Exit fullscreen mode

Habilidades e Plugins

O Que São Habilidades?

Macros reutilizáveis para tarefas complexas.

Exemplos integrados:

  • code_review — Revisão de código
  • debug_session — Depuração
  • api_tester — Teste de APIs
  • git_workflow — Operações Git
  • documentation — Gerar docs a partir do código

Navegar e Instalar Habilidades

Listar habilidades:

> /skills list
Enter fullscreen mode Exit fullscreen mode

Instalar:

> /skills install code_review
Enter fullscreen mode Exit fullscreen mode

Usar:

> /skills run code_review ./src/auth.py
Enter fullscreen mode Exit fullscreen mode

Habilidades Personalizadas

Crie em ~/.hermes/skills/:

# ~/.hermes/skills/my_skill.py
from hermes.skills import Skill

class MyCustomSkill(Skill):
    name = "my_custom_skill"
    description = "Faz algo útil"

    def execute(self, context):
        return "Habilidade executada com sucesso"
Enter fullscreen mode Exit fullscreen mode

Sistema de Plugins

Crie plugins personalizados em ~/.hermes/plugins/:

# ~/.hermes/plugins/my_tool.py
from hermes.tools import Tool

class MyCustomTool(Tool):
    name = "my_tool"
    description = "Uma ferramenta personalizada"

    def run(self, **kwargs):
        return {"result": "sucesso"}
Enter fullscreen mode Exit fullscreen mode

Tipos de plugin: Ferramentas, Comandos, Hooks.

Recursos Avançados

Agendamento Cron

Agende tarefas automáticas:

> Configure um resumo diário das minhas notificações do GitHub às 9h
Enter fullscreen mode Exit fullscreen mode

Ou no config.yaml:

cron:
  - name: "Resumo Diário"
    schedule: "0 9 * * *"
    command: "/skills run github_digest"
    model: "anthropic/claude-haiku-4-5"
Enter fullscreen mode Exit fullscreen mode

Delegação de Subagentes

Trabalho paralelo:

> Revise todos os PRs e resuma as mudanças
Enter fullscreen mode Exit fullscreen mode

Modo de Voz

CLI:

hermes --voice
Enter fullscreen mode Exit fullscreen mode

Telegram/Discord: envie mensagem de voz.

Discord: Hermes pode entrar em canais de voz.

Controle do Navegador

Automação web:

> Vá para github.com e encontre os 5 repositórios Python mais populares
Enter fullscreen mode Exit fullscreen mode

Conectar ao Chrome via CDP:

hermes browser connect --cdp
Enter fullscreen mode Exit fullscreen mode

Integração MCP

Configuração:

mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]
    git:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-git"]
Enter fullscreen mode Exit fullscreen mode

Modo Worktree

Isolamento de worktree Git:

hermes -w
Enter fullscreen mode Exit fullscreen mode

Executar Outros Agentes

Chame outros agentes IA como subagentes:

> Use claude-code para revisar este pull request
Enter fullscreen mode Exit fullscreen mode

Solução de Problemas

Problemas Comuns

Chave de API não encontrada

hermes config get OPENROUTER_API_KEY
hermes config set OPENROUTER_API_KEY sk-or-...
Enter fullscreen mode Exit fullscreen mode

Modelo não disponível

hermes models list
hermes config set model anthropic/claude-opus-4
Enter fullscreen mode Exit fullscreen mode

Falha ao iniciar o Gateway

hermes gateway status
hermes gateway stop
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Corrupção de memória

hermes memory export ~/backup/memory-backup.json
hermes memory reset
hermes memory import ~/backup/memory-backup.json
Enter fullscreen mode Exit fullscreen mode

Obtendo Ajuda

Ajuda integrada:

> /help
Enter fullscreen mode Exit fullscreen mode

Ver logs:

hermes logs tail --follow
Enter fullscreen mode Exit fullscreen mode

Executar diagnósticos:

hermes doctor
Enter fullscreen mode Exit fullscreen mode

FAQ

Quanto custa para rodar o Hermes?

O Hermes é gratuito; você paga apenas pelo uso do LLM.

  • Uso leve: $5-15/mês (OpenRouter)
  • Uso moderado: $20-50/mês
  • Uso intenso: $50-200/mês
  • Modelos locais (Ollama): grátis, exige hardware

O Hermes pode rodar 24/7?

Sim, em VPS:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes service install
hermes service start
Enter fullscreen mode Exit fullscreen mode

O Hermes é adequado para uso empresarial?

Sim. Recursos:

  • Gateway multiusuário com isolamento
  • Redação de PII
  • Segurança reforçada
  • Implantação self-hosted
  • Auditoria

Como migrar do OpenClaw? 

hermes claw migrate --dry-run
hermes claw migrate
hermes doctor
Enter fullscreen mode Exit fullscreen mode

Posso usar o Hermes sem internet?

Sim, com modelos locais:

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen2.5-coder:32b
hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

Qual a diferença entre Hermes e ChatGPT?

Recurso Hermes ChatGPT
Memória Persistente, pesquisável Apenas na sessão
Implantação Auto-hospedado, 24/7 Apenas na nuvem
Modelos +200 modelos Apenas GPT
Extensibilidade Plugins, habilidades Limitada
Custo Pague pelo uso Assinatura
Privacidade Você controla os dados OpenAI armazena dados

Como faço backup dos meus dados do Hermes? 

hermes export --all ~/backup/hermes-full-backup.tar.gz
Enter fullscreen mode Exit fullscreen mode

O Hermes pode acessar meus arquivos locais?

Apenas os arquivos/diretórios explicitamente autorizados. Por padrão, não há acesso irrestrito.

💡 Quer testar APIs como parte do seu fluxo de trabalho de desenvolvimento impulsionado por IA? Conheça o Apidog, a plataforma completa de desenvolvimento de API para projetar, testar e documentar APIs.

Top comments (0)