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

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)

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