API do Hermes Agent: um endpoint, qualquer frontend

Todo frontend de chat compatível com OpenAI já sabe falar /v1/chat/completions. O Hermes Agent parte desse fato e vai até o fim: aponte qualquer um deles para http://localhost:8642/v1, passe uma chave de API e você tem o runtime completo do Hermes - ferramentas, memória, skills, cron - por trás de uma superfície HTTP conhecida, sem mudar nada no cliente.

Essa é toda a ideia do servidor API do Hermes. Não é um SDK específico do Hermes que você precisa aprender. É o formato do OpenAI, servido localmente, encapsulando o agente. Se você já usa Open WebUI, LobeChat, LibreChat, NextChat, ChatBox ou um script que fala com o openai-python, você já sabe integrar.

Este post mostra o que o servidor API expõe, como ativá-lo e os padrões que se seguram quando você começa a plugar frontends reais nele.

O que o servidor API realmente expõe

O servidor API é um componente dentro do gateway do Hermes. Quando ativado, ele escuta por padrão em 127.0.0.1:8642 e fala o contrato HTTP do OpenAI em quatro famílias de endpoints:

/v1/chat/completions - o clássico endpoint Chat Completions. Sem estado, com ou sem streaming. É o que 90% dos frontends compatíveis com OpenAI usam.
/v1/responses - a mais recente Responses API, com estado, com encadeamento por previous_response_id, para que uma conversa possa ser retomada por ID em vez de reenviar todo o histórico.
/v1/runs - uma API de tarefas longas para trabalhos que passam de um único ciclo de request/response. O cliente submete um run, consulta o status e busca o resultado quando estiver pronto.
/api/jobs - uma camada REST para o agendador cron interno, para que um app externo crie, liste e cancele execuções agendadas do agente do mesmo jeito que gerenciaria qualquer outro recurso.

Cada request atravessa o stack completo do Hermes. O modelo não responde sozinho. Ele tem acesso ao terminal, ao sistema de arquivos, à busca na web, aos arquivos de memória e a qualquer servidor MCP que você tenha configurado. Para uma visão mais ampla de como essas ferramentas chegam ao modelo, veja Hermes Agent e MCP.

Ligando o servidor API

O servidor API vem desligado por padrão. Você opta por ativá-lo com duas configurações em ~/.hermes/.env:

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

Depois reinicie o gateway (hermes gateway). Os mesmos valores podem viver em ~/.hermes/config.yaml sob gateway.api_server: se você preferir YAML, mas as variáveis de ambiente ganham quando ambos estão setados.

Algumas coisas que vale saber antes de ativar:

O endereço de bind padrão é 127.0.0.1, o que significa que o endpoint só é acessível do mesmo host. Se você está rodando o Hermes em um contêiner Docker e quer que outro contêiner ou a sua máquina hospedeira alcance, defina também API_SERVER_HOST=0.0.0.0 e garanta que a porta esteja mapeada.
API_SERVER_KEY precisa ter no mínimo 8 caracteres. Trate como qualquer segredo de API: não faça commit, não cole em canal compartilhado. Se vazar, qualquer coisa na rede pode executar runs do agente na sua conta com as suas ferramentas e as suas credenciais.
A porta 8642 é uma convenção do Hermes, não um padrão. Se conflitar com algo na sua máquina, mude API_SERVER_PORT. Tudo depois só precisa da URL base.

Assim que o servidor estiver no ar, faça um teste com qualquer SDK do OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="a-chave-que-voce-definiu",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "Que dia é hoje e leia o README.md."}],
)
print(resp.choices[0].message.content)

Nada nesse trecho é específico do Hermes exceto a URL base. É esse o ponto.

Frontends que simplesmente funcionam

Como a superfície é a do OpenAI, a maioria dos frontends de chat existentes se conecta com uma única mudança de configuração. Um passeio rápido pelos que as pessoas mais perguntam:

Open WebUI. Admin Settings → Connections → OpenAI → Add Connection. Coloque a URL base como http://localhost:8642/v1 e a chave API como sua API_SERVER_KEY. O erro mais comum é esquecer o sufixo /v1 - não esqueça. O Open WebUI persiste isso no próprio banco, então se você mudar a chave depois, atualize pela UI de admin, não reeditando a variável de ambiente.

