Tích hợp trợ lý tại nhà

Hermes Agent tích hợp với Home Assistant theo hai cách:

1. Nền tảng cổng — đăng ký các thay đổi trạng thái theo thời gian thực thông qua WebSocket và phản hồi các sự kiện
2. Công cụ nhà thông minh — bốn công cụ có thể gọi LLM để truy vấn và điều khiển thiết bị thông qua API REST

Thiết lập

1. Tạo mã thông báo truy cập tồn tại lâu dài

1. Mở phiên bản Home Assistant của bạn
2. Đi tới Hồ sơ của bạn (nhấp vào tên của bạn ở thanh bên)
3. Cuộn đến Mã thông báo truy cập tồn tại lâu
4. Nhấp vào Tạo mã thông báo, đặt tên như "Đặc vụ Hermes"
5. Sao chép mã thông báo

2. Cấu hình biến môi trường

# 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

`

:::info
Bộ công cụ 
`homeassistant
` được bật tự động khi 
`HASS_TOKEN
` được đặt. Cả nền tảng cổng và công cụ điều khiển thiết bị đều kích hoạt từ mã thông báo duy nhất này.
:::

### 3. Khởi động Gateway

``` bash
Hermes gateway

`
``Home Assistant sẽ xuất hiện dưới dạng một nền tảng được kết nối cùng với mọi nền tảng nhắn tin khác (Telegram, Discord, v.v.).

## Công cụ có sẵn

Đại lý Hermes đăng ký 4 công cụ điều khiển nhà thông minh:

###
`ha_list_entities
``Liệt kê các thực thể Trợ lý Trang chủ, được lọc tùy ý theo miền hoặc khu vực.

**Thông số:**

- 
`domain
` *(tùy chọn)* — Lọc theo miền thực thể: 
`light

, 
`switch

, 
`CLImate

, 
`sensor

, 
`binary_sensor

, 
`cover

, 
`fan

, 
`media_player

, v.v.
- 
`area
` *(tùy chọn)* — Lọc theo tên khu vực/phòng (khớp với tên thân thiện): 
`living room

, 
`kitchen

, 
`bedroom

, v.v.

**Ví dụ:**

`

List all lights in the living room

`
``Trả về ID thực thể, trạng thái và tên thân thiện.

###
`ha_get_state
``Nhận trạng thái chi tiết của một thực thể duy nhất, bao gồm tất cả các thuộc tính (độ sáng, màu sắc, điểm đặt nhiệt độ, chỉ số cảm biến, v.v.).

**Thông số:**
- 
`entity_id
` *(bắt buộc)* — Thực thể cần truy vấn, ví dụ: 
`light.living_room

, 
`CLImate.thermostat

, 
`sensor.temperature
``**Ví dụ:**

`

What's the current state of CLImate.thermostat?

`
``Trả về: trạng thái, tất cả các thuộc tính, dấu thời gian được thay đổi/cập nhật lần cuối.

###
`ha_list_services
``Liệt kê các dịch vụ (hành động) có sẵn để điều khiển thiết bị. Hiển thị những hành động nào có thể được thực hiện trên từng loại thiết bị và những thông số nào chúng chấp nhận.

**Thông số:**
- 
`domain
` *(tùy chọn)* — Lọc theo tên miền, ví dụ: 
`light

, 
`CLImate

, 
`switch
``**Ví dụ:**

`

What services are available for CLImate devices?

`

###
`ha_call_service
``Gọi dịch vụ Home Assistant để điều khiển thiết bị.

**Thông số:**
- 
`domain
` *(bắt buộc)* — Miền dịch vụ: 
`light

, 
`switch

, 
`CLImate

, 
`cover

, 
`media_player

, 
`fan

, 
`scene

, 
`script

- 
`service
` *(bắt buộc)* — Tên dịch vụ: 
`turn_on

, 
`turn_off

, 
`toggle

, 
`set_temperature

, 
`set_hvac_mode

, 
`open_cover

, 
`close_cover

, 
`set_volume_level

- 
`entity_id
` *(tùy chọn)* — Thực thể mục tiêu, ví dụ: 
`light.living_room

- 
`data
` *(tùy chọn)* — Tham số bổ sung dưới dạng đối tượng JSON`**Ví dụ:**

`
Turn on the living room lights
→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")

`

`

Set the thermostat to 22 degrees in heat mode
→ ha_call_service(domain="CLImate", service="set_temperature",
    entity_id="CLImate.thermostat", data=\{"temperature": 22, "hvac_mode": "heat"})

`

`

Set living room lights to blue at 50% brightness
→ ha_call_service(domain="light", service="turn_on",
    entity_id="light.living_room", data=\{"brightness": 128, "color_name": "blue"})

`

## Nền tảng cổng: Sự kiện thời gian thực

Bộ điều hợp cổng Home Assistant kết nối qua WebSocket và đăng ký các sự kiện 
`state_changed

. Khi trạng thái thiết bị thay đổi và khớp với bộ lọc của bạn, trạng thái đó sẽ được chuyển tiếp tới tổng đài viên dưới dạng tin nhắn.

### Lọc sự kiện

:::warning[Required Configuration]
Theo mặc định, **không có sự kiện nào được chuyển tiếp**. Bạn phải định cấu hình ít nhất một trong các 
`watch_domains

