Agent Harness 三层接入接口对比与选型
作者:4042026.11.16 10:30浏览量:0简介:本文对比 AI Agent 执行框架的三类典型接入方式——一次性非交互调用、SDK 程序化编排、持久化会话服务驱动。围绕状态归属、并发模型、审批与沙箱边界、上下文管理、可观测性与迁移成本逐层拆解差异,帮助开发者在 CI 流水线、产品内嵌、多租户平台等场景中做出条件化的选型判断。
agent-">一、对比背景:接入层正在成为 Agent 效果的分水岭
2026 年 8 月中旬,某主流开源 Agent 执行框架宣布完整开源:此前只开放命令行前端,而真正驱动 Agent 循环的底层内核与会话服务层属于闭源实现。此次变化的关键是接入接口的完整开放,而不再只是”给了一个可执行的命令行工具”。
这个变化的意义在于:过去团队只能在”直接调模型 API 自己写循环”和”调用某个现成工具替代人工”之间二选一;现在多出了一个中间层——复用一套成熟的 harness(执行框架),但用自己的产品逻辑去驱动它。
理解这一层的价值,需要先接受一个判断:决定 Agent 表现上限的往往不是模型本身,而是 harness 策略。同一模型在”保留推理上下文 + 上下文压缩”策略下的评测成绩,可以是朴素”全量塞入历史”策略的数倍,同时输出 token 消耗还能下降数倍。差异来自 harness 对上下文窗口的调度、工具调用的编排、失败重试与审批流的设计,而不是模型换了。
本文要对比的,就是这套 harness 对外暴露的三种接入层次,以及它们各自适配的工程约束。
二、对比对象界定
对象 A:一次性非交互式调用(脚本级接入)
以单条命令的方式提交一个任务,进程执行完毕后退出,不保留会话。典型形态是”传入提示词与工作目录,输出结果与退出码”。
对象 B:SDK 程序化编排(进程内接入)
以代码库依赖的方式引入,宿主程序在自己的进程内创建会话、消费事件流、拦截工具调用、插入审批逻辑。宿主掌握产品上下文与业务规则。
对象 C:持久化会话服务驱动(服务端接入)
以独立服务进程的形式运行,通过带状态的会话协议对外提供服务,客户端可多轮对话、可断线重连、可多客户端共享同一会话。官方对其职责的概括是:”你的应用掌握产品上下文、业务规则与工具,服务端提供 Agent 循环。”
对象 D(横向对比项):完全自建 Agent 循环
不引入 harness,自己实现对话状态机、工具注册、沙箱与审批。本文在选型部分将其作为参照系。
四者的关系不是替代,而是同一内核之上的三种暴露粒度。这一点是后续所有差异的根因。
三、相同点:共享同一套语义内核
无论选择哪一层,以下能力来自同一实现,因此行为一致:
- 工具调用协议:函数定义、参数校验、调用结果回传格式一致;
- 沙箱执行语义:命令执行的隔离级别、文件系统读写策略、网络访问策略同源;
- 人工审批模型:高风险操作触发审批请求、审批通过后才执行的流程一致;
- 流式输出格式:文本增量、工具调用事件、推理状态的呈现方式一致;
- 上下文管理机制:历史裁剪、上下文压缩、推理内容保留策略由内核统一负责,而不是由接入层各自实现。
这意味着从 A 迁移到 B 或 C,通常不需要重写 Agent 行为逻辑,只需要改变驱动方式。这也是三层接口能够共存的前提。
四、核心差异分析
4.1 状态归属与生命周期
A 是无状态的:状态生命周期等于进程生命周期,任务结束即销毁。好处是心智负担最低,坏处是无法做多轮交互——用户追问一句,就得把全部上下文重新提交一次。
B 的状态归宿主进程所有。会话对象活在宿主内存里,宿主可以选择持有、序列化或丢弃。灵活度最高,但状态持久化责任转移给了开发者:进程重启后如何恢复会话,需要自己设计。
C 的状态归服务端所有。会话在服务端持续存在,客户端只是连接方。这带来两个能力:客户端断线后可按事件序号重放补齐;多个客户端(例如 Web 前端与移动端)可挂载同一会话协作。
4.2 接入改造量与编程模型
A 的改造量最小,本质是”进程边界调用”,任何语言、任何构建系统都能接入,无需引入运行时依赖。代价是失去了细粒度控制:无法在工具执行前插入业务校验,无法逐 token 渲染。
B 要求宿主程序与 harness 的运行时环境绑定(通常需要同一语言的运行时,或至少通过进程内绑定通信),依赖体积和构建复杂度上升。换来的是完全的流程控制权:可以拦截任意工具调用、注入业务侧权限判断、在任意节点插入自己的状态机。
C 的改造量介于两者之间,且改造集中在网络协议适配层。开发者需要实现会话建立、事件消费、断线重连、幂等重放这套客户端逻辑,但不需要理解内核内部。
4.3 并发模型与弹性伸缩
这是生产环境最容易踩坑的差异。
- A 的并发单位是进程。扩容靠调度器拉起更多进程,隔离性最好,但每个进程都要加载完整运行时,冷启动成本高,高密度并发时资源浪费明显。
- B 的并发单位是宿主进程内的会话。资源占用低,但所有会话共享宿主的内存与事件循环,单个任务失控(例如工具陷入死循环)会影响同进程内的其他会话,需要自行设计隔离与超时熔断。
- C 的并发单位是服务端的会话,天然支持集中式配额、排队、限流与优先级调度。扩容靠增加服务端实例,配合无状态网关做会话路由(通常需要会话亲和或共享会话存储)。
4.4 流式输出与前端交互体验
A 只能提供最终结果,或把完整事件流一次性写入文件,不适合直接面向终端用户。
B 和 C 都能提供增量事件流。差异在于传输链路:B 是进程内回调,延迟最低但无法跨网络;C 通过长连接传输,需要处理心跳、重连、事件序号对齐与背压。做 Web 或移动端产品时,C 的模型与前端交互天然匹配;做本地桌面工具时,B 的零网络开销更合适。
4.5 审批、权限与安全边界
三者的沙箱能力同源,但审批的落点不同:
- A 通常只能通过静态配置或环境变量声明策略(例如”只读””禁止网络”),无法在运行时按上下文动态决策;
- B 可以在代码里对每个工具调用做实时判断,例如”仅当改动路径不在受保护目录内才自动放行”;
- C 把审批变成一个可被远端 UI 响应的协议消息,这正是”人类在环”产品形态所需要的——审批按钮在 Web 端,执行发生在服务端。
安全上需要注意的共同点:Agent 沙箱隔离的是工具执行环境,不隔离凭据。无论哪层,模型端点凭据、代码仓库凭据都应通过短期令牌或代理服务下发,避免直接暴露给 Agent 进程。
4.6 会话持久化与故障恢复
A 无恢复可言,失败即重跑。
B 需要自己实现检查点:把会话状态序列化到外部存储,重启后反序列化恢复。建议只持久化必要字段(消息序列、工具调用记录、工作目录标识),而不是整个运行时快照。
C 的服务端通常提供会话导出与事件重放能力,故障恢复语义更明确,但代价是多了一个必须做高可用的有状态组件,会话存储本身成为容量与备份规划的对象。
4.7 上下文管理与 token 成本
这是三层共享、但使用方式差异被放大的部分。内核提供的上下文压缩与推理保留策略是否生效,取决于调用方是否维持了正确的会话连续性:
- A 每次全新会话,等于放弃了跨轮次的上下文复用,长任务的 token 成本会显著高于 B、C;
- B、C 维持会话,可以复用已建立的上下文,但长会话本身会持续膨胀,必须配合摘要压缩与工具输出截断,否则单轮成本会随对话轮次线性上升。
因此成本优化的重点不在换模型,而在于:是否会话复用 + 是否启用上下文压缩 + 是否截断冗余工具输出。
4.8 可观测性与运维
A 的可观测性最朴素:日志与退出码,接入现有 CI 报表即可。
B 需要宿主自己埋点:会话标识贯穿日志、工具调用耗时、审批拒绝率、上下文压缩触发次数。
C 天然产生服务端指标,但需要额外的分布式追踪:一次用户请求可能跨网关、会话服务、模型端点、沙箱容器。这是运维复杂度最高的一档。
4.9 成本结构
| 成本项 | A 脚本级 | B SDK 嵌入 | C 会话服务 |
|---|---|---|---|
| 计算资源 | 中(进程冷启动开销) | 低(复用宿主进程) | 高(常驻服务 + 会话存储) |
| 模型 token 成本 | 高(无上下文复用) | 中 | 中 |
| 人力/研发成本 | 极低 | 高(状态与并发自理) | 中(协议适配为主) |
| 运维成本 | 极低 | 中 | 高(有状态组件高可用) |
| 迁移成本 | — | 中 | 中(协议层重写) |
五、对比表格:关键差异速查
| 维度 | A 一次性非交互调用 | B SDK 程序化编排 | C 持久会话服务驱动 |
|---|---|---|---|
| 状态归属 | 无状态 | 宿主进程 | 服务端 |
| 多轮对话 | 不支持 | 支持 | 原生支持 |
| 断线重连 | 不适用 | 需自研 | 通常内置事件重放 |
| 运行时审批 | 静态策略 | 代码内实时拦截 | 远端 UI 响应协议消息 |
| 并发隔离性 | 强(进程级) | 弱(需自行隔离) | 中(依赖配额与路由) |
| 弹性扩展 | 水平扩进程 | 扩宿主实例 | 扩服务实例 + 会话路由 |
| 前端友好度 | 低 | 中(本地) | 高 |
| 接入改造量 | 最小 | 最大 | 中等 |
| 新增大故障点 | 无 | 无 | 有(会话存储/网关) |
| 典型形态 | CI 任务、批量修复 | 产品内嵌 Agent、桌面工具 | 对话式产品、协作型 Agent |
六、典型场景选择
场景一:CI/CD 中的自动化任务(失败测试修复、依赖升级、代码规范整改)
优先 A。任务边界清晰、无需交互、失败即重跑,用进程隔离换取稳定性,是投入产出比最高的选择。
场景二:在自有产品中嵌入 Agent 能力(业务系统里的智能助手、编辑器内的编码代理)
在 B 与 C 之间取舍,判断标准是是否需要人类在环与跨端会话:
- 纯本地、单机、低延迟优先 → B;
- 审批发生在服务端 UI、用户会换设备继续对话 → C。
场景三:多租户 Agent 平台(对外提供 Agent 服务)
倾向 C。集中式配额、排队、审计与计费都需要一个统一的服务端入口,把调度权收在平台侧而非租户进程里。
场景四:高安全要求的封闭环境(离线、无法访问外部模型端点)
推荐”自建循环(D)+ 私有化模型端点”,或者选择支持完全离线运行的 A/B 形态。C 引入的服务端与存储会扩大需要审计的边界。
七、选型建议
- 先确定交互形态,再选接入层。有没有”人类在环审批”和”跨会话续聊”,是 A 与 B/C 的分界线,比性能考量更优先。
- 团队运维能力不足时,优先考虑改造量集中在协议层的方案。会话服务的状态管理、路由与备份是有状态系统的经典难题,低估其成本是常见的翻车点。
- 需要弹性伸缩与集中管控时,服务化接入更契合;追求低延迟与强隔离时,进程内或进程级接入更契合。
- 模型可替换性应作为硬性验收项。无论哪层,都应通过统一的兼容端点配置切换模型提供方,避免业务代码与特定模型绑定;这样在成本与效果权衡时才有调整空间。
- 不要为了”以后可能要”提前上最重的方案。A 到 B 的迁移成本通常低于预期(共享同一内核语义),先落地再演进是合理的路径。
- 自建 Agent 循环只在有明确约束时才划算:需要深度定制状态机、内核无法满足工具协议、或必须完全离线。否则要自行承担上下文管理、沙箱、审批、重试这一整套重复建设。
八、迁移与使用注意事项
- 会话协议是主要改造面。从 A 迁移到 C,需实现事件序号与幂等重放,否则网络抖动会导致消息重复或丢失。
- 审批语义变更需回归测试。运行时审批替代静态策略后,”自动放行”的默认值一旦配置过宽,等于取消了安全边界。建议默认拒绝、显式放行。
- 沙箱资源要设上限。工具执行需要 CPU、内存、执行时长与产物体积的硬限制,以及并发数上限,防止单个任务拖垮宿主。
- 凭据最小权限 + 短期有效。Agent 进程只应拿到完成任务所需的最小权限令牌,并具备可撤销性。
- 成本观测先于成本优化。会话级 token 统计、上下文压缩触发率、工具输出体积分布,这三项数据缺一时无法判断优化方向。
- 版本兼容要显式锁定。harness 的事件格式与会话存储结构可能随版本演进,升级前应评估会话数据的可迁移性,并在预发环境跑通升级与回滚。
- 托管化配套能力可显著降本。若团队自建有状态服务的压力大,可评估百度智能云等云平台提供的容器平台、负载均衡、日志服务、监控告警、身份认证等通用云产品能力来承载会话服务与可观测链路,把精力集中在 Agent 逻辑本身而非基础设施运维。
九、总结
三种接入方式的本质区别,不在功能多寡,而在状态归属与调度权归属:
- A 把状态交给进程,调度权交给构建系统——简单、隔离好、无交互;
- B 把状态交给宿主程序,调度权交给开发者——灵活、低延迟、责任重;
- C 把状态交给服务端,调度权交给平台——可管控、可跨端、组件多。
它们共享同一套工具、沙箱、审批与上下文语义,因此迁移的主成本是驱动层重写而非 Agent 逻辑重写。决策时建议按”是否需要人工审批 → 是否需要跨端续聊 → 是否需要集中管控”的顺序依次判断,前两问的答案基本就能定位到合适的层次;最后再考虑性能与成本,通常不会选错。

登录后可评论,请前往 登录 或 注册