agent-harness-">Agent Harness的本质：环境与上下文的双重治理

在构建智能体（Agent）系统时，许多团队最初会把注意力放在”角色设定”上——给模型写一段人格化的系统提示词，期望它像某个岗位的员工一样工作。这种做法看似直观，却容易偏离工程本质。Agent Harness（智能体运行框架）真正要解决的问题，不是让模型扮演谁，而是控制模型在每一步能看到什么、能做什么、会得到什么反馈。本文从外部环境与内部上下文两个维度，拆解Harness工程的本质与实践路径。

一、重新理解子代理：分工是为了控制上下文

子代理（Subagent）常被误解为”角色扮演游戏”：设定一个研究员角色、一个审核员角色，让它们互相对话。这种理解忽略了子代理最重要的工程价值——上下文隔离与分工控制。

当一个任务同时包含调研与实现时，如果全部塞进单一上下文窗口，模型会面临两类干扰：一是调研阶段产生的大量素材挤占实现阶段所需的精确细节；二是不同阶段的目标相互冲突，导致输出质量在”广撒网”与”精雕琢”之间摇摆。子代理机制通过拆分上下文，让每个执行单元只承载与当前职责相关的信息，从而降低噪声、提升稳定性。

实践中可以用如下方式组织：

主代理（编排者）
├── 调研子代理：只读检索工具，输出结构化结论
├── 实现子代理：读写代码工具，输入为结论而非原始素材
└── 校验子代理：只读代码与测试工具，输出问题清单

关键原则是：子代理之间传递的是压缩后的结论，而不是原始上下文。这与”角色扮演”的区别在于，前者的目标是信息流控制，后者的目标是行为拟人化。

二、U型曲线：调研与实现需要不同的上下文密度

调研与实现的工作曲线并不是线性的，而更接近U型：任务初期需要广泛探索，上下文密度低、覆盖面广；中段需要收敛聚焦，上下文逐渐收窄；末段实现阶段又需要重新引入精确的局部细节（接口签名、数据结构、边界条件）。

这意味着Harness不能对所有阶段采用同一套上下文策略。常见做法包括：

• 探索阶段：放宽工具权限，允许大范围检索，输出以摘要为主；
• 收敛阶段：限制工具集合，要求模型产出明确的计划或结论；
• 实现阶段：切换为高精度上下文，注入相关文件片段与约束条件。

如果把三个阶段混在同一个上下文中，模型往往会在实现时反复回看无关素材，既浪费token也降低准确率。

三、缓存保持：上下文工程的隐形基础设施

上下文工程不仅是”放什么进去”，还包括”如何稳定地放”。多数模型服务对相同前缀的上下文具备缓存复用能力，若每次请求都重排系统提示词或频繁改动前置内容，缓存命中率会显著下降，带来延迟与成本的双重损失。

工程上的应对策略是：

1. 稳定前缀：系统提示词、工具定义、固定约束放在上下文最前部，且保持字节级稳定；
2. 追加式写入：新增信息尽量以追加方式置于尾部，避免中间插入导致前缀失效；
3. 分区管理：将易变内容（如临时观察结果）与稳定内容分离，必要时通过摘要替换而非原地修改。

[稳定区] 系统提示词 + 工具Schema + 全局约束   ← 保持不动
[缓存区] 历史对话摘要 + 已确认结论             ← 低频更新
[易变区] 最新工具返回 + 临时观察               ← 高频追加

四、可见性：让Agent”知道自己知道什么”

上下文管理的另一个常被忽视的维度是可见性。模型无法直接感知自己的上下文有多满、哪些信息已经过期、哪些结论尚未验证。Harness需要主动把这些元信息暴露给模型，例如：

• 当前上下文占用比例与剩余预算；
• 已完成的子任务与待办事项清单；
• 关键结论的来源标记（来自哪次工具调用）。

可见性提升的直接收益是减少重复检索与无效推理。当模型能”看到”已有结论时，它更倾向于复用而非重新探索。

五、让Agent参与上下文管理

完全由外部框架静态裁剪上下文，往往难以适配动态任务。更合理的做法是把部分上下文管理权交给Agent自身：提供摘要工具、记忆写入工具、上下文清理指令，让模型在运行中主动决定保留什么、压缩什么、丢弃什么。

这要求Harness提供清晰的元工具，例如：

summarize_span(start, end)   // 将指定区间压缩为摘要
pin_fact(key, value)         // 将关键结论写入稳定区
drop_span(start, end)        // 释放不再需要的上下文

同时需要配套约束，防止模型过度压缩导致关键信息丢失，例如要求压缩后必须保留来源引用与未决问题清单。

六、Harness架构：环境工程与上下文工程

综合来看，Agent Harness的研发包含两个相互支撑的部分。

1. 外部环境工程

外部环境定义Agent可作用的世界，包含三个要素：

• 工具供给：没有外部工具，模型只是”瓶中之脑”，无法对外部世界产生影响。工具是广义概念，既包括系统提示词中定义的函数调用，也包括技能包与通过标准协议接入的外部服务。不同Agent所需工具差异明显：编码类需要文件读写、编辑、版本控制与语言服务工具；知识库类需要关键词检索与语义检索工具；深度调研类需要网络检索与内容抓取工具；客服类需要企业知识库、语音识别与语音合成工具。
• 约束设定：明确工具权限边界、可访问资源范围、操作频率限制，避免越权与副作用扩散。
• 反馈回路：对期望行为给予正向信号（如通过校验、任务达成），对不期望行为给予负向信号（如测试失败、越界操作被拒绝），使模型在闭环中调整策略。

值得注意的是，工具供给形态近一年出现明显回摆：从早期的协议化远程服务调用，逐步转向以命令行接口为主的本地工具形态。原因在于命令行工具具备组合性强、调试直观、权限边界清晰、易于版本化等优势，更适合需要频繁试错与管道组合的Agent场景。这一趋势提示我们：工具形态的选择应服务于上下文效率与可控性，而非追逐接口潮流。

2. 内部上下文工程

上下文工程的核心定义是：策展模型所看到的信息，以换取更好的结果。它关注的是”模型此刻应该知道什么”，而非”系统拥有什么”。

其工作内容包括：决定注入哪些检索片段、以何种粒度呈现、何时用摘要替换原文、如何在多轮交互中维持关键约束不丢失。一个实用的判断标准是：任何进入上下文的内容都应能回答”它对当前决策有什么作用”，无法回答的内容应当被压缩或移除。

七、落地建议

1. 先定上下文预算，再定工具清单：工具越多，返回内容越容易淹没上下文，需同步设计裁剪策略。
2. 把子代理当作上下文边界，而非人格边界：按信息依赖关系拆分，而非按岗位名称拆分。
3. 为缓存设计稳定性：把不变内容前置并冻结，把变化内容追加到尾部和易变区。
4. 给模型元认知：暴露上下文占用、结论来源、待办状态，减少无效探索。
5. 保留人工兜底：对高风险工具调用设置确认环节，反馈回路中保留可审计日志。

Agent Harness的本质可以概括为一句话：通过环境工程界定行为空间，通过上下文工程界定认知空间，两者共同决定Agent的实际能力上限。理解这一点，才能跳出”提示词调优”的局部视角，建立可复用、可度量的智能体工程体系。