Integração com o Home Assistant

O Hermes Agent se integra ao Home Assistant de duas formas:

1. Plataforma no gateway — assina mudanças de estado em tempo real por WebSocket e responde a eventos
2. Ferramentas de casa inteligente — quatro ferramentas chamáveis pelo LLM para consultar e controlar dispositivos pela API REST

Configuração

1. Crie um Long-Lived Access Token

1. Abra a sua instância do Home Assistant
2. Vá até o seu Profile (clique no seu nome na barra lateral)
3. Role até Long-Lived Access Tokens
4. Clique em Create Token e dê um nome, algo como "Hermes Agent"
5. Copie o token

2. Configure as variáveis de ambiente

# Adicione ao ~/.hermes/.env

# Obrigatório: o seu Long-Lived Access Token
HASS_TOKEN=seu-long-lived-access-token

# Opcional: URL do HA (padrão: http://homeassistant.local:8123)
HASS_URL=http://192.168.1.100:8123

informação

O conjunto de ferramentas homeassistant é habilitado automaticamente quando HASS_TOKEN está definida. Tanto a plataforma do gateway quanto as ferramentas de controle de dispositivos são ativadas por esse único token.

3. Suba o gateway

hermes gateway

O Home Assistant vai aparecer como uma plataforma conectada, ao lado das outras plataformas de mensagens (Telegram, Discord etc.).

Ferramentas disponíveis

O Hermes Agent registra quatro ferramentas para controle da casa inteligente:

ha_list_entities

Lista entidades do Home Assistant, opcionalmente filtradas por domínio ou área.

Parâmetros:

• domain (opcional) — filtra pelo domínio da entidade: light, switch, climate, sensor, binary_sensor, cover, fan, media_player etc.
• area (opcional) — filtra pelo nome da área/cômodo (comparado com os nomes amigáveis): sala, cozinha, quarto etc.

Exemplo:

Liste todas as luzes da sala

Devolve os IDs das entidades, os estados e os nomes amigáveis.

ha_get_state

Pega o estado detalhado de uma única entidade, incluindo todos os atributos (brilho, cor, temperatura alvo, leituras de sensor etc.).

Parâmetros:

• entity_id (obrigatório) — a entidade a consultar, por exemplo light.living_room, climate.thermostat, sensor.temperature

Exemplo:

Qual é o estado atual de climate.thermostat?

Devolve: estado, todos os atributos e os horários da última mudança/atualização.

ha_list_services

Lista os serviços (ações) disponíveis para controlar dispositivos. Mostra que ações dá para executar em cada tipo de dispositivo e que parâmetros elas aceitam.

Parâmetros:

• domain (opcional) — filtra pelo domínio, por exemplo light, climate, switch

Exemplo:

Que serviços estão disponíveis para dispositivos de climatização?

ha_call_service

Chama um serviço do Home Assistant para controlar um dispositivo.

Parâmetros:

• domain (obrigatório) — domínio do serviço: light, switch, climate, cover, media_player, fan, scene, script
• service (obrigatório) — nome do serviço: turn_on, turn_off, toggle, set_temperature, set_hvac_mode, open_cover, close_cover, set_volume_level
• entity_id (opcional) — entidade alvo, por exemplo light.living_room
• data (opcional) — parâmetros extras, como objeto JSON

Exemplos:

Acenda as luzes da sala
→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")

Coloque o termostato em 22 graus, no modo aquecimento
→ ha_call_service(domain="climate", service="set_temperature",
    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})

Deixe as luzes da sala azuis com 50% de brilho
→ ha_call_service(domain="light", service="turn_on",
    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})

Plataforma no gateway: eventos em tempo real

O adaptador de gateway do Home Assistant conecta por WebSocket e assina eventos state_changed. Quando o estado de um dispositivo muda e casa com os seus filtros, o evento é encaminhado ao agente como mensagem.

Filtragem de eventos

Configuração obrigatória

Por padrão, nenhum evento é encaminhado. Você precisa configurar pelo menos um entre watch_domains, watch_entities ou watch_all para receber eventos. Sem filtros, um aviso é registrado na inicialização e todas as mudanças de estado são descartadas em silêncio.

Configure quais eventos o agente enxerga no ~/.hermes/config.yaml, na seção extra da plataforma do Home Assistant:

platforms:
  homeassistant:
    enabled: true
    extra:
      watch_domains:
        - climate
        - binary_sensor
        - alarm_control_panel
        - light
      watch_entities:
        - sensor.front_door_battery
      ignore_entities:
        - sensor.uptime
        - sensor.cpu_usage
        - sensor.memory_usage
      cooldown_seconds: 30

