Hermes Agent: Cómo Configurarlo Paso a Paso

Hermes Agent no es un npm install y ya. Es un framework que necesita potencia cerebral detrás — ya sea en forma de GPU local o de API key con saldo. Esto es lo que necesitas tener listo:

Hardware (si quieres local)

Para que Hermes genere skills útiles (no scripts llenos de bugs), el modelo necesita ser potente. En mi experiencia, con menos de 24GB de VRAM los resultados son inconsistentes. Si tienes una RTX 3090 o 4090, estás del otro lado. Si tienes menos, vas a sufrir con modelos 7B que escriben skills mediocres.

Yo empecé con una RTX 3080 (10GB) y tuve que rendirme a los 3 días — las skills que generaba Llama 3 8B eran básicamente inútiles para tareas complejas. Me cambié a OpenRouter (API) y la diferencia fue abismal.

API key de OpenRouter (recomendado para empezar)

Si no tienes GPU sobrada, usa OpenRouter. Te da acceso a decenas de modelos y solo pagas por uso. Para empezar, te recomiendo estos modelos:

• NousResearch Hermes 3 405B — el mejor para generar skills de calidad. ~$2-3 por hora de uso intensivo
• DeepSeek V4 Flash — mucho más barato ($0.10/M tokens), buena relación calidad-precio para skills simples
• Claude 3.5 Sonnet — excelente pero caro. Solo si necesitas skills muy complejas

Regístrate en openrouter.ai, genera una API key, y métete unos dólares de prueba. Con $10 tienes para experimentar una semana larga.

Python 3.10+

Hermes corre en Python. Necesitas Python 3.10 o superior. Para verificarlo:

python3 --version
# Tiene que decir Python 3.10.x o superior

Si tienes Python 3.8 o 3.9, vas a tener problemas de dependencias. Usa pyenv para instalar una versión moderna sin romper tu sistema:

# Instalar pyenv (macOS/Linux)
curl https://pyenv.run | bash

# Instalar Python 3.11
pyenv install 3.11
pyenv global 3.11

# Verificar
python3 --version  # → Python 3.11.x

Git

Necesitas git para clonar el repositorio. Si estás en macOS o Linux, ya lo tienes. En Windows, instala Git for Windows.

Una vez que tienes los prerrequisitos, la instalación es directa. Estos son los pasos exactos que he validado en Ubuntu 24.04 y macOS Sonoma:

Paso 1: Clonar el repositorio

git clone https://github.com/NousResearch/hermes-function-calling.git
cd hermes-function-calling

Paso 2: Crear y activar un entorno virtual

Nunca instales dependencias de Python directamente en el sistema. Usa un venv:

python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# En Windows: .venvScriptsactivate

Paso 3: Instalar dependencias

pip install -r requirements.txt

Esto instala todo lo que Hermes necesita: transformers, torch, httpx, pyyaml, y demás. Si tienes problemas con torch (gordísimo), puedes instalar la versión CPU-only para empezar:

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt

⚠️ Pitfall real: Si estás en macOS con Apple Silicon (M1/M2/M3), torch se instala con soporte Metal por defecto. Si ves errores de libomp, instala brew install libomp y vuelve a intentar.

Paso 4: Copiar la configuración por defecto

cp config.yaml.example config.yaml

Este archivo es el corazón de Hermes. Ahí defines qué modelo usa, cómo se conecta, y dónde guarda sus skills. Vamos a editarlo en la siguiente sección.

Paso 5: Test rápido

Antes de configurar nada, verifica que Hermes arranca:

python run_agent.py --help

Si ves la ayuda con todas las opciones, la instalación está correcta. Si te sale un traceback de Python, algo falló en los pasos anteriores.

El config.yaml es donde Hermes aprende quién es y cómo trabaja. Aquí te explico cada sección con valores reales que he usado:

Configuración básica del modelo

# Para usar OpenRouter (API, sin GPU local)
model:
  provider: openrouter
  name: nousresearch/hermes-3-llama-3.1-405b
  api_key: ${OPENROUTER_API_KEY}

El ${OPENROUTER_API_KEY} es una variable de entorno. Crea un archivo .env en la raíz del proyecto o exporta la variable en tu ~/.bashrc:

export OPENROUTER_API_KEY="sk-or-v1-tu-api-key-aqui"

