智能体运行框架工程：无需微调，提升 AI 表现

智能体运行框架（agent harness）可以通过调整模型接收的上下文、可调用的工具和执行规则，改善一个固定语言模型的任务表现。在 StaffOS，我们将这些控制机制纳入智能体运行时，并支持经过审核的业务指令与配置变更。本文介绍这一架构、相关的公开研究证据，以及衡量运行框架改动是否有效的方法。

本文图表采用公开研究结果。工作流示例均为虚构，评测流程使用工程师编写的场景和合成记录。在整个评测流程中，模型权重保持不变。

摘要

业务智能体需要在对话、数据库和外部服务之间协作。故障经常出现在这些系统的交界处：上下文缺失、工具结果含糊、状态过期，或在缺少依据时声称某项操作已经成功。运行框架工程通过明确的软件契约处理这些问题。本文分析三项公开实验，分别涉及工具接口、提示词优化和上下文适配，再说明这些方法如何应用于 StaffOS。我们定义了一套固定模型、衡量经验证结果，并计入延迟、推理成本和运行负载的评测流程。下文的基准数据均来自所引用的研究。本文的工程贡献是所述架构与评测规范。

1. 智能体运行框架控制什么

智能体运行框架是围绕语言模型构建的软件，决定模型看到哪些信息、可以请求哪些操作、操作如何执行，以及任务何时结束。其范围包括上下文组装、检索、工具契约、状态管理、执行限制、审批规则和评测反馈。

以一个虚构的预约请求为例。模型需要识别所需服务、获取有效时段、理解选定时间、请求创建预约，并报告结果。外围软件决定了时段是否仍然有效、重试是否会重复创建预约，以及返回的状态是否足以让模型正确作答。

分析时，可以将智能体表示为：

Agent outcome = F(model, harness, task, environment)

Harness = {
  instructions,
  context selection,
  tool interfaces,
  execution policy,
  working state and evaluation feedback
}

修改运行框架，就改变了模型执行任务的条件。因此，有意义的比较应固定模型和环境，同时修改运行框架中明确指定的部分。如果同时更换模型、增加尝试次数并调整工具，就很难判断改善来自哪里。

我们将改动分为三类：

• 提示词或操作手册修订： 修改某个决策所用的指令。
• 工具契约修订： 修改可执行的操作，或某项操作返回的信息。
• 运行时修订： 修改检索、上下文组装、执行限制或状态处理方式。

每一类改动都有不同的故障模式，需要各自的测试用例。

2. 模型权重固定时的公开研究结果

本节中的研究采用不同的任务和指标。每组比较都在各自实验内保持已部署模型不变。这些数据可以为特定机制提供证据；将它们汇总为一个平均值，会掩盖各自的实验条件。

工具接口：FrogNano

Kim 等人报告，将 R2E-Gym 替换为其 Leaf 运行框架后，SWE-bench Verified 的解题率如下。Leaf 同时修改了工具接口、指令和终止行为。1

固定模型	R2E-Gym	Leaf	绝对变化
Qwen3.5-4B	8.3%	37.2%	+28.9 个百分点
MiniMax-M2.5	66.5%	66.5%	0.0 个百分点

图 1. FrogNano 第 2 节公开的运行框架对比。坐标轴从零开始。较大模型的结果没有变化。

对 Qwen3.5-4B 而言，两者之比为 37.2 / 8.3 = 4.48。这是接口实验中针对该模型得到的结果。FrogNano 后续的强化学习结果涉及权重更新，不在这组比较的范围内。

提示词优化：GEPA

GEPA 利用执行反馈提出并评测提示词修订。在 HotpotQA 上，论文中的 Qwen3-8B 基线得分为 42.33%，GEPA 得分为 62.33%，提升 20.00 个百分点。官方实验采用答案完全匹配指标。在 IFBench 上，对应的提升较小：从 36.90% 升至 38.61%。这些结果说明，提示词优化需要针对具体任务进行评测。2、4

上下文适配：ACE

