智能体执行框架开源:三层接入与app-server协议解析

一、概念定义:什么是智能体执行框架(Harness)

智能体执行框架(Agent Harness)是驱动智能体(Agent)实际运行的那一层”外壳”基础设施。 它不直接提供智能,也不定义业务规则,而是把模型的能力”包裹”起来,以可控、可审批、可持久化的方式对外输出。

用一句更凝练的话概括:模型负责”想”,Harness 负责”想完之后怎么落地、怎么约束、怎么被看见”。

这个定义包含三层含义,建议分开理解:

• 技术视角:Harness 是一个长驻的执行引擎。它维护一轮又一轮的对话上下文,决定何时把哪些工具暴露给模型,在受控环境里执行模型请求的操作,把执行结果回灌给模型,并把整个过程以事件流的形式推送给上层界面。
• 产品视角:Harness 把”一个会推理的模型”变成”一个能完成任务的代理”。同一个 Harness 进程可以同时被桌面应用、命令行工具和编辑器插件使用,从而保证三种交互形态的行为完全一致,不会出现”在命令行里能做的事,在编辑器插件里做不了”的分裂。
• 治理视角:Harness 是权限、审计与安全的落点。工具调用是否允许、文件写入范围在哪里、网络是否可达、哪些动作必须先获得人工确认,这些策略都由 Harness 集中裁决,而不是散落在每个前端里。

二、为什么需要它:直接调用模型接口缺了什么

如果只是把请求发给模型接口、再把返回内容显示出来,会立刻遇到几个结构性问题,这正是 Harness 出现的原因。

1. 模型是无状态的,任务是有状态的。 一次真实任务往往跨越几十个来回,涉及中间产物、已读过的文件、已执行过的命令。谁保存这些状态、如何裁剪到模型上下文窗口内、失败时如何回滚,这些都必须由外层框架承担。
2. 模型只会输出文本,不会改变世界。 模型能表达”我打算读取这个文件、执行这条命令”,但真正落地需要执行器、权限校验和错误处理。这一层能力缺失,智能体就只是一个会描述动作的对话框。
3. 执行必须有边界。 允许模型执行操作,等于把一部分系统控制权交出去。没有沙箱与策略引擎,任何一次误判都可能造成数据破坏。Harness 把”能力授予”变成显式配置,而不是隐式默认。
4. 过程需要可见、可打断、可回放。 长任务需要流式输出、进度反馈、随时中断、事后复盘。这些属于运行时的横切能力,不适合由每个应用各自实现一遍。
5. 多端需要一致性。 当同一套能力要出现在三四种客户端上时,只有把 agent loop 下沉到共享进程,才能避免行为漂移和重复实现。

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

一个成熟的执行框架通常可以拆成以下部分,它们共同构成 Harness 的最小完整形态。

• 会话与上下文管理:负责消息历史、上下文窗口预算、压缩与摘要策略,以及会话的持久化、恢复与分支(fork)。它决定了”记忆”的边界。
• 工具注册与描述:每个工具都需要一份机器可读的说明(名称、用途、参数结构、返回形态)以及权限声明。描述质量直接决定模型调用的准确率,这是 Harness 中最容易被低估的工程细节。
• 执行沙箱:把模型的意图放入受限环境。典型隔离维度包括文件系统可见范围、进程与命令白名单、网络出口策略、CPU/内存/时长配额、临时目录生命周期。沙箱既可以是轻量的受限目录,也可以是容器化的独立实例。
• 审批与策略引擎:对高风险动作(写生产配置、执行删除、发起外部请求)触发人工确认或策略校验,并输出可追溯的审批记录。它需要支持”整轮自动放行”与”逐次确认”两档粒度。
• 事件流与流式输出:把内部状态变化翻译成有序事件,供界面实时渲染增量文本、工具调用进度、状态切换和错误提示。
• 审计与回放:记录完整的事件日志,使一次任务可以被复盘、导出、重放,也便于定位”模型为什么做了这个决定”。

四、工作原理:一轮 agent loop 的链路

