Adicionar Provedores

O Hermes já consegue falar com qualquer endpoint compatível com a OpenAI pelo caminho de provedor personalizado. Não adicione um provedor embutido a não ser que você queira uma experiência de primeira classe para aquele serviço:

• autenticação ou renovação de token específicas do provedor
• um catálogo de modelos curado
• entradas nos menus de hermes setup / hermes model
• apelidos de provedor para a sintaxe provider:model
• um formato de API que não é da OpenAI e precisa de adaptador

Se o provedor é só "mais uma URL-base compatível com a OpenAI, com chave de API", um provedor personalizado nomeado pode ser suficiente.

O modelo mental

Um provedor embutido precisa estar alinhado em algumas camadas:

1. hermes_cli/auth.py decide como as credenciais são encontradas.
2. hermes_cli/runtime_provider.py transforma isso em dados de execução:
   • provider
   • api_mode
   • base_url
   • api_key
   • source
3. run_agent.py usa o api_mode para decidir como as requisições são montadas e enviadas.
4. hermes_cli/models.py e hermes_cli/main.py fazem o provedor aparecer na CLI. (O hermes_cli/setup.py delega para o main.py automaticamente — não precisa mudar nada lá.)
5. agent/auxiliary_client.py e agent/model_metadata.py mantêm funcionando as tarefas auxiliares e o orçamento de tokens.

A abstração importante é o api_mode.

• A maioria dos provedores usa chat_completions.
• O Codex e a Meta Model API (api.meta.ai — Muse Spark) usam codex_responses (envia automaticamente prompt_cache_retention: 24h para cache de prompt; o api.meta.ai chega a 93–99% de acerto de cache apenas em /v1/responses).
• A Anthropic usa anthropic_messages.
• Um protocolo novo, que não seja da OpenAI, normalmente significa acrescentar um adaptador novo e um ramo novo de api_mode.

Formato de fio das chamadas de ferramenta

Internamente, o Hermes guarda o histórico da conversa no formato de chat completions da OpenAI. Por isso, o convert_messages / convert_tools do transporte chat_completions (agent/transports/chat_completions.py) é quase uma identidade, e todos os outros transportes convertem daquele formato para o próprio protocolo nativo. A referência canônica desse formato — definições de tools com parameters em JSON Schema, entradas tool_calls do assistente com function.arguments em string, e mensagens de resultado com role: "tool" indexadas por tool_call_id — é a referência da API de chat completions da OpenAI. Quando você escreve um adaptador nativo, aquela página define o lado de entrada da sua conversão; a documentação do seu provedor define o lado de saída.

Escolha primeiro o caminho de implementação

Caminho A — provedor compatível com a OpenAI

Use este quando o provedor aceita requisições no estilo padrão de chat completions.

Trabalho típico:

• acrescentar metadados de autenticação
• acrescentar catálogo de modelos / apelidos
• acrescentar a resolução em tempo de execução
• ligar o provedor aos menus da CLI
• acrescentar os padrões de modelo auxiliar
• acrescentar testes e documentação para o usuário

Normalmente você não precisa de um adaptador novo nem de um api_mode novo.

Caminho B — provedor nativo

Use este quando o provedor não se comporta como o chat completions da OpenAI.

Exemplos que já existem na árvore:

• codex_responses (OpenAI Codex, xAI Grok e Meta Muse Spark via api.meta.ai — este último envia automaticamente prompt_cache_retention: 24h)
• anthropic_messages

Este caminho inclui tudo do Caminho A, mais:

• um adaptador de provedor em agent/
• ramos no run_agent.py para montagem da requisição, despacho, extração de uso, tratamento de interrupção e normalização da resposta
• testes do adaptador

Checklist de arquivos

Obrigatório para todo provedor embutido

1. hermes_cli/auth.py
2. hermes_cli/models.py
3. hermes_cli/runtime_provider.py
4. hermes_cli/main.py
5. agent/auxiliary_client.py
6. agent/model_metadata.py
7. testes
8. documentação para o usuário em website/docs/