ACE 通过生成、反思和整理，维护结构化的操作手册条目。在 AppWorld 上使用 DeepSeek-V3.1 时，采用真实标签的离线配置将报告的平均值从 42.4% 提升至 59.4%，增加 17.0 个百分点。该平均值涵盖普通测试集和挑战测试集上的任务完成率与场景完成率。不使用真实标签的离线配置达到 57.2%。3

图 2. 两组独立实验分别来自 ACE 表 1 和 GEPA 表 1。AppWorld 采用四项完成率指标的平均值；HotpotQA 采用答案完全匹配指标。两个面板对应各自独立的实验条件。

对工程团队来说，实际问题是每项改动解决了哪种故障。更清楚的工具返回结果可以解决接口问题。操作手册可以补充缺失的流程。检索改动可以让已有事实在正确的步骤进入上下文。每项判断都可以直接测试。

3. StaffOS 运行框架的结构

StaffOS 将上下文检索、结构化工具、受限执行和经过审核的配置变更结合起来。这些组件之间的边界很重要，因为一个请求可能同时涉及语言理解、业务规则和状态变更。对于能可靠地用代码表达的规则与状态检查，我们将其保留在应用代码中。

上下文：为当前决策选择信息

我们的知识检索会应用业务与智能体的范围限制、启用状态和有效性规则、相似度阈值，以及条目数量限制。流程类操作手册采用独立的检索路径。这样，运行时就可以区分产品规格这类事实，与线索筛选步骤这类流程。

对话历史为处理当前请求提供上下文，并受到预算限制。较长的智能体循环可以压缩早期上下文，同时保留系统指令和近期的工具交互。运行层面需要回答具体问题：相关来源是否被选中？内容是否能装入上下文？压缩时是否删掉了必要事实？该机制是否实际执行？

仅有一项上下文设置无法回答这些问题。评测需要记录实际生效的配置，以及实际执行路径上的观测结果。

工具：明确操作与返回结果

工具包含名称、描述和结构化参数模式。工具注册表执行准入检查，并将适用的配置变更暂存待审。每个工具也会检查自身的业务前置条件。

我们的原生预约流程体现了这类契约：

appointment_offer_slots
  -> available slots with exact start times

appointment_book(starts_at: selected_slot.starts_at)
  -> booked appointment
  -> existing booking reused
  -> slot_unavailable

新建预约、重试时复用已有预约，以及时段冲突，会向模型返回不同的结果。遇到冲突，模型就有依据重新获取可用时段。已有预约则提供了可稳定报告的结果。

预约工具还必须能处理并发请求。重试行为属于操作本身的责任。重复发送格式正确的请求，不应在没有提示的情况下增加客户的预约数量。

执行：限制循环，核查完成声明

运行时限制工具调用轮数，并在接近上限时加入收尾指令。它还会针对部分操作完成声明进行检查，包括转交处理和配置变更。这些检查会核对工具证据或应用状态，随后替换没有依据的转交声明，或补充适当的状态说明。

完成状态检查的范围应当明确。能验证转交是否完成的规则，无法证明回复中的每一项事实都正确。每增加一类声明，都需要相应的证据和失败处理方式。

一项完成声明，需要有与其所描述的业务操作相同的证据。

配置：审核变更并管理版本

StaffOS 支持对五类配置进行审核后变更：角色设定、提示词、操作手册、知识和产品信息。运营人员可以通过这些配置，指定智能体应如何处理所属业务的工作流。提示词变更通过带版本管理的写入机制完成；评测系统支持预先编排的用例，也支持调用模型提供方进行测试。

每类配置都有负责人和用途。错误的产品事实应在知识来源中修正。必要的操作顺序应写入操作手册。含糊的成功响应应在工具契约中解决。将三者都塞进系统提示词，会让责任划分和测试更困难。

4. 根据工作流规范编写评测用例

工程师可以依据工作流需求、业务规则和工具契约编写评测用例。每个用例定义一个决策、该时点可用的信息，以及预期结果。对于会改变状态的任务，测试还要规定执行后应存在哪些记录。

用例规范要求包含以下字段：