Harness 的运行可以抽象为一个循环,伪代码如下(仅示意,不涉及具体实现细节):

session = harness.create_session(tools=[read_file, write_file, run_command],
                                 sandbox=restricted_workspace,
                                 approval_policy="ask_on_write")
stream.append(session, """
prompt = "找出项目中所有未处理的异常分支,并给出修复建议"
history  = []
loop:
    resp = model.call(history, tools)
    if resp.is_final:
        emit(final_answer); break
    for call in resp.tool_calls:
        decision = policy.check(call)          # 是否放行 / 是否需审批
        if decision == NEED_APPROVAL:
            emit(approval_request(call))
            wait_for(human_decision)           # 可拒绝、可修改参数
        result = sandbox.execute(call, timeout, quotas)
        emit(tool_result(result))
        history.append(call, result)           # 结果回灌,进入下一轮
""")

链路上有几个关键点值得强调:

• 模型输出的是意图,不是效果。 任何工具调用在真正执行前都必须经过策略检查。
• 执行结果以结构化形式回灌。 截断、错误码、超时都需要被明确表达,否则模型会基于残缺信息继续推理。
• 审批是同步阻塞点。 因此 Harness 必须能在等待期间保持会话状态,并允许用户中断或修改待执行参数。
• 每一步都产生事件。 前端拿到的是事件序列而非最终文本,这是流式体验的技术前提。

五、三层接入形态与 app-server 协议

5.1 三层接入:同一底座,不同交互

所谓三层接入,指的是同一套 Harness 后端被三类客户端复用,差异只体现在交互形态上:

• 桌面应用层:面向完整的任务管理体验,通常提供会话列表、差异审阅、文件改动对比、任务编排等富交互能力。
• 命令行层:面向脚本化、批处理与自动化流水线,输入输出以文本协议为主,便于管道组合与无人工值守运行。
• 编辑器插件层:面向”就在代码旁边干活”的场景,强调上下文注入(当前文件、光标位置、仓库结构)与轻量确认。

三层的价值不在于数量,而在于行为一致性:工具集、权限模型、沙箱策略、审批规则都在服务端统一定义,客户端只负责呈现与交互。

5.2 app-server 协议:职责切分是关键

app-server 是这套架构的核心接口层。官方对其价值的描述可以概括为一句话:应用侧持有产品上下文、业务规则与工具集,app-server 负责提供 agent loop。

这句话精确定义了职责边界:

职责	归属方
用户身份、租户与权限数据	应用侧
业务领域规则、企业知识、专有工具	应用侧
交互形态、界面渲染、通知	应用侧
上下文管理与压缩	app-server
模型调用、工具调度、循环控制	app-server
沙箱执行、资源配额	app-server
审批流程与策略执行	app-server
会话持久化与事件回放	app-server

协议层面的几个通用设计要点(业界普遍做法,不指向特定实现):

• 双向长连接 + 事件推送:一次客户端请求会派生大量服务端事件,单纯请求-响应模型无法承载。
• 会话为一等公民:客户端通过会话标识复用历史状态,支持恢复、分支与并行多会话。
• 审批走独立回环:审批请求作为事件下发,用户决策作为独立请求回传,二者通过标识符关联。
• 能力协商:客户端可查询服务端当前可用的工具与模型,从而按端能力裁剪界面。

示意性事件序列(字段为描述性示例,非真实参数):

→ session.start  { workspace, tools, policy }
← session.ready  { capabilities, models }
→ turn.send      { text }
← turn.delta     { chunk }
← tool.request   { id, name, args }        // 需要执行工具
← approval.ask   { id, summary, args }     // 需人工确认
→ approval.reply { id, decision }
← tool.result    { id, output, status }
← turn.done      { usage }

六、典型应用场景

