ai-agent/integrations/home-assistant

ai_agent — Home Assistant custom integration

The Home Assistant side of the ai-agent notification hub. It registers a webhook (/api/webhook/ai_agent) that the ai-agent backend forwards its notify and ask events to, and turns them into Android companion-app notifications:

• notify — a normal push on the per-type channel (Claude · Deploy, Claude · Error, …) with the same icon/color/vibration map the notify-done skill used to apply client-side. Explicit payload fields (icon, channel, vibrationPattern, …) always win over the type defaults.
• ask — a persistent notification on the dedicated Claude · Ask channel with the ". .. .._" morse vibration pattern (0, 100, 350, 100, 120, 100, 350, 100, 120, 100, 120, 450) and one action button per option. When a button is tapped the integration POSTs {"index": n} back to the backend (POST /api/ask/{id}/answer) and clears the notification from the phone. Whatever is long-polling GET /api/ask/{id}?waitSecs=… (normally ask.sh) then unblocks with the chosen label.

Android locks a channel's importance/vibration when the channel is first created — to re-tune the ask buzz, rename ASK_CHANNEL in const.py (or clear the companion app's storage).

The voice leg (phone_service)

A notify has two destinations in the homelab: the screen (the Pixel push above) and the AI desk phone (services/phone, a Yealink that reads updates aloud over an auto-answer call). Both go through this one webhook: when phone_service: <domain>.<service> is configured, every notify is also handed to that HA service with the phone-relevant fields —

{"spoken": …, "type": …, "title": …, "message": …, "audio": …}

— non-blocking and best-effort, so a ringing (or absent) phone never delays the push nor fails the hub's webhook. The homelab points it at script.ai_agent_phone_notify (services/home-assistant/config/packages/ai_agent_phone.yaml), which POSTs to the phone bridge; that script is where HA-side routing policy belongs. Leave phone_service unset for screen-only notifications.

Asks have no voice leg on purpose — answering one means tapping a button.

Events on the bus

Every handled payload is also fired on the HA event bus as ai_agent_notify / ai_agent_ask (the raw webhook JSON as event data), so automations can react to agent activity — flash a light on type: error, count deploys, mirror asks to another device — without re-implementing the webhook.

Install

./install.sh --restart     # copy component + config block, restart HA

HA_CONFIG overrides the target config dir (default: services/home-assistant/config). The config block it adds:

ai_agent:
  webhook_id: ai_agent                  # -> POST /api/webhook/ai_agent
  notify_target: mobile_app_pixel_9     # notify.<target>
  callback_url: http://127.0.0.1:8096   # ai-agent backend (host-published port)
  phone_service: script.ai_agent_phone_notify   # voice leg (see below)

HA runs on the host network, so 127.0.0.1:8096 reaches the ai-agent container's published port; the backend's trusted-caller gate accepts the connection because it arrives from the docker gateway.

Verify

docker logs home-assistant 2>&1 | grep ai_agent          # "ai_agent ready: …"
curl -s -X POST http://127.0.0.1:8123/api/webhook/ai_agent \
  -H 'Content-Type: application/json' \
  -d '{"event":"notify","title":"test","message":"hello","type":"success"}'