, 
`watch_entities
` hoặc 
`watch_all
` để nhận sự kiện. Nếu không có bộ lọc, cảnh báo sẽ được ghi lại khi khởi động và tất cả các thay đổi trạng thái sẽ bị loại bỏ một cách âm thầm.
:::

Định cấu hình những sự kiện mà tác nhân nhìn thấy trong 

~/.Hermes/config.yaml
` trong phần 
`extra
` của nền tảng Trợ lý gia đình:

``` yaml
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

`

| Cài đặt | Mặc định | Mô tả |
|----------|----------|-------------|
| 
`watch_domains
` | *(không có)* | Chỉ xem các miền thực thể này (ví dụ: 
`CLImate

, 
`light

, 
`binary_sensor

) |
| 
`watch_entities
` | *(không có)* | Chỉ xem các ID thực thể cụ thể này |
| 
`watch_all
` | 
`false
` | Đặt thành 
`true
` để nhận **tất cả** các thay đổi trạng thái (không được khuyến nghị cho hầu hết các thiết lập) |
| 
`ignore_entities
` | *(không có)* | Luôn bỏ qua các thực thể này (áp dụng trước các bộ lọc tên miền/thực thể) |
| 
`cooldown_seconds
` | 
`30
` | Số giây tối thiểu giữa các sự kiện cho cùng một thực thể |

:::tip
Bắt đầu với một nhóm miền tập trung — 
`CLImate

, 
`binary_sensor
` và 
`alarm_control_panel
` bao gồm các hoạt động tự động hóa hữu ích nhất. Thêm nhiều hơn khi cần thiết. Sử dụng 
`ignore_entities
` để ngăn chặn các cảm biến gây nhiễu như nhiệt độ CPU hoặc bộ đếm thời gian hoạt động.
:::

### Định dạng sự kiện

Các thay đổi trạng thái được định dạng dưới dạng thông báo mà con người có thể đọc được dựa trên miền:

| Tên miền | Định dạng |
|--------|--------|
| 
`CLImate
` | "Chế độ HVAC đã thay đổi từ 'tắt' thành 'nhiệt' (hiện tại: 21, mục tiêu: 23)" |
| 
`sensor
` | "thay đổi từ 21°C thành 22°C" |
| 
`binary_sensor
` | "kích hoạt" / "xóa" |
| 
`light

, 
`switch

, 
`fan
` | "bật" / "tắt" |
| 
`alarm_control_panel
` | "trạng thái cảnh báo đã thay đổi từ 'armed_away' thành 'kích hoạt'" |
| *(khác)* | "đã thay đổi từ 'cũ' thành 'mới'" |

### Phản hồi của Đại lý

Tin nhắn gửi đi từ tổng đài viên được gửi dưới dạng **Thông báo liên tục của Trợ lý gia đình** (thông qua 
`persistent_notification.create

). Chúng xuất hiện trong bảng thông báo HA với tiêu đề "Đặc vụ Hermes".

### Quản lý kết nối
- **WebSocket** với nhịp tim 30 giây cho các sự kiện theo thời gian thực
- **Tự động kết nối lại** có thời gian chờ: 5s → 10s → 30s → 60s
- **REST API** cho thông báo gửi đi (phiên riêng biệt để tránh xung đột WebSocket)
- **Ủy quyền** — Các sự kiện HA luôn được ủy quyền (không cần danh sách cho phép của người dùng vì 
`HASS_TOKEN
` xác thực kết nối)

## Bảo mật

Các công cụ Home Assistant thực thi các hạn chế về bảo mật:

:::warning[Blocked Domains]
Các miền dịch vụ sau bị **chặn** để ngăn việc thực thi mã tùy ý trên máy chủ HA:
- 
`shell_command

 - lệnh shell tùy ý
- 
`command_line
` — cảm biến/công tắc thực thi lệnh
- 
`Python_script

 - thực thi Python theo kịch bản
- 
`pyscript
` — tích hợp tập lệnh rộng hơn
- 
`hassio
` — kiểm soát tiện ích bổ sung, tắt/khởi động lại máy chủ
- 
`rest_command

 - Yêu cầu HTTP từ máy chủ HA (vectơ SSRF)

Việc cố gắng gọi các dịch vụ trong các miền này sẽ trả về lỗi.
:::

ID thực thể được xác thực theo mẫu 

^[a-z_][a-z0-9_]*\.[a-z0-9_]+$
` để ngăn chặn các cuộc tấn công tiêm nhiễm.

## Ví dụ về tự động hóa

### Thói quen buổi sáng

`
User: Start my morning routine

Agent:
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")

`

### Kiểm tra bảo mật

`
User: Is the house secure?

Agent:
1. ha_list_entities(domain="binary_sensor")
     → checks door/window sensors
2. ha_get_state(entity_id="alarm_control_panel.home")
     → checks alarm status
3. ha_list_entities(domain="lock")
     → checks lock states
4. Reports: "All doors closed, alarm is armed_away, all locks engaged."

`

### Tự động hóa phản ứng (thông qua Sự kiện cổng)

Khi được kết nối dưới dạng nền tảng cổng, tác nhân có thể phản ứng với các sự kiện:

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

Agent automatically:
1. ha_get_state(entity_id="binary_sensor.front_door")
2. ha_call_service(domain="light", service="turn_on",
     entity_id="light.hallway")
3. Sends notification: "Front door opened. Hallway lights turned on."

`
`