También puedes escribir la key directamente en el YAML, pero no lo hagas — acaba en GitHub y te la roban.

Configuración con Ollama (modelo local)

# Para usar modelo local
model:
  provider: ollama
  name: llama3:70b
  base_url: http://localhost:11434

Nota importante: Si usas Ollama, el modelo debe estar descargado antes de arrancar Hermes. ollama pull llama3:70b descarga ~40GB así que hazlo con tiempo y buena conexión.

Configuración multi-modelo (mi setup favorito)

Hermes permite usar modelos diferentes según la tarea. Esto es muy útil para optimizar costes:

models:
  default:
    provider: openrouter
    name: nousresearch/hermes-3-llama-3.1-405b
  cheap:
    provider: openrouter
    name: deepseek/deepseek-v4-flash
  code:
    provider: ollama
    name: codellama:34b

Con esta configuración, Hermes usa el modelo 405B para tareas complejas (generar skills nuevas), DeepSeek para tareas simples (buscar información), y CodeLlama para tareas de programación. El ahorro es brutal — bajé mi gasto mensual de ~$120 a ~$35 usando esta estrategia.

Sección de skills

skills:
  directory: ./skills
  max_skills: 50
  auto_generate: true

• directory: dónde guarda las skills autogeneradas. Por defecto ./skills/
• max_skills: número máximo de skills que mantiene. Cuando llegas al límite, Hermes borra las menos usadas. 50 es un buen número para empezar
• auto_generate: si está en true, Hermes genera skills automáticamente cuando se enfrenta a una tarea nueva. Si lo pones en false, solo usa las skills que tú crees manualmente

Una de las funciones que más me costó encontrar (y que más útiles me han resultado) es el sistema de perfiles de Hermes. Te permite tener configuraciones separadas para proyectos distintos.

Por defecto, Hermes usa el perfil default que está en ~/.hermes/config.yaml. Pero puedes crear perfiles adicionales:

# Crear un perfil para un proyecto específico
hermes-agent --profile mi-proyecto --create

# Usar un perfil específico
hermes-agent --profile mi-proyecto --task "analiza estos datos"

Cada perfil tiene su propia carpeta en ~/.hermes/profiles/<nombre>/ con:

• config.yaml — configuración específica del perfil
• skills/ — skills generadas para ese proyecto
• memories/ — memoria persistente del agente para ese contexto
• cron/ — tareas programadas específicas del perfil
• plugins/ — plugins cargados solo en ese perfil

Caso de uso real: Yo tengo un perfil dev para proyectos de programación (con CodeLlama como modelo principal y skills de Git, Docker, Python), y un perfil research para investigación de mercado (con Hermes 3 405B y skills de web scraping, análisis de datos). Así no se mezclan las skills de un contexto con el otro.

Cómo crear un perfil desde config.yaml

# ~/.hermes/config.yaml (perfil default)
profiles:
  dev:
    model:
      provider: openrouter
      name: codellama/codellama-34b
    skills:
      directory: ~/.hermes/profiles/dev/skills
  research:
    model:
      provider: openrouter
      name: nousresearch/hermes-3-llama-3.1-405b
    skills:
      directory: ~/.hermes/profiles/research/skills

Con esto, cuando ejecutas hermes-agent --profile dev, Hermes carga automáticamente la configuración de ese perfil.

La magia de Hermes empieza cuando le pides hacer algo y él mismo se inventa la skill para hacerlo. Aquí te muestro cómo funciona con un ejemplo real:

Pide algo que no sabe hacer

hermes-agent --task "Busca el precio actual del Bitcoin en CoinGecko y guárdalo en un archivo JSON"

Lo que pasa internamente:

1. Hermes analiza la tarea y determina que necesita hacer una petición HTTP a una API
2. Como no tiene una skill para eso, le pide al modelo de IA que genere código Python
3. Ejecuta el código generado
4. Si funciona, guarda la skill como skills/coingecko-price.md
5. La próxima vez que pidas algo similar, Hermes reutiliza esa skill sin generar código nuevo

Es fascinante verlo en acción la primera vez. Pero también tiene su lado frustrante: el código generado puede tener bugs, especialmente si el modelo no es lo suficientemente potente.

