agent-harness-">Agent Harness 是什么：智能体执行框架的定义、三层接入与运行原理

一、先回答”它是什么”

Agent Harness（智能体执行框架、执行底座）是包裹在大语言模型外围、负责驱动模型完成多步任务的一层运行时基础设施。 它本身不产生智能，模型才是决策来源；但它决定了模型的能力以何种形态、何种边界、何种可观测方式对外输出。

一个更准确的定义可以这样表述：

Harness 是把”模型推理”转化为”可执行、可控制、可恢复的智能体行为”的中间层。它管理对话与会话状态、工具调用与参数校验、代码与命令的沙箱执行、流式事件输出、人工审批门禁，以及长任务的上下文组织策略。

从三个视角理解它会更清晰：

• 技术视角：它是一个长驻或多进程的执行运行时，包含代理主循环（agent loop）、工具注册与调用表、隔离执行环境、事件流协议和状态持久化存储。
• 业务视角：它划定了”谁拥有什么”的边界。业界一种被广泛引用的表述是：产品方拥有业务上下文、业务规则和自有工具，而执行框架只负责提供代理主循环。这意味着业务逻辑留在你的代码库里，而不是被固化进模型或某个封闭产品中。
• 使用视角：对开发者而言，它是三个层级递进的接入面——一行命令完成任务、用 SDK 把智能体嵌进程序、用长连接会话服务把智能体变成产品的一个常驻能力。

需要强调的是：harness 是一种架构角色，而不是某一类唯一实现。任何承担”代理主循环 + 工具执行 + 状态管理”职责的组件，无论其内部实现语言是系统级编程语言、脚本语言还是托管语言，都属于 harness 范畴。

二、为什么需要这一层：模型 API 解决不了的四个问题

如果模型 API 已经能生成高质量代码和方案，为什么还要一层框架？原因在于”生成”与”完成”之间存在四道鸿沟。

1. 状态连续性。一次复杂任务往往跨越几十轮推理与上百次工具调用。API 是无状态的请求-响应模型，谁负责保存中间结论、失败尝试、已读文件清单、待办队列？这正是 harness 的职责。
2. 执行权限与副作用边界。模型只能”说”要执行什么命令，真正落地需要一个执行体：写哪个目录、能否访问网络、是否需要人批准。没有这一层，智能体要么不可用，要么不可控。
3. 上下文长度与成本约束。上下文窗口有限、token 计费真实存在。长任务必须通过压缩、摘要、检索式回看等手段在”信息完整”与”成本可控”之间取得平衡。
4. 可观测与可恢复性。生产环境要求每一步动作可审计、会话可中断可续跑、失败可定位。这些属于系统工程问题，不是模型能力问题。

因此，”换一个更强的模型”与”换一个更好的 harness”是两个正交的优化维度，而后者往往被严重低估。

三、核心组成：六个关键模块

一个生产可用的 harness 通常由以下模块构成。以某个以系统级编程语言实现内核、同时提供脚本语言 SDK 的双栈开源实现为参照（其代码结构普遍包含 CLI 前端、核心 crate、协议与会话服务层等子模块），可以抽象出共性结构：

1) 代理主循环（agent loop）
循环的基本形态是：组装上下文 → 请求模型 → 解析输出 → 若包含工具调用则执行并把结果回填 → 判断是否终止。终止条件通常包括模型不再请求工具、达到最大轮次、触发预算上限或用户中断。

2) 工具与函数调用层
负责工具描述（名称、参数 schema、语义说明）向模型的暴露、参数校验、调用分发、错误归一化。工具设计质量直接决定智能体成功率：描述含糊、返回体过大会显著推高无效轮次。

3) 沙箱执行环境
承载 shell 命令、构建、测试、文件读写。常见隔离级别由弱到强为：仅限工作目录写权限、容器级隔离、虚拟机或微虚拟机隔离。安全模型的核心是”默认拒绝 + 显式授权”：默认不可联网、不可越出工作区、不可提权。

4) 会话与状态持久化
保存完整事件历史（用户消息、推理要点、工具调用与结果、审批记录），支持恢复、回放与分支。持久化通常需要与对象存储、数据库或消息服务等通用云产品能力配合，用于跨进程与跨机器的场景。

5) 流式输出与事件协议
以统一事件模型（消息增量、工具调用开始/结束、审批请求、状态变更、错误）向宿主 UI 推送，是终端、IDE 插件与 Web 产品复用同一内核的前提。事件必须带序号与幂等语义，以便断线重连后补齐。

6) 上下文管理与人工审批门禁
前者决定”往窗口里放什么”，后者决定”什么时候必须停下来问人”。这两者是最能体现工程功力的部分，也是不同 harness 之间差距的主要来源。

四、三层接入接口：从一行命令到产品化嵌入

开源这类执行框架时，最关键的开放内容往往不是模型权重，而是集成接口。典型设计是三层递进的接入面，覆盖从脚本到产品的全部形态：

