智能代理 Harness 三层接入与服务协议解析

一、智能代理 Harness 是什么

智能代理 Harness 可以理解为“驱动代理稳定运行的执行框架”。它位于基础模型与最终应用之间，负责把一次模型推理转化为可控制、可追踪、可持续运行的任务流程。

模型本身通常只负责理解输入并生成下一步行动建议，而 Harness 负责真正执行这些行动，包括：

• 保存和恢复对话状态；
• 管理上下文窗口与历史消息；
• 调度文件读写、命令执行、网络访问等工具；
• 为任务提供隔离的沙箱环境；
• 处理模型输出与工具结果之间的循环；
• 向调用方提供流式事件；
• 在高风险操作前暂停并等待人工审批；
• 记录任务日志、错误信息和执行轨迹；
• 在长任务中进行上下文压缩与状态整理。

因此，Harness 不是简单的接口封装，也不是一个单独的模型调用库。它更接近代理系统的运行时，负责解决“模型应该做什么”之外的另一个问题：模型提出行动后，系统如何安全、可靠、可恢复地把行动完成。

从应用角度看，业务系统拥有产品上下文、权限规则、用户界面和业务工具，Harness 则提供代理循环。代理循环通常包含以下过程：

接收任务
  ↓
构建上下文
  ↓
请求模型生成下一步行动
  ↓
判断是直接回答还是调用工具
  ↓
执行工具并收集结果
  ↓
将结果写回上下文
  ↓
继续推理或结束任务

这个循环可能只运行几秒，也可能持续数小时。Harness 的价值就在于，它能够用统一的机制管理这两类任务。

二、为什么需要 Harness

如果直接在业务代码中调用模型接口，开发者往往需要自行实现大量基础能力。例如，需要手动拼接历史消息、解析工具调用、维护任务状态、处理超时重试，还要考虑用户中途取消任务后如何恢复。

当任务从“回答问题”扩展到“修改代码、执行测试、读取日志、生成报告”时，直接调用模型会迅速出现几个问题。

1. 状态难以维护

代理任务不是一次请求就能完成的。模型可能需要多轮观察、判断和行动。如果上下文仅保存在内存中，进程重启后任务就会丢失；如果完全由业务系统保存，又需要自行定义消息格式、事件顺序和恢复逻辑。

Harness 通常会把会话、消息、工具结果和任务状态统一管理，使任务具备可恢复性。

2. 工具调用缺少边界

代理需要操作文件、执行程序或访问外部服务，但这些操作不能直接拥有无限权限。Harness 可以将工具调用放入受限环境中，并根据策略限制目录、网络、资源额度和执行时长。

3. 长任务容易失控

上下文不断增长会导致成本上升、响应变慢，甚至超出模型上下文限制。Harness 可以通过摘要、压缩、保留关键推理结果和清理低价值历史信息，维持长任务的连续性。

4. 人机协同难以统一

某些操作可以自动完成，某些操作则需要审批。例如删除文件、修改生产配置、访问敏感数据等。Harness 可以在执行前生成审批事件，等待用户确认后再继续，而不是把审批逻辑散落在每个工具实现中。

三、三层接入接口的含义

这类 Harness 通常提供三种层次不同的接入方式。三者并不是互相替代，而是分别面向脚本自动化、应用编排和产品级集成。

1. 轻量非交互调用

第一层是非交互式调用。调用方提交一个明确任务，Harness 在后台运行，最终返回文本结果、结构化结果或执行状态。

这种方式适合：

• 持续集成中的代码检查；
• 自动生成变更说明；
• 批量处理文档和数据；
• 定时分析日志；
• 自动执行测试并汇总结果；
• 一次性运维辅助任务。

它的特点是接入成本低、流程简单。调用方通常不需要管理复杂的会话界面，只需要关心任务输入、最终输出和退出状态。

但它也有明显边界：如果任务需要实时展示中间过程、人工审批、动态追加指令或长期恢复，就不应只使用这一层。

2. 程序化编排接口

第二层是软件开发工具包。它允许业务代码以编程方式创建会话、注册工具、监听事件、设置权限策略，并根据任务状态决定下一步动作。

程序化编排适合构建：

• 自动化开发助手；
• 代码审查工作流；
• 企业知识处理流程；
• 多步骤数据分析任务；
• 带有自定义工具的内部 Agent；
• 需要与身份系统、任务系统和审计系统结合的业务应用。

与轻量调用相比，程序化编排拥有更强的控制力。业务代码可以在每轮事件到达时进行判断，例如：

收到代理输出
  ├─ 如果是普通文本：展示给用户
  ├─ 如果是工具请求：检查权限后执行
  ├─ 如果是审批请求：通知相关人员
  ├─ 如果是错误事件：重试或终止
  └─ 如果是完成事件：保存结果并关闭会话

这种模式适合需要“代理能力，但不能把控制权完全交给代理”的场景。

3. 持久会话服务接口

第三层是持久会话驱动的服务接口，也就是常说的 app-server 形态。它通过长期运行的服务进程，为多个客户端提供会话创建、消息发送、事件订阅、工具执行和状态恢复能力。

这一层通常面向：

• 图形化代理产品；
• 编辑器插件；
• 企业内部工作台；
• 多用户并发使用的 Agent 平台；
• 需要断线重连和后台运行的长任务；
• 需要统一权限、审计和资源治理的生产系统。

持久会话的关键不是“连接一直不关闭”，而是会话状态可以独立于某个前端进程存在。用户关闭页面后，任务仍可继续；用户重新进入后，可以订阅已有会话的最新状态。

