API Server — Hermes as a Service | Easy Understand Hermes Agent

Servidor API — Hermes como Servicio

Imagina esto: has construido un agente de IA increíble con Hermes. Puede ejecutar comandos de terminal, buscar en la web, gestionar archivos y recordar cosas. Pero vive en tu terminal. ¿Qué pasaría si pudieras conectarlo a una interfaz de chat bonita como Open WebUI o LobeChat? Eso es exactamente lo que hace el Servidor API.

Piénsalo como un traductor universal. El Servidor API expone Hermes como un endpoint HTTP compatible con OpenAI. Esto significa que cualquier interfaz que hable el “idioma OpenAI” — y hay cientos de ellas — puede conectarse a Hermes y usarlo como un potente backend. Tu agente conserva todo su conjunto de herramientas, y la interfaz se convierte simplemente en una cara bonita para él.

¿La mejor parte? Cuando transmites respuestas, los indicadores de progreso de las herramientas aparecen en línea. Así tus usuarios pueden ver realmente al agente ejecutando un comando o buscando en la web, en lugar de quedarse mirando un cursor parpadeante.

Un Solo Backend, Todo el Poder

Antes de sumergirnos, un consejo rápido. Hermes necesita un proveedor configurado y backends de herramientas para ser útil. Una suscripción a Nous Portal cubre ambos — obtienes acceso a más de 300 modelos, además de herramientas web, de imagen, TTS y de navegador a través del Tool Gateway.

Ejecuta hermes setup --portal una vez, y estarás listo para darle a cualquier interfaz un backend completamente equipado con herramientas. Es la forma más fácil de empezar.

Inicio Rápido: Tres Pasos

1. Habilita el Servidor API

Abre tu archivo ~/.hermes/.env y añade estas líneas:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Opcional: solo si un navegador debe llamar a Hermes directamente
# API_SERVER_CORS_ORIGINS=http://localhost:3000

La API_SERVER_KEY es tu contraseña. ¡Cámbiala por algo seguro!

2. Inicia el Gateway

Ejecuta este comando:

hermes gateway

Verás un mensaje como este:

[API Server] API server listening on http://127.0.0.1:8642

Eso es todo. Tu agente ahora es un servicio.

3. Conecta una Interfaz

Apunta cualquier cliente compatible con OpenAI a http://localhost:8642/v1. Probémoslo con curl:

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

O conecta Open WebUI, LobeChat, o cualquier otra interfaz. Consulta la guía de integración con Open WebUI para instrucciones paso a paso.

Los Endpoints: Dos Formas de Hablar

El Servidor API ofrece dos endpoints principales.

POST /v1/chat/completions

Este es el formato estándar de Chat Completions de OpenAI. Es sin estado — envías el historial completo de la conversación en cada solicitud mediante el array messages.

Aquí tienes una solicitud simple:

{
  "model": "hermes-agent",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

Y la respuesta:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

Las imágenes en línea son compatibles. Puedes enviar imágenes como parte del contenido del mensaje:

{
  "model": "hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

Tanto las URLs remotas como las URLs data:image/... funcionan. Ten en cuenta que los archivos subidos y las URLs de datos que no sean imágenes devolverán un error 400 unsupported_content_type.

La transmisión es donde ocurre la magia. Establece "stream": true y recibirás Server-Sent Events (SSE) con respuestas token por token. Para Chat Completions, verás eventos estándar chat.completion.chunk más un evento personalizado hermes.tool.progress. Esto permite que las interfaces muestren la actividad de las herramientas sin contaminar el texto final del asistente.

POST /v1/responses

Este es el formato más nuevo de la API de Responses de OpenAI. ¿La gran diferencia? Soporta estado de conversación del lado del servidor mediante previous_response_id. El servidor almacena el historial completo de la conversación, incluyendo las llamadas a herramientas y sus resultados, de modo que el contexto multi-turno se conserva sin que el cliente lo gestione.

Aquí tienes una solicitud:

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

La respuesta muestra las llamadas a herramientas que ya se ejecutaron:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "hermes-agent",
  "output": [
    {"type": "function_call", "status": "completed", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "status": "completed", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Observa cómo las llamadas a herramientas tienen "status": "completed". Hermes ya las ejecutó del lado del servidor. El cliente solo renderiza la interfaz estructurada de las herramientas.

El multi-turno es fácil. Simplemente encadena respuestas:

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

El servidor reconstruye la conversación completa, incluyendo todas esas llamadas a herramientas, y continúa desde donde lo dejaste.

¿Listo para Servir?

El Servidor API transforma a Hermes de una herramienta local a un servicio completo. Ya sea que prefieras la simplicidad de Chat Completions o el poder con estado de Responses, ahora tienes un backend universal para cualquier interfaz compatible con OpenAI. Pruébalo — tu agente está listo para servir.