홈 어시스턴트 통합

Hermes 에이전트는 두 가지 방식으로 홈 어시스턴트와 통합됩니다:

게이트웨이 플랫폼 — WebSocket을 통해 실시간 상태 변경을 구독하고 이벤트에 응답
스마트 홈 도구 — REST API를 통해 장치를 조회하고 제어할 수 있는 네 가지 LLM 호출 가능 도구

설치

1. 장기 액세스 토큰 생성

홈 어시스턴트 인스턴스를 엽니다
프로필로 이동합니다 (사이드바에서 이름 클릭)
장기 액세스 토큰으로 스크롤하기
토큰 만들기를 클릭하고, 'Hermes Agent'와 같은 이름을 지정하세요
토큰을 복사하세요

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

정보

homeassistant 도구 세트는 HASS_TOKEN 가 설정되면 자동으로 활성화됩니다. 게이트웨이 플랫폼과 장치 제어 도구 모두 이 단일 토큰에서 활성화됩니다.

3. 게이트웨이 시작

hermes gateway

Home Assistant는 다른 메신저 플랫폼(Telegram, Discord 등)과 함께 연결된 플랫폼으로 나타납니다.

사용 가능한 도구

Hermes 에이전트는 스마트 홈 제어를 위해 네 가지 도구를 등록합니다:

`ha_list_entities`

홈 어시스턴트 엔티티를 나열하며, 선택적으로 도메인이나 영역으로 필터링할 수 있습니다.

매개변수:

domain (선택 사항) — 엔티티 도메인별로 필터링: light, switch, climate, sensor, binary_sensor, cover, fan, media_player 등.
area (선택 사항) — 영역/방 이름으로 필터링 (친숙한 이름과 일치): living room, kitchen, bedroom 등.

예시:

List all lights in the living room

엔티티 ID, 상태 및 친근한 이름을 반환합니다.

`ha_get_state`

단일 엔티티의 모든 속성(밝기, 색상, 설정 온도, 센서 읽기 등)을 포함한 자세한 상태를 확인합니다.

매개변수:

entity_id (필수) — 조회할 엔터티, 예: light.living_room, climate.thermostat, sensor.temperature

예시:

What's the current state of climate.thermostat?

반환값: 상태, 모든 속성, 마지막 변경/업데이트 시각.

`ha_list_services`

장치 제어를 위한 사용 가능한 서비스(동작)를 나열합니다. 각 장치 유형에서 수행할 수 있는 동작과 허용되는 매개변수를 보여줍니다.

매개변수:

domain (선택 사항) — 도메인별로 필터링, 예: light, climate, switch

예시:

What services are available for climate devices?

`ha_call_service`

디바이스를 제어하기 위해 Home Assistant 서비스를 호출하세요.

매개변수:

domain (필수) — 서비스 영역: light, switch, climate, cover, media_player, fan, scene, script
service (필수) — 서비스 이름: turn_on, turn_off, toggle, set_temperature, set_hvac_mode, open_cover, close_cover, set_volume_level
entity_id (선택 사항) — 대상 엔티티, 예: light.living_room
data (선택 사항) — JSON 객체로 추가 매개변수

