Home Generative Agent（HGA）
把生成式 AI 智能体装进 Home Assistant：用自然语言控制设备、编写自动化、看懂摄像头并主动预警异常。
- Star 数
- ★ 374
- 最近更新
- 1 天前
- License
- MIT
- 主语言
- Python
- FA 评分
- 51/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台OpenAI API · Claude API
- 开始前需要
- 典型场景
- 已经用 Home Assistant 管理全屋设备，希望不写 YAML 就能用中文/英文口语描述并生成自动化的人。
- 主要局限
- 安装门槛高：需 HA 2026.8.0+、HACS、PostgreSQL + pgvector 数据库及至少一个模型提供商；推荐路径还要求 Home Assistant OS 或 Supervised，Container/Core 无法使用配套应用。
- 源码审查
- 51/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Home Generative Agent 是一个 Home Assistant 自定义集成，通过 HACS 或手动方式安装，把基于 LangGraph 构建的 AI 智能体接入 HA 的 Assist 对话界面。它不只是把用户的话转发给 LLM，而是通过工具调用控制已暴露给 Assist 的实体、查询历史数据库、分析摄像头画面并直接写入并注册真实的 HA 自动化 YAML。长期语义记忆存放在 PostgreSQL + pgvector 中，使跨会话的偏好得以保留；内置的 Sentinel 异常引擎用确定性规则做安全判断，LLM 只提供建议而不直接执行动作。模型后端可以是 OpenAI、Gemini、Anthropic 等云端服务，也可以是 Ollama 或任意 OpenAI 兼容的本地服务器，从而让数据完全留在家庭网络中。集成还自带基于 OpenAI Whisper 或本地 Speaches 的 STT/TTS 提供程序，可组成完整的语音管道。
用户在 HA Assist 中提问或下指令，LangGraph 智能体读取已暴露给 Assist 的实体状态与历史（recorder 数据库），调用工具执行开关灯、查询能耗、分析摄像头画面（可结合外部 face-service 做人脸识别并生成 recognized_people 等传感器）等操作。当用户描述想要的自动化时，智能体生成 YAML，逐条校验其中的 entity_id 与服务调用是否真实存在，再把自动化注册到 HA，使其出现在自动化编辑器中；若启用 Critical Action PIN，涉及开门或开锁的自动化会先等待 PIN 确认。Sentinel 引擎以确定性规则监控未上锁的门锁、敞开的门窗、未知人员、功率/电池/环境传感器异常，并提供 Home Assistant 与网络安全审计（新管理员账号、长效令牌、暴露的插件端口、UPnP、新入网设备等），发现后向手机推送通知；LLM 可参与分诊与规则发现，但不会直接执行动作。集成还提供流式回复、按需执行的“我的家安全吗”审计、MCP 服务器或 LLM API 集成的外部工具，以及内置 STT/TTS 提供程序。
- 已经用 Home Assistant 管理全屋设备，希望不写 YAML 就能用中文/英文口语描述并生成自动化的人。
- 家里装了多路摄像头，想让智能体在检测到运动时自动分析画面、识别熟人并推送差异化通知的用户。
- 对安全敏感、希望定时收到门锁未锁、门窗敞开、未知人员、路由器新设备上线等告警的家庭。
- 重视隐私、要求所有推理在本地 Ollama 或本地 OpenAI 兼容服务器上完成的技术型用户。
- 想用语音与家庭对话、并且需要本地 STT/TTS 组成完整 Assist 语音管道的用户。
- 希望智能体记住“我晚上 7:30 到家”等长期偏好并据此写自动化的进阶用户。
如何安装或部署这个 Agent？
需要 Home Assistant 2026.8.0 或更高版本、HACS、带 pgvector 的 PostgreSQL，以及至少一个模型提供商。推荐路径要求 Home Assistant OS 或 Supervised，因为第一步要安装配套的应用商店插件。
第一步，添加 PostgreSQL + pgvector 应用仓库并安装该应用：
仓库地址：https://github.com/goruck/addon-postgres-pgvector
设置 → 应用 → 应用商店 → ⋮ → 仓库 → 填入上面的地址 → 搜索并安装 postgres_pgvector第二步，通过 HACS 添加本集成：
HACS → 集成 → 自定义仓库 → https://github.com/goruck/home-generative-agent → 类别选择 Integration → 安装第三步，重启 Home Assistant，然后在“设置 → 设备与服务 → 添加集成”中搜索 Home Generative Agent 并完成引导页。
第四步，在集成页面点击“+ Model Provider”，先选择 Edge（Ollama、OpenAI Compatible）或 Cloud（OpenAI、Gemini、Anthropic），再填写对应提供商的连接信息。至少需要一个提供商才能继续 Setup。
第五步，点击“+ Setup”选择模式：Basic 会启用全部功能并使用推荐默认值，同时自动创建数据库子条目；Advanced 则逐项配置并包含数据库配置步骤。
如何使用这个 Agent？
把 HGA 设为语音助手：设置 → 语音助手 → 选择 Home Generative Agent 作为对话代理，之后即可在 Assist 面板中直接对话。注意智能体只能看到暴露给 Assist 的实体，新设备需要到“设置 → 语音助手 → 暴露”中手动开放，并给它起好名称与区域，否则智能体找不到它。
常用操作示例：
“把客厅的灯打开”
“前廊的灯今天什么时候亮的？”
“冰箱今天用了多少电？”
“每 30 分钟提醒我一次，猫砂盆废料抽屉超过 90% 就通知我”
“大门有快递吗？”
“我的家安全吗？”自动化创建示例（由智能体生成并校验后注册）：
alias: Check Litter Box Waste Drawer
triggers:
- minutes: /30
trigger: time_pattern
conditions:
- condition: numeric_state
entity_id: sensor.litter_robot_4_waste_drawer
above: 90
actions:
- data:
message: The Litter Box waste drawer is more than 90% full!
action: notify.notify可选的语音输入输出：在集成页面分别点击“+ STT Provider”和“+ TTS Provider”，填入 OpenAI API 密钥，或指向任意可达的本地 Speaches 服务器（OpenAI 兼容的 /v1/audio/transcriptions 与 /v1/audio/speech 端点），然后在 Assist 管道中选择它们。
这个 Agent 有哪些优点和局限？
- 真正的智能体架构：基于 LangGraph 的工具调用、上下文管理与流式回复，而非简单的提示词转发，能实际写 YAML、校验 entity_id 并把自动化注册进 HA。
- 模型可替换：OpenAI、Gemini、Anthropic、Ollama 及任意 OpenAI 兼容服务器均可，配合本地语音服务可做到数据不出户。
- 安全设计谨慎：Sentinel 用确定性规则做安全判断，LLM 只建议不执行；Critical Action PIN 可拦截开锁/开门类自动化的安装。
- 长期记忆使用 pgvector 做语义检索，跨会话保留用户偏好，并能据此生成贴合习惯的自动化。
- 摄像头分析覆盖面广，支持 Axis、Ring via ring-mqtt、Reolink、UniFi Protect 等，并提供人脸识别与主动通知。
- 自带 STT/TTS 提供程序（可选接入 Speaches），使整条语音管道可在本地网络内闭环。
- 安装门槛高：需 HA 2026.8.0+、HACS、PostgreSQL + pgvector 数据库及至少一个模型提供商；推荐路径还要求 Home Assistant OS 或 Supervised，Container/Core 无法使用配套应用。
- 实体可见性需要人工维护：只有暴露给 Assist 的实体可被对话与历史查询访问，漏暴露会让智能体误报“没有这个设备”。
- 云端模型意味着数据外发与按量计费，虽然可切换本地模型，但本地推理需要自己维护 Ollama/vLLM 等服务和相应硬件。
- 人脸识别依赖额外的外部 face-service，Sentinel 的未知人员规则在该服务未配置时不会触发。
- 功能面极广（Sentinel 审计、发现规则、多种摄像头集成、STT/TTS），配置项多，排障成本高于轻量对话集成。
- 安全审计中的部分能力（如路由器/eero 相关检查）依赖相应集成是否安装，未安装时检查会缺失。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Home Generative Agent（HGA） 当前 | 51 · 缺口较多 | — | ★ 374 | 1 天前 | Python | OpenAI API · Claude API |
| Local OpenAI LLM（Home Assistant 自定义集成） | 66 · 存在缺口 | 自托管服务免费 + 模型费 | ★ 306 | 1 天前 | Python | OpenAI API |
| Tracekit 智能体审计与策略守护 | 82 · 表现良好 | 命令行工具免费 | ★ 431 | 1 天前 | Python | Claude Code |
| 小金丝雀注入探测器 | 78 · 表现良好 | 命令行工具免费 | ★ 41 | 15 天前 | Python | Claude Code · OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示存在 Critical Action PIN 对开门/车库等关键动作的确认门控，Sentinel 采用确定性规则且 LLM 不直接执行动作，网络审计对 MAC/IP/主机名做脱敏，这些是加分项。但扣分点明确：集成以 Home Assistant 管理员级权限运行并读取全部实体与注册表，最小权限仅靠 HA 自身边界，未见细粒度权限声明；依赖安全无锁文件或审计证据；外部副作用（写自动化、通知、服务调用）缺少统一回滚机制；来源归属仅 README 自述，发布者身份未经验证。
文档对失败路径描述较充分（数据库连接重试、pgvector 缺失、表属主错误、能力缺失降级为显式 gap），失败信息具体可操作。但依赖可用性证据薄弱：要求 HA 2026.8+、外部 PostgreSQL+pgvector、可选 face-service 与本地模型服务器，均无版本锁定或依赖审计文件；自洽性仅靠文档叙述，无测试或运行证据支撑。
受众与场景覆盖良好（云/本地模型、STT/TTS、摄像头、Sentinel），能力边界写得很清楚（不主动扫描、不做深度包检测、ZHA permit-join 不可观测、zwave_inclusion_active 仅轮询）。扣分在于触发精度：轮询间隔会漏掉短时 inclusion 窗口，新设备仅在注册后可见；环境适配要求 HA OS/Supervised 才能用内置 app，HA Container/Core 用户受限。
信息架构清晰，安装步骤与故障排查详尽，示例与社区仪表盘丰富，已知限制显式列出，MIT 许可证明确。扣分：版本与变更记录仅在文档中零散提及（v3.39.0 等），未见独立 CHANGELOG 文件；命名稳定性无法从片段确认；维护责任由未验证的单一发布者承担，无治理或支持承诺。
输出可用性高：自动化 YAML 在写入前校验实体 ID 与服务调用，通知分级明确，审计报告按严重度给出修复建议。边际价值明显优于纯 prompt 透传集成。但成本收益扣分：需要 PostgreSQL+pgvector、可选 GPU 边缘服务器与外部人脸服务，运维与硬件成本对普通家庭用户偏高，且云模型路径涉及持续 API 费用。
文档对事实与推断有一定区分（明确标注哪些检查无法运行及原因、哪些路径仅 fixture 测试），这是加分项。但主张可追溯性弱：README 的性能与行为主张多无对应代码或测试引用；交叉佐证仅限同一仓库内文档互引，无独立第三方验证；发布者未验证进一步限制了外部佐证。
- 该集成以 Home Assistant 管理员权限运行并读取全部实体、设备注册表与认证信息，部署前应评估其权限范围是否可接受。
- 依赖外部 PostgreSQL+pgvector、可选 face-service 与本地模型服务器，且无依赖锁定或安全审计证据，升级前应自行核查依赖版本。
- 发布者身份未经验证，维护责任与更新路径不明确，长期使用需自行承担跟进风险。
- Sentinel 轮询机制可能漏掉短时事件（如 Z-Wave inclusion 窗口），不应将其视为完整的安全监控。
- 云模型路径会将对话与摄像头分析数据发送至第三方 LLM 提供商，需确认脱敏边界与隐私政策。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v3.45.0-beta.5 预发布
发布说明摘录
Pre-release of v3.45.0, for field validation of #866: Sentinel's calls stalling voice on a shared local model. HACS offers it only to users who opted into betas. It contains everything on main as of 3fd752a. #866 step 1: Sentinel no longer stalls a voice turn on a shared local model (#875) On an edge model shared with chat, Sentinel now avoids starting calls rather than cancelling them, since a cancel is what can wedge an Ollama runner: …在 GitHub 查看 ↗ -
发布说明摘录
Fixed - The Critical Action PIN is now asked for a service call however the tool names the service ([#837](https://github.com/goruck/home-generative-agent/issues/837)). The gate read a service-calling tool's domain and service arguments only. A tool that named the service another way ran with no PIN: {"action": "lock.unlock", "entity_id": "lock.front_door"}, {"action": "scene.apply", "entities": {"lock.front_door": "unlocked"}}, a dotted service ("service": "lock.unlock"), a domain with the service under action, or a tool named after the service (lock.unlock, or `sce …在 GitHub 查看 ↗ -
发布说明摘录
Fixed - Turning on an offline group that holds the garage relay now asks for the Critical Action PIN, and switch device actions are held only when they act on the relay ([#804](https://github.com/goruck/home-generative-agent/issues/804)). A switch group helper that was unavailable or not yet loaded showed no members, so turning it on was not held even when it held the relay a garage door is built on (from #794), another wrapper of that relay, or a template switch that switches it; nor was a group listing the relay by its registry id. These groups are now read from their settings and h …在 GitHub 查看 ↗