HA Agent
holger81/ha_agent
Agente conversacional inteligente para Home Assistant com LLM local e ferramentas MCP
Ver no GitHubServidor MCP que funciona como agente conversacional para Home Assistant, conectando um LLM local a ferramentas MCP para controlar dispositivos, responder perguntas e executar tarefas complexas. Oferece memória multi-turno, streaming de respostas e aprendizado de skills automático.
Instalação
npx convez-ai holger81/ha_agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Controlar dispositivos smart home via voz e conversa natural
- Executar tarefas complexas multi-etapas com memória de contexto
- Integrar LLM local (llama.cpp, Ollama) ao pipeline de assistente
- Aprender e reusar fluxos de automação como skills personalizadas
Veredito

Solução técnica robusta para quem precisa de um agente conversacional nativo em Home Assistant com modelos locais. Requer conhecimento de LLMs, MCP e Home Assistant, mas oferece flexibilidade e privacidade superiores. Ótima alternativa ao n8n para builders experientes.
README
A tradução para o português deste README ainda está na fila.
HA Agent
HA Agent is a Home Assistant custom integration that powers the Assist conversation stage of your voice pipeline. It connects your assistant to a local LLM and an MCP tool server so Assist can answer questions, control devices, fetch news, check email, and more — with multi-turn memory and optional learned skills.
Replaces the n8n Webhook Conversation agent from ha_liquidai_n8n. See Migration from n8n if you are switching from the hybrid workflow. Pair it with LiquidAI for speech-to-text and text-to-speech in the same pipeline.
Migrating from n8n? Follow docs/migration-from-n8n.md for a step-by-step cutover from Webhook Conversation to HA Agent.
flowchart LR
subgraph assist [Assist pipeline]
STT[LiquidAI STT]
Agent[HA Agent]
TTS[LiquidAI TTS]
end
subgraph backends [Backends]
LLM[OpenAI-compatible LLM]
MCP[MCP Proxy]
end
You((You)) --> STT --> Agent --> TTS --> You
Agent --> LLM
Agent --> MCP
MCP --> HA[Home Assistant]
What it does
- Conversation agent — registers as your Assist conversation provider
- Tool loop — calls MCP tools (lights, covers, news, mail, …) until the task is done
- Multi-turn memory — follow-ups like “turn them back off” reuse prior context
- Streaming — text deltas flow to LiquidAI TTS for responsive voice replies
- Learned skills — optional workflows saved after successful multi-step tasks and reused later
- Live tuning — change chat/action models and skill settings from the HA Agent device page
Requirements
| Item | Notes |
|---|---|
| Home Assistant | 2025.10+ (conversation streaming) |
| LLM server | OpenAI-compatible API (e.g. llama.cpp) |
| MCP Proxy | Tool server with bearer token (Home Assistant, news, email, …) |
| Speech (optional) | ha_liquidai for STT/TTS |
Install with HACS
The easiest way to install is through HACS.
1. Add the custom repository
-
Open HACS → Integrations
-
Click the ⋮ menu (top right) → Custom repositories
-
Paste the repository URL:
https://github.com/holger81/ha_agent -
Category: Integration → Add
2. Download the integration
- In HACS → Integrations, search for HA Agent
- Open it → Download
- Restart Home Assistant
3. Add the integration
- Settings → Devices & services → Add integration
- Search for HA Agent and complete the setup wizard (see First-time setup below)
Tip: Install LiquidAI the same way if you want voice input and output.
Manual install
Copy the integration into your config folder and restart Home Assistant:
git clone https://github.com/holger81/ha_agent.git
HA_CONFIG=/path/to/your/homeassistant/config ./ha_agent/scripts/deploy_to_ha.sh
Or copy custom_components/ha_agent/ into <config>/custom_components/ yourself.
First-time setup
After adding the integration, the config flow walks you through:
| Step | What you configure |
|---|---|
| Agent prompts | System prompt and short MCP tool reminder |
| LLM backend | Base URL, model, API key (optional), temperature, timeout |
| MCP Proxy | URL, bearer token, health check URL |
| Action model (optional) | Smaller/faster model for device commands only |
| Agent settings | Max tool iterations, conversation history, streaming |
Defaults assume a local stack (e.g. llama.cpp on :9292, MCP Proxy on :2222). Change everything in the UI — nothing is hardcoded at runtime.
Wire up Assist
1. Expose entities
Settings → Voice assistants → Expose — enable the lights, covers, and other entities you want the agent to control.
2. Set the pipeline
Settings → Voice assistants → your assistant → Configure:
| Stage | Provider |
|---|---|
| Speech-to-text | LiquidAI STT |
| Conversation | HA Agent |
| Text-to-speech | LiquidAI TTS |
Remove any old Webhook Conversation entry if you are migrating from n8n.
3. Talk or type
Use Assist from the dashboard, the companion app, or a voice satellite. Example prompts:
- “Turn off the dining room lights”
- “What’s the news?”
- “How many unread emails do I have?”
- “Turn them back off” (follow-up — uses conversation memory)
Using the agent day to day
Device page
Open Settings → Devices & services → HA Agent → your device.
Configuration (you can change these anytime):
| Entity | Purpose |
|---|---|
| Chat model | Main conversational model |
| Action model | Optional faster model for device actions |
| Action model routing | Send device commands to the action model |
| Skill learning | Learn workflows from successful multi-step tasks |
| Skill auto-save | Save skills without asking |
| Skill auto-use | Inject matching skills into new requests |
Diagnostic sensors show last route (chat / action), MCP tool count, LLM/MCP reachability, active skill, and skill stats.
Options flow
Configure on the integration card → Models and routing, then Skills to set how many skills are injected per turn (default 3).
Learned skills
When Skill learning is on and a multi-step task succeeds:
- Auto-save off — the agent asks “Save this as a skill?”; reply yes to store it
- Auto-save on — the skill is saved in the background
Manage skills by voice or text:
- “List my skills”
- “Disable the dining room lights skill”
- “Enable skill …” / “Delete skill …”
Automations can call ha_agent.enable_skill, ha_agent.disable_skill, ha_agent.delete_skill, and ha_agent.list_skills.
Follow-up conversations
The agent keeps short per-conversation history (configurable turn count). Pronouns and phrases like “them”, “again”, and “back” can refer to entities controlled in the previous turn.
HA Agent Console
Open the HA Agent item in the Home Assistant sidebar (admin only) for text chat, skills management, settings, and an activity log — without using Assist voice. See Agent Console for the WebSocket API and feature overview.
Architecture (short)
Assist → ha_liquidai STT → HA Agent → ha_liquidai TTS → you
↓
LLM (:9292/v1) + MCP Proxy (:2222/mcp)
HA Agent runs an LLM tool loop: the model may call MCP tools several times per turn until it has a final answer. Streaming mode sends text to TTS as it is generated.
Verify everything works
From your dev machine (optional):
pip install aiohttp
export HA_AGENT_MCP_TOKEN="your-bearer-token" # if required
python3 scripts/smoke_test_phase4.py
In Assist, try a device command, a news question, and a follow-up in the same conversation. Enable streaming in agent settings and check that replies appear progressively.
More detail: Assist pipeline setup · HA Agent Console · Migration from n8n · LiquidAI STT/TTS
Development
pip install -r requirements.txt
ruff check custom_components tests
pytest tests/
See PLAN.md for the roadmap.
License
MIT