家庭能源 Agent 的构建实践

家庭能源电站能够为用户创造长期收益，但其运行受发电、储能、用电需求与电价等因素共同影响，每个家庭的条件也各不相同。Agent 通过按需分析、行为解释与优化建议，持续缩小用户与系统之间的认知距离，帮助用户逐步理解自己的能源电站、改善用能决策，并将这种理解转化为长期收益。

产品上线后，客户工单与内部维护成本下降，用户粘性提高，用能决策的改善也带来了能源收益的提升；持续的使用与反馈进一步推动了产品迭代。

这篇文章梳理了家庭能源 Agent 构建过程中的关键设计与取舍，分享我们在实践中形成的经验与思考。

1. 架构设计

什么是家庭能源 Agent？

家庭能源领域关注家庭中的电能生产、储存、使用与电网交互。家庭光储系统由光伏、电池、家庭用电设备和电网连接构成：光伏为家庭供电，富余电能可以存入电池或送往电网；发电不足时，家庭可以由电池或电网补充供电。能源流向随发电、用电需求和运行策略变化，共同影响家庭的能源利用与用电成本。

家庭能源 Agent 是面向家庭用户的能源助手，将专业知识与用户家庭的实际运行数据结合，帮助用户理解和使用自己的能源系统。它可以解释当前状态与能量流向，查询和比较历史能源表现，分析用电成本与收益，说明常见运行行为的原因，并结合家庭情况提供用能建议。用户可以围绕“电从哪里来、流向哪里”“这一周的用电表现如何”“为什么电池没有放电”等问题展开对话，逐步获得相关数据、原因解释和建议。

为什么选择单 Agent？

家庭能源对话往往跨越多个相互关联的目标：用户在了解某段时间的用电表现后，可能继续追问变化原因，再讨论可以采取的措施。后续问题需要沿用前文的时间范围、家庭状态和已有证据，新的查询结果又可能改变分析方向。能力可以分别封装，对话中的目标、约束和任务进度则需要持续共享。

基于这一特点，我们选择单 Agent 架构，以标准 Agent Loop 在同一上下文中持续组织对话。Agent 围绕用户目标选择行动、观察执行反馈，再决定下一步，直到完成任务、需要澄清或达到停止条件。Skills 按需提供专项任务流程，Tools 提供证据与业务能力，共同支撑这一循环。

这一架构没有采用 Intent Router 对用户请求进行分类并分发到固定 Workflow。请求直接进入 Agent 循环，由同一个 Agent 根据目标、上下文和执行反馈决定后续路径。

Intent Router 配合固定 Workflow，适合意图边界清晰、任务相对独立、执行步骤稳定的场景。请求分类后进入明确流程，便于约束执行顺序、检查必经环节和验证结果。

在这类对话中，固定路由需要跨流程传递上下文，并预先定义目标组合与追问分支。随着需求扩展，原本用于分拣请求的 Intent Router 会逐渐变成复杂编排器。

我们也没有采用 Multi-Agent。子 Agent 的核心作用是隔离上下文：将专项任务的探索过程留在独立上下文中，只向主 Agent 返回必要结果。当前的查询、分析与建议高度依赖共享上下文，尚无明确的隔离需求，因此采用单 Agent 配合 Skills，避免额外的上下文交接与模型交互成本。

Agent 与业务系统的职责边界

Agent 负责理解用户目标、选择业务能力，并根据执行结果组织分析与回答。确定性的任务流程与复杂计算由业务系统承担。相关规则在业务系统中统一实现、验证和维护，避免由模型在对话中重新推演和执行。

在家庭能源场景中，IoT 云平台可以复用已有业务逻辑，也可以针对 Agent 的需求构建新的任务流程。例如，运行诊断所需的数据获取、条件判断与计算可以在平台侧完成，再封装为便于 Agent 理解和调用的工具。Agent 选择诊断类型和时间范围，平台执行诊断流程并返回结果，Agent 据此组织解释。

2. Agent Harness

Agent Harness 是模型循环的运行环境，负责上下文组装、受控执行、状态保存和运行观测。模型发出的决策需要经过这些机制，才能形成有执行边界、可恢复且可检查的行为。

约束落实在运行时

Prompt 与 Skills 指导 Agent 如何完成任务，运行时控制它能够执行哪些操作、访问哪些数据。涉及权限和数据范围的约束，需要通过工具注册、请求校验和访问控制落实，不能仅依赖模型遵守提示词。

在家庭能源场景中，当前 Agent 提供只读分析与建议，运行时只开放相应的工具和文件读取权限。用户与家庭能源系统的身份信息由可信运行时绑定到业务请求，无需模型自行填写，从而将数据访问范围与模型生成的参数分开管理。

这些机制约束了执行范围，但不能保证分析正确。即使请求通过校验，Agent 仍可能选错时间范围或误解工具结果，这类问题需要通过评估发现和改进。