dica

O hermes_cli/setup.py não precisa de mudança. O assistente de configuração delega a escolha de provedor/modelo para o select_provider_and_model() no main.py — qualquer provedor adicionado lá fica automaticamente disponível no hermes setup.

Adicional para provedores nativos / não OpenAI

10. agent/<provider>_adapter.py
11. run_agent.py
12. pyproject.toml, se for preciso um SDK do provedor

Caminho rápido: provedores só de chave de API

Se o seu provedor é apenas um endpoint compatível com a OpenAI que autentica com uma única chave de API, você não precisa mexer no auth.py, no runtime_provider.py, no main.py nem em nenhum dos outros arquivos do checklist completo abaixo.

Tudo de que você precisa é:

1. Um diretório de plugin em plugins/model-providers/<seu-provedor>/ contendo:
   • __init__.py — chama register_provider(profile) no nível do módulo
   • plugin.yaml — o manifesto (name, kind: model-provider, version, description)
2. É isso. Plugins de provedor carregam sozinhos na primeira vez que algo chama get_provider_profile() ou list_providers() — tanto plugins embutidos (deste repositório) quanto plugins do usuário em $HERMES_HOME/plugins/model-providers/ são detectados.

Quando você adiciona um plugin e ele chama register_provider(), o seguinte é ligado automaticamente:

1. Entrada em PROVIDER_REGISTRY no auth.py (resolução de credenciais, consulta de variável de ambiente)
2. api_mode definido como chat_completions
3. base_url obtido da configuração ou da variável de ambiente declarada
4. env_vars consultadas em ordem de prioridade para achar a chave de API
5. Lista fallback_models registrada para o provedor
6. A opção --provider da CLI aceita o id do provedor
7. O menu do hermes model passa a incluir o provedor
8. O assistente do hermes setup delega para o main.py automaticamente
9. A sintaxe de apelido provider:model funciona
10. O resolvedor em tempo de execução devolve o base_url e o api_key corretos
11. A opção --provider <name> da CLI aceita o id do provedor
12. A ativação de modelo de reserva consegue passar para o provedor sem tropeços

Plugins do usuário em $HERMES_HOME/plugins/model-providers/<name>/ têm precedência sobre plugins embutidos de mesmo nome (vale quem escreve por último no register_provider()) — assim, terceiros podem aplicar monkey patch ou substituir qualquer perfil embutido sem editar o repositório.

Use plugins/model-providers/nvidia/ ou plugins/model-providers/gmi/ como modelo, e veja o guia de Plugin de Provedor de Modelo completo para a referência de campos, os idiomas de gancho e exemplos de ponta a ponta.

Caminho completo: OAuth e provedores complexos

Use o checklist completo abaixo quando o seu provedor precisar de alguma destas coisas:

• OAuth ou renovação de token (Nous Portal, Codex, Qwen Portal, Copilot)
• Um formato de API que não é da OpenAI e exige um adaptador novo (Anthropic Messages, Codex Responses)
• Detecção de endpoint própria ou sondagem de várias regiões (z.ai, Kimi)
• Um catálogo estático de modelos curado, ou busca ao vivo em /models
• Entradas próprias no menu do hermes model, com fluxos de autenticação feitos à mão

Passo 1: escolha um único id canônico de provedor

Escolha um único id de provedor e use-o em todos os lugares.

Exemplos do repositório:

• openai-codex
• kimi-coding
• minimax-cn

Esse mesmo id deve aparecer em:

• PROVIDER_REGISTRY, em hermes_cli/auth.py
• _PROVIDER_LABELS, em hermes_cli/models.py
• _PROVIDER_ALIASES, tanto em hermes_cli/auth.py quanto em hermes_cli/models.py
• nas opções de --provider da CLI, em hermes_cli/main.py
• nos ramos de configuração / escolha de modelo
• nos padrões de modelo auxiliar
• nos testes

