LiveKit Agent integrated with Home Assistant MCP Server

Home Assistant Voice Agent（LiveKit）

一个面向 Home Assistant 的语音 + 文本助手，基于 LiveKit Agents 构建。本仓库是 worker（Agent 大脑）：它通过框架内置的 MCPToolset 连接 Home Assistant 原生的 MCP Server，并通过 LiveKit Inference 提供 STT / LLM / TTS。

仪表盘 UI 是一个 Home Assistant 自定义集成 + Lovelace 卡片，可在 HA 内运行会话： ha-livekit-agent-frontend。运行这个 worker，安装该集成，让两者指向同一个 LiveKit 项目，就配置完成了。

• 原生 MCP —— Home Assistant 工具（HassTurnOn、HassLightSet、GetLiveContext……） 通过 LiveKit 的 MCPToolset 直接暴露给大模型。无需自定义 MCP 客户端代码。
• LiveKit Inference —— STT、LLM 和 TTS 由 LiveKit 的推理网关提供；无需 各服务商的 API key。
• 成本感知 —— STT 按持续使用计费，因此它跟随麦克风：音频 输入处于活动状态时启用，麦克风被门控后经过 STT_IDLE_TIMEOUT 秒（默认 120）后销毁。Worker 启动时处于休眠状态（STT 关闭、无 TTS），因此仪表盘上闲置的卡片 除 worker 连接外不产生任何费用，并且文本聊天无需启用 STT 即可使用。
• 轮次模式 —— 手动按键说话（start_turn / end_turn / cancel_turn）或自动 轮次检测；可在运行时通过 set_turn_mode 切换。
• 辅助工具 —— 若干函数工具（get_areas、get_device_domains、get_devices、 get_environment_info）将 GetLiveContext 预处理为按区域/域过滤的紧凑视图， 以免大模型被完整的家庭状态淹没。

结构

.
├── agent/            # Python LiveKit worker (uv)
│   ├── src/          # main.py (entrypoint), agent.py, config.py, ha.py, scheduler_client.py, …
│   ├── prompt.yaml   # system prompt (bind-mounted, edit without a rebuild)
│   ├── mcp.yaml      # MCP servers besides Home Assistant's (bind-mounted too)
│   ├── pyproject.toml
│   └── Dockerfile
├── ha-notify-scheduler/  # people, scheduled tasks and HA notifications (FastAPI + APScheduler)
├── docker-compose.yml
├── .env.example      # agent + scheduler env
└── README.md

前置条件

• 已启用 MCP Server 集成的 Home Assistant，以及一个长期访问令牌。
• 一台 LiveKit 服务器（可自托管或 LiveKit Cloud），用于实时传输。
• 用于 STT/LLM/TTS 的 LiveKit Inference 凭据（LiveKit Cloud）。
• 已安装 HA 集成，用于 仪表盘 UI。

运行 worker

使用 uv。

cd agent
cp ../.env.example ../.env    # then fill in the values (see below)
uv sync
uv run src/main.py dev        # or `console` to test in the terminal

或使用 Docker Compose（构建并运行 worker）：

docker compose up --build

环境变量（仓库根目录下的 .env）

Agent 会调用 load_dotenv()，它会向上查找直到仓库根目录的 .env。