状态与恢复

对话历史、执行状态和会话产物需要持久化保存，支持后续交互与服务重启后的恢复。

我们通过检查点保存消息历史与执行状态，并在会话存储中单独保存卸载后的大型工具结果、用于图表展示的数据快照及图表组件。继续对话时，系统加载已有状态；重新打开聊天时，前端读取保存的消息与图表组件，恢复此前的展示。

Agent 为什么这样回答？

Observability 负责记录 Agent 的完整执行 Trace，覆盖模型输入与输出、工具调用及执行结果，使每轮决策与执行过程可追踪。

这些记录用于定位错误发生的环节，也支持分析调用轮次、延迟与用量，为调试、评估和后续迭代提供依据。

3. 上下文工程

Agent 需要上下文来完成任务。上下文工程的核心，是在执行的每一步，为模型提供恰当的信息。常见策略包括 Write、Select、Compress 和 Isolate，分别用于保存、选择、压缩和隔离信息。

我们的设计围绕三个问题展开：选择什么信息、如何组装输入，以及如何管理增长。

选择什么信息

指令放在 System Prompt 还是 Skills，主要取决于使用频率。System Prompt 每轮可见，但持续占用上下文；Skills 按需加载，减少常驻内容，却增加读取所需的模型轮次。高频使用的指令适合常驻，低频指令适合放入 Skills。

我们从精简的 System Prompt 开始，再结合请求分布与评估中的实际调用行为调整：反复需要读取的指令考虑移入系统提示词，仅在特定任务中使用的流程保留在 Skills。参考知识按需读取，工具结果随查询进入上下文，补充任务所需的知识与证据。

如何组装输入

长会话中，每轮请求都会重复携带不断增长的历史上下文。Prompt Cache 复用相同前缀的 KV Cache，减少重复的输入计算，降低首 Token 延迟；缓存输入 Token 的优惠计费也能显著降低成本。因此，我们在组装输入时尽量保持前缀稳定，让已有上下文在后续轮次中持续复用。

时间是家庭能源分析的重要依据，查询范围与数据解释都需要结合家庭本地时间。我们在系统上下文中注入本地日期与时区，同一天内保持稳定，避免频繁破坏 Prompt Cache；需要精确时刻或滚动时间范围时，通过时钟工具按需获取。这样兼顾了缓存复用与业务所需的时间精度。

如何管理增长

随着对话推进，我们通过压缩历史控制上下文规模，同时保留原始信息，为 Agent 提供回顾完整过程的能力。

较早的消息整理为摘要，保留目标、约束、任务进度与关键证据，近期消息保持原文。压缩前的历史完整转录到会话文件中，Agent 可以通过虚拟文件系统按需回查；过大的工具结果同样保存完整内容，在上下文中保留引用。

摘要是对历史信息的高保真、有损压缩。我们保留完整转录与回查路径，让 Agent 在需要时读取原文、补足细节，在缩减上下文的同时保留回顾完整过程的能力。

4. 工具设计

Agent 友好的工具契约，需要支持调用前的能力判断和调用后的证据解释。工具用途、模型输入、结果范围以及失败语义共同决定模型能否完成任务。设计应从用户目标和所需结论出发，再确定能力边界及数据结构。

围绕业务任务划分能力

每个工具应完成一项独立的业务任务，并明确适用范围。我们按状态、趋势、统计与诊断等任务划分能力，Agent 根据用户目标选择和组合工具，平台承担内部的数据获取、计算与判断。输入只保留模型需要决定的业务参数。

大范围概览，小范围针对性

工具通过响应模式与按需选项控制详细程度。大范围查询使用概览定位关注点，小范围查询获取针对性细节；问题已明确时，可以直接读取明细。

我们为历史趋势与事件提供 SUMMARY、DETAIL 模式，统计结果按需展开。概览减少输入成本，明细补充判断依据，选择取决于当前问题与已有证据。

让结果可解释、有边界

输出应明确单位、方向、时间范围与数据状态，减少模型对业务语义的猜测。例如，趋势代表点用于描述变化，累计电量由周期统计提供，两类证据不能混用。

我们通过代表点数量、分页与时间桶上限约束输出规模，并保留必要的汇总与覆盖信息。超限时明确反馈，避免静默截断，让 Agent 能判断是否缩小范围、调整粒度或继续读取。

工具如何处理失败？

工具应提供明确的错误语义与必要的修正信息，让 Agent 判断调用是否可以修复。对于可修复的参数错误，例如查询范围超限，Agent 可以根据反馈调整参数后重新调用；不可修复的错误应明确标识，避免无效重试。

无需重新决策的恢复由运行时处理。我们对指定的瞬时服务故障执行有限重试，耗尽后再将失败反馈给 Agent，减少不必要的模型交互，同时控制重复调用与等待成本。

UI 组件作为工具

