Integração com o Open WebUI

O Open WebUI (126 mil ★) é a interface de chat para IA auto-hospedada mais popular. Com o servidor de API embutido do Hermes Agent, você pode usar o Open WebUI como um frontend web caprichado para o seu agente — com gestão de conversas, contas de usuário e uma interface de chat moderna.

Arquitetura

flowchart LR
    A["Open WebUI<br/>interface no navegador<br/>porta 3000"]
    B["hermes-agent<br/>servidor de API do gateway<br/>porta 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|resposta em streaming por SSE| A

O Open WebUI se conecta ao servidor de API do Hermes Agent do mesmo jeito que se conectaria à OpenAI. O Hermes atende as requisições com todo o seu conjunto de ferramentas — terminal, operações de arquivo, busca na web, memória, skills — e devolve a resposta final.

Onde o runtime roda

O servidor de API é um runtime de agente do Hermes, não um proxy puro de LLM. Para cada requisição, o Hermes cria um AIAgent do lado do servidor, na máquina do servidor de API. As chamadas de ferramenta rodam onde esse servidor de API está rodando.

Por exemplo: se um notebook aponta o Open WebUI (ou outro cliente compatível com a OpenAI) para um servidor de API do Hermes numa máquina remota, o pwd, as ferramentas de arquivo, as de navegador, as ferramentas MCP locais e as demais ferramentas de espaço de trabalho rodam na máquina remota do servidor de API, não no notebook.

O Open WebUI fala com o Hermes de servidor para servidor, então você não precisa de API_SERVER_CORS_ORIGINS para esta integração.

Configuração rápida

1. Ligue o servidor de API

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY sua-chave-secreta

O hermes config set manda a flag para o config.yaml e o segredo para o ~/.hermes/.env sozinho. Se o gateway já estiver rodando, reinicie-o para a mudança valer:

hermes gateway stop && hermes gateway

2. Suba o gateway do Hermes Agent

hermes gateway

Você deve ver:

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

3. Confirme que o servidor de API responde

curl -s http://127.0.0.1:8642/health
# {"status": "ok", ...}

curl -s -H "Authorization: Bearer sua-chave-secreta" http://127.0.0.1:8642/v1/models
# {"object":"list","data":[{"id":"hermes-agent", ...}]}

Se o /health falhar, o gateway não pegou o API_SERVER_ENABLED=true — reinicie. Se o /v1/models devolver 401, o seu cabeçalho Authorization não bate com a API_SERVER_KEY.

4. Suba o Open WebUI

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=sua-chave-secreta \
  -e ENABLE_OLLAMA_API=false \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

O ENABLE_OLLAMA_API=false esconde o backend padrão do Ollama, que apareceria vazio e poluiria o seletor de modelos. Omita se você tiver mesmo um Ollama rodando ao lado.

A primeira subida leva de 15 a 30 segundos: o Open WebUI baixa modelos de embedding do sentence-transformers (cerca de 150 MB) na primeira vez. Espere o docker logs open-webui sossegar antes de abrir a interface.

5. Abra a interface

Vá em http://localhost:3000. Crie a sua conta de administrador (o primeiro usuário vira administrador). O seu agente deve aparecer na lista de modelos (com o nome do seu perfil, ou hermes-agent no perfil padrão). Pode começar a conversar!

Configuração com Docker Compose

Para algo mais permanente, crie um docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=sua-chave-secreta
      - ENABLE_OLLAMA_API=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

Depois:

docker compose up -d

Configurar pela interface de administração

Se você prefere configurar a conexão pela interface em vez de variáveis de ambiente:

1. Entre no Open WebUI em http://localhost:3000
2. Clique no avatar do seu perfil → Admin Settings
3. Vá em Connections
4. Em OpenAI API, clique no ícone de chave inglesa (Manage)
5. Clique em + Add New Connection
6. Preencha:
   • URL: http://host.docker.internal:8642/v1
   • API Key: exatamente o mesmo valor da API_SERVER_KEY no Hermes
7. Clique no visto para verificar a conexão
8. Salve

O modelo do seu agente deve aparecer agora na lista de modelos (com o nome do seu perfil, ou hermes-agent no perfil padrão).

aviso

As variáveis de ambiente só valem na primeira subida do Open WebUI. Depois disso, os ajustes de conexão ficam no banco de dados interno dele. Para mudá-los mais tarde, use a interface de administração ou apague o volume do Docker e comece de novo.

Tipo de API: Chat Completions vs Responses

O Open WebUI aceita dois modos de API ao se conectar a um backend:

Modo	Formato	Quando usar
Chat Completions (padrão)	/v1/chat/completions	Recomendado. Funciona de cara.
Responses (experimental)	/v1/responses	Para estado de conversa no servidor via previous_response_id.

Usando Chat Completions (recomendado)

É o padrão e não exige configuração extra. O Open WebUI manda requisições no formato padrão da OpenAI e o Hermes Agent responde de acordo. Cada requisição inclui o histórico completo da conversa.

Usando a API Responses

Para usar o modo da API Responses:

1. Vá em Admin Settings → Connections → OpenAI → Manage
2. Edite a sua conexão do hermes-agent
3. Mude o API Type de "Chat Completions" para "Responses (Experimental)"
4. Salve

Com a API Responses, o Open WebUI manda as requisições no formato Responses (array input + instructions), e o Hermes Agent consegue preservar o histórico completo de chamadas de ferramenta entre os turnos com o previous_response_id. Quando stream: true, o Hermes também emite em streaming itens function_call e function_call_output nativos da especificação, o que viabiliza interfaces estruturadas de chamada de ferramenta em clientes que renderizam eventos do Responses.

observação

O Open WebUI hoje gerencia o histórico de conversa do lado do cliente mesmo no modo Responses — ele manda o histórico inteiro de mensagens em cada requisição em vez de usar o previous_response_id. A vantagem principal do modo Responses hoje é o fluxo estruturado de eventos: os deltas de texto e os itens function_call e function_call_output chegam como eventos SSE do Responses da OpenAI, em vez de pedaços do Chat Completions.

Como funciona

Quando você manda uma mensagem no Open WebUI:

1. O Open WebUI manda uma requisição POST /v1/chat/completions com a sua mensagem e o histórico da conversa
2. O Hermes Agent cria uma instância de AIAgent do lado do servidor, usando o perfil do servidor de API, a configuração de modelo/provedor, a memória, as skills e os conjuntos de ferramentas configurados para o servidor de API
3. O agente processa a sua requisição — ele pode chamar ferramentas (terminal, operações de arquivo, busca na web etc.) na máquina do servidor de API
4. Conforme as ferramentas rodam, mensagens de progresso aparecem no fluxo da interface para você ver o que o agente está fazendo (por exemplo, `💻 ls -la`, `🔍 Python 3.12 release`)
5. A resposta final em texto do agente volta em streaming para o Open WebUI
6. O Open WebUI mostra a resposta na interface de chat

O seu agente tem acesso às mesmas ferramentas e capacidades daquela instância do Hermes que serve a API. Se o servidor de API é remoto, essas ferramentas também são remotas.

Se você precisa hoje que as ferramentas rodem contra o seu espaço de trabalho local, rode o Hermes localmente e aponte-o para um provedor puro de LLM ou um proxy puro de modelo compatível com a OpenAI (por exemplo vLLM, LiteLLM, Ollama, llama.cpp, OpenAI, OpenRouter etc.). Um futuro modo de runtime dividido, de "cérebro remoto, mãos locais", está sendo acompanhado na #18715; não é o comportamento do servidor de API atual.

Progresso das ferramentas

Com o streaming ligado (o padrão), você vê indicadores curtos no fluxo enquanto as ferramentas rodam — o emoji da ferramenta e o argumento principal dela. Eles aparecem no fluxo da resposta antes da resposta final do agente, dando visibilidade do que acontece nos bastidores.

Referência de configuração

Hermes Agent (servidor de API)

Variável	Padrão	Descrição
API_SERVER_ENABLED	false	Liga o servidor de API
API_SERVER_PORT	8642	Porta do servidor HTTP
API_SERVER_HOST	127.0.0.1	Endereço de escuta
API_SERVER_KEY	(obrigatória)	Token bearer de autenticação. Igual ao OPENAI_API_KEY.

Open WebUI

Variável	Descrição
OPENAI_API_BASE_URL	URL da API do Hermes Agent (inclua o /v1)
OPENAI_API_KEY	Não pode ficar vazia. Igual à sua API_SERVER_KEY.

Solução de problemas

Nenhum modelo aparece na lista

• Confira se a URL termina em /v1: http://host.docker.internal:8642/v1 (não só :8642)
• Confirme que o gateway está rodando: curl http://localhost:8642/health deve devolver {"status": "ok"}
• Confira a listagem de modelos: curl -H "Authorization: Bearer sua-chave-secreta" http://localhost:8642/v1/models deve devolver uma lista com hermes-agent
• Rede do Docker: de dentro do Docker, localhost é o contêiner, não a sua máquina. Use host.docker.internal ou --network=host.
• Backend vazio do Ollama roubando a cena no seletor: se você omitiu o ENABLE_OLLAMA_API=false, o Open WebUI mostra uma seção vazia do Ollama acima dos seus modelos do Hermes. Reinicie o contêiner com -e ENABLE_OLLAMA_API=false ou desligue o Ollama em Admin Settings → Connections.

O teste de conexão passa mas nenhum modelo carrega

Isso é quase sempre o sufixo /v1 faltando. O teste de conexão do Open WebUI é uma checagem básica de conectividade — ele não verifica se a listagem de modelos funciona.

A resposta demora muito

O Hermes Agent pode estar executando várias chamadas de ferramenta (lendo arquivos, rodando comandos, buscando na web) antes de produzir a resposta final. Isso é normal em consultas complexas. A resposta aparece de uma vez quando o agente termina.

Erros de "Invalid API key"

Garanta que o OPENAI_API_KEY do Open WebUI bate com a API_SERVER_KEY do Hermes Agent.

aviso

O Open WebUI guarda os ajustes de conexão compatível com a OpenAI no banco de dados dele depois da primeira subida. Se você salvou uma chave errada na interface de administração sem querer, corrigir só as variáveis de ambiente não basta — atualize ou apague a conexão salva em Admin Settings → Connections, ou zere o diretório de dados / o banco do Open WebUI.

Configuração para vários usuários, com perfis

Para rodar instâncias separadas do Hermes por pessoa — cada uma com configuração, memória e skills próprias —, use perfis. Cada perfil roda o próprio servidor de API numa porta diferente e anuncia sozinho o nome do perfil como modelo no Open WebUI.

1. Crie os perfis e configure os servidores de API

As API_SERVER_* são variáveis de ambiente, não chaves YAML de configuração, então grave-as no .env de cada perfil. Escolha portas fora da faixa das plataformas padrão (8644 é o adaptador de webhook, 8645 é o wecom-callback, 8646 é o msgraph-webhook), por exemplo 8650 em diante:

hermes profile create alice
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

hermes profile create bob
cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

2. Suba cada gateway

hermes -p alice gateway &
hermes -p bob gateway &

3. Acrescente as conexões no Open WebUI

Em Admin Settings → Connections → OpenAI API → Manage, acrescente uma conexão por perfil:

Conexão	URL	Chave de API
Alice	http://host.docker.internal:8650/v1	alice-secret
Bob	http://host.docker.internal:8651/v1	bob-secret

A lista de modelos vai mostrar alice e bob como modelos distintos. Dá para atribuir modelos aos usuários do Open WebUI pelo painel de administração, dando a cada pessoa um agente do Hermes isolado.

Nomes de modelo personalizados

O nome do modelo é o nome do perfil por padrão. Para sobrescrever, defina o API_SERVER_MODEL_NAME no .env do perfil:

hermes -p alice config set API_SERVER_MODEL_NAME "Agente da Alice"

Docker no Linux (sem Docker Desktop)

No Linux sem o Docker Desktop, o host.docker.internal não resolve por padrão. Opções:

# Opção 1: acrescentar o mapeamento de host
docker run --add-host=host.docker.internal:host-gateway ...

# Opção 2: usar a rede do host
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Opção 3: usar o IP da ponte do Docker
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...

---