예시:

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"})
```

## 게이트웨이 플랫폼: 실시간 이벤트 \{#gateway-platform-real-time-events}

홈 어시스턴트 게이트웨이 어댑터는 WebSocket을 통해 연결되며 `state_changed` 이벤트를 구독합니다. 장치 상태가 변경되고 필터와 일치하면 메시지로 에이전트에 전달됩니다.

### 이벤트 필터링 \{#event-filtering}

:::warning[Required Configuration &#123;#event-filtering&#125;]
기본적으로 **이벤트는 전달되지 않습니다**. 이벤트를 수신하려면 `watch_domains`, `watch_entities` 또는 `watch_all` 중 최소 하나를 구성해야 합니다. 필터가 없으면 시작 시 경고가 기록되며 모든 상태 변경은 조용히 무시됩니다.

:::
Home Assistant 플랫폼의 `extra` 섹션에서 에이전트가 `~/.hermes/config.yaml`에서 보는 이벤트를 구성하세요:

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

| 설정 | 기본값 | 설명 |
|---------|---------|-------------|
| `watch_domains` | *(없음)* | 이 엔티티 도메인만 확인하세요 (예: `climate`, `light`, `binary_sensor`) |
| `watch_entities` | *(없음)* | 이 특정 엔티티 ID만 확인하세요 |
| `watch_all` | `false` | 모든 상태 변경을 수신하려면 `true`로 설정하세요(대부분의 설정에서는 권장되지 않음) |
| `ignore_entities` | *(없음)* | 항상 이러한 엔터티를 무시합니다(도메인/엔터티 필터 적용 이전에 적용됨) |
| `cooldown_seconds` | `30` | 같은 엔터티에 대한 이벤트 간 최소 초 |

:::tip
집중적인 도메인 세트로 시작하세요 — `climate`, `binary_sensor`, 그리고 `alarm_control_panel`가 가장 유용한 자동화를 다룹니다. 필요에 따라 더 추가하세요. `ignore_entities`를 사용하여 CPU 온도나 가동 시간 카운터와 같은 시끄러운 센서를 억제하세요.

:::
### 이벤트 형식 \{#event-formatting}

상태 변경은 도메인에 따라 사람이 읽을 수 있는 메시지 형식으로 표시됩니다:

| 도메인 | 형식 |
|--------|--------|
| `climate` | 'HVAC 모드가 '꺼짐'에서 '난방'으로 변경됨 (현재: 21, 목표: 23)' |
| `sensor` | 21°C에서 22°C로 변경됨 |
| `binary_sensor` | "발동됨" / "해제됨" |
| `light`, `switch`, `fan` | "켜짐" / "꺼짐" |
| `alarm_control_panel` | 알람 상태가 '외출 모드'에서 '발동됨'으로 변경되었습니다 |
| *(기타)* | 'old'에서 'new'로 변경됨 |

### 에이전트 응답 \{#agent-responses}

에이전트의 아웃바운드 메시지는 **Home Assistant 지속 알림**으로 전달됩니다(`persistent_notification.create`을 통해). 이들은 HA 알림 패널에 'Hermes Agent'라는 제목으로 나타납니다.

### 연결 관리 \{#connection-management}

- **WebSocket**을 통한 실시간 이벤트용 30초 하트비트
- **자동 재연결** 백오프: 5초 → 10초 → 30초 → 60초
- **REST API**를 이용한 아웃바운드 알림 (WebSocket 충돌을 피하기 위해 별도 세션)
- **승인** — HA 이벤트는 항상 승인됩니다 (사용자 허용 목록이 필요하지 않습니다. `HASS_TOKEN`가 연결을 인증하기 때문입니다)

## 보안 \{#security}

홈 어시스턴트 도구는 보안 제한을 적용합니다:

:::warning[Blocked Domains]
다음 서비스 도메인은 HA 호스트에서 임의 코드 실행을 방지하기 위해 **차단**됩니다:

- `shell_command` — 임의의 셸 명령어
- `command_line` — 명령을 실행하는 센서/스위치
- `python_script` — 스크립트화된 Python 실행
- `pyscript` — 더 광범위한 스크립팅 통합
- `hassio` — 애드온 제어, 호스트 종료/재부팅
- `rest_command` — HA 서버에서의 HTTP 요청 (SSRF 벡터)

이 도메인에서 서비스를 호출하려고 하면 오류가 발생합니다.

:::
엔터티 ID는 주입 공격을 방지하기 위해 `^[a-z_][a-z0-9_]*\.[a-z0-9_]+엔터티 ID는 주입 공격을 방지하기 위해  패턴에 대해 검증됩니다.

## 예제 자동화 \{#example-automations}

### 아침 일과 \{#morning-routine}

```
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")
```

### 보안 검사 \{#security-check}

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

### 게이트웨이 이벤트를 통한 반응형 자동화 \{#reactive-automation-via-gateway-events}

게이트웨이 플랫폼으로 연결될 때, 에이전트는 이벤트에 반응할 수 있습니다:

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

설치​

1. 장기 액세스 토큰 생성​

2. 환경 변수 구성​

3. 게이트웨이 시작​

사용 가능한 도구​

ha_list_entities​

ha_get_state​

ha_list_services​

ha_call_service​

설치

1. 장기 액세스 토큰 생성

2. 환경 변수 구성

3. 게이트웨이 시작

사용 가능한 도구

`ha_list_entities`

`ha_get_state`

`ha_list_services`

`ha_call_service`