Mi recomendación después de usarlo 3 meses: revisa siempre las skills autogeneradas antes de reutilizarlas en producción. En mis primeras semanas, Hermes generó una skill de web scraping que funcionaba perfectamente... hasta que la página web cambió su estructura HTML y la skill empezó a devolver datos vacíos. Sin una review humana, ese bug pasa desapercibido hasta que alguien confía en los datos incorrectos.

Skills manuales: cuando quieres control total

Si prefieres escribir tus propias skills (más trabajo, más control), el formato es simple. Cada skill es un archivo Markdown con esta estructura:

# skill-name

## Description
Qué hace esta skill

## Code
```python
def run(input_data):
    # tu código aquí
    return resultado
```

## Parameters
- param1: descripción
- param2: descripción

## Example
```
hermes-agent --skill skill-name --param1 valor
```

Las skills manuales tienen prioridad sobre las autogeneradas. Si creas una skill con el mismo nombre que una autogenerada, la manual gana.

Después de meses usando Hermes, estos son los errores que más me han aparecido y cómo los resolví:

Error 1: "ModuleNotFoundError" al importar dependencias

Síntoma: ImportError cuando ejecutas cualquier comando.

Causa: El venv no está activado o instalaste dependencias fuera del venv.

Solución:

source .venv/bin/activate  # activa el venv
pip list | grep -i hermes    # verifica que hermes está instalado
pip install -r requirements.txt  # reinstala si es necesario

Error 2: La skill generada no funciona o tira error

Síntoma: Hermes genera una skill, pero al ejecutarla falla con un error de Python.

Causa: El modelo de IA generó código con bugs. Pasa sobre todo con modelos pequeños (7B-13B).

Solución: Usa un modelo más potente. Si estás con Ollama, cambia a llama3:70b o mixtral:8x7b. Si estás en API, usa nousresearch/hermes-3-llama-3.1-405b. También puedes editar la skill manualmente en el archivo .md — el formato es sencillo.

Error 3: "Rate limit exceeded" en OpenRouter

Síntoma: Hermes se queda colgado después de unas cuantas ejecuciones.

Causa: Llegaste al límite de requests por minuto de OpenRouter (depende de tu plan).

Solución: Añade una pausa entre ejecuciones en el config.yaml:

rate_limit:
  requests_per_minute: 10
  retry_delay: 5  # segundos entre reintentos

Error 4: Hermes no encuentra skills existentes y regenera las mismas

Síntoma: Cada vez que pides lo mismo, Hermes genera una skill nueva en vez de reutilizar la que ya tiene.

Causa: El directorio de skills no está correctamente configurado, o el matching de nombres falla.

Solución: Verifica que skills.directory en config.yaml apunta a la carpeta correcta. Si usas perfiles, asegúrate de que cada perfil tiene su propio directorio de skills.

Después de meses usando Hermes Agent en proyectos reales, estos son los consejos que más me habría gustado tener desde el día uno:

Empieza con API, no con local. Configurar modelos locales es una pérdida de tiempo si tu objetivo es aprender a usar Hermes. OpenRouter te da resultados en 5 minutos. El setup local, si no tienes la GPU adecuada, es frustrante y lento. Una vez que entiendas cómo funciona Hermes, entonces prueba con local si te interesa.

Usa perfiles desde el principio. Separar proyectos en perfiles distintos te ahorra dolores de cabeza cuando llevas semanas de uso y tienes 40 skills mezcladas. Cuesta 5 minutos configurarlo y te ahorra horas de confusión después.

Revisa las skills generadas. Hermes es impresionante cuando funciona, pero no es perfecto. Las skills autogeneradas pueden tener errores sutiles que solo aparecen en casos borde. Acostúmbrate a leer el código que genera antes de confiar ciegamente en él.

Monitorea el gasto de API. Si usas OpenRouter, el gasto se acumula rápido. Yo aprendí esta lección cuando recibí una factura de $47 en una semana de pruebas intensivas con Claude Sonnet. Pon límites de gasto en OpenRouter (Settings → Spending limits) y usa modelos baratos para tareas sencillas.

Si quieres entender mejor cómo Hermes encaja en el ecosistema de agentes de IA, te recomiendo leer Hermes Agent a Fondo (el review general que escribí antes) y Agentes IA Open Source 2026 para ver alternativas. Para una visión más amplia de los conceptos, ¿Qué son los Agentes de IA? cubre los fundamentos.

→ También te puede interesar: implantación en empresas.