Gabriel Vidal
e62df7e6c3
Custom component under integrations/home-assistant/: registers the
/api/webhook/ai_agent webhook, renders notify events with the per-type
channel map, and renders asks on a dedicated 'Claude · Ask' channel with
the '. .. .._' vibration pattern as persistent tappable notifications —
the tapped answer is POSTed back to /api/ask/{id}/answer and the
notification cleared. install.sh copies it into the HA config and wires
configuration.yaml.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# `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
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
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"}'
|
|
```
|