A Home Assistant custom integration that connects Hermes Agent by Nous Research as a conversation agent for voice assistants and the conversation panel.
- Conversation agent — use Hermes Agent as your voice assistant in Home Assistant
- Streaming — low latency for voice pipelines (first token arrives fast)
- Entity exposure — includes your smart home device states in the system prompt
- Multi-turn — maintains conversation history across turns
- Username resolution — passes the user's name to the agent
- Configurable — connection settings and prompt options can be changed anytime via Configure
- Multiple instances — connect to both the local add-on and an external Hermes Agent
- Home Assistant 2024.12 or newer
- A running Hermes Agent instance with the API server enabled:
- Easiest: Install the Hermes Agent add-on and enable the API in the add-on configuration
- Alternative: Run Hermes Agent standalone and point the integration at its API endpoint
- Open HACS in Home Assistant
- Click the three dots in the top right → Custom repositories
- Add
https://github.com/WolframRavenwolf/hermes-ha-integrationas an Integration - Search for "Hermes Agent" and install it
- Restart Home Assistant
- Copy the
custom_components/hermes_conversationfolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
- Make sure the Hermes Agent add-on is running with Enable API turned on
- Go to Settings → Devices & Services → Add Integration
- Search for "Hermes Agent"
- Enter the Host, Port (default: 8443), and the API Key (the Access Password from the add-on configuration)
- Use HTTPS is on by default (the add-on uses a self-signed certificate)
- Verify SSL certificate is off by default (for self-signed certs)
- Click Submit
- Go to Settings → Voice Assistants
- Create a new assistant or edit an existing one
- Select Hermes Agent as the Conversation agent
- Disable Prefer handling commands locally (Hermes Agent handles everything)
After setup, all settings can be changed via Settings → Devices & Services → Hermes Agent → Configure:
| Option | Default | Description |
|---|---|---|
| Host | homeassistant.local | Hermes Agent hostname or IP |
| Port | 8443 | API port |
| API Key | (empty) | API key (the Access Password from the add-on configuration) |
| Use HTTPS | Yes | Connect via HTTPS |
| Verify SSL certificate | No | Verify the SSL certificate (disable for self-signed) |
| System Prompt | (built-in) | Jinja2 template — leave empty to use Hermes Agent's own prompt |
| Include exposed entities | No | Include smart home device states in the system prompt |
| Max context characters | 12000 | Character limit for the entity context block |
The default system prompt includes the current date/time, timezone, the user's name, the home name, and exposed device states (if enabled). Entity exposure is off by default since Hermes Agent can access Home Assistant entities directly when a Home Assistant token is configured in the Hermes Agent add-on.
This integration communicates with Hermes Agent's OpenAI-compatible API (/v1/chat/completions) using only Home Assistant's built-in HTTP client — no external Python dependencies.
Hermes Agent handles tool execution (controlling lights, checking sensors, etc.) server-side through its own Home Assistant tools. This means the conversation integration stays simple: it sends your message, gets back the response (which may include results from tool actions the agent performed), and displays it.