• 代码与工程类任务:仓库理解、缺陷定位、测试补充、依赖升级、变更审阅。这是 Harness 形态最先成熟的领域,因为它高度依赖工具调用与差异审阅。
• 运维与故障处置:日志检索、指标查询、变更执行。此类场景对审批与沙箱要求最高,通常配合只读模式先行。
• 企业内部流程自动化:把审批流、报表生成、数据核对等业务工具注册为 Harness 工具,让智能体在既定规则内操作。
• 多智能体编排:一个负责规划的智能体调用多个专职子智能体,由 Harness 统一约束它们的上下文、并发与失败重试。
• 无人值守流水线:命令行接入形态最适合接入持续集成体系,实现夜间批量任务与回归检查。

七、与相关概念的区别

• 与模型接口:模型接口提供无状态推理能力;Harness 提供有状态的执行环境。前者是”大脑”,后者是”身体与安全带”。
• 与 Agent SDK:SDK 通常是库形态,由开发者自己搭循环;Harness 是可直接运行的完整框架,自带沙箱、审批、持久化与协议层,开发者更多是配置而非实现。
• 与 API 网关:网关解决的是流量、鉴权、限流与路由;Harness 解决的是执行语义与安全边界。二者可以叠加,但不可互相替代。
• 与工作流引擎:工作流引擎执行的是预先编排好的确定步骤;Harness 执行的是由模型在运行时动态决定的步骤序列。企业实践中常见的组合是:外层用工作流保证合规节点,内层用 Harness 处理开放性子任务。
• 与单纯的对话式助手:助手的产出是文本;Harness 承载的代理产出是被执行的动作,因此它必须承担副作用管理责任。

业界同期还出现了多个思路相近的开源框架,它们共同体现了一种设计倾向:一切能力都通过 Harness 暴露——模型不直接面向用户,而是被 Harness 封装成可控、可审批、可持久化的服务。这条思路正在成为该类项目的共识性架构范式。

八、使用注意事项

• 默认最小权限:工具集按需注册,写操作默认关闭;沙箱的工作目录、网络出口、执行时长都应显式设定,而不是依赖运行时自行判断。
• 警惕间接提示注入:被智能体读取的网页、日志、代码注释都可能包含恶意指令。应在 Harness 层做来源标注与信任分级,并对高危工具调用坚持审批。
• 凭据不入上下文:密钥通过运行时注入或短时令牌提供,避免出现在对话历史与日志中,否则会被上下文压缩与回放机制带出。
• 协议版本治理:三层接入意味着多客户端长期共存,协议需具备向后兼容与能力协商机制,防止旧客户端遇到新事件类型时崩溃。
• 性能关注首字节延迟:流式体验的关键指标是首个增量事件的到达时间,其次是工具调用的往返开销与并发会话数,这些比整体任务耗时更影响主观体验。
• 可观测性要提前设计:建议从一开始就采集事件级日志、工具调用成功率、审批拦截率、上下文压缩次数等指标。这类框架上线后最常见的排查难题是”为什么某一步没被触发”,只有完整事件流能回答。
• 成本与配额:上下文压缩策略与循环最大轮数直接决定单次任务开销,应设置硬性上限,避免失控循环产生高额消耗。
• 部署形态:若选择云端托管运行,可结合容器平台做沙箱隔离与弹性扩缩、对象存储保存会话产物与日志、日志服务与监控告警做事件采集与异常告警、身份认证与访问控制做客户端鉴权。百度智能云等主流云平台均提供上述通用能力类别,可按需组合;涉及具体规格与计费,请以对应平台的官方文档为准。

九、总结

智能体执行框架的定义可以回到一句话:它是把模型能力转化为可执行、可约束、可观测行为的中间层基础设施。

它的价值不在于增加智能,而在于解决”如何让一个概率性的推理系统安全地作用于确定性的真实环境”这一工程难题。判断一个项目是否真正具备 Harness 形态,可以看三点:是否统一管理会话状态与上下文、是否强制经过沙箱与审批、是否把执行过程抽象为可回放的事件流。

对于正在做技术选型的团队,合理的切入方式是:先用命令行形态验证工具集与沙箱策略,再把经过验证的 agent loop 通过 app-server 接入自家产品界面,最后逐步扩展接入端。理解了这层职责切分,无论具体开源项目如何演进,都能快速判断它是否满足自己的安全与集成要求。