Adding a Hermes Model Provider

Hermes already supports custom OpenAI-compatible endpoints. Add a first-class provider only when the service needs a discoverable identity, dedicated authentication, model catalog behavior, or a native protocol path.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/adding-providers

Choose the smallest path

A simple OpenAI-compatible service can often use a model-provider plugin with a profile that declares base URL, environment variables, API mode, and fallback models. OAuth, live catalogs, or nonstandard protocols may require deeper integration. A native protocol also needs an adapter and an audit of every API-mode branch in the agent loop.

The same provider identity must line up across authentication, aliases, model parsing, runtime resolution, setup, auxiliary tasks, context metadata, and documentation. Half-wired providers commonly authenticate successfully but fail in the model picker or side tasks.

Provider checklist

Decide whether custom configuration already solves the use case.
Choose one canonical provider ID and alias policy.
Declare exact credential precedence and endpoint scope.
Use chat_completions only for truly compatible endpoints.
Add model discovery or a maintained static fallback catalog.
Configure auxiliary-model defaults and context lengths.
Add a native adapter only when protocol differences require it.
Cover setup, model switching, runtime, fallback, and tool calls in tests.

Pitfalls

Adding auth metadata without model-parser support.
Sending provider-specific request fields to every endpoint.
Forgetting compression, vision, or other auxiliary routes.
Assuming a text response proves tool-call compatibility.
Shipping a model without accurate context-window metadata.

Verification steps

Configure the provider in a disposable profile.
Confirm it appears in setup and model-selection surfaces.
Resolve the runtime and verify provider, API mode, and endpoint.
Run a plain response and a harmless tool call.
Exercise an auxiliary task.
Test invalid credentials and a retryable service failure.
Run provider-parity and model-switch tests.
Verify the public setup and environment-variable documentation matches the implementation.