核心论点能上生产的 Agent harness指套在 LLM 外面、把工程约束编织进运行时的那层骨架不是 LangChain 文档里那个think → act → observe的单循环而是路由层 多策略执行器 生产守卫的三层结构。把延迟、韧性、安全、可观测性直接编进运行时本身而不是等出事后再打补丁。一、教科书里的 Agent 循环为什么不够所有 Agent 入门文章都会画同一张图LLM 产出想法 → 选工具 → 执行 → 观察结果 → 再思考……直到给出最终答案。ReAct 范式干净、优雅但它偷偷假设了四件事LLM 永远在线、且调用免费可用性与成本两件事工具总是成功返回用户输入是干净的没人需要盯着它。生产环境把这四条全破了LLM 有速率限制和偶发超时且每 token 都要计费远程工具会限流、返回空、部分成功用户输入带 typo、情绪甚至攻击合规还要求高风险动作必须人确认。所以 harness 真正要解决的不是怎么跑循环而是循环之外的工程问题请求进来前怎么净化、循环怎么设上限、出错怎么兜底、谁在盯着。这就是本文要拆的生产级 harness。二、Harness 的三层结构路由层 执行器 守卫第一篇从分层视角讲了系统由哪些层组成本篇换一个切面把运行时单独拎出来看一次请求在 harness 内部实际经过了哪些闸门。先看全貌——Shop-Agent 的 harness 不是单一 loop而是三段生产守卫外包一层输入安全过滤 · 输出安全过滤 · 人在回路 · 全链路可观测按意图分发按意图分发按意图分发按意图分发用户请求路由层 · 入口归一化 / Token 截断 / 情绪 / 意图识别ReAct 执行器自由循环固定步骤执行器Plan-Execute / RAG 兜底 / 固定四步直接分发简单查询纠纷协调器专用 · 分布式锁注图上把 Plan-Execute 与 RAG 兜底合并为一类——它们走的是同一套固定步骤执行器。纠纷协调器带分布式锁、不跑通用循环属于特化路径不计入多策略三选一。第一个反直觉结论harness 路由层 多策略执行器而不是一个万能循环。路由层负责该用哪个执行器每个执行器负责在自己的循环里把事做成。把这两层分开守卫才能被复用而不是在每个执行器里重写一遍。顺带区分两个三导语说的三层是纵向的处理阶段路由层 / 执行器 / 守卫而多策略三选一是横向的执行器分工ReAct / 固定步骤 / 直接分发两者不是同一个三。三、路由层harness 的第一道闸门路由层是 harness 的入口它本身不跑 LLM 循环而是把生产约束前置到循环之外。逐一看它立下的几道闸门同义词归一化规则 本地模型零 LLM 成本轻度清洗失败就回退原文本绝不阻塞流程。Token 预算截断用 tokenizer 精确估算中文 ≈ 1.5 token/字超限就重建不可变frozen的请求对象。这避免了一个超长输入把后续整条链路拖垮。情绪检测级联规则 1ms 本地模型 ~30ms本地模型优先保持延迟可控。舆情风险 → 立即升级检测到紧急情况直接短路整条管线返回已升级高级专员连意图识别都不做。这是 fail-closed出问题时默认拒绝而非放行的教科书示例。意图识别 → 路由分发命中远程调用走参数抽取 门控复杂意图走 ReAct简单意图走直接分发纠纷类走协调器。纠纷协调前的分布式锁锁的 key 由会话号 订单号拼接TTL 5 分钟。防止接口重试或消息队列至少一次投递导致的重复触发——这是 harness 给幂等上的第一道锁。输出内容安全过滤规则引擎零 LLM 成本。全链路 trace A/B 注入整条管线共享一个 handler实验分组在出口注入。论点这些守卫前置到路由层意味着无论请求最终落到哪个执行器净化、截断、情绪、安全、可观测都已经发生。这正是守卫是 harness 一等公民的体现下文「守卫不是补丁」一节收口成表。四、执行器一ReAct 循环递归上限即护栏ReAct 执行器图编排框架驱动是自由循环执行器。它做对了几件生产化的事工具选择前置按意图过滤 embedding 重排把文本转成向量、用相似度匹配只把相关工具喂给 LLM而不是几百个全量 Function Calling把工具描述全塞进 prompt 让模型自己挑呼应《软预过滤工具选择方案》。输入安全过滤规则引擎拦截不进循环。图状态存档checkpointer状态存档器把执行到一半的图状态存下来是人在回路interrupt()的必需品。递归上限 基础步数 × 2 2基础步数设为 5 → 上限 12。这是 harness 给循环装的断路器——把教科书里可能无限转圈的 ReAct变成有限状态机。没有它一个钻牛角尖的 Agent 会一直烧 token。这个值在图默认配置与每次调用的配置里双重设定防止漏配。人在回路当退款申请这类工具被调用置待审批标志把图状态按会话级标识存下返回等待确认。后续人工审批后用同一标识 resume 恢复而不是从头重跑。推理链抽取从图的消息里抽出最终答案 中间步骤think→act→observe 的痕迹作为可审计的推理链。关键论点递归上限是循环的断路器状态存档器是循环的暂停键。这两样东西才是 ReAct 从demo 玩具变成生产组件的分水岭。五、执行器二Plan-and-Execute 固定步骤固定步骤执行器是第二个执行器但它不跑自由循环而是固定四步理解 / 改写查询并检测元描述陷阱如问题类型流程咨询命中就回退原始问题避免改写丢失意图。安全审查门控不通过就生成降级回复直接返回。并行检索向量检索 图查询并行且复用路由层预计算的 embedding省掉一次 embedding API 调用。生成 质量评估打质量分与是否解决标志并上报 Prometheus 指标。为什么需要第二个执行器因为不是所有任务都该跑自由 ReAct。知识问答即 RAG 兜底是确定性步骤流用固定四步比自由循环更可控、更便宜、更易观测。harness 的多策略本质是按任务复杂度选执行器简单查询走直接分发多步推理走 ReAct知识问答走固定步骤。这就是前面那张分发图的真正含义。六、守卫不是补丁是 harness 的一等公民把前面散落的守卫收口成一张表能看清 harness 的设计哲学——守卫分层、前置、复用而不是事后打补丁守卫点机制失败语义输入归一化规则 / 本地模型回退原文本不阻塞Token 截断tokenizer 精确估算重建请求防拖垮链路情绪 / 舆情级联检测 升级短路管线fail-closed意图路由意图识别 复杂度门控选对执行器工具选择意图过滤 embedding 重排降维候选集输入 / 输出安全规则引擎零 LLM 成本拦截 / 过滤幂等分布式锁TTL 5 分钟跳过重复触发人在回路状态存档 interrupt暂停等待人工可观测全链路 trace 指标全链路 trace 指标这张表也回答了开篇的问题为什么教科书循环不够因为守卫必须前置且分层否则每个执行器都要各自重写一遍安全、截断、可观测——那才是真正的维护噩梦。七、Harness 与外围设施的关系此外多工具部分成功、跨服务上下文同步等失败模式不在本文范围见《AI Agent 分布式系统》系列的《工具调用部分成功》《分布式上下文存储与同步》两篇。八、要点harness ≠ 单一 ReAct 循环而是路由层 多策略执行器 生产守卫的三层结构。路由层把生产约束前置到循环之外执行器按任务复杂度分工直接分发 / ReAct / 固定步骤。递归上限是循环的断路器状态存档器是循环的暂停键——这两样是 ReAct 生产化的分水岭。守卫是 harness 的一等公民分层、前置、复用而不是每个执行器各写一遍。harness 与 LLM 网关、监控 Agent 是配套的网关管出得去监控管看得见。
Agent 运行时与 Harness：从教科书循环到生产级运行时
核心论点能上生产的 Agent harness指套在 LLM 外面、把工程约束编织进运行时的那层骨架不是 LangChain 文档里那个think → act → observe的单循环而是路由层 多策略执行器 生产守卫的三层结构。把延迟、韧性、安全、可观测性直接编进运行时本身而不是等出事后再打补丁。一、教科书里的 Agent 循环为什么不够所有 Agent 入门文章都会画同一张图LLM 产出想法 → 选工具 → 执行 → 观察结果 → 再思考……直到给出最终答案。ReAct 范式干净、优雅但它偷偷假设了四件事LLM 永远在线、且调用免费可用性与成本两件事工具总是成功返回用户输入是干净的没人需要盯着它。生产环境把这四条全破了LLM 有速率限制和偶发超时且每 token 都要计费远程工具会限流、返回空、部分成功用户输入带 typo、情绪甚至攻击合规还要求高风险动作必须人确认。所以 harness 真正要解决的不是怎么跑循环而是循环之外的工程问题请求进来前怎么净化、循环怎么设上限、出错怎么兜底、谁在盯着。这就是本文要拆的生产级 harness。二、Harness 的三层结构路由层 执行器 守卫第一篇从分层视角讲了系统由哪些层组成本篇换一个切面把运行时单独拎出来看一次请求在 harness 内部实际经过了哪些闸门。先看全貌——Shop-Agent 的 harness 不是单一 loop而是三段生产守卫外包一层输入安全过滤 · 输出安全过滤 · 人在回路 · 全链路可观测按意图分发按意图分发按意图分发按意图分发用户请求路由层 · 入口归一化 / Token 截断 / 情绪 / 意图识别ReAct 执行器自由循环固定步骤执行器Plan-Execute / RAG 兜底 / 固定四步直接分发简单查询纠纷协调器专用 · 分布式锁注图上把 Plan-Execute 与 RAG 兜底合并为一类——它们走的是同一套固定步骤执行器。纠纷协调器带分布式锁、不跑通用循环属于特化路径不计入多策略三选一。第一个反直觉结论harness 路由层 多策略执行器而不是一个万能循环。路由层负责该用哪个执行器每个执行器负责在自己的循环里把事做成。把这两层分开守卫才能被复用而不是在每个执行器里重写一遍。顺带区分两个三导语说的三层是纵向的处理阶段路由层 / 执行器 / 守卫而多策略三选一是横向的执行器分工ReAct / 固定步骤 / 直接分发两者不是同一个三。三、路由层harness 的第一道闸门路由层是 harness 的入口它本身不跑 LLM 循环而是把生产约束前置到循环之外。逐一看它立下的几道闸门同义词归一化规则 本地模型零 LLM 成本轻度清洗失败就回退原文本绝不阻塞流程。Token 预算截断用 tokenizer 精确估算中文 ≈ 1.5 token/字超限就重建不可变frozen的请求对象。这避免了一个超长输入把后续整条链路拖垮。情绪检测级联规则 1ms 本地模型 ~30ms本地模型优先保持延迟可控。舆情风险 → 立即升级检测到紧急情况直接短路整条管线返回已升级高级专员连意图识别都不做。这是 fail-closed出问题时默认拒绝而非放行的教科书示例。意图识别 → 路由分发命中远程调用走参数抽取 门控复杂意图走 ReAct简单意图走直接分发纠纷类走协调器。纠纷协调前的分布式锁锁的 key 由会话号 订单号拼接TTL 5 分钟。防止接口重试或消息队列至少一次投递导致的重复触发——这是 harness 给幂等上的第一道锁。输出内容安全过滤规则引擎零 LLM 成本。全链路 trace A/B 注入整条管线共享一个 handler实验分组在出口注入。论点这些守卫前置到路由层意味着无论请求最终落到哪个执行器净化、截断、情绪、安全、可观测都已经发生。这正是守卫是 harness 一等公民的体现下文「守卫不是补丁」一节收口成表。四、执行器一ReAct 循环递归上限即护栏ReAct 执行器图编排框架驱动是自由循环执行器。它做对了几件生产化的事工具选择前置按意图过滤 embedding 重排把文本转成向量、用相似度匹配只把相关工具喂给 LLM而不是几百个全量 Function Calling把工具描述全塞进 prompt 让模型自己挑呼应《软预过滤工具选择方案》。输入安全过滤规则引擎拦截不进循环。图状态存档checkpointer状态存档器把执行到一半的图状态存下来是人在回路interrupt()的必需品。递归上限 基础步数 × 2 2基础步数设为 5 → 上限 12。这是 harness 给循环装的断路器——把教科书里可能无限转圈的 ReAct变成有限状态机。没有它一个钻牛角尖的 Agent 会一直烧 token。这个值在图默认配置与每次调用的配置里双重设定防止漏配。人在回路当退款申请这类工具被调用置待审批标志把图状态按会话级标识存下返回等待确认。后续人工审批后用同一标识 resume 恢复而不是从头重跑。推理链抽取从图的消息里抽出最终答案 中间步骤think→act→observe 的痕迹作为可审计的推理链。关键论点递归上限是循环的断路器状态存档器是循环的暂停键。这两样东西才是 ReAct 从demo 玩具变成生产组件的分水岭。五、执行器二Plan-and-Execute 固定步骤固定步骤执行器是第二个执行器但它不跑自由循环而是固定四步理解 / 改写查询并检测元描述陷阱如问题类型流程咨询命中就回退原始问题避免改写丢失意图。安全审查门控不通过就生成降级回复直接返回。并行检索向量检索 图查询并行且复用路由层预计算的 embedding省掉一次 embedding API 调用。生成 质量评估打质量分与是否解决标志并上报 Prometheus 指标。为什么需要第二个执行器因为不是所有任务都该跑自由 ReAct。知识问答即 RAG 兜底是确定性步骤流用固定四步比自由循环更可控、更便宜、更易观测。harness 的多策略本质是按任务复杂度选执行器简单查询走直接分发多步推理走 ReAct知识问答走固定步骤。这就是前面那张分发图的真正含义。六、守卫不是补丁是 harness 的一等公民把前面散落的守卫收口成一张表能看清 harness 的设计哲学——守卫分层、前置、复用而不是事后打补丁守卫点机制失败语义输入归一化规则 / 本地模型回退原文本不阻塞Token 截断tokenizer 精确估算重建请求防拖垮链路情绪 / 舆情级联检测 升级短路管线fail-closed意图路由意图识别 复杂度门控选对执行器工具选择意图过滤 embedding 重排降维候选集输入 / 输出安全规则引擎零 LLM 成本拦截 / 过滤幂等分布式锁TTL 5 分钟跳过重复触发人在回路状态存档 interrupt暂停等待人工可观测全链路 trace 指标全链路 trace 指标这张表也回答了开篇的问题为什么教科书循环不够因为守卫必须前置且分层否则每个执行器都要各自重写一遍安全、截断、可观测——那才是真正的维护噩梦。七、Harness 与外围设施的关系此外多工具部分成功、跨服务上下文同步等失败模式不在本文范围见《AI Agent 分布式系统》系列的《工具调用部分成功》《分布式上下文存储与同步》两篇。八、要点harness ≠ 单一 ReAct 循环而是路由层 多策略执行器 生产守卫的三层结构。路由层把生产约束前置到循环之外执行器按任务复杂度分工直接分发 / ReAct / 固定步骤。递归上限是循环的断路器状态存档器是循环的暂停键——这两样是 ReAct 生产化的分水岭。守卫是 harness 的一等公民分层、前置、复用而不是每个执行器各写一遍。harness 与 LLM 网关、监控 Agent 是配套的网关管出得去监控管看得见。
