跳转至

Agent 生产级 Harness 工程实践

Ch04.829 Agent 生产级 Harness 工程实践

📊 Level ⭐⭐⭐ | 8.3KB | entities/agent-harness-production.md

Agent 生产级 Harness 工程实践

摘要

生产级 Agent Harness 是弥合"Demo 能跑"与"生产能用"之间鸿沟的工程层：把模型外部的执行环境、工具、上下文、生命周期、可观测、验证与治理组织成一个状态清楚、证据可查、失败可恢复的运行时闭环。它必须直面长时运行、状态恢复、并发隔离、失败回滚等真实边界条件。Harness Engineering 之于 AI Agent，正如 DevOps 之于软件部署——模型是 CPU，Harness 是操作系统。

核心要点

  • 边界条件决定架构：Demo 级假设理想环境（网络通畅、单用户、短任务）；生产级必须处理网络分区、状态漂移、多租户争抢与部分失败，驱动状态持久化、心跳检测、优雅降级、断路器模式的系统性引入。
  • 可观测性是部署前提：日志、指标、链路追踪三支柱构成监控基础，没有可观测性生产部署等同于盲飞；Trace 还应回写为记忆更新与验证反馈的输入。
  • 安全边界必须由系统强制：文件系统范围、网络访问、API 频率、信息脱敏不能依赖 Agent"自觉"，需按风险分级（只读自动 → 危险审批 → 高危拦截）在 Harness 层强制实施，并配套审计日志。
  • 长任务靠状态恢复而非长上下文：checkpoint 持久化、断点续跑与 Progress File 是 10 分钟以上任务的必需品；候选/已验证/已执行/已提交的状态分层才是可靠性关键。
  • 成本是持续运营约束：模型路由、上下文压缩、预算硬顶、子 Agent 隔离构成多层成本控制；成本-质量-速度三难困境要求显式权衡。
  • 失败要可诊断、可回滚：完成幻觉、上下文腐烂、级联错误等失败模式各有缓解策略；Harness 变更必须跑系统级回归，Golden Trace 与 canary 是自进化 Harness 的安全护栏。
  • 人机协同是持久状态：审批、拒绝、例外处理应成为可查询的系统状态而非一次性干预——Agent 卡住时会等人、能汇报进展，是生产级成熟度的标志。

深度分析

Demo 到生产的鸿沟：边界条件的系统性处理

生产级与 Demo 级的根本区别在于对边界条件的处理：Demo 在理想环境运行，生产必须面对网络分区、部分失败、多租户争抢与跨会话状态丢失。这些约束不是偶发事故而是常态，Harness 的每个决策——状态持久化、心跳检测、优雅降级、断路器——本质上都是把"意外"提前建模为"预期路径"。如果 Harness 只保证顺畅路径的可用性，它就不是生产级，只是放大了规模的 Demo。

鸿沟可量化：真实系统中单次 Agent 运行可持续数小时甚至数天，任何一次中断都可能浪费数小时算力与 Token——这迫使 Harness 把"可恢复性"从可选项变为一等公民。

可观测性与 Trace 回写：仪表盘与反馈环

生产环境中 Agent 行为不再是"黑盒一次调用"，而是跨越数分钟到数小时、涉及多次工具调用的执行轨迹。可观测性三支柱——日志、指标（Token 消耗、步骤耗时、错误率）、链路追踪——构成监控基础；更进一步是 deep telemetry：记录提示词、检索内容、工具参数、延迟、被拒绝方案与人工干预点，这是定位"失败发生在 Harness 哪一层"（上下文不足？工具定义错误？验证器漏检？）的唯一依据。

可观测性还应形成回写闭环：生产 traces 自动生成回归用例，失败模式沉淀为评估基准。这与 Agent Harness 架构 中 Observability 独立成层的趋势一致；度量也应从"最终成功率"转向过程指标（工具调用效率、验证覆盖率、平均步数）。

安全沙箱与并发隔离：能力-控制权衡的两端

生产 Harness 必须为 Agent 操作划定强制边界：文件系统访问范围、网络访问控制、API 调用频率限制、敏感信息脱敏。安全不能依赖模型"自觉"，必须按风险分级在 Harness 层强制执行，形成从工作目录隔离到容器级的多层次防御；审计日志与证据包是问责与调试的基础。

并发隔离同样属于"能力-控制"天平：多租户下会话隔离（独立生命周期 + LRU 淘汰）防止上下文污染；长任务拆解后由子 Agent 独立上下文与权限运行；并行分支（git worktree）提升吞吐，但共享状态的事务语义仍是开放难题。共性原则是：每一项能力扩张都必须伴随对应的控制收紧。

状态恢复与失败闭环：长任务的可靠性支柱

生产 Agent 的可靠性不取决于模型有多强，而取决于状态边界是否清楚、失败闭环是否完整。状态要分层：候选、已验证、已执行、已提交的动作必须显式区分，同一运行事实不应从多个来源拼接。State Schema First 是落地原则——先回答"哪些事实必须恢复、哪些必须跨端一致、哪些只是派生视图"，再设计 prompt 与工具。重启后能从 checkpoint 恢复、用户 stop 后后端不再执行——这些可检查标准定义了状态边界的验收线。

失败闭环的另一半是恢复与回滚：长任务定期 checkpoint，失败时从最近点续跑而非从头重跑；跨会话靠 Progress File 避免重复劳动。Harness 自身的变更必须可回归，自进化 Harness（AHE 方向）只在可评估、可回滚、有 canary 时才放开。这与 Harness 之后：状态边界与失败闭环 的判断一致：很多失败不是模型不会想，而是系统没有区分已验证动作与已提交状态。

实践启示

  1. 从可观测性开始建设：部署首日就打通日志、指标、链路追踪三条管线并让 Trace 回写为回归素材；事后补的成本远高于一开始就设计进去。
  2. 用状态分层与 checkpoint 支撑长任务：为 10 分钟以上任务设计状态 schema，定期 checkpoint 从最近点恢复，跨会话用 Progress File 防止重复劳动。
  3. 安全护栏渐进式收紧：从环境变量白名单与命令风险分级起步，逐步扩展到网络策略与文件系统隔离；破坏性操作从第一天就要求审批，审计日志全程开启。
  4. 成本预算前置化并设硬顶：设定单任务 Token 预算上限，超出时触发降级（切轻量模型、压缩上下文）而非直接失败；先做模型路由与上下文压缩可省大部分成本。
  5. 把失败模式表当作 post-mortem 工具：用八类失败模式（完成幻觉、上下文腐烂、过早停止、级联错误、工具误用、跨会话失忆、范围蔓延等）对照生产事故诊断，沉淀"表现 → 诊断 → 缓解"三段式记录。
  6. Harness 变更走系统级测试流程：任何工具 schema、验证规则或记忆策略的调整都跑回归基准；Golden Trace 目录作为持续基线，自进化 Harness 只在可评估、可回滚、有 canary 时放开。

相关实体