Ferramentas e conjuntos de ferramentas

Ferramentas são funções que ampliam o que o agente sabe fazer. Elas ficam organizadas em conjuntos de ferramentas lógicos, que você pode ligar ou desligar por plataforma.

Ferramentas disponíveis

O Hermes vem com um registro embutido e amplo de ferramentas, que cobre busca na web, automação de navegador, execução de terminal, edição de arquivos, memória, delegação, tarefas agendadas, Home Assistant e mais.

observação

A memória entre sessões do Honcho vem como plugin de provedor de memória (plugins/memory/honcho/), não como conjunto embutido. Veja Plugins para instalar.

Categorias de alto nível:

Categoria	Exemplos	Descrição
Web	web_search, web_extract	Busque na web e extraia o conteúdo das páginas.
Busca no X	x_search	Busque posts e threads do X (Twitter) pela ferramenta x_search embutida das Responses da xAI — depende de credenciais da xAI (OAuth do SuperGrok ou XAI_API_KEY); vem desligada, ative em hermes tools → 🐦 X (Twitter) Search.
Terminal e arquivos	terminal, process, read_file, patch	Execute comandos e manipule arquivos.
Navegador	browser_navigate, browser_snapshot, browser_vision	Automação interativa de navegador, com suporte a texto e visão.
Mídia	vision_analyze, image_generate, text_to_speech	Análise e geração multimodal.
Orquestração de agentes	todo, clarify, execute_code, delegate_task	Planejamento, esclarecimento, execução de código e delegação para subagentes.
Memória e recuperação	memory, session_search	Memória persistente e busca em sessões.
Automação	cronjob	Tarefas agendadas, com ações de criar/listar/atualizar/pausar/retomar/rodar/remover. A entrega de saída fica por conta da entrega do próprio cron, da CLI hermes send e do notificador do gateway — não de uma ferramenta que o agente possa chamar.
Integrações	ha_*, ferramentas de servidor MCP	Home Assistant, MCP e outras integrações.

Para o registro oficial, derivado do código, veja a Referência de ferramentas embutidas e a Referência de conjuntos de ferramentas.

Nous Tool Gateway

Assinantes pagos do Nous Portal podem usar busca na web, geração de imagem, TTS e automação de navegador pelo Tool Gateway — sem precisar de chaves de API separadas. Rode hermes model para ativar, ou configure ferramentas individuais com hermes tools.

Usar conjuntos de ferramentas

# Use conjuntos específicos
hermes chat --toolsets "web,terminal"

# Veja todas as ferramentas disponíveis
hermes tools

# Configure as ferramentas por plataforma (interativo)
hermes tools

Entre os conjuntos mais comuns estão web, search, terminal, file, browser, vision, image_gen, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, messaging, spotify, discord, discord_admin, debugging e safe.

Veja a Referência de conjuntos de ferramentas para o conjunto completo, incluindo os presets de plataforma como hermes-cli e hermes-telegram, e os conjuntos dinâmicos de MCP como mcp-<server>.

Anotações no resultado das ferramentas

Alguns comportamentos das ferramentas valem a pena conhecer na hora de ler as transcrições do agente:

• Mortes por sinal são explicadas. Quando um comando de terminal é morto por um sinal, o resultado traz uma nota legível em vez de um código numérico seco — por exemplo, a saída -9/137 vira "terminated by signal 9: SIGKILL — often the kernel OOM killer on memory exhaustion, or an explicit kill -9", e falhas de segmentação, aborts, SIGTERM, canos quebrados e limites de CPU/tamanho de arquivo ganham rótulos do mesmo tipo. Códigos negativos (semântica de subprocesso) são afirmados com certeza; a convenção 128+signum do shell vem com um "usually", já que um aplicativo pode legitimamente sair com esses códigos.
• Arquivos de texto em UTF-16 são transcodificados, não recusados. O read_file detecta UTF-16 (por BOM ou heurística de padrão de bytes, em qualquer endianness — comum em arquivos do Bloco de Notas do Windows e em redirecionamentos > do PowerShell) e transcodifica para UTF-8 na exibição, em vez de marcar o arquivo como binário. O resultado inclui uma dica informando a conversão; edições via patch/write_file gravam de novo em UTF-8. Arquivos acima de 10 MB e arquivos realmente binários continuam recebendo a recusa de arquivo binário.

Backends de terminal

A ferramenta de terminal pode executar comandos em ambientes diferentes:

