Usar Apexnova AI Hub con Hermes Agent

Hermes Agent es el agente de terminal de código abierto de Nous Research (licencia MIT), con memoria persistente, uso de herramientas y sistema de habilidades. Funciona con cualquier endpoint compatible con OpenAI, así que basta su opción de endpoint personalizado más la base URL de la plataforma y un nombre de modelo.

Usa el endpoint estándar de chat completions (/v1/chat/completions), la misma ruta que los SDK y el Playground, con idéntica autenticación, límites, descuentos y facturación.

Dos requisitos obligatorios al elegir modelo

Elige el modelo antes de configurar nada: si falla cualquiera de los dos, tendrás que empezar de nuevo a mitad de camino. Ambos figuran en la ficha del modelo en el catálogo.

• Una ventana de contexto de al menos 64.000 tokens. Hermes documenta este mínimo para uso como agente con herramientas y rechaza al arrancar las ventanas menores: el prompt de sistema, los esquemas de herramientas y el estado de la conversación ya ocupan buena parte antes de que escribas nada. Es un mínimo, no una recomendación.
• Soporte de llamadas a herramientas (function calling). Leer y escribir archivos, ejecutar comandos y buscar se apoyan en ellas; sin eso el modelo solo puede conversar.

Antes de empezar

• Una API key creada en API Keys dentro de la consola. El valor sk- completo solo se muestra una vez, guárdalo en ese momento.
• Un modelo de chat del catálogo de modelos que cumpla los dos requisitos anteriores: anota su Public Model Name y su longitud de contexto, porque harán falta los dos.
• Saldo positivo en la cuenta. Sin saldo la API devuelve HTTP 402.

1. Instalar Hermes Agent

El instalador oficial trae sus propias dependencias — Python 3.11, Node.js, ripgrep, ffmpeg — y en Windows un Git portátil que no toca el Git del sistema:

# Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# Reload your shell, then start it
hermes

2. Conectar la plataforma con el asistente (recomendado)

La vía documentada es el asistente interactivo, que pide tres datos:

hermes model

# Select "Custom endpoint (self-hosted / VLLM / etc.)", then enter:
#   API base URL : https://api.apexnova-consulting.com/v1
#   API key      : sk-xxxxxxxx
#   Model name   : glm-4.6

⚠️ Ejecuta hermes model en la terminal, no dentro de una sesión. El /model de la sesión solo cambia entre proveedores ya configurados: no puede añadir uno ni pedirte una clave. Para añadir un proveedor, sal antes de la sesión (Ctrl+C o /quit).

3. O editar config.yaml directamente

El asistente escribe este archivo, y también puedes editar ~/.hermes/config.yaml tú mismo:

# ~/.hermes/config.yaml
model:
  default: glm-4.6                                   # a Public Model Name
  provider: custom
  base_url: https://api.apexnova-consulting.com/v1
  api_key: sk-xxxxxxxx
  context_length: 128000                             # must be at least 64000

Para que la clave no quede en config.yaml — o si ya apuntas Hermes a otro endpoint — usa un proveedor con nombre: la clave sale de una variable de entorno y en el archivo solo queda el nombre de la variable.

# ~/.hermes/config.yaml
providers:
  apexnova:
    api: https://api.apexnova-consulting.com/v1
    key_env: APEXNOVA_API_KEY
    transport: chat_completions
    default_model: glm-4.6
    context_length: 128000

4. Verificar

Llama primero con curl al endpoint de chat completions, así distingues un error de configuración del comportamiento propio de Hermes:

curl https://api.apexnova-consulting.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.6",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Después arranca Hermes y selecciona el modelo explícitamente:

hermes

# Inside the session, pick the model explicitly:
/model custom:glm-4.6              # single custom endpoint
/model custom:apexnova:glm-4.6     # named provider

Por último, comprueba en «Uso» de la consola que aparece la llamada con ese modelo. Ten en cuenta que /model custom a secas solo autoselecciona cuando el endpoint tiene exactamente un modelo cargado; la plataforma sirve un catálogo entero, así que nombra el modelo.

Diagnóstico

• Rechazado al arrancar por contexto insuficiente —— Cambia a un modelo con al menos 64k de contexto, o corrige context_length en config.yaml con el valor real del catálogo. Este mínimo es de Hermes, no de la plataforma.
• 401 —— La clave es incorrecta o está revocada. Con un proveedor con nombre, comprueba que la variable que indica key_env existe en la shell desde la que lanzaste hermes.
• 404 model_not_found —— El nombre en default o en /model no es un Public Model Name de la plataforma, o el modelo queda fuera de la lista blanca del espacio de trabajo de esa clave, o es un modelo privado sin autorizar.
• 429 —— Un tope de presupuesto del espacio de trabajo o de la clave, o un límite de RPM/TPM. Un agente encadena varias llamadas por su cuenta, así que los alcanza antes que un chat escrito a mano.
• Los modelos de la plataforma no aparecen en /model —— /model solo cambia entre proveedores configurados. Si aún no has dado de alta el endpoint personalizado, sal de la sesión, ejecuta hermes model para añadirlo y abre una sesión nueva.

Buenas prácticas

• Dale a Hermes su propia clave dentro de su propio espacio de trabajo, con tope de presupuesto y límites de RPM/TPM. Un agente llama de forma autónoma y a ráfagas: si se desboca, prefieres que choque contra el tope y no contra el saldo.
• Las tareas auxiliares de Hermes — títulos de conversación, compresión de contexto, visión — siguen por defecto a tu modelo principal. Suman bastante, así que vale la pena apuntarlas a un modelo más barato de la plataforma.
• Si apuntas Hermes a más de un endpoint, o sincronizas la configuración entre equipos, usa un proveedor con nombre y key_env: la clave se queda en el entorno y config.yaml se puede compartir sin riesgo.
• Configura una cadena de conmutación por error en «Fallback de modelos» para que un fallo del proveedor no interrumpa una ejecución. La facturación sigue al modelo que realmente respondió.