层级	形态	生命周期	状态归属	典型使用者
第一层	非交互式单次调用	一次性进程	无（结果即产物）	流水线脚本、批处理、自动化任务
第二层	程序化 SDK	宿主进程内	由宿主代码持有	后端服务、内部平台、自研 Agent 产品
第三层	持久会话服务	长驻服务 + 多会话	由服务端持久化	IDE 插件、桌面与 Web 应用、多用户 SaaS

第一层：轻量非交互调用。 面向”给一个任务、拿一个结果”的场景。特征是进程即作用域，无需会话管理，退出码与标准输出可直接被流水线消费，天然适合无人值守。

# 示意：非交互式单次任务（通用形态，非特定工具命令）
agent-run --task "修复失败的单元测试" \
          --workspace ./ci-checkout \
          --sandbox workspace-write \
          --network off \
          --approval never

第二层：程序化 SDK。 面向把智能体当作一个库来用的场景。宿主进程持有会话对象，可自行决定工具集、权限策略、模型端点与流式回调，适合嵌入既有后端服务或构建多智能体协作系统。

# 示意性伪代码：SDK 形态的程序化编排
client = AgentClient(model_endpoint="https://<your-compatible-endpoint>/v1")
with client.session(cwd="/srv/project",
                    tools=my_business_tools,      # 业务方自有工具
                    approval_policy="on-request") as s:
    for event in s.stream("重构登录模块并补齐测试"):
        if event.type == "approval.required":
            if not policy_engine.allow(event.tool, event.args):
                event.deny("命中高危命令规则")
            else:
                event.approve()
        elif event.type == "message.delta":
            ui.append(event.text)
        elif event.type == "tool.result":
            audit_log.write(event)                 # 全量审计落盘

第三层：持久会话服务（长连接会话协议）。 面向产品化嵌入。宿主通过长连接或事件流与会话服务通信，服务端维护会话与历史，客户端可随时 attach、中断、恢复、并行推进多个任务。价值在于：UI 可以重连而不丢上下文；多个终端（终端、插件、Web）可以共享同一会话；权限与审计可以集中治理。

会话事件流（示意，统一事件模型）
  {"seq": 12,  "type": "message.delta",      "text": "正在定位失败用例…"}
  {"seq": 13,  "type": "tool.call.started",  "tool": "read_file", "args": {...}}
  {"seq": 14,  "type": "tool.call.finished", "tool": "read_file", "ok": true, "bytes": 4210}
  {"seq": 15,  "type": "approval.required",   "tool": "exec_command", "args": {"cmd": "rm -rf …"}}
  {"seq": 16,  "type": "session.status",     "status": "waiting_for_user"}

三层的取舍很清楚：层级越高，宿主承担的状态管理越少，但对服务的运维与协议稳定性要求越高；层级越低，控制力越强，但需要自己补齐会话、审批与可观测性。实际产品常同时使用三层——流水线用第一层，后端服务用第二层，交互式界面用第三层。

五、工作原理：一次任务的完整生命周期

把三层接口统一到一次执行来看，流程大致如下：

1. 初始化：加载工作区快照、AGENTS 类约定文件或项目规范、可用工具清单，建立权限策略与预算（最大轮次、最大 token、超时时间）。
2. 上下文组装：注入系统提示、项目结构摘要、近期对话与必要文件内容。此处决定首轮 token 成本。
3. 推理与决策：模型输出”自然语言回复 + 若干工具调用”的混合结构。
4. 工具执行：参数校验 → 权限判定（是否需人工批准）→ 在沙箱内执行 → 结果截断与归一化 → 回填上下文。
5. 循环与收敛：若模型认为任务完成则输出总结并结束；否则回到第 3 步。同时持续监控轮次、成本、异常循环（如同一命令反复失败）。
6. 落盘与可观测：事件全量持久化，支持回放、分叉（从某一步重跑）与后续审计。

其中”结果截断与归一化”是被低估的环节。一条命令输出数万行日志若原样回填，会在两三轮内耗尽窗口，因此主流实现会对工具返回值做长度上限、关键片段保留与结构化摘要。

六、上下文管理：harness 质量的直接证据

同一模型、不同 harness 策略，效果差距可以非常大。公开的第三方评测资料给出了一个具有代表性的例子：在某抽象推理类评测基准上，引入保留关键推理要点（retained reasoning）与上下文压缩（context compaction）两项策略后，同一模型的得分从约 13% 提升至约 38%，同时输出 token 消耗降至原来的约六分之一，整体效果差距达到约 3 倍。

这两个机制为什么关键，值得单独说明：

• 保留推理要点：多轮任务中，早期推导的结论往往在后期仍然必要，但原始推理文本冗长。将”结论 + 关键假设 + 已排除方案”提炼保留、丢弃过程性文字，可以在压缩体积的同时不损失决策质量。
• 上下文压缩：接近窗口上限时，把较早的轮次折叠为结构化摘要（已完成事项、修改文件清单、失败原因、待办），保留最近若干轮原文。压缩必须是有损但可回溯的——摘要中要保留可回查的锚点（文件路径、命令、事件序号），以便需要时从持久化历史中取回细节。

这也解释了为什么”评测榜单分数”与”产品实际体验”常有落差：榜单通常固定上下文与工具，而产品体验由 harness 的策略决定。