Se o id divergir entre esses arquivos, o provedor vai parecer ligado pela metade: a autenticação pode funcionar enquanto o /model, a configuração ou a resolução em tempo de execução silenciosamente não o encontram.

Passo 2: acrescente os metadados de autenticação em hermes_cli/auth.py

Para provedores com chave de API, acrescente uma entrada ProviderConfig ao PROVIDER_REGISTRY com:

• id
• name
• auth_type="api_key"
• inference_base_url
• api_key_env_vars
• opcionalmente, base_url_env_var

Acrescente também os apelidos em _PROVIDER_ALIASES.

Use os provedores existentes como modelo:

• caminho simples de chave de API: Z.AI, MiniMax
• caminho de chave de API com detecção de endpoint: Kimi, Z.AI
• resolução nativa de token: Anthropic
• caminho de OAuth / armazenamento de credenciais: Nous, OpenAI Codex

Perguntas a responder aqui:

• Quais variáveis de ambiente o Hermes deve consultar, e em que ordem de prioridade?
• O provedor precisa de sobrescrita de URL-base?
• Ele precisa de sondagem de endpoint ou de renovação de token?
• O que a mensagem de erro de autenticação deve dizer quando faltam credenciais?

Se o provedor precisa de algo além de "buscar uma chave de API", acrescente um resolvedor de credenciais dedicado, em vez de enfiar lógica em ramos que não têm nada a ver.

Passo 3: acrescente o catálogo de modelos e os apelidos em hermes_cli/models.py

Atualize o catálogo de provedores para que o provedor funcione nos menus e na sintaxe provider:model.

Edições típicas:

• _PROVIDER_MODELS
• _PROVIDER_LABELS
• _PROVIDER_ALIASES
• a ordem de exibição dos provedores dentro de list_available_providers()
• provider_model_ids(), se o provedor aceita busca ao vivo em /models

Se o provedor expõe uma lista de modelos ao vivo, prefira essa lista e mantenha o _PROVIDER_MODELS como reserva estática.

Este arquivo também é o que faz entradas como estas funcionarem:

anthropic:claude-sonnet-4-6
kimi:model-name

Se faltarem apelidos aqui, o provedor pode autenticar direito e ainda assim falhar na interpretação do /model.

Passo 4: resolva os dados de execução em hermes_cli/runtime_provider.py

O resolve_runtime_provider() é o caminho compartilhado usado pela CLI, pelo gateway, pelo cron, pelo ACP e pelos clientes auxiliares.

Acrescente um ramo que devolva um dicionário com, no mínimo:

