Home Assistant

Hermes Agent 与 Home Assistant 的集成包含两部分：

1. 网关平台：通过 WebSocket 订阅实时状态变化，并对事件做出响应
2. 智能家居工具：提供 4 个可由 LLM 调用的工具，通过 REST API 查询和控制设备

设置

1. 创建 Long-Lived Access Token

1. 打开你的 Home Assistant 实例
2. 进入 Profile（点击侧边栏中的你的名字）
3. 滚动到 Long-Lived Access Tokens
4. 点击 Create Token，例如命名为 “Hermes Agent”
5. 复制该 token

2. 配置环境变量

# Add to ~/.hermes/.env

# Required: your Long-Lived Access Token
HASS_TOKEN=your-long-lived-access-token

# Optional: HA URL (default: http://homeassistant.local:8123)
HASS_URL=http://192.168.1.100:8123

信息

只要设置了 HASS_TOKEN，homeassistant 工具集就会自动启用。网关平台和设备控制工具都共用这一份 token。

3. 启动网关

hermes gateway

Home Assistant 会作为一个已连接平台出现在网关中，与 Telegram、Discord 等其他消息平台并列。

可用工具

Hermes Agent 会注册以下 4 个智能家居控制工具：

ha_list_entities

列出 Home Assistant 实体，可按 domain 或区域过滤。

参数：

• domain (optional)：按实体 domain 过滤，如 light、switch、climate、sensor、binary_sensor、cover、fan、media_player 等
• area (optional)：按区域/房间名过滤（匹配友好名称），如 living room、kitchen、bedroom

示例：

List all lights in the living room

返回实体 ID、状态和友好名称。

ha_get_state

获取单个实体的详细状态，包括所有属性（亮度、颜色、温控目标值、传感器读数等）。

参数：

• entity_id (required)：要查询的实体，如 light.living_room、climate.thermostat、sensor.temperature

示例：

What's the current state of climate.thermostat?

返回：状态、全部属性、最后变更时间和最后更新时间。

ha_list_services

列出可用服务（动作），展示每类设备支持哪些操作及其参数。

参数：

• domain (optional)：按 domain 过滤，如 light、climate、switch

示例：

What services are available for climate devices?

ha_call_service

调用 Home Assistant service 来控制设备。

参数：

• domain (required)：service 所属 domain，如 light、switch、climate、cover、media_player、fan、scene、script
• service (required)：service 名称，如 turn_on、turn_off、toggle、set_temperature、set_hvac_mode、open_cover、close_cover、set_volume_level
• entity_id (optional)：目标实体，如 light.living_room
• data (optional)：额外参数，JSON 对象格式

网关平台：实时事件

Home Assistant 网关适配器通过 WebSocket 连接，并订阅 state_changed 事件。当设备状态变化且命中你的过滤规则时，该事件会作为一条消息转发给 agent。

事件过滤

必需配置

默认情况下，不会转发任何事件。你必须至少配置 watch_domains、watch_entities 或 watch_all 其中之一，否则启动时会记录警告，并静默丢弃所有状态变化事件。

在 ~/.hermes/config.yaml 的 Home Assistant 平台 extra 段中配置 agent 能看到哪些事件：

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

Setting	Default	Description
watch_domains	(none)	只监听这些 entity domain
watch_entities	(none)	只监听这些指定 entity ID
watch_all	false	设为 true 时接收全部状态变化
ignore_entities	(none)	始终忽略这些实体
cooldown_seconds	30	同一实体两次事件之间的最小间隔（秒）

Agent 响应

agent 的出站消息会以 Home Assistant 持久化通知 的形式发送（通过 persistent_notification.create），显示在 HA 通知面板中，标题为 “Hermes Agent”。

安全

禁止的 domain

以下 service domain 会被阻止，以防在 HA 主机上执行任意代码：

• shell_command
• command_line
• python_script
• pyscript
• hassio
• rest_command

尝试调用这些 domain 下的服务时会直接返回错误。