API de Hermes Agent: un endpoint, cualquier frontend

Cualquier frontend de chat compatible con OpenAI ya sabe hablar /v1/chat/completions. Hermes Agent aprovecha ese hecho al máximo: apunta cualquiera de ellos a http://localhost:8642/v1, pasa una clave API y obtienes todo el runtime de Hermes - herramientas, memoria, skills, cron - detrás de una superficie HTTP familiar, sin cambios en el cliente.

Esa es la idea completa del servidor API de Hermes. No es un SDK específico de Hermes que tengas que aprender. Es la forma de OpenAI, servida localmente, envolviendo al agente. Si ya usas Open WebUI, LobeChat, LibreChat, NextChat, ChatBox o un script que habla con openai-python, ya sabes cómo integrarlo.

Este post repasa qué expone el servidor API, cómo activarlo y los patrones que aguantan cuando empiezas a conectarle frontends reales.

Qué expone realmente el servidor API

El servidor API es un componente dentro del gateway de Hermes. Cuando se habilita, escucha por defecto en 127.0.0.1:8642 y habla el contrato HTTP de OpenAI sobre cuatro familias de endpoints:

/v1/chat/completions - el clásico endpoint de Chat Completions. Sin estado, con o sin streaming. Es lo que usa el 90% de los frontends compatibles con OpenAI.
/v1/responses - la más reciente Responses API, con estado y encadenamiento mediante previous_response_id, para que una conversación pueda retomarse por ID en lugar de reenviar todo el historial.
/v1/runs - una API de tareas largas para trabajos que superan un ciclo de request/response. El cliente envía un run, consulta el estado y recoge el resultado cuando está listo.
/api/jobs - una capa REST para el planificador cron integrado, para que una app externa cree, liste y cancele ejecuciones programadas del agente igual que gestionaría cualquier otro recurso.

Cada request atraviesa el stack completo de Hermes. El modelo no responde solo. Tiene acceso a la terminal, al sistema de archivos, a búsqueda web, a los archivos de memoria y a cualquier servidor MCP que hayas configurado. Para una visión más amplia de cómo esas herramientas llegan al modelo, mira Hermes Agent y MCP.

Cómo activar el servidor API

El servidor API está desactivado por defecto. Se activa con dos ajustes en ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=$(openssl rand -hex 32)

Luego reinicia el gateway (hermes gateway). Los mismos valores pueden vivir en ~/.hermes/config.yaml bajo gateway.api_server: si prefieres YAML, pero las variables de entorno tienen prioridad cuando ambos están definidos.

Algunas cosas que conviene saber antes de activarlo:

La dirección de escucha por defecto es 127.0.0.1, lo que significa que el endpoint solo es accesible desde el mismo host. Si estás ejecutando Hermes en un contenedor Docker y quieres que otro contenedor o tu máquina anfitriona lo alcance, define también API_SERVER_HOST=0.0.0.0 y asegúrate de mapear el puerto.
API_SERVER_KEY debe tener al menos 8 caracteres. Trátala como cualquier otro secreto de API: no la subas al repo, no la pegues en un canal compartido. Si se filtra, cualquier cosa en la red puede ejecutar runs del agente en tu cuenta con tus herramientas y tus credenciales.
El puerto 8642 es una convención de Hermes, no un estándar. Si choca con algo en tu máquina, cambia API_SERVER_PORT. Todo lo que viene después solo necesita la URL base.

Una vez que el servidor está en marcha, pruébalo con cualquier SDK de OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="la-clave-que-configuraste",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "¿Qué día es y lee README.md."}],
)
print(resp.choices[0].message.content)

Nada en ese fragmento es específico de Hermes salvo la URL base. Ese es el punto.

Frontends que simplemente funcionan

Como la superficie es la de OpenAI, la mayoría de los frontends de chat existentes se conectan cambiando un único ajuste. Un recorrido corto por los que la gente pregunta más:

Open WebUI. Admin Settings → Connections → OpenAI → Add Connection. Pon la URL base en http://localhost:8642/v1 y la clave API en tu API_SERVER_KEY. El error más común es olvidar el sufijo /v1: no lo hagas. Open WebUI guarda esto en su propia base de datos, así que si cambias la clave más adelante, actualízala desde la UI de admin y no volviendo a editar la variable de entorno.