四、App-Server 协议通常解决什么问题

App-Server 协议本质上是一套面向代理运行时的通信约定。它需要描述的不只是请求和响应，还包括任务生命周期中的各种事件。

典型协议对象可以抽象为以下几类：

1. 会话对象
   表示一段持续存在的代理任务，通常包含会话标识、创建时间、当前状态和关联配置。

2. 消息对象
   表示用户输入、代理回复、系统提示和工具结果等内容。

3. 事件对象
   表示任务运行过程中的增量变化，例如文本片段、工具开始、工具结束、审批请求、错误和完成通知。

4. 工具对象
   描述代理可以调用的能力，包括输入结构、权限要求和执行结果。

5. 审批对象
   描述需要人工确认的动作，以及批准、拒绝或超时等后续状态。

一个成熟的服务协议还需要考虑以下问题：

• 事件是否有顺序编号；
• 客户端断线后如何补发事件；
• 同一请求是否可能重复提交；
• 任务取消后能否安全停止；
• 服务重启后如何恢复会话；
• 错误是针对单个工具，还是针对整个任务；
• 多个客户端同时订阅时如何保持一致。

因此，App-Server 并不只是把命令行功能搬到网络接口中。它需要把代理执行过程抽象为可观察、可恢复、可并发管理的服务。

五、Harness 的核心工作机制

一个完整的代理执行过程，通常可以拆分为六个阶段。

1. 初始化运行环境

系统读取任务配置、用户身份、权限策略、模型连接配置和工具清单，并创建隔离的执行环境。

2. 构建初始上下文

Harness 将用户任务、系统规则、历史会话、项目文件摘要和可用工具说明组合成模型可理解的上下文。

3. 执行代理循环

模型输出下一步行动后，Harness 判断该行动属于文本回复、工具调用、等待审批还是任务结束。

4. 调度工具并回收结果

对于工具调用，Harness 负责参数校验、权限检查、资源限制、实际执行和结果标准化。工具结果不会直接绕过控制层写入模型，而是经过统一封装后重新进入上下文。

5. 管理上下文和记忆

当上下文变长时，系统会压缩历史内容，保留任务目标、关键结论、未完成事项和重要工具结果。对于长期任务，还可能将阶段性状态持久化到外部存储中。

6. 输出事件并完成收尾

任务结束时，Harness 返回最终答案、执行状态、工具记录和错误信息。生产系统还应同步保存审计日志、资源消耗和关键决策依据。

六、与其他概念的区别

Harness 与模型的区别

模型负责生成预测和行动建议，Harness 负责执行、约束和持久化。没有 Harness，模型通常无法独立完成复杂工具任务；没有模型，Harness 也只能成为普通的工作流引擎。

Harness 与 SDK 的区别

SDK 是开发者接入 Harness 的编程接口，而 Harness 是实际运行代理循环的底层系统。SDK 更关注“如何调用”，Harness 更关注“如何运行”。

Harness 与工作流引擎的区别

工作流引擎的步骤通常由开发者预先定义，分支条件相对固定；Harness 的步骤可以由模型根据上下文动态决定。不过，在生产环境中二者经常结合使用：工作流负责确定边界，Harness 负责处理边界内的动态任务。

Harness 与普通接口网关的区别

接口网关主要负责路由、认证、限流和协议转换，Harness 则要管理会话、工具、上下文、审批和代理循环。前者解决请求治理，后者解决智能任务执行。

七、典型应用场景

在持续集成环境中，Harness 可以自动读取代码变更、执行测试、分析失败日志并生成修复建议。由于任务通常是非交互的，轻量调用接口即可满足需求。

在企业应用中，程序化编排接口可以连接知识库、工单系统、数据库和内部工具，并根据权限控制代理可以执行的动作。

在面向终端用户的产品中，持久会话服务更适合处理实时流式输出、断线恢复、多端同步和人工审批。

在资源密集型任务中，还应结合容器平台、任务队列、对象存储、日志服务和监控告警系统，形成完整的运行基础设施。

八、接入和部署时的注意事项

首先，要明确代理权限边界。默认情况下不应允许代理访问所有文件、网络和系统资源，应采用最小权限原则。

其次，要区分“模型输出”和“已执行动作”。文本内容可以被展示，但工具调用必须经过校验、审计和策略判断。

再次，要设计可靠的取消、超时和重试机制。对于具有副作用的操作，不能简单重复执行，否则可能造成重复写入或状态破坏。

还要关注上下文成本。应通过摘要、分阶段任务和结构化状态降低无效历史信息的累积。

最后，需要建立完整的可观测性，包括会话状态、事件延迟、工具耗时、失败原因、审批记录和资源使用情况。只有能够还原任务全过程，才能在出现错误时定位问题。

九、总结

智能代理 Harness 的核心定义，是一套位于模型与应用之间的代理运行时。它通过统一管理上下文、工具、沙箱、审批、事件和持久会话，把一次模型调用扩展为可执行、可恢复、可治理的智能任务。

三层接入方式分别适合不同复杂度的需求：轻量非交互调用适合脚本和自动化流水线，程序化编排适合业务系统集成，持久会话服务适合构建完整的 Agent 产品。理解这三层接口及其边界，有助于开发者避免把简单任务过度工程化，也能避免在复杂生产场景中只依赖一次性模型调用。

从长期建设角度看，Harness 的价值不在于替代模型，而在于为模型能力提供稳定的执行边界。它决定了代理能做什么、如何被观察、何时需要审批，以及任务能否在真实业务环境中安全持续地运行。