Cómo convertir un agente Hermes en una API privada lista para clientes

Configuración base del gateway

Usa placeholders genéricos. Cada cliente debe tener su propio puerto, token, perfil y ruta de persistencia.

platforms:
  api_server:
    enabled: true
    host: "127.0.0.1"   # o 0.0.0.0 SOLO dentro de Docker privado
    port: 8642

platform_toolsets:
  api_server:
    - clarify
    - crm-tools
    - knowledge-search

tools:
  api_server:
    disabled:
      - terminal
      - process
      - execute_code
      - write_file
      - patch
      - cronjob
      - delegate_task
      - web_search
      - browser_navigate

API_SERVER_KEY="generar-con-openssl-rand-hex-32"
API_SERVER_HOST="127.0.0.1"
API_SERVER_PORT="8642"
API_SERVER_CORS_ORIGINS="https://app.cliente.com"
API_SERVER_MODEL_NAME="agente-ventas"

# Provider LLM
NAN_API_KEY="..."
HERMES_MODEL="qwen3.6"

# Tools internas
CRM_TOOL_BASE_URL="http://app-interna:3000"
AGENT_TOOLS_SECRET="otro-secreto-fuerte"

Si corres en Docker, el bind 0.0.0.0 es aceptable solo si el puerto no se publica al host y la comunicación ocurre por red interna.

Middleware mínimo en Node/Next.js

export async function POST(request) {
  const { message, userId } = await request.json();

  const response = await fetch(`${process.env.HERMES_URL}/v1/chat/completions`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.HERMES_API_KEY}`,
      "Content-Type": "application/json",
      "X-Hermes-Session-Key": `web:${userId}`,
    },
    body: JSON.stringify({
      model: process.env.HERMES_MODEL,
      messages: [{ role: "user", content: message }],
      stream: false,
    }),
  });

  if (!response.ok) return Response.json({ error: "agent_unavailable" }, { status: 502 });
  const data = await response.json();
  return Response.json({ answer: data.choices?.[0]?.message?.content ?? "" });
}

Validación antes de entregar

Referencia completa del API Server

¿Qué es el API Server? Es el adaptador HTTP de Hermes Agent. Mantiene compatibilidad OpenAI-compatible, sesiones nativas, ejecución de herramientas en servidor y runs estructurados para procesos largos.

Esta sección conserva los puntos operativos importantes de la guía base, adaptados a un documento genérico para clientes y equipos técnicos.

Reglas duras del servidor

• El gateway se niega a arrancar si API_SERVER_KEY no está configurada.
• Si el bind es accesible por red, rechaza claves placeholder o débiles.
• Límite de body: 10 MB.
• Los headers de sesión deben tener longitud acotada para evitar abuso.
• Los logs no deben imprimir tokens, claves, teléfonos ni payloads sensibles.

Endpoints disponibles

Autenticación y headers especiales

Todas las rutas operativas deben usar Authorization: Bearer <API_SERVER_KEY>. El servidor compara el token con una comparación segura tipo hmac.compare_digest(); un fallo debe devolver un 401 con error tipo Invalid API key.

Ejemplo con Python requests

import requests

BASE = "http://localhost:8642"
API_KEY = "usar-variable-de-entorno"

response = requests.post(
    f"{BASE}/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "X-Hermes-Session-Key": "lead:web:123",
    },
    json={
        "model": "agente-ventas",
        "messages": [
            {"role": "user", "content": "Resume este lead y clasifica urgencia."}
        ],
    },
    timeout=60,
)
print(response.json()["choices"][0]["message"]["content"])

Ejemplo con SDK oficial de OpenAI

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="usar-variable-de-entorno",
    default_headers={
        "X-Hermes-Session-Key": "cliente:crm:123"
    },
)

response = client.chat.completions.create(
    model="agente-ventas",
    messages=[
        {"role": "system", "content": "Eres un asistente comercial claro y breve."},
        {"role": "user", "content": "¿Qué información falta para cotizar?"},
    ],
)
print(response.choices[0].message.content)

Casos de uso reusable

Systemd y operación

En VPS tradicional, evita procesos sueltos tipo nohup. Usa unidades systemd o contenedores supervisados por Docker/Coolify.

systemctl --user start hermes-gateway-default.service
systemctl --user restart hermes-gateway-default.service
systemctl --user stop hermes-gateway-default.service

Si el gateway habilita jobs o cron internos, audita rutas como /api/jobs y evita que cualquier cliente con API key pueda crear tareas no deseadas.

Diagnóstico rápido