LiveKit Agent integrated with Home Assistant MCP Server

Home Assistant 音声エージェント (LiveKit)

Home Assistant 向けの音声 + テキストアシスタントで、 LiveKit Agents 上に構築されています。このリポジトリは ワーカー(エージェントの頭脳)です。フレームワークに組み込まれた MCPToolset を通じて Home Assistant ネイティブの MCP Server に接続し、LiveKit Inference 経由で STT / LLM / TTS を提供します。

ダッシュボード UI は、HA 内でセッションを実行する Home Assistant カスタム統合 + Lovelace カードです: ha-livekit-agent-frontend。この ワーカーを実行し、その統合をインストールし、両方を同じ LiveKit プロジェクトに向ければ 準備完了です。

• ネイティブ MCP — Home Assistant のツール(HassTurnOn、HassLightSet、GetLiveContext、…)は LiveKit の MCPToolset を通じて LLM に直接公開されます。独自の MCP クライアントコードは 不要です。
• LiveKit Inference — STT、LLM、TTS は LiveKit の推論ゲートウェイによって提供され、 プロバイダーごとの API キーは不要です。
• コストを考慮 — STT は継続的に課金されるため、マイクに追随します。音声入力が ライブの間は有効になり、マイクがゲートされた STT_IDLE_TIMEOUT 秒(デフォルト 120)後に 破棄されます。ワーカーは休止状態で起動する(STT オフ、TTS なし)ため、ダッシュボード上の アイドル状態のカードはワーカー接続以外のコストがかからず、STT を一度も有効にせずに テキストチャットが機能します。
• ターンモード — 手動プッシュトゥトーク(start_turn / end_turn / cancel_turn)または 自動ターン検出。set_turn_mode で実行時に切り替え可能です。
• ヘルパーツール — いくつかの関数ツール(get_areas、get_device_domains、get_devices、 get_environment_info)が GetLiveContext を前処理して、エリア/ドメインでフィルタリング されたコンパクトなビューにし、LLM が家全体の状態で溢れないようにします。

構成

.
├── 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)。
• ダッシュボード UI 用にインストールされた HA 統合。

ワーカーを実行する

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 を使用します(ワーカーをビルドして実行します):

docker compose up --build

環境変数(リポジトリルートの .env)

エージェントは load_dotenv() を呼び出し、リポジトリルートの .env まで遡って読み込みます。

変数	目的
HA_URL	Home Assistant のベース URL。/api/mcp が自動的に付加されます。
HA_TOKEN	Home Assistant の長期アクセストークン(ベアラートークンとして送信されます)。
HA_HIDDEN_TOOLS	LLM から隠す HA MCP ツールをカンマ区切りで指定します。たとえば、家に存在しないデバイス用のインテントなどです。デフォルトは GetDateTime,HassBroadcast,HassCancelAllTimers です。
PARALLEL_API_KEY / MEM0_API_KEY / HERDR_MCP_URL	agent/mcp.yaml 内のオプションの MCP サーバーのキーと URL。MCP サーバーを参照してください。
CALLBACK_BASE_URL	MCP サーバーがこのエージェントに到達する際の、このエージェントの HTTP アプリ。例: http://<agent-host>:8952。長時間タスクを報告してくるサーバー向けです。
AGENT_PROMPT / AGENT_MCP_CONFIG	docker-compose がマウントするための、agent/prompt.yaml と agent/mcp.yaml の独自コピーです。agent/*.local.yaml は git で無視されます。
AGENT_NAME	明示的ディスパッチのワーカー名(デフォルト 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} として取得されるため、このファイルにシークレットは含まれません。キーが未設定のサーバーはスキップされるため、エージェントは Home Assistant のツールだけで動作します。同梱のファイルには 3 つのサーバーが列挙されています：

• Web 検索 (Parallel Search): web_search と web_fetch。匿名の無料枠はキーなしで利用できます。
• メモリ (Mem0): 会話をまたいで記憶される設定を、人ごとに分けて保持します。MEM0_API_KEY が必要です。
• コーディングエージェント (herdr-mcp-server): herdr が動作しているコンピューター上で Claude Code セッションを開始、確認、プロンプト送信します。そのため「用电脑…」や「on my computer…」といったリクエストとその続きは、そこの 1 つのセッションに送られます。HERDR_MCP_URL が必要です。そこではコードを実行できるため、これは restricted です：Settings のエントリで servers の下に herdr が記載されている人だけが利用できます。

callback: true とマークされたサーバーは、このエージェントの webhook を X-Callback-Url と X-Callback-Token ヘッダーで受け取ります。タスクがツール呼び出しより長く続く場合、サーバーは {"source", "text"} を /chat/events に POST し、エージェントはそのターンはツールをオフにした状態で、テキスト会話の中でその人に伝えます。これには CALLBACK_BASE_URL と TEXT_API_TOKEN が必要です。mcp.yaml の先頭にあるコメントに、すべてのフィールドが説明されています。サーバーを追加するには、そこにエントリを追加するか、AGENT_MCP_CONFIG が指すコピーに独自のリストを保持してください。

ターンモードとセッション制御

カードは、ワーカーが登録する RPC を介して実行時にセッションを設定します：

• set_turn_mode (manual | auto) — manual はプッシュトゥトークです：マイクは start_turn までゲートされたままで、その後 end_turn が確定し（エージェントが応答）、cancel_turn が破棄します。 auto はマイクを常時有効に保ち、モデルにターンの終わりを検出させます。
• start_turn / end_turn / cancel_turn — 手動ターンのライフサイクル。start_turn は マイクを開き（STT を復帰させ）、end_turn/cancel_turn はマイクをゲートします（STT は アイドルタイムアウト後に破棄されます）。STT は単にマイクに追従します。
• set_audio_output (on | off) — エージェントの音声（TTS）応答を切り替えます。off は テキストのみを意味します。デフォルトでは off なので、テキストチャットは STT/TTS のコストなしで常に機能します。

ワーカーは、ライブの STT と音声出力の状態を ha.speech_state データチャネルでブロードキャストし、 カードがそれを反映できるようにします（例：STT が破棄されたときの「スリーピング」インジケーター）。また、 ツール実行のライフサイクルを ha.tool_call でブロードキャストします。

HTTP 経由のテキストチャット

ポート 8952 の POST /chat は 1 行のテキストを受け取り、プレーンテキストで応答します。再開されるまで再起動をまたいで持続する 1 つの会話で動作し、iPhone のショートカット向けに作られています。これは draft の livekit-agents API 上で動作します。使い方、仕組み、アップグレード方法については docs/text-endpoint.md を参照してください。

フロントエンド / ダッシュボード UI

コンパニオンの Home Assistant インテグレーションを使用してください： ha-livekit-agent-frontend — ネイティブのデバイスタイル（タップで制御）、音声、テキスト チャット、トランスクリプト、ツール呼び出しステータスを備えた HACS カスタムインテグレーション + Lovelace カードです。ログイン中の HA ユーザー用に LiveKit トークンを発行し、 AGENT_NAME によってこのワーカーをディスパッチします。