变量	用途
HA_URL	Home Assistant 基础 URL。会自动追加 /api/mcp。
HA_TOKEN	Home Assistant 长期访问令牌（作为 bearer token 发送）。
HA_HIDDEN_TOOLS	以逗号分隔的、要对大模型隐藏的 HA MCP 工具，例如家庭中不存在的设备所对应的 intent。默认为 GetDateTime,HassBroadcast,HassCancelAllTimers。
PARALLEL_API_KEY / MEM0_API_KEY / HERDR_MCP_URL	agent/mcp.yaml 中可选 MCP 服务的 key 和 URL；见 MCP 服务。
CALLBACK_BASE_URL	MCP 服务访问本 Agent 的 HTTP 应用时所用的地址，例如 http://<agent-host>:8952，供需要回报长任务的服务使用。
AGENT_PROMPT / AGENT_MCP_CONFIG	供 docker-compose 挂载的、你自己版本的 agent/prompt.yaml 和 agent/mcp.yaml；agent/*.local.yaml 已被 git 忽略。
AGENT_NAME	显式调度时的 worker 名称（默认 ha-agent）。必须与集成中的 Agent name 一致。
STT_IDLE_TIMEOUT	麦克风被门控后、销毁 STT 以节省成本前的等待秒数（默认 120）。
LIVEKIT_URL / LIVEKIT_API_KEY / LIVEKIT_API_SECRET	你的 LiveKit 服务器。
LIVEKIT_INFERENCE_URL / LIVEKIT_INFERENCE_API_KEY / LIVEKIT_INFERENCE_API_SECRET	推理网关。未设置时回退到 LIVEKIT_*。

模型默认使用对中文友好的选项，可通过 STT_MODEL、STT_LANGUAGE、LLM_MODEL、TTS_MODEL、TTS_VOICE、TTS_LANGUAGE 覆盖（见 .env.example）。

MCP 服务

Home Assistant 的 MCP 服务始终处于连接状态。其他服务列在 agent/mcp.yaml 中，其键从 .env 以 ${VAR} 形式读取，因此该文件不包含任何密钥。键未设置的服务会被跳过，因此 Agent 仅使用 Home Assistant 的工具运行。随附的文件列出了三个服务：

• Web 搜索（Parallel Search）：web_search 和 web_fetch。匿名免费层无需密钥即可使用。
• 记忆（Mem0）：跨对话记住偏好，并为每个人单独保存。需要 MEM0_API_KEY。
• 编码 Agent（herdr-mcp-server）：在运行 herdr 的电脑上启动、检查并提示 Claude Code 会话，因此"用电脑…"或"on my computer…"请求及其后续内容都会发送到那里的同一个会话。需要 HERDR_MCP_URL。它可以在那里运行代码，因此被标记为 restricted：只有其设置条目在 servers 下列出 herdr 的人才能使用它。

标记为 callback: true 的服务会在其 X-Callback-Url 和 X-Callback-Token 请求头中收到此 Agent 的 webhook。当任务超出其工具调用的生命周期时，该服务会向 /chat/events POST {"source", "text"}，然后 Agent 会在其文本对话中告知用户，并在此期间关闭工具。这需要 CALLBACK_BASE_URL 和 TEXT_API_TOKEN。mcp.yaml 顶部的注释描述了每个字段。要添加服务，请在那里添加一个条目，或者将你自己的列表保存在 AGENT_MCP_CONFIG 指向的副本中。

轮次模式与会话控制

卡片通过 worker 注册的 RPC 在运行时配置会话：

• set_turn_mode（manual | auto）— manual 是按住说话：麦克风保持关闭， 直到 start_turn，然后 end_turn 提交（Agent 回复）或 cancel_turn 丢弃。 auto 保持麦克风开启，让模型检测轮次结束。
• start_turn / end_turn / cancel_turn — 手动轮次生命周期。start_turn 打开 麦克风（重新启动 STT）；end_turn/cancel_turn 将其关闭（STT 在空闲超时后 拆除）。STT 完全跟随麦克风。
• set_audio_output（on | off）— 切换 Agent 的语音（TTS）回复；关闭表示 仅文本。默认为关闭，因此文本聊天始终可用，且没有任何 STT/TTS 成本。

worker 在 ha.speech_state 数据通道上广播其实时 STT + 音频输出状态， 以便卡片可以同步显示（例如 STT 被拆除时显示"睡眠"指示），并在 ha.tool_call 上 广播工具执行生命周期。

基于 HTTP 的文本聊天

端口 8952 上的 POST /chat 接收一行文本并以纯文本作答，在一个对话中进行，该对话在重启后仍会持续，直到被更新 — 专为 iPhone 快捷指令而设计。它运行在草稿版 livekit-agents API 上；用法、工作原理以及如何升级请参见 docs/text-endpoint.md。

前端 / 仪表盘 UI

使用配套的 Home Assistant 集成： ha-livekit-agent-frontend — 一个 HACS 自定义集成 + Lovelace 卡片，带有原生设备磁贴（点击即可控制）、语音、文本 聊天、转录和工具调用状态。它为已登录的 HA 用户铸造 LiveKit 令牌，并通过 AGENT_NAME 调度此 worker。