Opção	Padrão	Descrição
watch_domains	(nenhum)	Observa só estes domínios de entidade (por exemplo climate, light, binary_sensor)
watch_entities	(nenhum)	Observa só estes IDs de entidade específicos
watch_all	false	Defina como true para receber todas as mudanças de estado (não recomendado na maioria dos casos)
ignore_entities	(nenhum)	Ignora sempre estas entidades (aplicado antes dos filtros de domínio/entidade)
cooldown_seconds	30	Intervalo mínimo, em segundos, entre eventos da mesma entidade

dica

Comece com um conjunto enxuto de domínios — climate, binary_sensor e alarm_control_panel cobrem as automações mais úteis. Acrescente mais conforme a necessidade. Use ignore_entities para calar sensores barulhentos, como temperatura de CPU ou contadores de tempo ligado.

Formatação dos eventos

As mudanças de estado viram mensagens legíveis, conforme o domínio:

Domínio	Formato
climate	"HVAC mode changed from 'off' to 'heat' (current: 21, target: 23)"
sensor	"changed from 21°C to 22°C"
binary_sensor	"triggered" / "cleared"
light, switch, fan	"turned on" / "turned off"
alarm_control_panel	"alarm state changed from 'armed_away' to 'triggered'"
(outros)	"changed from 'old' to 'new'"

Respostas do agente

As mensagens de saída do agente são entregues como notificações persistentes do Home Assistant (via persistent_notification.create). Elas aparecem no painel de notificações do HA com o título "Hermes Agent".

Gerenciamento da conexão

• WebSocket com heartbeat de 30 segundos para eventos em tempo real
• Reconexão automática com espera crescente: 5s → 10s → 30s → 60s
• API REST para as notificações de saída (sessão separada, para evitar conflito com o WebSocket)
• Autorização — eventos do HA são sempre autorizados (não precisa de lista de usuários permitidos, já que o HASS_TOKEN autentica a conexão)

Segurança

As ferramentas do Home Assistant aplicam restrições de segurança:

Domínios bloqueados

Os domínios de serviço abaixo são bloqueados, para impedir execução arbitrária de código na máquina do HA:

• shell_command — comandos de shell arbitrários
• command_line — sensores/interruptores que executam comandos
• python_script — execução de Python por script
• pyscript — integração de scripting mais ampla
• hassio — controle de addons, desligamento/reinício do host
• rest_command — requisições HTTP a partir do servidor do HA (vetor de SSRF)

Tentar chamar serviços nesses domínios devolve erro.

Os IDs de entidade são validados contra o padrão ^[a-z_][a-z0-9_]*\.[a-z0-9_]+$, para prevenir ataques de injeção.

Exemplos de automação

Rotina matinal

Usuário: Comece a minha rotina matinal

Agente:
1. ha_call_service(domain="light", service="turn_on",
     entity_id="light.bedroom", data={"brightness": 128})
2. ha_call_service(domain="climate", service="set_temperature",
     entity_id="climate.thermostat", data={"temperature": 22})
3. ha_call_service(domain="media_player", service="turn_on",
     entity_id="media_player.kitchen_speaker")

Checagem de segurança

Usuário: A casa está segura?

Agente:
1. ha_list_entities(domain="binary_sensor")
     → confere sensores de porta/janela
2. ha_get_state(entity_id="alarm_control_panel.home")
     → confere o estado do alarme
3. ha_list_entities(domain="lock")
     → confere o estado das fechaduras
4. Responde: "Todas as portas fechadas, alarme em armed_away, todas as fechaduras travadas."

Automação reativa (por eventos do gateway)

Conectado como plataforma do gateway, o agente consegue reagir a eventos:

[Home Assistant] Front Door: triggered (was cleared)

O agente, automaticamente:
1. ha_get_state(entity_id="binary_sensor.front_door")
2. ha_call_service(domain="light", service="turn_on",
     entity_id="light.hallway")
3. Envia a notificação: "Porta da frente aberta. Luzes do corredor acesas."

Resolução de problemas

As variáveis de ambiente não são aplicadas. O adaptador lê as credenciais do ~/.hermes/.env (mesclado automaticamente na inicialização) ou do config.yaml. Confira se o arquivo está dentro da pasta do perfil Hermes ativo e se não sobrou aspa perdida em volta da URL ou do token. Reinicie o gateway depois de editar — mudanças de ambiente só valem quando o processo sobe.

Autenticação REST falhando (401 Unauthorized). O token precisa ser um Long-Lived Access Token criado na página de perfil do seu usuário do HA (Profile → Security → Long-lived access tokens). Tokens de sessão da interface, de curta duração, não funcionam. Confira também se a base URL inclui o esquema e a porta (por exemplo, http://homeassistant.local:8123) e se ela é alcançável a partir da máquina que roda o Hermes — o comando curl -H "Authorization: Bearer <token>" <url>/api/ deve devolver {"message": "API running."}.