代理工具工程：模型相关的状态、验证与控制机制
生产代理的运行时视角：为何提示和上下文不够用，以及持久化状态、强制机制、验证与可观测性如何填补这一缺口。
来源: Agent Harness Engineering: The Runtime Architecture Behind Reliable AI Agents
即使拥有强大模型仍会失败
想象这样一个智能体：它配备了市场上最先进的模型、精心调优的系统提示词、数十种工具，以及足以容纳整个代码库的上下文窗口。即便如此，在任何合格工程师看来都属于常规任务的工作它仍可能出错——选对了行动方式却执行不当；找到了关键信息，却在上下文重置时丢失了它；正确编辑了十个文件，却在第十一个文件中悄悄引入了缺陷；花费一小时去调试自己造成的问题。更有甚者，它甚至可能撰写一份看似合理的报告，声称任务已经完成，而实际上根本没有任何检查。
通常的应对方式是改进提示词：给出更多指令、示例、背景信息，或恳请模型更加谨慎。这种方法暂时有效，但最终仍无济于事。更深层次的缺陷在于那种将模型视为主体、将其周围的一切都视为配置的心理模式。一旦模型需要在真实环境中持续运行，这种观念就会彻底破灭。
智能体代理并非仅仅是带有提示词的模型。它其实是一个运行时系统：能够维护状态、执行操作、与外部系统交互、处理故障、接收反馈，并且需要具备恢复、验证及被控制的能力。围绕这种运行时形成的学科被称为智能体框架工程。将其与提示词技术作比较：提示词工程关注的是如何指导模型表现，而框架工程则着眼于如何构建一个能让模型可靠达成目标的环境。这并非对提示词技术的改进，而是一种不同的抽象方式——它既涵盖模型生成的输出，也涉及系统能执行的功能、故障后的存活状态、允许的操作以及何为完成的标准。
概率模型的运行时环境
最简单的智能体模型就是包含提示词和若干工具的模型。这种模型足以帮助理解单一推理过程，但对于实际应用中的智能体来说则不够用，后者更应被视为基于概率模型的运行时系统。
模型负责进行推理，而框架则决定这些推理在何种条件下才能转化为实际执行：模型能看到什么、能够触及什么、允许采取哪些行动、何种状态会持续存在，以及在宣布成功之前需要哪些证据。
以某个编程智能体为例，其提示词要求它先检查架构、运行测试，并且不干扰无关组件。这些文字仅说明了意图，却并未强制执行任何操作。而框架则可以指定某些文件可写、其他文件不可写，每次修改后进行验证，阻止被禁止的操作，保存进度，并且在没有相应证据时拒绝关闭任务。因此，提示词决定了智能体应该做什么，而框架则决定系统允许什么以及什么算作已完成。模型提供智能能力，框架则将其转化为可实际操作的形式。
三层工程架构
智能体工程已经经历了三种逐步抽象化的层次：首先是提示词，其次是上下文，最后是框架。
提示工程旨在明确模型应执行的任务。它通过优化指令、示例、工具描述及行为限制，能让简单任务的处理效果极为出色。但提示仅属于指令，本身并无强制力。被要求运行测试的模型仍可不实际执行就宣称任务已完成；即便明确告知其不得触碰生产文件，若运行环境允许其无限制访问，这一要求也几乎起不到作用。要求模型将某个决策记住六小时，这种需求又会与其他所有输入到上下文中的信息产生冲突。
上下文工程解决的是下一个问题，即模型在做出决策时应当掌握哪些信息。检索、技能、记忆、工具结果、结构化状态、逐步披露与数据压缩等机制共同构建更优的决策上下文，目标也从拥有更多上下文转变为拥有更高质量的上下文。即便如此，模型仍可能选择错误的行动、破坏状态、跳过验证、陷入循环，或过早宣布成功。
从这一点开始，工程实现工作便展开了——需要思考应该为模型构建怎样的系统才能确保任务可靠完成。工程系统能够提供提示词和上下文无法单独实现的功能：持久状态、受限工具、权限控制、隔离机制、验证功能、恢复手段、评估能力以及可观测性。它还改变了工程循环的流程。出现故障时不再只是需要重新措辞提示词，而是要思考究竟缺少了哪种控制机制，其解决方案可能包括验证器、更严格的工具契约、策略边界、检查点、恢复策略或更好的可观测性。每一次故障最终都会导致系统发生改变。
其结果就是一种“安全带棘轮机制”：出现故障后，先是失去控制，接着对安全带进行改进，再进行验证，最终形成更强的基础。提示工程能优化输入给模型的内容，上下文工程则能提升模型所掌握的知识。而安全带工程则能改善模型工作的条件，使系统更难以以相同方式再次出错。
运行时负责的内容
如果将安全带视为运行时，它究竟承载了什么？与其列举提示、工具、内存和调度代码，不如明确运行时的职责。
- 上下文决定了模型为做出下一个决策所需了解的信息：指令、检索到的资料、技能、相关工具的输出以及当前的观察结果。
这些并非七个独立的特性，也不一定非得是七种服务。它们共同构成了围绕概率模型的控制循环。一旦该循环的运行时间从几分钟延长到数小时，能够承受上下文限制、故障、重试以及工作节点的更换，这种架构就会逐渐呈现出工程师们早已熟悉的形态——分布式系统。
上下文窗口并非状态存储
在智能体设计中，最容易犯的错误之一就是将上下文窗口视为内存。
那确实是个诱人的习惯。模型能够看到整个对话、之前的工具调用、决策以及中间结果，因此似乎再添加一些内容并无害处。然而该窗口只是一个工作集，并非数据库。其中的任何内容都不是持久化的：重启、截断或压缩操作都可能缩小其规模，甚至直接替换掉它。虽然扩大窗口能增加容量，但持久性依然保持不变。
对于长时间运行的智能体而言，权威的任务状态必须存储在其他地方：目标、已完成和待处理的工作、决策、生成物、检查点、验证结果以及对外部资源的引用。随后系统会根据模型当前的需求，从这些状态中重新构建上下文。两者的区别很简单：上下文是模型所看到的内容，而状态则是系统所掌握的信息。
压缩功能使这一点显而易见。一个花费三小时修改代码库的智能体可能会产生数百次工具调用记录、被放弃的尝试以及各种观察结果。压缩这些历史数据可以让后续使用到有用的上下文，但总结仍是对所发生事情的一种解读，因此关键状态不应依赖于压缩器保留的内容。相反，该框架可以从稳定状态按以下顺序构建新的上下文：任务状态、相关成果、当前观察结果、技能信息，最后是模型的上下文。
检查点在进程崩溃时遵循相同原理，而结构化的任务交接则在不同代理或工作节点之间应用这一原理。后续节点只需具备正确继续运行所需的状态，无需前序节点的完整对话记录。此时的架构问题在于：哪些信息必须独立于上下文而保留？一旦明确了这一点，上下文管理就变成了状态管理问题。
长时间运行的代理即分布式系统
当一个代理程序运行数小时甚至数天时，传统的请求-响应模型就不再适用。进程可能会崩溃，工具可能会出现超时，工作节点在完成操作但尚未报告结果之前就可能消失。还有可能出现两个工作节点同时处理同一任务的情况，模型的上下文也可能在运行过程中丢失。这些都不是什么罕见现象，因为它们都是分布式系统中的经典问题，而长期运行的程序需要明确的执行语义来应对这些问题。
如果任务能够比工作节点存在更久，那么就必须对任务的归属进行限制。租约机制可以让工作节点在限定时间内占有某项任务，而心跳信号则能为外部观察者提供该节点仍在运行的指示。一旦工作节点消失，租约就会到期，其他节点就可以从持久化的状态中继续处理该任务。
重试机制需要同等程度的谨慎处理。设想这样一个场景：某个代理提交了部署请求，但在得到任何结果之前调用就超时了。盲目的重试可能会导致该部署被执行两次。因此，代理工具需要分布式系统中常见的那些保障机制：操作标识符、幂等性、明确的失败状态，以及负责处理重试行为的指定责任人。
接下来是恢复功能。长期任务应表现为持久的进度状态，而非内存中的临时对话，其执行遵循检查点、执行、观察、持久化与继续的循环。如果执行过程中中断，系统需要判断当前步骤是否可以安全重试、是否已提交、是否部分完成或是否需要补偿措施。恢复并不意味着重新执行所有内容，而是重建为安全继续所需的最小状态。任务交接也遵循相同模式：新的执行者会获得目标、决策结果、生成物、验证状态以及未完成的工作，而不会继承其他执行者的对话历史。
这确立了核心的可靠性边界。一旦智能体能够比其进程更长久地存在，进程就不再是可靠性的衡量单位，持久化的任务才是。
验证是智能体的另一半
智能体可以编写代码、执行部署、构建数据库查询或更改基础设施。生成内容并不等同于任务完成，而危险的做法是让智能体自行决定其工作是否成功，比如通过消息宣称认证流程已完成且所有测试均通过。管控系统不应将此类消息视为有效证据，而应重新运行相关测试。同样地，声称服务状态正常时也应触发健康检查而非直接结束任务；数据迁移的判断应基于模式和数据不变性，而非模型对自身工具调用的解读。智能体认为任务已完成的判断并不能作为可靠的完成信号。
正因如此，生产环境会设置三个独立的角色。规划者决定需要执行什么操作，执行者负责完成特定范围内的工作，而评估者则判断最终的系统状态是否符合要求。一个模型可以承担这三个角色，但它们的职责依然各不相同。
验证应基于可观察的事物，只要存在确定性的证据，就应优先使用：编译器、测试运行工具、模式验证器、健康检查机制、部署状态监控、策略检查或直接的断言。当正确性本身具有语义意义时，基于模型的评分方法很有用，但它需要具体的标准，而非“结果是否看起来良好”这类模糊的判断。此时完成状态便成为系统的属性，而非模型所描述的内容：需求已满足、验证通过、所需文件存在、策略检查合格，只有满足了这些条件，任务才算完成。换言之，验证会产生证据，评估者通过阅读这些证据来决定是否可以继续执行，因此评估者就相当于反馈回路中的传感器。智能体推动进度的发展，而验证机制则负责提供证据。
从指令到执行
可以要求代理不要执行某些操作，但并不会使其无法执行。诸如“不得修改生产环境”、“仅可在工作区内编写代码”以及“绝不可泄露凭证”之类的指令固然有用，但如果运行时仍允许相关操作，这些就都不能构成安全边界。指令用于传达意图，而执行则用于确立不可变规则。
工具设计清楚地展现了这种差异。将通用的 execute_sql() 函数交给智能体后，其可执行的操作范围与拥有受限、只读查询接口的智能体截然不同。受限接口便于进行授权检查、参数验证、操作审计，并能缩小影响范围。MCP 工具、API、文件系统、shell 以及外部服务的工作原理也是如此：模型提出操作建议，而框架则决定该操作是否可行，以及应在何种身份、权限、环境和策略下执行。
一个实用的经验法则是按成本对约束条件进行排序：
- 如果违反某项约束的代价可承受，仅给出指令可能就足够了。
- 如果违反该约束的代价很高，就需要增加验证步骤。
- 如果违反该约束会带来危险，则应在边界处强制实施限制。
沙箱机制引入了第二个维度。授权机制决定某个操作是否被允许，而沙箱则负责处理代理程序出现异常行为时的后果。文件系统与网络上的边界、资源限制以及范围有限的凭证，都能将异常行为带来的影响控制在较小范围内。更为成熟的系统还会强制实现工作流转换，而不仅仅是单一工具的调用。在测试通过、预发布环境正常且得到相关人员批准之前，生产环境部署仍不可实现。模型可以建议进行转换，但最终是否合法仍需遵循运行时规则。这更接近状态机机制，而非依赖自然语言指令。其目的并非限制智能，而是限制功能及其影响范围。
无法观察的事物就无法操作
常规的可观测性仅能判断服务是否正常、延迟为何上升以及哪些依赖项出现了故障。而代理系统则需要更深入的层次。当某个代理发生故障时，需要了解究竟发生了什么，以及为何会走向那种状态——它原本试图实现什么目标？它获得了怎样的上下文信息？它调用了哪些工具？哪些策略允许或阻止了这些调用？有哪些状态发生了变化？又有什么证据让它确信任务已经完成？这就是轨迹可观测性。
诸如令牌数、延迟、成本、模型版本以及输入输出等标准大型语言模型指标虽必不可少，却仍不够全面，因为单次模型调用只是更复杂流程中的一个环节：包括意图识别、上下文获取、决策制定、动作执行、观察反馈、状态更新、验证过程以及最终结果。假设某个智能体花费40分钟尝试迁移服务却失败了，仅知道它使用了8万令牌几乎无法说明问题。有用的分析路径应能显示：该工具调用了过时的迁移指南，智能体选择了已废弃的API，部署在技术层面上虽成功，但集成测试失败，后续恢复尝试仍沿用相同策略。这才是真正的诊断依据。
这意味着上下文需要具备来源信息：即能够显示是哪些技能、文档、状态及工具结果影响了某一决策。工具调用同样需要因果上下文，包括触发这些调用的任务步骤、所使用的身份信息、被评估的策略以及后续结果。策略决策和状态变化也应清晰可见，同时还要展示那些成功的操作。最能反映情况的指标其实是行为层面的：任务成功率、验证失败次数、恢复成功率、提前完成情况、策略拒绝次数、反复出现的故障模式、需要人工介入的情况以及每项成功任务所需的步骤数。
可观测性是完善整个系统机制的关键要素。一次故障不应仅留下日志记录，其发展轨迹应当有助于识别问题所在，并明确缺失的控制机制——无论是上下文源、评估器、策略、工具边界、检查点还是恢复策略。理想的状态是系统无法以完全相同的方式再次出现故障。
一种新的系统学科
当智能体的自主性提升时，关于如何让其更高效工作的答案也会更加丰富。提示工程用于优化指令，上下文工程则用于调整决策时可用的信息，而系统机制工程则着眼于整个执行流程：状态、动作、边界、反馈、恢复、验证以及可观测性。这些方法并非相互替代，而是覆盖范围逐渐扩大的不同层面。
合理的职责划分是整个系统的基础：模型负责在不确定性条件下的推理，而运行时则负责处理不变性。那些绝不能被修改的文件会设有文件系统边界。那些不可被篡改的生产系统会经过授权检查。那些必须成功完成的迁移会根据最终状态进行验证，而那些需要在重启后依然保留的任务状态则会被持久化存储。不应要求模型来提供运行时更可靠的保障。
生产代理将会出现故障，而一个成熟系统的标志就在于它如何应对这些故障。每次故障都会反馈到运行时环境中。如果同样的错误不断出现，系统就会为其配置专门的评估器。如果某个操作被证明存在风险，其背后的功能范围就会缩小。如果进度丢失，系统会在缺失的位置生成检查点；而如果恢复尝试持续失败，系统则会启动升级机制。执行过程会生成相关证据，这些证据能揭示缺失的控制措施，而这些控制措施则能让后续运行更加稳健。
这同时也改变了对智能体的评判标准。问题不再在于模型有多好，而在于整个系统完成这类任务的可靠性如何。“Harness工程”并非另一种编排框架，而是一门旨在让概率智能具备可靠性的系统学科。演示只能证明智能体能够一次性完成某项任务，而生产系统则必须能够稳定、可验证、可恢复地反复执行该任务，并且每次失败都能让下一次运行更加完善。如今，大部分艰巨的工作都隐藏在提示语之下，体现在状态管理、反馈机制、验证流程、恢复策略以及控制循环的架构之中，正是这些要素将智能体的推理转化为持久的系统行为。