家庭能源分析涉及随时间变化的运行数据，以及不同来源、去向和周期之间的比较。图表能直观呈现变化趋势与组成关系，帮助用户理解数据；文字则解释结论与原因，两者共同构成回答。

对话中的展示需求随用户目标变化。我们将 UI 组件作为工具，由 Agent 按需选择展示内容与阅读顺序，服务端负责数据校验与组件组装，前端负责渲染与交互。

呈现工具通过 result_ref 读取已保存的查询结果，使分析与图表共享同一份数据，避免模型重新转写数值。相应代价是结果引用与快照的管理；生成后的组件也会保存，支持重新打开对话时恢复此前的展示。

5. 评估与迭代

评估（Eval）通过明确的任务与判定标准，衡量 Agent 的实际表现。它将产品对“成功”的要求转化为可检查的依据，帮助团队发现能力缺口、验证改进并识别退化。Agent 的执行路径和结果具有不确定性，持续评估让模型、工具与上下文的调整有据可循。可靠的评估，是 Agent 持续迭代与质量保障的重要支撑。

建立评估起点

初始评估从一组具有代表性的核心任务开始，为每个案例明确用户目标、必要上下文、事实依据与完成条件，同时覆盖数据缺失、能力限制等边界情况。不要求 Agent 遵循唯一调用路径，但需要明确哪些结论必须有证据支持。

经审核的案例、事实预期与人工判定共同构成基准真相集，为评分提供可信参照。它不必是一组固定措辞的标准答案，而应说明正确回答需要满足什么、哪些判断不能成立。

在可控环境中执行案例，保存完整 Trace 与最终回答。数值和边界等可精确检查的项目使用代码校验，语义完成度由明确的评分准则与 LLM Judge 判断，再通过人工审核校准自动评分。先建立小规模、可复核的基线，再逐步扩充覆盖。

让评估形成闭环

评估发现失败后，先沿 Trace 定位原因：是 Agent 选错能力或误读结果，工具与数据存在问题，还是案例预期或评分标准不准确。归因决定修改位置，避免通过调整 Prompt 掩盖其他环节的问题。

修复后，先复测原问题，再运行相关案例检查退化。有代表性的失败经审核后加入回归集，让一次问题发现转化为持续的验证能力。修改评分标准时，可以对已有执行记录重新判分，但应区分评分变化与 Agent 行为变化。

版本比较还需要保持模型、数据与评估标准等条件可比，并结合任务质量观察延迟、调用量和 Token 成本。随着真实使用数据积累，持续补充自然问法、多轮追问与新的失败模式，使评估逐步贴近实际需求。

我们的评估实践

案例从用户任务出发，覆盖机制理解、状态与设置、历史回顾、表现分析、行为解释和决策支持，再映射到知识回答、事实查询、多证据综合、固定诊断及结果依赖等能力路径。不要求 Agent 遵循唯一的工具调用顺序，重点检查证据是否充分、任务是否完成。

案例按目标与证据的依赖关系组织复杂度，从直接回答逐步扩展到多目标组合与依赖推进。先验证证据充分、工具正常的核心路径，再扩展数据缺失、工具失败与交互边界等情形。

评分围绕目标完成、证据支撑、安全边界和表达清晰展开，同时记录延迟、调用量与 Token 用量。专项案例分别检查 Skill 是否加载、方法是否落实与业务目标是否完成，避免以局部行为替代整体判断。结果按具体标准统计通过、失败与不可判定状态，结合人工复核与回归记录，定位能力缺口并验证后续改进。

6. 未来展望

家庭能源 Agent 的演进

家庭能源 Agent 可以从用户发起的对话，走向围绕长期目标的持续服务。长期记忆帮助它跨会话保留家庭偏好与用能约束，定时任务支持周期回顾和主动提醒，使服务不再局限于用户每次提问。

能源优化能力是引入写操作的核心前提。Agent 将用户目标与家庭约束交给专业优化系统，由其计算可执行的能源方案，再通过写操作工具落实到设备。执行状态与实际效果形成反馈，使服务从分析建议延伸到可验证的行动。

多模态支持将丰富交互方式，Agent 也可以为产品已落地的用能场景提供新的服务。例如，能量柜支持房东与租客之间的能源交易，Agent 可以帮助双方理解交易规则、查询用能与费用，并处理账单疑问。面向内部技术人员的告警排查 Agent，则通过技术数据与专用工具支持问题定位和排查。

生产级系统的演进

随着 Agent 承担更长期、更复杂的任务，生产级系统需要支持目标的持续推进、执行中断后的恢复，以及实际结果的验证。模型能力、运行机制与评估体系需要共同演进，才能将更强的自主能力转化为可靠的服务。

能否在明确的授权范围内完成长期委托，并在出现偏差时纠正或交还用户，将成为衡量生产级 Agent 系统的重要标准。