字段	用例需要包含的内容
决策点	启动测试的合成消息或模拟工具结果
可用上下文	仅包含该决策之前能够访问的信息
初始状态	相关记录、权限、可用资源与时钟假设
预期行为	必须执行的操作、可接受的回复，或有合理依据的转交
禁止行为	重复写入、未经授权的操作，或无依据的成功声明
结果检查	尽可能使用确定性断言，否则使用经过审核的评分标准
来源标识	所属场景组、规范引用和测试夹具来源
版本标识	模型、运行框架、提示词、工具、测试夹具和评分器的版本

在一个合成预约用例中，可以设置为：选定的时段在预约调用之前变得不可用。测试检查智能体是否说明冲突并提供替代时段。预期文本可以变化，业务不变量保持不变：回复不能描述一个并不存在的预约。

受控变体可以暴露相近的故障。同一个用例可以改变日期表述、模拟超时，或在成功写入后重复请求。每个变体都需要有效的初始状态和经过核查的预期结果。同一场景的变体应放在同一评测划分中，避免几乎相同的用例同时出现在开发集和最终测试集中。

应分别评估回复和最终状态。表述清楚的回复仍可能描述一次失败的操作。成功创建的测试预约也可能得到令人困惑的确认消息。用例需要同时检查这两方面。

使用虚构的消息、标识符和业务记录构建测试夹具，并记录其来源。测试材料应排除生产环境对话记录、账户标识符、凭据和私有文档。本文附带的示例与可下载资料仅包含公开研究信息和虚构的工作流描述。

5. 运行框架发布的评测流程

运行框架实验在等价的初始条件下比较两套明确声明的配置。我们保持模型身份、提供方设置、用例输入和预算不变，再修改一个机制或一组清楚标明的机制。结果应展示哪些用例改善、哪些退步，以及改动带来的成本。

我们的评测规范包括六个步骤：

1. 冻结用例和评分规则。 在运行候选版本之前，确定任务成功的条件和硬性业务约束。
2. 将相关示例归为一组。 将每个合成场景及其变体保留在同一个数据划分中，为最终测试预留独立用例。
3. 声明实验改动。 记录正在测试的提示词、工具、检索或运行时变更。
4. 每次尝试前重置状态。 两套配置使用相同的预约可用时段、记录和权限。
5. 在固定预算内重复执行。 报告尝试次数、置信区间和配对结果差异，并在分析中考虑同一用例的重复运行。
6. 发布前检查退步。 按工作流、语言和操作类型审查失败，包括旧运行框架原本能正确处理的用例。

每次模拟都应保持事件顺序。在某个决策点，模型只能接收该步骤当时可用的信息。预期答案、后续模拟消息和最终事务状态，都属于评测器检查的内容。

用于判断改进是否有效的指标

指标	定义	工程用途
经验证的任务成功率	满足所声明结果的尝试次数，除以所有符合纳入条件的尝试次数	主要效果指标
硬约束违规率	出现禁止操作的尝试次数，除以符合纳入条件的尝试次数	发布门槛
无依据的完成声明比例	经过检查但缺少状态或回执支持的操作声明数，除以所有经过检查的操作声明数	衡量一类特定的可靠性故障
工具错误率	失败的工具调用次数，除以尝试调用次数，并按错误类别分别统计	区分接口、策略和基础设施故障
人工介入率	需要运营人员修复或接管的尝试次数，除以符合纳入条件的尝试次数	衡量运营负担
p50、p95 和 p99 延迟	端到端耗时，另行记录排队时间和提供方耗时	展示典型表现和较慢执行路径的表现
每次经验证成功的成本	所有尝试的计量成本总额，除以经验证的成功次数	包含失败尝试的成本
证据覆盖率	具备所需观测记录的尝试次数，除以独立统计的尝试总次数	表明报告能够证实多大范围的结果

在执行前定义纳入条件。超时、提供方错误和追踪记录不完整的用例，仍应计入尝试总数。待定和未知结果也要保留展示。用量缺失应与已计量的支出分开报告。如果报告从分母中剔除失败运行，就可能让一个更慢或可靠性更低的运行框架显得更好。