LobeChat. Em Settings → Language Model → OpenAI, sobrescreva a API proxy URL para http://localhost:8642/v1 e cole a chave. A lista de modelos pode ser uma única entrada chamada hermes; o servidor mapeia tudo para o mesmo agente.

LibreChat. Adicione um endpoint customizado em librechat.yaml com apiKey: sua-chave, baseURL: http://localhost:8642/v1 e o nome de modelo que você quiser mostrar no seletor. O LibreChat cuida do resto como se fosse um OpenAI auto-hospedado.

NextChat, ChatBox e amigos. Mesmo padrão: URL base e chave. Se um frontend afirma ser compatível com OpenAI, é quase certeza que funciona.

O legal de rodar o Hermes atrás desses frontends é que você ganha o polimento da UI deles - histórico de conversas, sessões fixadas, troca de modelo, comparação lado a lado - enquanto o "modelo" é na verdade o seu agente com as suas ferramentas.

Streaming, progresso de ferramentas e a Responses API

Duas coisas do servidor API surpreendem na primeira vez.

A primeira é que o streaming carrega o progresso das ferramentas. Quando o agente decide rodar o shell, ir na web ou ler um arquivo, o stream expõe esse passo para o cliente. Frontends que respeitam o formato de streaming mostram "running tool: web_search" ou algo assim inline, e depois continuam com a resposta real do modelo. Você ganha observabilidade real do que o agente está fazendo sem cablear um log à parte.

A segunda é a Responses API. /v1/responses é com estado de um jeito que /v1/chat/completions não é. Em vez de reenviar todo o histórico a cada turno, o cliente pode passar previous_response_id e o servidor retoma de onde a resposta anterior parou. Isso importa em conversas longas de vários turnos, onde reenviar o histórico é caro, e casa naturalmente com a direção que os SDKs mais novos do próprio OpenAI estão tomando. Se o seu frontend suporta os dois, prefira Responses para sessões longas e Chat Completions para chamadas pontuais.

Runs e Jobs cobrem os casos que ficam estranhos no modelo request/response: um run que leva dez minutos ou um trabalho agendado que dispara toda manhã às 8h e deixa um resumo num canal. Veja Hermes Agent scheduled tasks and automation para o padrão do lado cron.

Padrões que valem seguir

Alguns hábitos que se sustentam quando o servidor API está fazendo trabalho de verdade:

Mantenha o endpoint em localhost enquanto não tiver motivo para tirar. O bind padrão é seguro. Se precisar de acesso remoto, coloque um proxy reverso de verdade na frente com TLS e autenticação; não simplesmente mude o host para 0.0.0.0 na internet pública.

Uma chave por cliente, se der. O servidor atual aceita uma única API_SERVER_KEY. Se você está ligando vários frontends e quer poder revogar um sem quebrar o resto, rode instâncias separadas do Hermes atrás de chaves separadas, ou termine em um proxy que emite chaves por cliente e encaminha uma compartilhada para o agente.

Nome de modelo é rótulo, não roteador. Cada request passa pelo mesmo agente. Aponte todo frontend para a mesma entrada model: "hermes" a menos que você queira especificamente que eles mostrem nomes diferentes na UI.

Fique de olho nos logs quando plugar um frontend novo. O gateway loga cada request de entrada e cada chamada de ferramenta. Corra o olho pelas primeiras conversas: você aprende rápido se o frontend está mandando as mensagens que você espera ou, por exemplo, injetando um system prompt que briga com seus arquivos de memória existentes.

Prefira Responses para conversas longas, Chat Completions para scripts. A complexidade do lado do cliente é a mesma. A do servidor não.

Onde a Hermify entra

Rodar o servidor API você mesmo é simples, mas ainda significa manter o processo do gateway vivo, atualizar o contêiner e garantir que a porta seja alcançável. Se você preferir pular isso, a Hermify roda um Hermes Agent gerenciado para você no Telegram, com as mesmas ferramentas, memória e skills, no ar em cerca de um minuto. Hoje a superfície de API gerenciada é Telegram primeiro; o servidor API auto-hospedado é para quando você quer apontar clientes customizados para o seu próprio agente. De um jeito ou de outro, o runtime por baixo é o mesmo, então o modelo mental deste post se transfere.