LobeChat. En Settings → Language Model → OpenAI, sobrescribe la API proxy URL con http://localhost:8642/v1 y pega la clave. La lista de modelos puede ser una única entrada llamada hermes; el servidor mapea todo al mismo agente.

LibreChat. Añade un endpoint personalizado en librechat.yaml con apiKey: tu-clave, baseURL: http://localhost:8642/v1 y el nombre de modelo que quieras mostrar en el selector. LibreChat gestiona el resto como si hubieras configurado un OpenAI autoalojado.

NextChat, ChatBox y compañía. Mismo patrón: URL base y clave. Si un frontend dice ser compatible con OpenAI, casi con seguridad funciona.

Lo bueno de ejecutar Hermes detrás de estos frontends es que te llevas su pulido de UI - historial de chat, sesiones fijadas, cambio de modelo, comparaciones en paralelo - mientras el "modelo" es en realidad tu agente con tus herramientas.

Streaming, progreso de herramientas y la Responses API

Dos cosas del servidor API sorprenden la primera vez.

La primera es que el streaming transporta el progreso de las herramientas. Cuando el agente decide ejecutar la shell, salir a la web o leer un archivo, el stream le informa al cliente de ese paso. Los frontends que respetan el formato de streaming mostrarán en línea "running tool: web_search" o similar, y luego continuarán con la respuesta real del modelo. Consigues observabilidad real de lo que hace el agente sin cablear un log aparte.

La segunda es la Responses API. /v1/responses es con estado de una forma que /v1/chat/completions no lo es. En lugar de reenviar el historial completo en cada turno, el cliente puede pasar previous_response_id y el servidor retoma donde terminó la respuesta anterior. Eso importa en conversaciones largas de varios turnos, donde reenviar el historial es caro, y encaja de forma natural con la dirección hacia la que se mueven los SDK más recientes del propio OpenAI. Si tu frontend soporta ambos, prefiere Responses para sesiones largas y Chat Completions para llamadas puntuales.

Runs y Jobs cubren los casos incómodos en el modelo request/response: un run que tarda diez minutos o un trabajo programado que se dispara cada mañana a las 8:00 y deja un resumen en un canal. Mira Hermes Agent scheduled tasks and automation para el patrón del lado cron.

Patrones que merece la pena seguir

Unos hábitos que aguantan cuando el servidor API hace trabajo real:

Mantén el endpoint en localhost mientras no tengas un motivo para no hacerlo. El binding por defecto es seguro. Si necesitas acceso remoto, pon un proxy inverso real por delante con TLS y autenticación, no cambies el host a 0.0.0.0 en la internet pública.

Una clave por cliente, si puedes. El servidor actual acepta una única API_SERVER_KEY. Si estás cableando varios frontends y quieres poder revocar uno sin romper el resto, ejecuta instancias de Hermes separadas detrás de claves separadas, o corta en un proxy que emita claves por cliente y reenvíe una única compartida al agente.

El nombre del modelo es una etiqueta, no un router. Cada request pasa por el mismo agente. Apunta cada frontend a la misma entrada model: "hermes" a no ser que quieras específicamente que muestren nombres distintos en su UI.

Vigila los logs cuando conectes un frontend nuevo. El gateway loguea cada request entrante y cada llamada a herramienta. Ojéalos en las primeras conversaciones: aprenderás rápido si el frontend está enviando los mensajes que esperas o, por ejemplo, inyectando un system prompt que pelea con tus archivos de memoria existentes.

Prefiere Responses para chats largos, Chat Completions para scripts. La complejidad del lado del cliente es la misma. La del servidor no.

Dónde encaja Hermify

Ejecutar el servidor API tú mismo es sencillo, pero sigue implicando mantener vivo el proceso del gateway, actualizar el contenedor y asegurar que el puerto sea alcanzable. Si prefieres saltarte eso, Hermify ejecuta un Hermes Agent gestionado para ti en Telegram, con las mismas herramientas, memoria y skills, activo en cerca de un minuto. Hoy la superficie de API gestionada es Telegram primero; el servidor API autoalojado es donde vas cuando quieres apuntar clientes personalizados a tu propio agente. En cualquier caso, el runtime subyacente es el mismo, así que el modelo mental de este post se traslada.