Prompt 之外生产级 Agent Harness 到底在控制什么发布边界本文的六层控制面是作者工程综合不是 OpenAI 官方产品架构。预算阈值、权限强度和状态转换必须按具体系统验证。摘要“最多搜索五次”“不要浪费 Token”“完成后立刻停止”写在 Prompt 中并不代表系统真的拥有这些约束。生产级 Agent 需要一个位于模型之外的 Harness负责作用域、持久状态、模型与工具调度、多维预算、验证恢复和回归评测。本文给出六层职责地图、层间交接物和最小实现顺序。关键词Agent Harness、任务契约、预算监督、状态机、工具调度一、模型负责判断Harness 负责让约束真正成立模型擅长理解目标、生成计划、解释不确定性和选择下一步。Harness 更适合执行确定性规则允许访问哪些文件和系统当前还剩多少轮次、时间和工具预算哪些动作可以并行哪些写入必须串行哪些验收项已经满足失败应重试、回滚、降级还是请求用户新线程恢复时需要加载哪些状态。核心关系不是 Harness 替代模型而是把不可依赖模型自觉完成的职责移到模型之外模型建议继续搜索 ↓ Harness检查证据缺口、搜索预算和最近收益 ↓ 允许 / 缩小范围 / 停止 / 请求新授权一个实用判断是如果某条规则必须在模型失误时仍然成立它就不应该只写在 Prompt 里。二、生产级 Harness 的六层控制面1. 任务契约任务契约把自然语言请求转换为可执行边界goal:要解决什么问题scope:允许读取和修改什么constraints:哪些行为禁止done_when:什么证据代表完成permissions:工具、网络和写入权限budget:时间、轮次、工具、搜索和子代理上限它的消费者不只是模型。权限层读取 scope预算层读取 budget验证层读取 done_when恢复层保存当前契约版本。没有任务契约后续每层都只能猜测“做到什么算完成”。OpenAI Codex Best Practices 明确建议在任务入口写清Goal、Context、Constraints和Done when。这直接支持“任务输入需要结构化”的判断但把权限检查、预算阻断和完成验收真正执行起来是本文进一步给出的 Harness 工程边界。2. 状态与上下文上下文管理不是把全部聊天记录持续塞回模型。Harness 应区分稳定规则仓库规范和长期约束当前任务目标、范围和验收已确认事实入口、接口和错误证据工作状态阶段、已完成项和剩余风险原始档案完整日志与旧对话需要时再取。这一层向模型提供最小必要上下文同时向恢复机制输出状态快照。它解决的是“下轮需要知道什么”而不是追求上下文窗口占满。3. 模型与工具调度模型路由决定当前阶段需要什么能力工具调度决定调用依赖、并发、限速、超时、结果压缩和幂等。“并行越多越好”不是调度策略。应先建立依赖图独立只读任务可以批处理相互依赖的调查保留反馈回路写入和外部副作用默认串行输出过大的批次拆分或先聚合。模型选择也不应只发生在入口。复杂发现阶段可能使用高能力模型机械实现阶段可以降级验证发现新风险时再升级。OpenAI 的 Programmatic Tool Calling 文档说明工具编排可以包含并行、循环、条件和中间结果处理同时由应用决定能力是否开放、哪些工具可被调用。这说明“工具调度”是显式控制流本文进一步主张把失败行为、权限、幂等和审批写进 Harness 合同。4. 预算与停止Token 上限无法覆盖全部资源。Agent 可能 Token 尚未超限却已经等待工具一小时、重复搜索二十次或创建多个子代理。预算至少应覆盖Credits / 模型轮次 / 工具调用 / 搜索 子代理 / 墙钟时间 / 重试 / 写入范围预算监督器还需要同时观察消耗与进展观察动作消耗正常验收持续推进继续消耗快速增长进展停滞暂停并重规划同一错误重复出现禁止盲目重试连续搜索没有新增证据停止搜索全部验收通过立即停止写入越界拒绝并回滚预算监督器真正需要的权力不是提醒模型“节省一点”而是拒绝继续执行。5. 验证、回滚与恢复模型说“完成了”不是状态转换条件。验证器必须逐项检查任务契约里的 done_whenroot_cause_explained:truerequired_tests_added:truetests_passed:truescope_respected:truerisk_documented:true若失败Harness 应区分实现错误回到 Implement发现新约束回到 Plan环境错误保留变更并交付阻塞证据越界写入拒绝并回滚预算不足保存检查点并等待授权。这样任务才是可恢复状态机而不是只能从头重跑的长对话。6. 事件账本与回归评测最终 Token 总数无法解释为什么任务变贵、为什么失败也无法解释模型升级后哪里发生了回归。事件至少应记录当前阶段与执行者模型和 reasoning effort工具、批次、延迟和结果大小输入、缓存输入和输出重试、错误分类和副作用对验收进展的增量状态快照与恢复点。这些事件支持更有用的指标验收通过率、每个通过任务的资源、人工返工、P95/P99 单任务消耗、重复读取、重复搜索、回滚率与越界动作。三、层与层之间必须交接结构化产物只有六个模块名称仍然只是一张概念图。真正的 Harness 必须规定层间交接上游交接产物下游用途任务契约Goal、Scope、Done when、权限、预算共同基线状态与上下文已确认事实、阶段、状态快照模型执行与恢复调度模型选择、工具依赖图、幂等信息安全执行预算监督剩余量、消耗速度、继续或暂停决定控制任务扩张验证与恢复验收结果、失败分类、回滚点决定状态迁移事件账本可重建执行轨迹回归、审计与优化任何一层缺少结构化输出下一层都会退回自然语言猜测没有 Done when验证器只能相信模型自述没有工具依赖图并行会制造写冲突没有失败分类重试会重复同一个错误没有状态快照新线程只能复制完整历史没有进展增量预算监督只能等额度耗尽。四、最小可用 Harness 的实现顺序不需要一开始就构建复杂多代理图编排。可以按以下顺序建立闭环任务契约与作用域先让 Goal、Scope、Constraints 和 Done when 可被机器读取。工具事件与幂等记录参数摘要、耗时、错误与副作用为写操作建立幂等或回滚单元。阶段状态与检查点至少区分 Discover、Plan、Implement、Verify、Deliver。验证器让状态迁移由验收证据触发。多维预算与停止条件控制轮次、工具、搜索、重试和时间。有限路由和子代理单代理闭环稳定后再增加模型升级、降级和有限子代理。回归与长尾观测固定简单修改、跨模块实现、工具超时、权限拒绝和长线程恢复任务。这个顺序的原则是先获得控制权再增加自主性。五、什么时候不需要完整 Harness一次只读解释、无外部副作用、几分钟可以人工复核的任务简单 Prompt、受限工具和最终检查可能已经足够。完整 Harness 的状态持久化、事件采集和恢复机制本身也有开发与运行成本。需要升级到完整控制面的信号通常包括任务持续时间长可能跨线程或跨人员恢复工具会写入代码、数据库或外部系统失败代价高必须审计和回滚子代理或并行调用让执行树明显扩大成本、延迟或限额需要稳定预算模型升级后必须比较行为回归人工无法逐步盯住每次执行。Harness 不是成熟度勋章而是风险和复杂度达到阈值后的工程选择。OpenAI Multi-agent 文档把并行执行、聚焦上下文和根 Agent 协调列为收益同时提醒顺序依赖、共享可变状态竞争和单一慢外部操作会削弱收益。这支持本文的边界多 Agent 不是默认升级项只有任务可拆分且控制面已经稳定时才值得引入。结论生产级 Agent 的关键差异不是系统提示写得更长而是模型之外是否存在一个真正能执行约束的控制面。这个控制面至少承担六种职责任务契约、状态与上下文、模型与工具调度、预算与停止、验证与恢复、事件账本与回归。它们共同回答Agent 现在允许做什么为什么还要继续什么证据代表完成失败后怎样恢复而不是从头再来。已有的安全治理、模型路由、Context Ledger、工具沙箱和异步网关可以继续深入每个模块。Harness 总览的价值是说明它们位于同一条可控执行链上的不同职责。参考来源OpenAI Codex Best PracticesOpenAI Codex ModelsOpenAI Programmatic Tool CallingOpenAI Multi-agent GuideOpenAI Codex Subagents