Home Assistant との連携

Hermes Agent は Home Assistant と 2 つの形で連携します。

ゲートウェイのプラットフォームとして — WebSocket で状態の変化をリアルタイムに受け取り、その出来事に反応します
スマートホームのツールとして — REST API 経由で機器の状態を調べたり操作したりする、LLM から呼べる 4 つのツールを提供します

設定

1. 長期アクセストークンを作る

自分の Home Assistant を開きます
プロフィール へ移動します（サイドバーで自分の名前をクリックします）
長期アクセストークン まで画面を下げます
トークンを作成 をクリックし、「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

3. ゲートウェイを起動する

hermes gateway

Home Assistant が、ほかのメッセージングサービス（Telegram、Discord など）と並んで、つながっているプラットフォームとして表示されます。

使えるツール

Hermes Agent は、スマートホームを操作するための 4 つのツールを登録します。

`ha_list_entities`

Home Assistant のエンティティを一覧します。ドメインやエリアで絞り込めます。

引数:

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`

1 つのエンティティの詳しい状態を取得します。明るさ、色、設定温度、センサーの測定値といった属性もすべて含みます。

引数:

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

ゲートウェイのプラットフォーム: リアルタイムの出来事

Home Assistant のゲートウェイアダプターは WebSocket で接続し、state_changed のイベントを購読します。機器の状態が変わり、それが指定した条件に合っていれば、メッセージとしてエージェントへ転送されます。

イベントの絞り込み

エージェントがどのイベントを見るかは、~/.hermes/config.yaml の Home Assistant プラットフォームの extra の下で設定します。

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`	同じエンティティのイベントの間に空ける最小の秒数

イベントの書式

状態の変化は、ドメインに応じて人が読める文章にまとめられます。

ドメイン	書式
`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'」
(そのほか)	「changed from 'old' to 'new'」

エージェントからの返答

エージェントから送られるメッセージは、Home Assistant の常設通知 として届きます（persistent_notification.create を使います）。HA の通知パネルに「Hermes Agent」という見出しで表示されます。

接続の管理

WebSocket で、30 秒ごとのハートビートを使ってリアルタイムのイベントを受け取ります
自動再接続 は待ち時間を延ばしながら行います: 5 秒 → 10 秒 → 30 秒 → 60 秒
REST API は送信する通知に使います（WebSocket とぶつからないよう、別のセッションを使います）
認可 — HA のイベントは常に許可されます（HASS_TOKEN が接続を認証しているので、ユーザーの許可リストは要りません）

セキュリティ

Home Assistant のツールには、安全のための制限があります。

エンティティ ID は、インジェクション攻撃を防ぐために ^[a-z_][a-z0-9_]*\.[a-z0-9_]+$ というパターンで検証されます。

自動化の例

朝の支度

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

戸締まりの確認

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

出来事に反応する自動化（ゲートウェイのイベント経由）

ゲートウェイのプラットフォームとしてつないでおくと、エージェントは出来事に反応できます。

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

困ったときは

環境変数が読み込まれない。 アダプターは認証情報を ~/.hermes/.env（起動時に自動で取り込まれます）か config.yaml から読みます。そのファイルが今使っている Hermes のプロファイルのホームの下にあるか、URL やトークンに余計な引用符が付いていないかを確認してください。編集したらゲートウェイを再起動します。環境変数の変更はプロセスの起動時にしか反映されません。

REST の認証が通らない（401 Unauthorized）。 トークンは、HA のユーザープロフィールのページ（プロフィール → セキュリティ → 長期アクセストークン）から作った *長期アクセストークン* である必要があります。画面のセッション用の短命なトークンでは動きません。ベース URL にスキームとポートが入っているか（例: http://homeassistant.local:8123）、Hermes を動かしているホストからつながるかも確認してください。 curl -H "Authorization: Bearer <token>" <url>/api/ が {"message": "API running."} を返せば大丈夫です。