voice-assistant/docs/agent-api.md

Voice-Agent Command API

The stable contract for sending a command to the Jervis LLM service and getting a spoken reply. Works for any AI model, script, N8N workflow, ESP32, web page, or Android app — not just Home Assistant.

---

Quick start

Send a command (HTTP):

curl -X POST http://192.168.20.13:8501/voice \
  -H "Content-Type: application/json" \
  -d '{"text":"add chicken to the shopping list"}'
# → {"text":"add chicken to the shopping list","reply":"Done, I've added chicken to your shopping list."}

The reply is also spoken through your speakers via Snapcast.

Send a command (MQTT):

mosquitto_pub -h 192.168.20.30 -u mqtt-user -P <pass> -t homeassistant/voice/text -m "what time is it"

Same effect — the agent picks up the topic and speaks the reply. (Use whichever transport is easier for the caller.)

---

Endpoint

Method	Path	Body	Returns
POST	/voice	{"text": "<command>"}	{"text": ..., "reply": ...}
GET	/health	—	{"status":"ok","model":"..."}

• Base URL: http://192.168.20.13:8501
• Optional: {"message": "..."} can be used instead of {"text": "..."}.

---

What the LLM can do (tools it will call)

Example command	Tool	Backend
"what time is it"	get_time	built-in
"what's the weather"	get_weather	Open-Meteo
"add milk to the shopping list"	add_shopping_item	KitchenOwl
"turn on the lounge lights"	control_ha	Home Assistant REST
"remind me to water the plants"	set_reminder	HA notification
"feed the fish"	feed_fish	HA input_button.fish_feeder
"put on your Donald Trump voice and tell me a joke"	speak_as	piper (per-character)
"send {topic}/{payload}" (advanced)	ha_service_cmd	HA any service
any open question	answer	OmniRoute LLM
"play {artist/album}"	play_music	Mopidy (planned)

The LLM picks the tool automatically from natural language — you don't pick it.

---

Voices (for speak_as)

trump, donald, hal, hal 9000, picard, captain, eminem, glados, ryan, alan, bt/bt7274, mech.

---

Notes for other AI agents

• The same text can be sent by any model/caller — the agent does the reasoning + tool dispatch + speaking.
• For non-voice callers (N8N, scripts) that just want the reply text without speaking, the agent currently speaks by design (voice assistant). A ?speak=0 / {"speak": false} option can be added if needed.
• Timeouts: LLM tool loops are bounded (max 5). Expect a few seconds for tool calls.

---

Config / env (/home/sam/voice-agent/.env)

Var	Meaning
LLM_BASE, LLM_MODEL, LLM_KEY	OmniRoute endpoint + model
HA_URL, HA_TOKEN	Home Assistant REST + long-lived token
KITCHENOWL_URL/_HOUSEHOLD/_LIST/_USER/_PASS	KitchenOwl shopping write
MQTT_BROKER/_TOPIC/_USER/_PASS	text intake + output
SPEAK_CMD, DEFAULT_VOICE	piper TTS command/voice
LAT, LON	weather location
AGENT_PORT	HTTP port (8501)

Secrets live in .env (gitignored) — never commit them.