七、典型应用场景

• 研发效率工具：CLI 与 IDE 插件共享同一内核，实现代码解释、跨文件重构、测试补齐、缺陷定位。
• CI/CD 中的无人值守代理任务：依赖升级、批量格式化、失败用例自动修复、文档同步。要求非交互、确定退出码、幂等、可回滚。
• 企业业务系统内嵌：把智能体作为业务系统的一个能力模块，工具由业务方提供（查询订单、调用内部服务），业务规则与数据不出自有边界。计算与存储可依托容器平台、对象存储、消息队列、日志与监控告警等通用云产品能力承载。
• SRE 与运维排障：读取日志与监控指标、提出假设、执行只读诊断命令、生成变更建议并等待人工批准。
• 数据与文档处理：批量 ETL 校验、报表生成、知识库整理，通常配合第一层非交互调用。
• 模型与策略评测：由于接口统一，可对不同模型端点、不同上下文策略做 A/B 回归，把”harness 变更”纳入与”模型变更”同等的评测流程。
• 多智能体协作：以 SDK 形态编排多个专职代理（规划、实现、评审），由主代理分派任务并汇总。

八、与容易混淆的概念的区别

• 与模型 API / 推理服务：API 提供无状态的单次生成能力；harness 提供有状态的执行闭环。二者是上下游关系，不是替代关系。绝大多数 harness 都设计为可切换后端，接入任意兼容接口协议的模型端点（自建网关、公有云模型服务或第三方兼容服务），从而避免模型锁定。
• 与 Agent 框架/SDK：范围重叠但重心不同。通用 Agent 框架通常强调图编排、提示模板、检索与记忆组件，偏”如何构造智能”；harness 强调执行、隔离、审批与持久化，偏”如何安全地跑起来并产品化”。
• 与工作流编排引擎：工作流引擎编排的是预先定义的确定性步骤（DAG、重试、补偿），控制流由人写死；harness 的控制流由模型在运行时决定，引擎只提供护栏（预算、超时、权限）。二者可以组合：harness 作为工作流中的一个”智能体任务节点”。
• 与代码助手补全类工具：补全是在编辑器内做局部预测，交互周期短、无长程状态；harness 面向的是跨文件、多轮次、有副作用的任务。
• 与检索增强生成（RAG）：RAG 是一种上下文获取手段，通常作为 harness 内部的一个工具或检索模块存在。

九、接入与选型注意事项

1. 安全是首要约束。默认最小权限：工作区外只读或禁止、默认断网、禁止提权、危险命令黑名单与二次确认。切勿以 root 或高权限账号运行沙箱。
2. 密钥与凭证隔离。凭证不应进入模型上下文，工具侧应做代理注入；日志与事件流需脱敏，避免密钥、令牌随事件持久化。
3. 幂等与可回滚。无人值守场景下，任何写操作都应可重入或可回滚（分支提交、快照、变更清单），避免半成品状态。
4. 预算与熔断。必须设置最大轮次、最大 token、最大时长与连续失败阈值；对重复失败命令做循环检测，否则单任务成本可能失控。
5. 上下文策略要显式配置并度量。把压缩阈值、保留策略、工具返回截断长度当作可配置项，并以”任务成功率 / 平均轮次 / 平均 token”三项指标持续观测。
6. 事件协议的稳定性。若采用长连接会话服务，需要处理重连补洞（按序号补齐）、多端并发、会话过期与版本兼容。协议演进应向后兼容。
7. 可观测性对齐既有体系。事件应能落到统一日志与监控告警平台，支持按会话、任务、模型版本维度聚合，便于定位”是模型退化还是策略退化”。
8. 评测先行。在替换 harness 或调整上下文策略前，建立内部固定任务集的回归评测；只看个别案例容易产生误判。
9. 合规与数据边界。明确代码与数据是否会离开自有环境、留存多久、用于何处；对敏感行业优先选择可私有化部署、可自带模型端点的方案。
10. 人才与运维成本。harness 引入的是一套长期运行的分布式组件（会话存储、沙箱池、网关），需评估其在容器平台上的容量规划与故障恢复方案，而非仅评估接入代码量。

十、总结

回到定义本身：Agent Harness 是介于模型与产品之间的执行运行时，负责把”会说”变成”会做”，并在做的过程中保证状态连续、权限可控、过程可观测、成本可预算。

它的核心价值可归纳为三点：一是解耦——模型可替换、业务上下文与工具留在产品侧，避免能力被单点锁定；二是可控——沙箱、审批与预算把生成式系统的不确定副作用约束在工程可接受的范围内；三是可产品化——统一的会话协议让同一内核同时支撑 CLI、插件与 Web 端，避免为每个前端重复实现智能体逻辑。

适用边界同样清晰：如果你的需求是单次文本生成或短链路结构化输出，直接使用模型 API 更简单；当你需要多步工具调用、长时任务、副作用操作、多端会话共享与审计留痕时，harness 才是必要的架构选择。而在实践中，最需要投入的不是接入接口的调用方式，而是上下文管理策略与权限模型的持续调优——这两处，恰恰是同一模型下效果差距数倍的根源。