Adding Providers
Hermes can already talk to any OpenAI compatible endpoint through the custom provider path. Do not add a built in provider unless you want first class UX for th
Hermes can already talk to any OpenAI-compatible endpoint through the custom provider path. Do not add a built-in provider unless you want first-class UX for that service: If the provider is just "another OpenAI-compatible base URL and API key", a named custom provider may be enough. A built-in provider has to line up across a few layers: 1. …
What this page covers
- The mental model
- Choose the implementation path first
- Path A — OpenAI-compatible provider
- Path B — Native provider
- File checklist
- Required for every built-in provider
- Additional for native / non-OpenAI providers
- Fast path: Simple API-key providers
- Full path: OAuth and complex providers
- Step 1: Pick one canonical provider id
- Step 2: Add auth metadata in hermescli/auth.py
- Step 3: Add model catalog and aliases in hermescli/models.py
- Step 4: Resolve runtime data in hermescli/runtimeprovider.py
- Step 5: Wire the CLI in hermescli/main.py
- Step 6: Keep auxiliary calls working
- agent/auxiliaryclient.py
- agent/modelmetadata.py
- Step 7: If the provider is native, add an adapter and runagent.py support
- New adapter file
- runagent.py
- Prompt caching and provider-specific request fields
- Step 8: Tests
- Step 9: Live verification
- Step 10: Update user-facing docs
- OpenAI-compatible provider checklist
- Native provider checklist
- Common pitfalls
- 1. Adding the provider to auth but not to model parsing
- 2. Forgetting that config["model"] can be a string or a dict
- 3. Assuming a built-in provider is required
- 4. Forgetting auxiliary paths
- 5. Native-provider branches hiding in runagent.py
- 6. Sending OpenRouter-only knobs to other providers
- 7. Updating hermes model but not hermes setup
- Good search targets while implementing
- Related docs
Section outline mirrored from the official Hermes Agent documentation. Follow any heading to read the complete text on the source site.
More in Developer Guide
Contributing
Thank you for contributing to Hermes Agent! This guide covers setting up your dev environment, understanding the codebase, and getting your PR merged. Contribut
Architecture
This page is the top level map of Hermes Agent internals. Use it to orient yourself in the codebase, then dive into subsystem specific docs for implementation d
Agent Loop Internals
The core orchestration engine is 's class — a large file that handles everything from prompt assembly to tool dispatch to provider failover. Core Responsibiliti
Prompt Assembly
Hermes deliberately separates: cached system prompt state ephemeral API call time additions This is one of the most important design choices in the project beca
Context Compression and Caching
Context Compression and Caching Hermes Agent uses a dual compression system and Anthropic prompt caching to manage context window usage efficiently across long
Gateway Internals
The messaging gateway is the long running process that connects Hermes to 20+ external messaging platforms through a unified architecture. Key Files File Purpos