Backend	Descrição	Caso de uso
local	Roda na sua máquina (padrão)	Desenvolvimento, tarefas confiáveis
docker	Contêineres isolados	Segurança, reprodutibilidade
ssh	Servidor remoto	Isolamento, manter o agente longe do próprio código
singularity	Contêineres de HPC	Computação em cluster, sem root
modal	Execução na nuvem	Serverless, escala
daytona	Espaço de trabalho sandbox na nuvem	Ambientes remotos de desenvolvimento persistentes
vercel_sandbox	microVM na nuvem do Vercel Sandbox	Execução na nuvem com persistência de sistema de arquivos por snapshot

Configuração

# Em ~/.hermes/config.yaml
terminal:
  backend: local    # ou: docker, ssh, singularity, modal, daytona, vercel_sandbox
  cwd: "."          # Diretório de trabalho
  timeout: 180      # Tempo limite do comando, em segundos

Arquivos de inicialização do shell e comandos não interativos

As chamadas de terminal do agente rodam o seu shell de forma não interativa — não há TTY nem gente no prompt. Uma inicialização de shell pesada ou interativa, que você nem percebe num terminal normal, pode quebrar ou deixar bem mais lento todo comando que o agente roda:

• Init lento (nvm, gerenciadores de versão, prompts que acessam a rede): o clássico carregamento do nvm.sh acrescenta latência perceptível a cada abertura de shell, e o agente abre muitos shells. Arquivos rc de vários segundos transformam um git status rápido em risco de tempo limite.
• Blocos que esperam um TTY: qualquer coisa no .bashrc/.zshrc que faça pergunta, rode um attach de tmux/screen, chame read ou imprima um menu vai travar um shell não interativo — o comando parece rodar para sempre e depois estoura o tempo limite.
• Saída incondicional: arquivos rc que dão echo em banners poluem a saída de todo comando que o agente precisa interpretar.

A correção é a guarda padrão que a maioria das distribuições já coloca no topo do .bashrc — retorne cedo quando o shell for não interativo e deixe tudo que é pesado ou interativo abaixo dela:

# ~/.bashrc — mantenha esta guarda perto do topo
case $- in
  *i*) ;;      # interativo: continue
  *) return;;  # não interativo: pare aqui
esac

# o init pesado/interativo vai ABAIXO da guarda
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Quem usa zsh: coloque a configuração só de login no .zprofile e a configuração só interativa no .zshrc; mantenha o .zshenv mínimo, já que ele roda para todo shell, inclusive os não interativos. Se o agente realmente precisar de uma ferramenta que só o seu arquivo rc coloca no PATH, exporte a mudança de PATH acima da guarda (exportar caminho é barato) ou crie um link simbólico do binário em ~/.local/bin.

Se os comandos de terminal do agente travam ou estouram o tempo limite logo depois de funcionarem no seu próprio terminal, o primeiro suspeito é o init do seu shell.

Backend Docker

terminal:
  backend: docker
  docker_image: python:3.11-slim

Um contêiner persistente, compartilhado pelo processo inteiro. O Hermes sobe um único contêiner de vida longa no primeiro uso (docker run -d ... sleep infinity) e roteia toda chamada de terminal, de arquivo e de execute_code por um docker exec nesse mesmo contêiner. Mudanças de diretório de trabalho, pacotes instalados, ajustes de ambiente e arquivos escritos em /workspace sobrevivem de uma chamada de ferramenta para a outra, atravessam /new, /reset e subagentes de delegate_task, durante toda a vida do processo do Hermes. O contêiner é parado e removido no desligamento.

Isso quer dizer que o backend Docker se comporta como uma VM sandbox persistente, não como um contêiner novo a cada comando. Se você fizer pip install foo uma vez, ele fica lá pelo resto da sessão. Se você fizer cd /workspace/projeto, as chamadas seguintes de ls enxergam esse diretório. Veja Configuração → Backend Docker para os detalhes completos de ciclo de vida e para a flag container_persistent, que controla se /workspace e /root sobrevivem a reinícios do Hermes.

Backend SSH

Recomendado por segurança — o agente não consegue alterar o próprio código:

terminal:
  backend: ssh

# Defina as credenciais em ~/.hermes/.env
TERMINAL_SSH_HOST=meu-servidor.exemplo.com
TERMINAL_SSH_USER=meuusuario
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Singularity/Apptainer

# Construa o SIF antes, para os workers paralelos
apptainer build ~/python.sif docker://python:3.11-slim

