A multi-agent AI assistant for Home Assistant with container-based A2A orchestration, two-tier caching, hybrid entity matching, MCP tool integration, and a plugin system.
- Multi-agent orchestration -- 13 specialized domain agents coordinated by a central orchestrator via the A2A protocol
- A2A protocol -- direct in-process agent-to-agent communication with registry, dispatcher, and transport
- Two-tier cache -- Routing cache (skip intent classification) and action cache, formerly response cache (caches the full agent response after the pipeline runs) using SQLite-backed SHA-256 exact hash matching
- Cache backup and restore -- Export and import the routing and action caches as a portable JSON envelope via
/api/admin/cache/exportand/api/admin/cache/import - Action-cache validator -- Background validation of action-cache entries with configurable model/batch size, exposed via
/api/admin/cache/validate - Conditional actions --
ActionableAgentskips redundant service calls when the current HA state already matches the requested end state - Hybrid entity matching -- Five-signal weighted matcher (Levenshtein, Jaro-Winkler, phonetic, embedding similarity, alias lookup) with LLM disambiguation fallback. Agents can explicitly declare extracted entities via
@entities:lines in their replies, replacing legacy regex heuristics with structured LLM-driven entity extraction - MCP tool integration -- Connect external tool servers via Model Context Protocol (stdio and SSE transports) and assign tools to agents
- Plugin system -- Extend functionality with Python plugins that inspect registered agents, dispatch work back through the orchestrator, add routes, subscribe to events, and access settings/MCP integrations
- Admin dashboard -- HTMX-powered admin dashboard for managing chat, persons, personality, system health, calendar, timers, send devices, logs, custom agents, agents, entities, cache, MCP servers, analytics, traces, and plugins
- Custom agents -- Create LLM-powered agents via the dashboard with custom system prompts, model selection, MCP tools, and intent patterns
- Rewrite agent -- Optional response variation for cached responses (driven by the personality prompt) to avoid repetitive answers
- Setup wizard -- Guided 5-step first-launch configuration (admin account, HA connection, API key, LLM providers, review)
- First-class LLM providers -- OpenRouter, Groq, Cerebras, Anthropic, and Ollama supported out of the box
- Analytics and tracing -- Request counts, cache hit rates, latency tracking, token usage, and per-request trace span Gantt visualization, with per-turn tracing on
/ws/conversation - TTFT/TPS instrumentation -- Per-request time-to-first-token and tokens-per-second metrics surfaced in traces and analytics
- Voice experience -- Filler-first return, post-filler push, sentence-by-sentence streaming, voice-followup, cancel-intent ("never mind"), and repeat-turn coalescing in the HA integration
- Mediation streaming -- Begins TTS playback earlier by streaming mediated response tokens before the full reply is finalized
- Real-pipeline scenario tests -- YAML scenarios and HA snapshots under
container/tests/data/scenarios/(runner incontainer/tests/scenarios/) exercising the full orchestrator pipeline against a curated HA snapshot - Remote Logs API -- In-memory ring-buffer log inspection with runtime level adjustment via admin endpoints
- Persistent file logs --
RotatingFileHandlerwrites toLOG_DIR/app.log (default/data/logs/app.log) in addition to the in-memory Remote Logs API - Cache Management UI Enhancements -- Per-entry cache deletion from the admin dashboard
| Agent | HA Domains | Capabilities |
|---|---|---|
| Light Agent | light, switch, sensor (illuminance) |
On/off, toggle, brightness, color, color temperature |
| Climate Agent | climate, weather, sensor |
Temperature, HVAC mode, fan speed, humidity, weather queries |
| Media Agent | media_player |
Playback, volume, source selection |
| Music Agent | media_player |
Music-focused playback (radio, playlists) |
| Cover Agent | cover |
Open, close, stop, set position, tilt control |
| Vacuum Agent | vacuum |
Start, pause, stop, return to base, clean spot, set fan speed |
| Scene Agent | scene |
Scene activation |
| Timer Agent | timer, input_datetime, input_boolean |
Timers, alarms, reminders |
| Automation Agent | automation, script |
Trigger, enable, disable, and query automations |
| Security Agent | lock, binary_sensor, alarm_control_panel |
Arm/disarm, lock/unlock, camera status |
| Calendar Agent | calendar |
Query events, add reminders |
| Lists Agent | todo, shopping_list |
Shopping and todo list management |
| Send Agent | — | Deliver content to phones, satellites, and notification targets |
| Agent | Purpose |
|---|---|
| Orchestrator | Intent classification, agent routing, mediation, and sequential dispatch |
| General Agent | Fallback for general questions, web search, and unroutable requests |
| Rewrite Agent | Response variation for cached hits to avoid repetitive answers |
| Filler Agent | Generate interim TTS filler phrases while agents compute |
These helpers run inside the container pipeline but are not registered as A2A agents:
- Cancel Speech -- LLM-generated acknowledgement for dismiss intents ("never mind")
- Wake Briefing Composer -- Compose spoken morning briefings for internal alarms
- Alarm Monitor -- Monitor internal alarms and trigger wake briefings
Tools are external capabilities connected via the Model Context Protocol (MCP) and can be assigned to any agent.
| Tool | Transport | Description |
|---|---|---|
| Wikipedia Search | stdio | Search Wikipedia articles (wikipedia_search) and retrieve summaries (wikipedia_summary) |
| DuckDuckGo Search | stdio | Web search via DuckDuckGo |
Custom MCP servers can be added through the admin dashboard (stdio or SSE transports).
HA-AgentHub (repository: ha-agenthub) runs as a Docker container with a FastAPI backend. A Home Assistant custom integration (custom_components/ha_agenthub/) bridges turns to the container, streams responses back, and honors a small set of container-directed bridge actions.
All configuration, secrets, and state are stored in SQLite. sqlite-vec provides vector storage for entity embeddings (moved from ChromaDB in v1.37.0); the routing and action caches are stored in SQLite with SHA-256 exact hash matching. No configuration files are used at runtime.
See docs/architecture.md for component diagrams, request flow, and detailed design.
- Docker Engine 20.10+ and Docker Compose v2
- A running Home Assistant instance (2025.1.0+)
- An LLM API key (OpenRouter, Groq, Cerebras, Anthropic, or Ollama)
git clone https://github.com/mainzerp/ha-agenthub.git
cd ha-agenthub/container
docker compose up -dThe production container/docker-compose.yml pulls the prebuilt
image from ghcr.io/mainzerp/ha-agenthub:${HA_AGENTHUB_TAG:-latest}.
For a local development build (sources from this checkout):
docker compose -f docker-compose_local.yml up -d --buildOpen http://<docker-host>:8080/setup/ in your browser and follow the 5-step wizard:
- Create an admin account
- Connect to Home Assistant (URL + Long-Lived Access Token)
- Generate a container API key (save it -- shown once)
- Configure LLM provider(s)
- Review and complete
After setup, the dashboard is available at /dashboard/. See the User Guide for a walkthrough of every page, embedded screenshots, and common workflows.
Via HACS (recommended):
- In HACS, add
https://github.com/mainzerp/ha-agenthubas a custom repository (category: Integration). - Install "HA-AgentHub" and restart Home Assistant.
Manual:
Copy custom_components/ha_agenthub/ to your HA config/custom_components/ directory and restart HA.
Configure:
In HA, go to Settings > Devices & Services > Add Integration > "HA-AgentHub". Enter the container URL and API key.
HA-AgentHub uses three configuration tiers:
- Environment variables -- Infrastructure-only (e.g.
LOG_LEVEL), set indocker-compose.yml - Setup wizard -- One-time secrets and connections, stored encrypted in SQLite
- Admin dashboard -- All runtime settings, hot-reloadable without restart
See docs/configuration.md for the full reference.
Language setting: For best results, set your preferred language explicitly in the admin dashboard (e.g.
de,fr,es) rather than leaving it onauto. Automatic language detection can be unreliable for very short voice commands. A manual setting ensures the assistant always uses your language and resolves entity names correctly.
- User Guide -- Dashboard walkthrough, screenshots, and common workflows
- Deployment Guide -- Docker setup, setup wizard, HA integration, networking, backup
- Configuration Reference -- Environment variables, SQLite settings, agent config
- Architecture Overview -- Components, A2A protocol, request flow, cache, entity matching
- API Reference -- All REST, SSE, and WebSocket endpoints covering conversation, admin settings, agents, custom agents, MCP servers, entity index/visibility, cache, calendar, timers, send devices, analytics, traces, logs, plugins, and setup wizard
- Backup and Restore -- Volume backup, Fernet key export, cache export/import
- Plugin Development -- Writing plugins, lifecycle hooks, event bus
- Troubleshooting -- Common issues and solutions
- UI Style Guide -- Design tokens, component classes, and dashboard conventions
cd container
pip install -r requirements-dev.txt
python -m pytest tests/ -qFast inner loop without integration-marked tests:
cd container
python -m pytest tests/ -q -m "not integration"Local parallel run when dev dependencies are installed:
cd container
python -m pytest tests/ -n auto -q --tb=shortpytest-xdist is declared in container/requirements-dev.txt, but -n auto only works in environments where the dev requirements have actually been installed.
cd container
ruff check .
ruff format --check .Run ruff check + format automatically on every git commit:
pip install pre-commit
pre-commit installHooks are scoped to container/ and pinned to ruff v0.15.15; dev
requirements install ruff==0.15.20, which is what CI runs.
container/ Docker container (FastAPI backend)
app/ Application code
a2a/ A2A protocol (registry, dispatcher, transport)
agents/ Specialized agents + orchestrator
analytics/ Analytics aggregation and queries
api/routes/ REST/SSE/WebSocket endpoints
cache/ Two-tier exact-hash cache (routing + action)
dashboard/ Admin dashboard (HTMX + Jinja2 templates)
db/ SQLite schema + repository
entity/ Hybrid entity matcher
ha_client/ Home Assistant REST + WebSocket client
llm/ LLM client (litellm)
mcp/ MCP tool integration
middleware/ Auth + tracing middleware
models/ Pydantic models
plugins/ Plugin system
prompts/ System prompts for orchestrator and domain agents
security/ Encryption, hashing, sanitization
setup/ Setup wizard
util/ Shared helpers
plugins/ User plugins directory
tests/ Test suite (incl. real-pipeline scenarios)
scenarios/ YAML scenarios and HA snapshots under `container/tests/data/scenarios/` (runner in `container/tests/scenarios/`)
data/ Test fixtures and curated HA snapshots
custom_components/ HA custom integration
ha_agenthub/ HA bridge
brand/ Brand icons and images for HACS
translations/ UI translation files (en.json, de.json, etc.)
Plugins extend HA-AgentHub without modifying core code. Create a .py file in container/plugins/, subclass BasePlugin, and implement lifecycle hooks.
See docs/plugin-development.md for the full guide.
MIT