汇总分数需要按维度拆分。预约流程的改善可能损害转交处理，而总体均值会掩盖这种退步。高用量语言组也可能掩盖较小语言组的退步。发布报告应保留这些差异。

6. 性能和存储也是设计的一部分

运行框架的改进会消耗资源。额外上下文会增加输入 token 成本。更多工具调用轮次会增加延迟和失败机会。详细的评测追踪记录会增加写入与存储成本。离线评测会消耗模型提供方预算和工作进程容量。这些成本应与任务成功率一并纳入工程审查。

性能规范为每类工作划定执行边界和成本限制：

工作	执行边界	成本控制
授权、前置条件与必要审批	受影响的操作执行之前	耗时短且有索引支持的状态检查
运行计数器、计时和错误码	预先定义的运行时检查点	限制字段规模和记录耗时
详细的合成评测追踪记录	选定的评测运行	采样和单次运行的字节预算
合成用例生成与测试结果分析	后台评测任务	批次、并发和支出限制
候选版本比较	隔离的评测运行	固定用例、重复次数和时间预算

可选遥测需要明确的耗时上限。捕获数据库异常，并不能阻止连接缓慢或锁等待拖延客户响应。必要的授权与审批记录则有另一套要求：一旦记录失败，就必须阻止依赖这些记录的操作。

本规范中的运行计数器衡量耗时、状态和资源使用量。合成评测的追踪记录保存详细的测试输入与输出。可根据评测量和保留证据的大小估算存储需求：

Daily evaluation evidence volume
  = recorded evaluation runs per day
  x mean retained bytes per recorded run

索引、复制和备份成本还需在此基础上另行计算。按场景采样时也要进行测量：少数长场景可能占据很大比例的工具调用和保留字节数。

重复保存的评测上下文快照尤其需要关注。后续轮次经常重复包含之前的合成消息和工具结果。不可变片段配合有序清单可以减少重复存储，前提是上下文重建和测试夹具版本管理仍然可靠。

7. 运行框架工程的局限

运行框架可以补充缺失的事实、提供更清晰的操作接口，并阻止无效写入。部分故障在这些问题修正后仍会存在。我们将其分别归类为：任务需求含糊、业务数据缺失、集成不可用，以及在上下文充足且工具正常时仍发生的推理失败。处理方法取决于具体类别。

公开基准也有适用边界。编程、问答和应用自动化采用不同的成功标准。我们的业务工作流还涉及租户策略、人工决策，以及状态会随时间变化的外部系统。这些实验表明，运行框架改动可能产生显著影响；针对实际部署的评测，才能确定具体工作流的改善幅度。

因此，生产发布既需要结果证据，也需要运行证据。任务必须在所声明的规则下成功完成，成本、延迟和失败时的行为也必须符合所支持服务的要求。

结论

运行框架工程为改进智能体提供了明确的着手点：接收的事实、遵循的流程、可以请求的操作，以及操作周围的检查。StaffOS 通过这一结构，支持经过审核的业务配置和明确的运行时控制。

对于每项改动，评测流程会识别故障，在受控用例中复现决策，并在模型保持不变的条件下比较修订后的运行框架。发布决策同时考虑成功情况、退步、延迟和成本。用例会保留在评测集中，以便再次检测同类故障。

作者与引用

Vin Lim 是 StaffOS 的首席技术官，负责智能体编排、业务系统集成、上下文管理和评测。

建议引用格式： Lim, V. (2026). Agent harness engineering: improving AI without fine-tuning. StaffOS technical paper, version 1.1, September 17. https://staffos.xyz/blog/agent-harness-engineering

下载 BibTeX 引用 · 下载基准数据与来源网址 · 图 1 的 SVG 文件 · 图 2 的 SVG 文件

图表复现了所选研究公开的数值。百分点差值通过相减计算，解题率倍数通过相除计算。图表没有将不同基准的结果合并。业务背景可参阅我们的线索筛选和线索响应时间研究文章。