API Server — Hermes as a Service

Servidor de API — Hermes como um Serviço

Imagine isto: você construiu um agente de IA incrível com o Hermes. Ele pode executar comandos no terminal, pesquisar na web, gerenciar arquivos e lembrar de coisas. Mas ele vive no seu terminal. E se você pudesse conectá-lo a uma interface de chat bonita como Open WebUI ou LobeChat? É exatamente isso que o Servidor de API faz.

Pense nele como um tradutor universal. O Servidor de API expõe o Hermes como um endpoint HTTP compatível com OpenAI. Isso significa que qualquer frontend que “fale a língua OpenAI” — e existem centenas deles — pode se conectar ao Hermes e usá-lo como um backend poderoso. Seu agente mantém todo o seu conjunto de ferramentas, e o frontend se torna apenas uma interface bonita para ele.

A melhor parte? Quando você transmite respostas, os indicadores de progresso das ferramentas aparecem inline. Então seus usuários podem realmente ver o agente executando um comando ou pesquisando na web, em vez de apenas encarar um cursor piscando.

Um Backend, Poder Total

Antes de mergulharmos, uma dica rápida. O Hermes precisa de um provedor configurado e backends de ferramentas para ser útil. Uma assinatura do Nous Portal cuida de ambos — você tem acesso a mais de 300 modelos, além de ferramentas de web, imagem, TTS e navegador via Tool Gateway.

Execute hermes setup --portal uma vez, e você estará pronto para dar a qualquer frontend um backend totalmente equipado com ferramentas. É a maneira mais fácil de começar.

Início Rápido: Três Passos

1. Ative o Servidor de API

Abra seu arquivo ~/.hermes/.env e adicione estas linhas:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Opcional: apenas se um navegador precisar chamar o Hermes diretamente
# API_SERVER_CORS_ORIGINS=http://localhost:3000

A API_SERVER_KEY é sua senha. Mude para algo seguro!

2. Inicie o Gateway

Execute este comando:

hermes gateway

Você verá uma mensagem como:

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

Pronto. Seu agente agora é um serviço.

3. Conecte um Frontend

Aponte qualquer cliente compatível com OpenAI para http://localhost:8642/v1. Vamos testar com 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!"}]}'

Ou conecte o Open WebUI, LobeChat, ou qualquer outro frontend. Confira o guia de integração com Open WebUI para instruções passo a passo.

Os Endpoints: Duas Maneiras de Conversar

O Servidor de API oferece dois endpoints principais.

POST /v1/chat/completions

Este é o formato padrão de Chat Completions da OpenAI. Ele é stateless — você envia todo o histórico da conversa em cada requisição através do array messages.

Aqui está uma requisição simples:

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

E a resposta:

{
  "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}
}

Imagens inline são suportadas. Você pode enviar imagens como parte do conteúdo da mensagem:

{
  "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 URLs remotas quanto URLs data:image/... funcionam. Observe que arquivos enviados e data URLs que não são de imagem retornarão um erro 400 unsupported_content_type.

É no streaming que a mágica acontece. Defina "stream": true e você receberá Server-Sent Events (SSE) com respostas token por token. Para Chat Completions, você verá eventos padrão chat.completion.chunk além de um evento personalizado hermes.tool.progress. Isso permite que os frontends mostrem a atividade das ferramentas sem poluir o texto final do assistente.

POST /v1/responses

Este é o formato mais novo da API de Responses da OpenAI. A grande diferença? Ele suporta estado de conversa no lado do servidor via previous_response_id. O servidor armazena todo o histórico da conversa, incluindo chamadas de ferramentas e resultados, então o contexto de múltiplas trocas é preservado sem que o cliente precise gerenciá-lo.

Aqui está uma requisição:

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

A resposta mostra as chamadas de ferramentas que já foram executadas:

{
  "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}
}

Observe como as chamadas de ferramentas têm "status": "completed". O Hermes já as executou no lado do servidor. O cliente apenas renderiza a UI estruturada da ferramenta.

Múltiplas trocas são fáceis. Basta encadear as respostas:

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

O servidor reconstrói a conversa completa, incluindo todas aquelas chamadas de ferramentas, e continua de onde você parou.

Pronto para Servir?

O Servidor de API transforma o Hermes de uma ferramenta local em um serviço completo. Se você prefere a simplicidade do Chat Completions ou o poder com estado do Responses, agora você tem um backend universal para qualquer frontend compatível com OpenAI. Experimente — seu agente está pronto para servir.