# Configure
hermes config set terminal.backend singularity
hermes config set terminal.singularity_image ~/python.sif

Modal (nuvem serverless)

uv pip install modal
modal setup
hermes config set terminal.backend modal

Vercel Sandbox

pip install 'hermes-agent[vercel]'
hermes config set terminal.backend vercel_sandbox
hermes config set terminal.vercel_runtime node24

Autentique com os três: VERCEL_TOKEN, VERCEL_PROJECT_ID e VERCEL_TEAM_ID. Essa configuração por token de acesso é o caminho com suporte para implantações e para processos normais e de longa duração do Hermes na Render, na Railway, no Docker e em hospedagens parecidas. Os runtimes com suporte são node24, node22 e python3.13; por padrão, o Hermes usa /vercel/sandbox como raiz do espaço de trabalho remoto.

Para desenvolvimento local pontual, o Hermes também aceita tokens OIDC de curta duração do Vercel:

VERCEL_OIDC_TOKEN="$(vc project token <nome-do-projeto>)" hermes chat

De dentro de um diretório de projeto já vinculado ao Vercel:

VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat

Com container_persistent: true, o Hermes usa snapshots do Vercel para preservar o estado do sistema de arquivos quando o sandbox é recriado para a mesma tarefa. Isso pode incluir credenciais sincronizadas pelo Hermes, skills e arquivos de cache dentro do sandbox. Os snapshots não preservam processos vivos, o espaço de PIDs, nem a mesma identidade de sandbox ativa.

Comandos de terminal em segundo plano usam o fluxo genérico de processo não local do Hermes: spawn, poll, wait, log e kill funcionam pela ferramenta normal de processo enquanto o sandbox está vivo, mas o Hermes não oferece recuperação nativa de processos desanexados do Vercel depois de uma limpeza ou reinício.

Deixe o container_disk sem valor ou no padrão compartilhado 51200; dimensionamento personalizado de disco não tem suporte no Vercel Sandbox e vai fazer falhar o diagnóstico e a criação do backend.

Recursos do contêiner

Configure CPU, memória, disco e persistência para todos os backends de contêiner:

terminal:
  backend: docker  # ou singularity, modal, daytona, vercel_sandbox
  container_cpu: 1              # Núcleos de CPU (padrão: 1)
  container_memory: 5120        # Memória em MB (padrão: 5GB)
  container_disk: 51200         # Disco em MB (padrão: 50GB)
  container_persistent: true    # Persistir o sistema de arquivos entre sessões (padrão: true)

Com container_persistent: true, os pacotes instalados, os arquivos e a configuração sobrevivem entre sessões.

Segurança do contêiner

Todos os backends de contêiner rodam com endurecimento de segurança:

• Sistema de arquivos raiz somente leitura (Docker)
• Todas as capabilities do Linux removidas
• Sem escalonamento de privilégio
• Limite de PIDs (256 processos)
• Isolamento total de namespaces
• Espaço de trabalho persistente por volumes, não pela camada raiz gravável

O Docker pode, opcionalmente, receber uma lista explícita de permissão de variáveis de ambiente pelo terminal.docker_forward_env, mas as variáveis repassadas ficam visíveis para os comandos dentro do contêiner e devem ser tratadas como expostas àquela sessão.

Gerenciamento de processos em segundo plano

Inicie processos em segundo plano e gerencie-os:

terminal(command="pytest -v tests/", background=true)
# Devolve: {"session_id": "proc_abc123", "pid": 12345}

# Depois, gerencie com a ferramenta process:
process(action="list")       # Mostra todos os processos em execução
process(action="poll", session_id="proc_abc123")   # Confere o status
process(action="wait", session_id="proc_abc123")   # Bloqueia até terminar
process(action="log", session_id="proc_abc123")    # Saída completa
process(action="kill", session_id="proc_abc123")   # Encerra
process(action="write", session_id="proc_abc123", data="y")  # Manda entrada

O modo PTY (pty=true) habilita ferramentas de CLI interativas, como o Codex e o Claude Code.

Suporte a sudo

Se um comando precisar de sudo, você vai receber um pedido de senha (guardado em cache pela sessão). Ou defina SUDO_PASSWORD em ~/.hermes/.env.

aviso

Nas plataformas de mensagens, se o sudo falhar, a saída inclui uma dica para acrescentar SUDO_PASSWORD ao ~/.hermes/.env.

---