Imagine a seguinte cena: sua equipe mantém um gateway de inferência compartilhado internamente, servindo seus próprios modelos com fine-tuning além de alguns modelos de terceiros via proxy. Cada vez que um novo modelo entra no ar, você edita o config.yaml do Hermes à mão — endpoint, chave de API, nomes de modelos, um campo por vez — e depois cada colega repete o mesmo ritual na própria máquina. Não seria ótimo empacotar “como falar com os modelos da nossa empresa” em um único pacote, para que qualquer pessoa possa simplesmente dar um pip install e pronto? O PR #85504, mesclado em 13 de agosto, torna isso realidade: model providers agora podem ser pacotes Python comuns que se auto-registram via entry points. Uma vez instalados, o Hermes os descobre na inicialização e seus modelos aparecem no model registry exatamente como os de qualquer provider integrado.

O mecanismo: um único entry point faz o registro

Um provider é a camada de adaptação do Hermes para “como alcançar um serviço de modelos” — ele conhece a forma do endpoint, onde a chave de API vai e como as requisições são enviadas. Antes, os providers só podiam ser registrados por meio de plugins de filesystem ou do conjunto integrado. O PR #85504 adiciona um “passo 0” ao fluxo de descoberta em providers/__init__.py: escanear os entry points de todas as distribuições Python instaladas e procurar qualquer uma que se declare como provider.

A configuração é pequena: no pyproject.toml do seu próprio pacote, declare um entry point apontando para uma função de registro sem argumentos:

[project.entry-points."hermes_agent.plugins"]
acme-inference = "acme_hermes_plugin:register"

A função register() constrói um ProviderProfile e chama register_provider():

# acme_hermes_plugin.py
from providers import register_provider
from providers.base import ProviderProfile

def register():
    register_provider(
        ProviderProfile(
            name="acme-inference",
            display_name="Acme Inference",
            base_url="https://inference.internal.acme.com/v1",
            env_vars=("ACME_API_KEY",),
            auth_type="api_key",
        )
    )

Os campos de ProviderProfile são exatamente o que “conectar a um serviço de modelos” exige: nome, nome de exibição, endpoint padrão, a variável de ambiente que guarda a chave de API, o tipo de autenticação, além de extras opcionais como uma lista de modelos de fallback (fallback_models). Os plugins de provider no estilo diretório que a documentação oficial descreve ($HERMES_HOME/plugins/model-providers/<name>/__init__.py) usam a mesma API — o mecanismo de entry points simplesmente troca “colocar um diretório” por “pip install”; o código de registro em si é idêntico.

Além da forma de callable module:func, o entry point também pode ser um nome de módulo simples (acme-inference = "acme_hermes_plugin") — o Hermes importa o módulo e depende da chamada register_provider no nível do módulo, espelhando o contrato de __init__.py dos plugins de filesystem. Uma vez instalado e habilitado pela porta descrita abaixo, o Hermes o invoca na inicialização e seus modelos aparecem no seletor hermes model e em todos os outros lugares onde providers são listados.

A porta crítica: instalado ≠ habilitado

Esta é a regra mais importante de todo o mecanismo, então leia duas vezes: instalar um pacote via pip não significa que ele é carregado. O escaneamento de entry points compartilha os mesmos interruptores do gerenciador geral de plugins — a allow-list plugins.enabled e a deny-list plugins.disabled:

plugins:
  enabled:
    - acme-inference   # only entry points listed here are loaded
  disabled:
    - some-other-plugin  # the deny-list always wins

Se o nome do seu pacote não estiver em plugins.enabled, o Hermes nem sequer o importa — um pacote pip nunca é executado apenas por estar instalado. Isso importa para a segurança: qualquer pacote que você instalar com pip install poderia silenciosamente declarar um entry point de hermes_agent.plugins, mas apenas aquele que você explicitamente colocou na allow-list realmente entra em vigor.

Detalhes de segurança que vale a pena conhecer

Além da porta allow-list, o design adiciona várias camadas de proteção:

• Faixa exclusiva para providers: o grupo de entry points hermes_agent.plugins é compartilhado com plugins gerais (plugins de UI, plugins de ferramentas, etc.). A diferença: as funções de registro de plugins gerais recebem um argumento (register(ctx)), enquanto os hooks de registro de providers são sem argumentos por contrato. O scanner ignora qualquer callable que exija argumentos, então plugins gerais nunca são confundidos com providers — e você também não recebe uma enxurrada de avisos de TypeError.
• Um pacote quebrado não derruba o Hermes: se o entry point de um pacote de terceiros falhar ao carregar, a falha é absorvida por entrada e registrada como aviso; a descoberta de providers continua. Um pacote ruim não impede o Hermes de iniciar.
• Os integrados sempre vencem em colisões de nome: o escaneamento de entry points roda primeiro na ordem de descoberta, e register_provider() segue a regra de quem escreve por último vence — então um pacote pip nunca pode sobrepor um provider embutido ou um em $HERMES_HOME. Ele pode registrar um nome totalmente novo, mas não pode sequestrar um nome de primeira parte já existente.

Quando vale a pena fazer isso

• Compartilhe uma integração de modelos com a equipe inteira: empacote seu gateway interno como um pacote pip; os colegas rodam pip install mais uma linha na allow-list e pronto — chega de editar endpoints máquina por máquina.
• Modelos privados / self-hosted: fine-tunes internos, clusters vLLM self-hosted — empacote o provider, versione-o com pip e faça upgrade com pip install -U.
• Publique para o mundo: se a sua integração de provider tem valor geral, publique-a no PyPI — qualquer pessoa pode instalá-la e habilitá-la com uma configuração de uma linha.

Se você já estende as ferramentas do Hermes com MCP (veja nosso guia de configuração de MCP e variáveis de contexto), os plugins de provider completam a outra metade do quadro: o MCP gerencia ferramentas, os providers gerenciam modelos — ambas são integrações declarativas, uma sobre o protocolo MCP e outra sobre entry points. Toda a superfície CLI de plugins está na página do comando hermes plugins; e um lembrete — em configurações com múltiplos perfis, plugins.enabled é configurado por perfil (veja o guia de múltiplas instâncias e perfis), então não assuma que uma allow-list definida em um perfil vale em todos os lugares.

Em uma linha: os plugins de provider transformam “ligar um novo serviço de modelos” de edição manual de config para “pip install + uma linha na allow-list” — o atrito está na segurança (a allow-list é explícita), a conveniência está na engenharia (empacotado, compartilhável e versionado).