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

thông tin

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

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

Hermes Agent đă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ựcBộ đ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

Cấu hình bắt buộc

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 số 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ổng đài viên nhìn thấy trong ~/.hermes/config.yaml trong phần extra của nền tảng 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

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 nên dùng 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ể

mẹo

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 để 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ý chí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:

Tên miền bị chặn

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."