{
    "provider": "seu-provedor",
    "api_mode": "chat_completions",  # ou o seu modo nativo
    "base_url": "https://...",
    "api_key": "...",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

Se o provedor é compatível com a OpenAI, o api_mode em geral deve continuar chat_completions.

Tome cuidado com a precedência das chaves de API. O Hermes já tem lógica para evitar vazar uma chave do OpenRouter para endpoints sem relação. Um provedor novo deve ser igualmente explícito sobre qual chave vai para qual URL-base.

Passo 5: ligue a CLI em hermes_cli/main.py

Um provedor não é descobrível até aparecer no fluxo interativo do hermes model.

Atualize o seguinte em hermes_cli/main.py:

• o dicionário provider_labels
• a lista providers em select_provider_and_model()
• o despacho de provedor (if selected_provider == ...)
• as opções do argumento --provider
• as opções de login/logout, se o provedor tem esses fluxos
• uma função _model_flow_<provider>() — ou reaproveite _model_flow_api_key_provider(), se servir

dica

O hermes_cli/setup.py não precisa de mudança — ele chama o select_provider_and_model() do main.py, então o seu provedor novo aparece automaticamente tanto no hermes model quanto no hermes setup.

Passo 6: mantenha as chamadas auxiliares funcionando

Dois arquivos importam aqui:

agent/auxiliary_client.py

Acrescente um modelo auxiliar barato/rápido como padrão em _API_KEY_PROVIDER_AUX_MODELS, se este for um provedor direto de chave de API.

As tarefas auxiliares incluem coisas como:

• resumo de visão
• resumo de extração de páginas web
• resumos de compressão de contexto
• resumos de busca em sessões
• descargas de memória

Se o provedor não tem um padrão auxiliar razoável, as tarefas laterais podem cair para uma reserva ruim ou usar, sem aviso, um modelo principal caro.

agent/model_metadata.py

Acrescente os tamanhos de contexto dos modelos do provedor, para que o orçamento de tokens, os limiares de compressão e os limites continuem coerentes.

Passo 7: se o provedor é nativo, acrescente um adaptador e suporte no run_agent.py

Se o provedor não é chat completions puro, isole a lógica específica dele em agent/<provider>_adapter.py.

Mantenha o run_agent.py focado na orquestração. Ele deve chamar funções auxiliares do adaptador, e não montar payloads de provedor na mão espalhados pelo arquivo.

Um provedor nativo em geral exige trabalho nestes pontos:

Arquivo novo de adaptador

Responsabilidades típicas:

• montar o cliente SDK / HTTP
• resolver tokens
• converter as mensagens da conversa no estilo OpenAI para o formato de requisição do provedor
• converter os esquemas de ferramenta, se preciso
• normalizar as respostas do provedor de volta ao que o run_agent.py espera
• extrair os dados de uso e de motivo de encerramento

run_agent.py

Busque por api_mode e revise todo ponto de decisão. No mínimo, confirme que:

• o __init__ escolhe o novo api_mode
• a construção do cliente funciona para o provedor
• o _build_api_kwargs() sabe formatar as requisições
• o _interruptible_api_call() despacha para a chamada de cliente certa
• os caminhos de interrupção / reconstrução do cliente funcionam
• a validação de resposta aceita o formato do provedor
• a extração do motivo de encerramento está correta
• a extração do uso de tokens está correta
• a ativação de modelo de reserva consegue passar para o provedor novo sem tropeços
• os caminhos de geração de resumo e de descarga de memória continuam funcionando

Busque também por self.client. no run_agent.py. Qualquer caminho de código que presume a existência do cliente padrão da OpenAI pode quebrar quando um provedor nativo usa outro objeto de cliente ou faz self.client = None.

Cache de prompt e campos de requisição específicos do provedor

Cache de prompt e ajustes específicos de provedor regridem com facilidade.

Exemplos que já existem na árvore:

• a Anthropic tem um caminho nativo de cache de prompt
• o OpenRouter recebe campos de roteamento de provedor
• não é para todo provedor receber toda opção do lado da requisição

Quando você acrescenta um provedor nativo, confira duas vezes se o Hermes está enviando apenas campos que aquele provedor realmente entende.

Passo 8: testes

No mínimo, mexa nos testes que protegem a ligação de provedores.

Lugares comuns:

• tests/hermes_cli/test_runtime_provider_resolution.py
• tests/cli/test_cli_provider_resolution.py
• tests/hermes_cli/test_model_switch_custom_providers.py (e os vizinhos tests/hermes_cli/test_model_switch_*.py)
• tests/hermes_cli/test_setup_model_provider.py
• tests/run_agent/test_provider_parity.py
• tests/run_agent/test_run_agent.py
• tests/test_<provider>_adapter.py, para um provedor nativo

Em exemplos que só mexem na documentação, o conjunto exato de arquivos pode ser outro. O ponto é cobrir:

• resolução de autenticação
• menu da CLI / escolha de provedor
• resolução do provedor em tempo de execução
• caminho de execução do agente
• interpretação de provider:model
• qualquer conversão de mensagem específica do adaptador

Rode os testes direcionados (ou use o scripts/run_tests.sh, que roda cada arquivo no próprio subprocesso):

source venv/bin/activate
python -m pytest tests/hermes_cli/test_runtime_provider_resolution.py tests/cli/test_cli_provider_resolution.py tests/hermes_cli/test_setup_model_provider.py tests/run_agent/test_provider_parity.py -q

Para mudanças mais profundas, rode a suíte completa antes de dar push:

source venv/bin/activate
python -m pytest tests/ -n0 -q

Passo 9: verificação ao vivo

Depois dos testes, faça um teste de fumaça de verdade.

source venv/bin/activate
python -m hermes_cli.main chat -q "Diga olá" --provider seu-provedor --model seu-modelo

Teste também os fluxos interativos, se você mudou menus:

source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup

Para provedores nativos, verifique pelo menos uma chamada de ferramenta também, não só uma resposta de texto simples.

Passo 10: atualize a documentação do usuário

Se o provedor deve ser entregue como opção de primeira classe, atualize também a documentação do usuário:

• website/docs/getting-started/quickstart.md
• website/docs/user-guide/configuration.md
• website/docs/reference/environment-variables.md

Uma pessoa pode ligar o provedor com perfeição e, ainda assim, deixar os usuários sem descobrir as variáveis de ambiente necessárias ou o fluxo de configuração.

Checklist de provedor compatível com a OpenAI

Use este se o provedor é chat completions padrão.

• ProviderConfig acrescentado em hermes_cli/auth.py
• apelidos acrescentados em hermes_cli/auth.py e hermes_cli/models.py
• catálogo de modelos acrescentado em hermes_cli/models.py
• ramo de execução acrescentado em hermes_cli/runtime_provider.py
• ligação da CLI acrescentada em hermes_cli/main.py (o setup.py herda automaticamente)
• modelo auxiliar acrescentado em agent/auxiliary_client.py
• tamanhos de contexto acrescentados em agent/model_metadata.py
• testes de execução / CLI atualizados
• documentação do usuário atualizada

Checklist de provedor nativo

Use este quando o provedor precisa de um caminho de protocolo novo.

• tudo do checklist de provedor compatível com a OpenAI
• adaptador acrescentado em agent/<provider>_adapter.py
• novo api_mode suportado no run_agent.py
• o caminho de interrupção / reconstrução funciona
• a extração de uso e de motivo de encerramento funciona
• o caminho de reserva funciona
• testes do adaptador acrescentados
• o teste de fumaça ao vivo passa

Armadilhas comuns

1. Adicionar o provedor à autenticação, mas não à interpretação de modelo

Isso faz as credenciais resolverem direito enquanto as entradas /model e provider:model falham.

2. Esquecer que config["model"] pode ser uma string ou um dicionário

Boa parte do código de escolha de provedor tem que normalizar as duas formas.

3. Presumir que um provedor embutido é obrigatório

Se o serviço é só compatível com a OpenAI, um provedor personalizado talvez já resolva o problema do usuário com menos manutenção.

4. Esquecer os caminhos auxiliares

O caminho principal de conversa pode funcionar enquanto o resumo, as descargas de memória ou os auxiliares de visão falham, porque o roteamento auxiliar nunca foi atualizado.

5. Ramos de provedor nativo escondidos no run_agent.py

Busque por api_mode e por self.client.. Não presuma que o caminho de requisição óbvio é o único.

6. Enviar ajustes exclusivos do OpenRouter para outros provedores

Campos como o de roteamento de provedor pertencem só aos provedores que os suportam.

7. Atualizar o hermes model e não o hermes setup

Os dois fluxos precisam conhecer o provedor.

Bons alvos de busca durante a implementação

Se você está caçando todos os lugares em que um provedor toca, busque por estes símbolos:

• PROVIDER_REGISTRY
• _PROVIDER_ALIASES
• _PROVIDER_MODELS
• resolve_runtime_provider
• _model_flow_
• select_provider_and_model
• api_mode
• _API_KEY_PROVIDER_AUX_MODELS
• self.client.

Documentação relacionada

• Resolução do Provedor em Tempo de Execução
• Arquitetura
• Contribuir

---